Smartcard HSM (Hardware Security Module)
  Download PDF

Setup of SmartCard-HSM devices to use with WebADM

1. Introduction

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 information.

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:

[root@webadm]# /opt/webadm/libexec/webadm-pcscd

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.

Important note

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 an 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 an 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 an 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 an HSM is obviously only recommended outside the production environment.

Important note

If you prefer to avoid entering 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 interactively 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/ --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 :


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 Manager in the File menu

  • Right-click on the User PIN not verified item, choose the Login with User PIN item from the contextual menu and input the user pin of the device

  • Right-click on the DKEK and choose the Generate AES Key item 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_ENC(10) and 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/ --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.