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 smart card token 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.
Currently the vSEC:CMS supports the following HSMs:
- Safenet Luna SA;
- Safenet ProtectServer;
- Thales nShield;
- Ultimaco SafeGuard CryptoServer;
- Black Vault.
Important: It is expected that the HSM PKCS#11 module is installed and configured to connect to the HSM on the server where the vSEC:CMS is installed. It is required that the 32 bit version (dll) of the HSM PKCS#11 module is available. The vSEC:CMS will search in the system path for the PKCS#11 module.
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.
3. In this article, we will demonstrate how a typical connection to a Safenet Luna SA HSM would be configured. 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. Click Save to save and close the configuration.
Once the connection is setup it will be necessary to create an Operator Service Key Store (OSKS). Refer to the article Create Operator Service Key Store for details on this. Once this has been setup you can continue with the setup below.
Generate New Master Key
If it is required to generate a new master key, either on the operator token or on the HSM follow the instruction here.
Important: It is important to remember that any new user smart card administration key will be diversified from the newly generated master key. Any user smart card administration key diversified from the old administration key of the vSEC:CMS application will remain operable. However, it is recommended to re-register those user cards issued from the old administration key of the vSEC:CMS. This will update the user's smart card 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. A dialog will be displayed.
3. Select On vSEC:CMS Operator Card if it is required that the new master key is generated on the connected full-featured operator token. The new master key will also be migrated to the HSM and any other full-featured operator token(s) used in the vSEC:CMS. For a full-featured operator token the migration will take place the next time an operator logs onto the vSEC:CMS.
4. Select the option On server side HSM if it is required that the new master key should be generate on the HSM only. In this case the new master key will only be available on the HSM. Therefore, all operations that require master key access to the newly generated master key will need to use the HSM. This will mean that the OSKS will need to be activated from the Options - Operators page. For any smart card that was previously managed by the vSEC:CMS with a full-featured operator token that used an older master key that was not generated by the HSM it will be possible to continue to manage these cards but it is recommended to update these cards so that they will be managed by the newly created master key.
Important: Once the HSM master key is generated it will not be possible to roll back to use a master key stored on the operator smart card(s). For any smart card that was previously managed by the vSEC:CMS with an operator card that used an older master key that was not generated by the HSM it will be possible to continue to manage these cards but it is recommended to update these cards so that they will be managed by the newly created master key.
Restore or Migrate to New HSM
If it is required to move and/or restore your current HSM then follow the instructions in this section.
Important: It is expected that proper backup procedures have been used when backing up your current HSM system such that any vSEC:CMS master key(s) are stored correctly by your HSM backup procedures. This is out of scope for the vSEC:CMS.
1. From Options - Operators select the HSM key store and delete it. You will be prompted that removing the key store will impact the listed card templates in the warning dialog. Select Yes to continue. As it is expected that the HSM is unavailable you will receive another warning dialog informing you that the HSM is currently not available and that the master key(s) previously stored on the HSM cannot be deleted. It is expected that the HSM administrator would manage any clean up tasks regarding these key(s). Select Yes to continue and complete the deletion.
2. Add a new connection for the HSM from Options - Connections similar to what is described in the Configure HSM Support above. When you click the Check connection button you will be prompted that the connection was established and all master key(s) found were successfully verified. Click the Save button on the connection dialog. You will be prompted that vSEC:CMS master key(s) were found and asked whether you want to make them available to the vSEC:CMS. Select Yes to continue. The vSEC:CMS will automatically create a new key store which you can verify and activate from the Options - Operators page.
3. From Options - Operators select the newly created key store. It should start with a name Restored from… and click the Activate button to complete the flow.
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 created and stored on operator smart card tokens and synced with the HSM OR the master key is generated only on the HSM the label will have a different value depending on which option is selected.
For a master key created and stored on operator smart card tokens 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.
For a master key generated only on the HSM the label on the HSM will be: CMS MK 4100, 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 4101 and so on.