Setup of SmartCard-HSM devices to use with WebADM
This guide will lead you through the setup of one or preferably several (for load-balancing and fail-over purposes) SmartCard-HSM to use hardware cryptography within WebADM, adding an extra layer of security to protect WebADM sensitives informations.
All steps of the initialization, configuration and replication of the devices can be performed directly with standard command line tools directly on the server where WebADM is installed, except for the generation of an AES secret key that will be, as we write these lines, only exportable to another device if it has been generated properly through the Smart Card Shell GUI.
2. Launch the PCSCD daemon
In order to use the SmartCard-HSM device, the daemon from the PCSC lite project, which is a middleware to access a smart card using SCard API, must be running.
To launch the daemon, run this command:
3. Create DKEK share(s) to allow secure import / export of the keys
In order to replicate the secret and private keys contained in one device to another device, these devices have to be initialized with the same Device Key Encryption Key (DKEK) which is a 256 bits AES key.
A DKEK is imported into a SmartCard-HSM using a preselected number of key shares. Each key share is given to a key custodian and only all key shares together assemble the DKEK. Key shares are individually imported and are assembled within the SmartCard-HSM. Key shares can be imported independently of time and location, allowing to pass a half-initialized device between key custodians until all shares have been imported.
The HSM supports an arbitrary number of DKEK shares. Typical values for the number of shares are:
- 0: The HSM generates an internal DKEK (no backups).
- 1: The HSM requests one external DKEK share to be imported.
- 3: The HSM requests three external DKEK shares to be imported by three different key custodians.
The DKEK must be set during initialization and before any other keys are generated. For a device initialized without a DKEK, keys can never be exported.
Create a DKEK share with the following command:
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --create-dkek-share dkek-share-1.pbe
The DKEK share will be enciphered using a key derived from a user supplied password. The security of the DKEK share relies on a well chosen and sufficiently long password. The recommended length is more than 10 characters, which are mixed letters, numbers and symbols.
Please keep the generated DKEK share file in a safe location. We also recommend to keep a paper printout, in case the electronic version becomes unavailable. A printable version of the file can be generated using :
[root@webadm]# openssl base64 -in <filename>
If you want several key shares, you can repeat the command giving another file name.
Control over a DKEK share can be split even further using a n-of-m threshold scheme for the DKEK share’s password. In such a scheme m key custodians are given a share of the password and n key custodians must come together to decrypt the DKEK share for import. For more information, you can consult this page from OpenSC’s wiki.
4. Initialization of a device
To initialize a HSM, you have to provide a Security Officer (admin) PIN, a user PIN and the number of DKEK shares.
The command below shows the initialization of a HSM with the one DKEK, using usual default SO pin and user PIN for the SmartCard-HSM. Using default SO pin and user PIN for a HSM is obviously only recommended outside the production environment.
If you prefer to avoid inputing the PIN on the command line, both here and on any command shown later in this documentation, you can simply omit this argument and you will then be prompted interactivly for it
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1
The HSM is not fully initialized yet as you requested one DKEK share:
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool Using reader with a card: Identiv uTrust 3512 SAM slot Token [CCID Interface] (55511822601831) 00 00 Version : 4.0 Config options : User PIN reset with SO-PIN enabled SO-PIN tries left : 15 User PIN tries left : 3 DKEK shares : 1 DKEK import pending, 1 share(s) still missing
5. Import the DKEK share(s) into the device
In order to complete the initialization of the device, you have to import the exact number of DKEK shares requested during the previous step.
To import the DKEK, type this command:
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --import-dkek-share dkek-share-1.pbe
The password of the given DKEK will be requested. Repeat the operation with all the remaining DKEK shares if needed.
You can then confirm that the HSM is properly initialized:
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool Using reader with a card: Identiv uTrust 3512 SAM slot Token [CCID Interface] (55511822601831) 00 00 Version : 4.0 Config options : User PIN reset with SO-PIN enabled SO-PIN tries left : 15 User PIN tries left : 3 DKEK shares : 1 DKEK key check value : F9C3647BEDBF0D80
6. Generating a RSA keypair for the certificate generation feature of WebADM
To generate a 2048 bits RSA keypair into the HSM, input a command similar to this one:
[root@webadm]# /opt/webadm/doc/scripts/pkcs11-tool --module /opt/webadm/lib/pcsc/schsm.so --login --pin 648219 --keypairgen --key-type rsa:2048 --label "HSM RSA Key"
7. Generating a symetric key for AES-CBC cryptography
As we write these lines and as far as we know, the only way to generate an AES key that would be exportable and importable to another device thanks to DKEK share(s) is through the Smart Card Shell GUI that you can download here : https://www.openscdp.org/scsh3/.
It is of course also possible to initialize, create / import DKEK, generating RSA keys and import / export keys through this GUI, even if we decided to document as much as possible the usage of command line tools that will allow to clone a device to a new device directly from the server
Follow the installation instructions given on its website then follow the documentation below to generate an AES key.
Launch the Smart Card Shell GUI and choose
Key Managerin the
Right-click on the
User PIN not verified item, choose the
Login with User PINitem from the contextual menu and input the user pin of the device
Right-click on the
DKEKand choose the
Generate AES Keyitem from the contextual menu
Select the key size (we recommend 256 bits), enter a key label, then select the capabilities of the AES key. At minimal, you must select
CBC_DEC(11)to operate the key with OpenOTP, and
WRAP(92)to be able to export the key from the device to import it on another device.
8. Cloning the device to another device
8.1 Export the key(s) from the device
To export a key from the HSM, you have to know its id. If you do not know it, you can list all the keys on the device :
[root@webadm]# /opt/webadm/doc/scripts/pkcs11-tool --module /opt/webadm/lib/pcsc/schsm.so --login --pin 648219 --list-objects Using slot 0 with a present token (0x1) Certificate Object; type = unknown cert type label: C.DevAut Certificate Object; type = unknown cert type label: C.DICA Public Key Object; RSA 2048 bits label: HSM RSA Key ID: 01 Usage: encrypt, verify Access: local Private Key Object; RSA label: HSM RSA Key ID: 01 Usage: decrypt, sign Access: sensitive, always sensitive, never extractable, local Secret Key Object; AES length 32 label: HSM AES Key ID: 02 Usage: encrypt, decrypt Access: sensitive, always sensitive, never extractable, local
Then input a command similar to this one, providing the file name under which you want to save the exported key and the ID of the key you want to export
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --wrap-key key1.bin --key-reference 01
Keep in mind that the index that will be later set in the WebADM configuration file is not related to the IDs shown here. It will be a sequential index in the list of keys found when searching the device for all AES secret keys. Please note that the index is only unique based on the type of the key.
8.2 Initialize a new device with the same DKEK share(s)
Repeat steps 4 and 5 of this documentation for a new device
8.3 Import the key(s) into the new device
To import the key(s) to a new device, input a command similar to this one:
[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --unwrap-key key1.bin --key-reference 01
9. Configuring WebADM for Hardware Encryption with the SmartCard-HSM
There are only four settings to be configured in WebADM to enable hardware encryption with your SmartCard-HSM. Edit the WebADM main configuration file
/opt/webadm/conf/webadm.conf and configure the following settings:
hsm_model: WebADM supports hardware security modules. When enabled, the hardware-based security complements the WebADM default software encryption: very sensitive user data like Token secrets or inventory data are transparently encrypted by the connected HSM(s) whereas other (less sensitive) data are encrypted using WebADM software encryption. WebADM supports eHSM and MIRkey. Several devices can be used concurrently (in failover and load-balanced mode). Moreover, the addition or removal of HSM modules is hot-plug.
hsm_keyid: Like with the software encryption, multiple HSM key IDs (i.e. key handles) can be used concurrently and the rollout of a new AES hardware master key is supported. You can set several encryption key IDs for automatic key rollout. All the defined keys are used for decrypting data. And the first defined key is used to (re-)encrypt data.
hsm_pincode: You have to provide the user password of the devices. As it is a sensitive information, please keep the permissions of the webadm.conf file safe. It should not be readable by another user than root and the group webadm.
Parameters look like this:
encrypt_hsm Yes hsm_model smartcard hsm_keyid 0 hsm_pincode 648219
10. Check the correct configuration and test the devices in WebADM
Click on the
Admin menu in the menu bar then select the
Hardware Modules Details link
You will see the status and details about the plugged HSM. Please ensure that all indicators are in green. HSMs must be reported as operational, with configured keys as consistent (same keys across all the HSMs) and with each individual configured key reported as Ok.
You can test the devices by clicking on the
Test HSM button. You should see a screen similar to the one bellow with all tests reported as passed.