Introduction
A HSM can be used to store the master key(s) used when performing administration key operations with the vSEC:CMS such as registering a credential or PIN unblock operations. The vSEC:CMS makes use of the PKCS#11 interface available in the HSM. All management functions around the master key stored on the HSM should be managed by the HSM key management tools available from the HSM vendor.
For a full list of supported HSMs see the product sheet here.
It is expected that the HSM PKCS#11 module, typically a DLL, is installed and configured to connect to the HSM on the server where the vSEC:CMS is installed. Depending on whether you are running the 32-bit or 64-bit version of vSEC:CMS, it will be required to have the correct version (32-bit or 64-bit) of the HSM PKCS#11 module. See the section Retrieve PKCS#11 DLL below to see how vSEC:CMS will search to find the PKCS#11 module for the HSM that you are attempting to connect to.
It will be required that a fully licensed version of vSEC:CMS is running in order to set up and use a HSM.
vSEC:CMS requires any available slot on any available partition on HSM that is being used. The master key that vSEC:CMS uses can be AES or DES3 key type.
Configure
1. From Options - Connections click the Configure button. Make sure that the Hardware Security Module (HSM) is in the Selected window.
2. Then click Hardware Security Module (HSM) and click the Add button to setup a template. Enter a template name and from the drop-down list select the HSM that you plan to use.
If after selecting the HSM that you want to use and you get an error like below:
Failed to retrieve slot list from HSM.
void C_PKCS11_DLL::Load():0x80000016:Signature check failed
ID:PTNI-6342
This means that the PKCS#11 dll is not in our trusted allow list. You can work around this by navigating to Options - Security and enable the checkbox Allow loading of unsigned library extensions (DLLs).
We do recommend that you send a SHA-1 hash of the DLL so we can add this to our list. Please send hash to support@versasec.com
3. The PKSC#11 module will be automatically detected and populated into the PKS11 DLL name field. The URL will be read from the configuration file that is typically included as part of the HSM configuration. Select the slot that the master key will reside in from the available slot list in the drop-down list. Enter the PIN credential for the user who has access to the slot and click Check connection to test connectivity. The PIN credential may not be required if the HSM does not require a PIN credential as the HSM may require that the PIN credential is entered on the HSM directly. If connectivity to HSM is functional as expected a success dialog will popup.
Click Save to save and close the configuration.
4. Once the connection is setup it will be necessary to create an Operator Service Key Store (OSKS). Navigate to Options - Operators and click the Add service key store button. Enter a name in the Store name field and click Add.
All vSEC:CMS master keys will be copied to the HSM during this process and at the end you will get a success dialog.
From the Operators table you can see that the HSM is now used as key store as indicated by the * character.
Additionally, if you go back to Options - Connections - Hardware Security Module (HSM) and select your HSM connector and Edit, then click the Check connection button you should see more information in the success dialog indicating that the master key used by vSEC:CMS was found in the slot on the HSM.
Generate New Master Key
It is strongly recommended to generate a new master key. Follow the instructions below to perform this task.
It is important to remember that any new credential administration key will be diversified from the newly generated master key. Any credential administration key diversified from older master key(s) of the vSEC:CMS application will remain operable. However, it is recommended to re-register those credentials issued from the older master key(s) of the vSEC:CMS. This will update the user's credential administration key so that it is diversified from the new master key.
1. From Options - Master Key click the Generate new master key button to start the process.
2. Select the option On server side HSM and from the drop-down list 3 options are available, DES-EDE3, AES128 and AES256. Select the appropriate key type and size as required for your environment.
It is recommended to select AES for key type as DES has been withdrawn as a standard by the National Institute of Standards and Technology. From version 6.5 of vSEC:CMS it is possible to migrate from DES managed master keys to AES.
Click Ok. A dialog will popup informing you about the change to the system. Click Yes to complete the setup.
3. Navigate to Repository - Master keys and you will see the entry. The * character indicates which master key is to be used by vSEC:CMS.
Additionally, from Repository - Credentials you will see that credentials managed by older master keys will have an Update needed message.
Once the HSM master key is generated it will not be possible to roll back to use an earlier master key. For any credential that was previously managed by the vSEC:CMS with an older master key that was not generated by the HSM it will be possible to continue to manage these credentials but it is recommended to update these credentials so that they will be managed by the newly created master key.
Credentials whose master key needs to be updated can be done as described below:
- From vSEC:CMS Admin console navigate to Actions - Credential Update and attach a credential that needs to be updated and click the Execute button;
- From a client host that has vSEC:CMS User installed and configured for updates, navigate to the Update tab to perform the update.
Retrieve PKCS#11 DLL
vSEC:CMS supports a wide range of HSMs. This section will describe how vSEC:CMS determines what HSM is available. vSEC:CMS connects/communicates with HSMs that it supports through the standard PKCS#11. All HSM vendors should provide a PKCS#11 module (usually in the form of a dll) which needs to be available on the server where vSEC:CMS is installed. It should be the 64-bit version of the PKCS#11 library that is used (presuming that vSEC:CMS is on 64-bit version).
|
HSM |
How vSEC:CMS Finds PKCS#11 DLL |
|
Safenet Luna |
Expects System Variable ChrystokiConfigurationPath to be set on the server where vSEC:CMS server is installed. This stores the path to crystoki.ini. This ini file has path to where dll is located on the server. |
|
Utimaco CryptoServer |
Copy the Ultimaco HSM config and dll file and paste it to the location where vSEC:CMS is installed (typically this location: C:\Program Files\Versasec\vSEC_CMS S-Series). |
|
Entrust nShield |
Expects System Variable NFAST_HOME to be set on the server where vSEC:CMS server is installed. This has the path to where HSM client is installed (typically here C:\Program Files\nCipher\nfast). Then vSEC:CMS will check the bin folder or the toolkits\pkcs11 folder for the dll file. |
|
SafeNet ProtectServer |
vSE:CMS checks the registry for below: Path: HKEY_LOCAL_MACHINE\SOFTWARE\Safenet\PTKC\CryptokiPath |
|
AEP |
Depending on whether you are using 64 or 32 bit version of vSEC:CMS, it will attempt to load bp201w32hsm.dll or ap220w64HSM.dll from either C:\Windows\System32 or C:\Windows\SysWOW64. |
|
Thales DPoD |
Expects System Variable ChrystokiConfigurationPath to be set on the server where vSEC:CMS server is installed. This stores the path to crystoki.ini. This ini file has path to where dll is located on the server. |
| Securosys Primus
|
vSE:CMS checks the registry for below: HKEY_LOCAL_MACHINE\SOFTWARE\Primus\configFilename |
| SafeNet T Series |
Expects System Variable ChrystokiConfigurationPath to be set on the server where vSEC:CMS server is installed. This stores the path to crystoki.ini. This ini file has path to where dll is located on the server. |
| FutureX VirtuCrypt |
vSEC:CMS expects the DLL to be here: C:\Program Files\Futurex\fxpkcs11\fxpkcs11.dll |
| YubiHSM2 |
Expects System Variable YUBIHSM_PKCS11_CONF to be set on the server where vSEC:CMS server is installed. This has the path to the configuration file yubihsm_pkcs11.conf. This is typically the same location that the PKCS#11 dll file resides. Therefore replace the path in this file that points to yubihsm_pkcs11.conf to instead point to yubihsm_pkcs11.dll. |
| Fortanix |
vSEC:CMS expects the DLL to be here: C:\Program Files\Fortanix\KmsClient\FortanixKmsPkcs11.dll |
Tip
Additional Information
Any master key added to the HSM will have a label starting with CMS MK on the HSM. Depending on whether the master key is generated only on the HSM or was a key created and stored on a full-featured operator credential and synced with the HSM, the label will have a different value depending on which option is selected.
For a master key generated only on the HSM the label on the HSM will be: CMS MK 4099 (this is a hex value), if this was the first key. Any additional key(s) would be incremented by one; therefore, a second master key would have a value of CMS MK 4100 and so on.
For a master key created and stored on a full-featured operator credential and synced with the HSM the label on the HSM will be: CMS MK 00, if this was the first key. Any additional key(s) would be incremented by one; therefore, a second master key would have a value of CMS MK 01 and so on.
HSM Tool
A PKCS#11 tool is included that can be useful when troubleshooting issues that may occur when setting up and using a HSM with vSEC:CMS.
This tool should be run directly on the server where vSEC:CMS is installed.
On the server where vSEC:CMS is installed you can find this tool by opening a command prompt and changing to the location where the tool is installed. If the default installation location was selected during the installation then change to C:\Program Files\Versasec\vSEC_CMS S-Series\tools for 64-bit version and C:\Program Files (x86)\Versasec\vSEC_CMS S-Series\tools for 32-bit version.
Launch the tool with -debug on as parameter.
You will be prompted to enter from a pre-existing list of HSMs but we recommend you enter the path of the pkcs#11 library that was used when setting up the HSM connection, therefore enter 8. You can get the path from the edit dialog of your HSM connection like in example below by selecting the PKCS11 DLL name and selecting Copy.
You should enter something similar to below:
You can now use PKCS11 commands to check and test that connectivity to the HSM is functional.
For example, if you want to check/compare that the master key(s) that have been configured in vSEC:CMS are present in the HSM slot you can do as below:
After connecting to the HSM (as described above) enter the slot that vSEC:CMS master key(s) are stored, for example 1 in the case of this example.
Then login to slot by selecting 14 and 1 for the USER and enter password (if this is required for the slot)
Now we want to find the master key object label so enter 19 and LABEL
In this example we have 3 keys listed
And we can cross reference these from the Repository - Master Keys in vSEC:CMS