6.4. Hardware Security Module

To use a Hardware Security Module (HSM), a Federal Information Processing Standard (FIPS) 140-2 validated HSM is required. See your HSM documentation for installing, configuring, and how to set up the HSM in FIPS mode.

6.4.1. Setting up SELinux for an HSM

Certain HSMs require that you manually update SELinux settings before you can install Certificate System.
The following section describes the required actions for supported HSMs:
nCipher nShield
After you installed the HSM and before you start installing Certificate System:
  1. Reset the context of files in the /opt/nfast/ directory: 
    # restorecon -R /opt/nfast/
  2. Restart the nfast software. 
    # /opt/nfast/sbin/init.d-ncipher restart
Thales Luna HSM
No SELinux-related actions are required before you start installing Certificate System.
For details about the supported HSMs, see Section 4.4, “Supported Hardware Security Modules”.

6.4.2. Enabling FIPS Mode on an HSM

To enable FIPS Mode on HSMs, please refer to your HSM vendor's documentation for specific instructions.

Important

nCipher HSM
On a nCipher HSM, the FIPS mode can only be enabled when generating the Security World, this cannot be changed afterwards. While there is a variety of ways to generate the Security World, the preferred method is always to use the new-world command. For guidance on how to generate a FIPS-compliant Security World, please follow the nCipher HSM vendor's documentation.
LunaSA HSM
Similarly, enabling the FIPS mode on a Luna HSM must be done during the initial configuration, since changing this policy zeroizes the HSM as a security measure. For details, please refer to the Luna HSM vendor's documentation.

6.4.3. Verifying if FIPS Mode is Enabled on an HSM

This section describes how to verify if FIPS mode is enabled for certain HSMs. For other HSMs, see the hardware manufacturer's documentation.

6.4.3.1. Verifying if FIPS Mode is Enabled on an nCipher HSM

Note

Please refer to your HSM vendor’s documentation for the complete procedure.
To verify if the FIPS mode is enabled on an nCipher HSM, enter: 
# /opt/nfast/bin/nfkminfo
With older versions of the software, if the StrictFIPS140 is listed in the state flag, the FIPS mode is enabled. In newer vesions, it is however better to check the new mode line and look for fips1402level3. In all cases, there should also be an hkfips key present in the nfkminfo output.

6.4.3.2. Verifying if FIPS Mode is Enabled on a Luna SA HSM

Note

Please refer to your HSM vendor’s documentation for the complete procedure.
To verify if the FIPS mode is enabled on a Luna SA HSM:
  1. Open the lunash management console
  2. Use the hsm show command and verify that the output contains the text The HSM is in FIPS 140-2 approved operation mode.: 
    lunash:> hsm show
...
       FIPS 140-2 Operation:
       =====================
       The HSM is in FIPS 140-2 approved operation mode.
...

6.4.4. Preparing for Installing Certificate System with an HSM

In Section 7.3, “Understanding the pkispawn Utility”, you are instructed to use the following parameters in the configuration file you pass to the pkispawn utility when installing Certificate System with an HSM: 
...
[DEFAULT]
##########################
# Provide HSM parameters #
##########################
pki_hsm_enable=True
pki_hsm_libfile=hsm_libfile
pki_hsm_modulename=hsm_modulename
pki_token_name=hsm_token_name
pki_token_password=pki_token_password

########################################
# Provide PKI-specific HSM token names #
########################################
pki_audit_signing_token=hsm_token_name
pki_ssl_server_token=hsm_token_name
pki_subsystem_token=hsm_token_name
...
  • The values of the pki_hsm_libfile and pki_token_name parameter depend on your specific HSM installation. These values allow the pkispawn utility to set up your HSM and enable Certificate System to connect to it.
  • The value of the pki_token_password depends upon your particular HSM token's password. The password gives the pkispawn utility read and write permissions to create new keys on the HSM.
  • The value of the pki_hsm_modulename is a name used in later pkispawn operations to identify the HSM. The string is an identifier you can set as whatever you like. It allows pkispawn and Certificate System to refer to the HSM and configuration information by name in later operations.
The following section provides settings for individual HSMs. If your HSM is not listed, consult your HSM manufacturer's documentation.

6.4.4.1. nCipher HSM Parameters

For a nCipher HSM, set the following parameters: 
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.

Example 6.1. Identifying the Token Name

To identify the token name, run the following command as the root user: 
[root@example911 ~]# /opt/nfast/bin/nfkminfo
World
 generation  2

...~snip~...

Cardset
 name          "NHSM-CONN-XC"
 k-out-of-n    1/4
 flags         NotPersistent PINRecoveryRequired(enabled) !RemoteEnabled
 timeout       none

...~snip~...
The value of the name field in the Cardset section lists the token name.
Set the token name as follows: 
pki_token_name=NHSM-CONN-XC

6.4.4.2.  SafeNet / Luna SA HSM Parameters

For a SafeNet / Luna SA HSM, such as a SafeNet Luna Network HSM, specify the following parameters: 
pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
pki_hsm_modulename=lunasa
Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.

Example 6.2. Identifying the Token Name

To identify the token name, run the following command as the root user: 
# /usr/safenet/lunaclient/bin/vtl verify

The following Luna SA Slots/Partitions were found:

Slot    Serial #            Label
====    ================    =====
   0       1209461834772     lunasaQE
The value in the label column lists the token name.
Set the token name as follows: 
pki_token_name=lunasaQE

6.4.5. Backing up Keys on Hardware Security Modules

It is not possible to export keys and certificates stored on an HSM to a .p12 file. If such an instance is to be backed-up, contact the manufacturer of your HSM for support.