HSM
HSM

Overview

This guide will walk you through setting up one or, preferably, several eHSM/MIRkey devices for hardware cryptography within WebADM. This setup adds an extra layer of security to protect sensitive data in WebADM. Note that MIRKey HSMs require at least WebADM version 2.0.17.

Download and install the ellipticSecure Device Manager

Although it is possible to initialize and set up the eHSM or MIRkey using standard command-line PKCS11 tools, we recommend using the ellipticSecure Device Manager GUI. This tool allows for firmware updates and the configuration of a backup domain, which facilitates restoring backups from one device to another. This feature is especially useful for load balancing across multiple HSMs and for disaster recovery purposes.

On Windows 10 version 1903 or later, you need to run the application as an Administrator to access the device information.

  • To set up the MIRkey or eHSM using this GUI, download the latest version of the ellipticSecure Device Manager application for Windows, macOS, or Linux.
  • Install the ellipticSecure Device Manager.
  • Insert the eHSM or MIRkey into an available USB port and run the ellipticSecure Device Manager.

Upgrade to the latest version of the firmware

To ensure optimal performance and reliability, please update the MIRkey and eHSM to the latest firmware version. For compatibility with our software, make sure you are running at least version 1.27 of the firmware.

To check for a firmware upgrade, click on the Help menu, then select Check for Updates... and follow the on-screen instructions if an update is available.

Note: If you encounter any errors while upgrading the firmware on macOS, please use Windows or Linux instead. Some macOS versions are known to be incompatible with the firmware upgrade feature of the ellipticSecure Device Manager.

Initialize the first device

  • Click on the settings icon:
HSM
  • You will be prompted to first initialize the device:
HSM
  • Provide the HSM label, admin password, and user password. Be sure to remember the admin password.
HSM
  • For optimal performance, we highly recommend setting sessions to automatically close after 1 minute of inactivity. Although this is less critical on a server, we also strongly advise disabling the FIDO2/FIDO interfaces to prevent potential communication issues caused by concurrent USB access, particularly if any process attempts to enumerate FIDO devices. You can adjust other settings to align with your password policies.
HSM
  • Enter the admin (security officer) password.

Generating a symmetric key for AES-CBC cryptography

To use hardware cryptography within WebADM, the HSM must store a symmetric key. This key should be generated directly within the HSM to ensure that it cannot be retrieved outside the device.

  • Click on the Tools menu, then select Generate Symmetric Key... and input the desired key label. It is strongly recommended to keep the key private, non-extractable, and with a size of 256 bits for the highest security.

Note: You may choose any ID, but remember that the index used in the WebADM configuration file is not related to this ID. The index will be a sequential number assigned to the keys when searching the device for all AES secret keys. It is advisable to use a sequential number starting from 0 when setting the keys. Note also that the index is unique only within the context of the key type.

HSM
  • Next input the user password to unlock the device, in order to save the generated key

Cloning the device to another device

Backup the current device

  • Click on Tools menu then on Backup device... while pressing the button on the device at the same time

  • Choose the filename and folder where to save the backup

Join a new device to the backup domain

  • Click on Tools menu then on Manage Backup domain...

{{< figure src="../backup_domain.webp" class="img70 center" width="560" height="529" >}}

  • Click on Join a new device to the current device domain

  • Insert a 2nd device and click on Yes

  • Close the dialog to manage the backup domain by clicking on OK

6.3 Restore the backup on the new device

  • Click on Tools menu then on Restore device...

  • Select the backup file to restore

HSM
  • Confirm the restoration by clicking on Yes while pressing the button on the device at the same time

Your devices are now correctly setup, and they must be enabled on WebADM.

Configuring WebADM for Hardware Encryption with the eHSM / MIRkey devices

There are only four settings to configure in WebADM to enable hardware encryption with your eHSM/MIRkey. Edit the WebADM main configuration file /opt/webadm/conf/webadm.conf and configure the following settings:

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

  • hsm_keyid: 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 only be readable by the root user and the webadm group.

The parameters should look like this:

encrypt_hsm  Yes
hsm_model MIRkey
hsm_keyid 0
hsm_pincode password

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

HSM

You will see the status and details about the connected HSM. Ensure that all indicators are green. HSMs should be reported as operational, with configured keys consistent across all HSMs, and each individual configured key should be reported as "Ok."
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.

HSM