Overview

This guide will walk you through setting up one or preferably several SmartCard-HSMs for hardware cryptography within WebADM, adding an extra layer of security to protect sensitive information.

All steps for initializing, configuring, and replicating the devices can be performed directly using standard command-line tools on the server where WebADM is installed. However, the generation of an AES secret key must be done through the Smart Card Shell GUI to ensure it can be properly exported to another device.

smartcard-hsm

Launch the PCSCD daemon

To use the SmartCard-HSM device, the PCSC-lite daemon must be running. PCSC-lite is middleware that provides access to smart cards using the SCard API.

To launch the daemon, run this command:

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

Create DKEK share(s) to allow secure import / export of the keys

To replicate the secret and private keys from one device to another, both devices must be initialized with the same Device Key Encryption Key (DKEK), which is a 256-bit AES key.

A DKEK is imported into a SmartCard-HSM using a predefined number of key shares. Each share is given to a key custodian, and all key shares together assemble the DKEK. Key shares are imported individually and are assembled within the SmartCard-HSM. Shares can be imported independently of time and location, allowing a partially initialized device to be passed 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.

To create a DKEK share, use the following command:

[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --create-dkek-share dkek-share-1.pbe

The DKEK share will be encrypted using a key derived from a user-supplied password. The security of the DKEK share depends on choosing a strong and sufficiently long password. A recommended password length is more than 10 characters, including a mix of letters, numbers, and symbols.

Please keep the generated DKEK share file in a safe location. We also recommend keeping 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 need multiple key shares, you can repeat the command with different file names.

Control over a DKEK share can be further refined using an n-of-m threshold scheme for the DKEK share’s password. In this scheme, m key custodians are each given a share of the password, and n key custodians must come together to decrypt the DKEK share for import. For more information, consult this page from OpenSC's wiki.

Initialization of a device

To initialize an HSM, you need to provide a Security Officer (admin) PIN, a user PIN, and the number of DKEK shares.

The command below shows how to initialize an HSM with one DKEK share, using the default SO PIN and user PIN for the SmartCard-HSM. Note that using default SO PIN and user PIN is only recommended outside of a production environment.

If you prefer to avoid entering the PIN on the command line, you can omit this argument, and you will be prompted to enter it interactively.

[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 only one DKEK share has been provided.

[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

Import the DKEK share(s) into the device

To complete the initialization of the device, you need to import the exact number of DKEK shares requested during the previous step.

To import the DKEK, use the following command:

[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --import-dkek-share dkek-share-1.pbe

You will be prompted for the password of the provided DKEK. Repeat this process with all remaining DKEK shares if necessary.

Once all shares have been imported, you can confirm that the HSM is properly initialized by running:

[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

Generating a RSA keypair for the certificate generation feature of WebADM

To generate a 2048-bit RSA key pair in the HSM, use a command similar to the following:

[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"

Generating a symetric key for AES-CBC cryptography

As of now, the only method known for generating an AES key that can be exported and imported to another device using DKEK shares is through the Smart Card Shell GUI, which you can download here: https://www.openscdp.org/scsh3/.

You can also initialize the device, create/import DKEK shares, generate RSA keys, and import/export keys using this GUI. However, we have documented the use of command-line tools as much as possible for cloning a device directly from the server.

Follow the installation instructions provided on the website and then use the documentation below to generate an AES key.

  • Launch the Smart Card Shell GUI and select Key Manager from the File menu.
smartcard-hsm
  • Right-click on the User PIN not verified item, select Login with User PIN from the context menu, and enter the user PIN for the device.
smartcard-hsm
  • Right-click on the DKEK and select Generate AES Key from the context menu.
smartcard-hsm
  • Select the key size (we recommend 256 bits), enter a key label, and then choose the capabilities for the AES key. At a minimum, you must select CBC_ENC(10) and CBC_DEC(11) to use the key with OpenOTP, and WRAP(92) to enable exporting the key from the device for import to another device.
smartcard-hsm

Cloning the device to another device

Export the key(s) from the device

To export a key from the HSM, you need to know its ID. If you don't know the ID, you can list all the keys on the device by using the following command:

[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 enter a command similar to the following, specifying the file name where you want to save the exported key and the ID of the key you wish to export:

[root@webadm]# /opt/webadm/doc/scripts/sc-hsm-tool --wrap-key key1.bin --key-reference 01

Keep in mind that the index used in the WebADM configuration file is not related to the IDs shown here. It will be a sequential index in the list of keys when searching the device for all AES secret keys. Note that this index is unique only within the context of the key type.

Initialize a new device with the same DKEK share(s)

Repeat steps 4 and 5 of this documentation for a new device

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

Configuring WebADM for Hardware Encryption with the SmartCard-HSM

There are only four settings to configure in WebADM to enable hardware encryption with your SmartCard-HSM. Edit the WebADM main configuration file /opt/webadm/conf/webadm.conf and set the following parameters:

  • hsm_model: WebADM supports hardware security modules. When enabled, hardware-based security complements WebADM’s default software encryption. Very sensitive user data, such as token secrets and inventory data, is transparently encrypted by the connected HSM(s), while less sensitive data is encrypted using WebADM’s software encryption. WebADM supports SmartCard-HSM, eHSM, and MIRkey. Multiple devices can be used concurrently for failover and load balancing, and HSM modules can be added or removed without restarting the system.

  • hsm_keyid: Similar to 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 specify several encryption key IDs for automatic key rollout. All defined keys are used for decrypting data, and the first defined key is used for (re-)encrypting data.

  • hsm_pincode: Provide the user password for the devices. As this is sensitive information, ensure the permissions for the webadm.conf file are secure. It should be readable only by the root user and the webadm group.

The parameters should look like this:

encrypt_hsm  Yes

hsm_model smartcard
hsm_keyid 0
hsm_pincode 648219

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.

smartcard-hsm

You will see the status and details of the connected HSM. Ensure that all indicators are green. The HSMs should be reported as operational, with configured keys consistent across all devices, and each individual key should be reported as "Ok".

smartcard-hsm

You can test the devices by clicking the Test HSM button. You should see a screen similar to the one below, with all tests reported as passed.

smartcard-hsm