8.2. Using Hardware Security Modules with Subsystems

The Certificate System supports the nCipher nShield hardware security module (HSM) and Gemalto Safenet LunaSA HSM by default. Certificate System-supported HSMs are automatically added to the secmod.db database with the modutil command during the pre-configuration stage of the installation, if the PKCS #11 library modules are in the specified installation paths.

Important

Certain deployments require to setup their HSM to use FIPS mode.

8.2.1. Enabling the 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.

8.2.2. 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.

8.2.2.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.

8.2.2.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.
...

8.2.3. Adding or Managing the HSM Entry for a Subsystem

During installation, when an HSM is selected as the default token where appropriate HSM-specific parameters are set in the configuration file passed to the pkispawn command, the following parameter is added to the /var/lib/pki/instance_name/conf/password.conf file for the HSM password: 
hardware-HSM_token_name=HSM_token_password

8.2.4. Setting up SELinux for an HSM

If you want to install Certificate System with an Hardware Security Modules (HSM) and SELinux is running in enforcing mode, 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
Gemalto Safenet LunaSA HSM
No SELinux-related actions are required before you start installing Certificate System.

8.2.5. Installing a Subsystem Using nCipher nShield HSM

To install a subsystem instance that use nCipher nShield HSM, follow this procedure:
  1. Prepare an override file, which corresponds to your particular deployment. The following default_hms.txt file is an example of such an override file:

    Note

    This file serves only as an example of an nCipher HSM override configuration file -- numerous other values can be overridden including default hashing algorithms. Also, only one of the [CA], [KRA], [OCSP], [TKS], or [TPS] sections will be utilized depending upon the subsystem invocation specified on the pkispawn command-line.

    Example 8.1. An Override File Sample to Use with nCipher HSM

    
###############################################################################
###############################################################################
###############################################################################
##                                                                           ##
## EXAMPLE: Configuration File used to override '/etc/pki/default.cfg'       ##
##          when using an nCipher Hardware Security Module (HSM):            ##
##                                                                           ##
##                                                                           ##
##     # modutil -dbdir . -list                                              ##
##                                                                           ##
##     Listing of PKCS #11 Modules                                           ##
##     -----------------------------------------------------------           ##
##       1. NSS Internal PKCS #11 Module                                     ##
##              slots: 2 slots attached                                      ##
##             status: loaded                                                ##
##                                                                           ##
##              slot: NSS Internal Cryptographic Services                    ##
##             token: NSS Generic Crypto Services                            ##
##                                                                           ##
##              slot: NSS User Private Key and Certificate Services          ##
##             token: NSS Certificate DB                                     ##
##                                                                           ##
##      2. nfast                                                             ##
##            library name: /opt/nfast/toolkits/pkcs11/libcknfast.so         ##
##             slots: 2 slots attached                                       ##
##            status: loaded                                                 ##
##                                                                           ##
##             slot: <serial_number> Rt1                                     ##
##            token: accelerator                                             ##
##                                                                           ##
##             slot: <serial_number> Rt1 slot 0                              ##
##            token: <HSM_token_name>                                        ##
##     -----------------------------------------------------------           ##
##                                                                           ##
##                                                                           ##
##     Based on the example above, substitute all password values,           ##
##     as well as the following values:                                      ##
##                                                                           ##
##         <hsm_libfile>=/opt/nfast/toolkits/pkcs11/libcknfast.so            ##
##         <hsm_modulename>=nfast                                            ##
##         <hsm_token_name>=NHSM6000                                         ##
##                                                                           ##
###############################################################################
###############################################################################
###############################################################################

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

##################################
# Provide PKI-specific passwords #
##################################
pki_admin_password=<pki_admin_password>
pki_client_pkcs12_password=<pki_client_pkcs12_password>
pki_ds_password=<pki_ds_password>

#####################################
# Provide non-CA-specific passwords #
#####################################
pki_client_database_password=<pki_client_database_password>

###############################################################
# ONLY required if specifying a non-default PKI instance name #
###############################################################
#pki_instance_name=<pki_instance_name>

##############################################################
# ONLY required if specifying non-default PKI instance ports #
##############################################################
#pki_http_port=<pki_http_port>
#pki_https_port=<pki_https_port>

######################################################################
# ONLY required if specifying non-default 389 Directory Server ports #
######################################################################
#pki_ds_ldap_port=<pki_ds_ldap_port>
#pki_ds_ldaps_port=<pki_ds_ldaps_port>

######################################################################
# ONLY required if PKI is using a Security Domain on a remote system #
######################################################################
#pki_ca_hostname=<pki_ca_hostname>
#pki_issuing_ca_hostname=<pki_issuing_ca_hostname>
#pki_issuing_ca_https_port=<pki_issuing_ca_https_port>
#pki_security_domain_hostname=<pki_security_domain_hostname>
#pki_security_domain_https_port=<pki_security_domain_https_port>

###########################################################
# ONLY required for PKI using an existing Security Domain #
###########################################################
# NOTE:  pki_security_domain_password == pki_admin_password
#        of CA Security Domain Instance
#pki_security_domain_password=<pki_admin_password>


[Tomcat]
##############################################################
# ONLY required if specifying non-default PKI instance ports #
##############################################################
#pki_ajp_port=<pki_ajp_port>
#pki_tomcat_server_port=<pki_tomcat_server_port>


[CA]
#######################################
# Provide CA-specific HSM token names #
#######################################
pki_ca_signing_token=<hsm_token_name>
pki_ocsp_signing_token=<hsm_token_name>

###########################################################################
# ONLY required if 389 Directory Server for CA resides on a remote system #
###########################################################################
#pki_ds_hostname=<389 hostname>


[KRA]
########################################
# Provide KRA-specific HSM token names #
########################################
pki_storage_token=<hsm_token_name>
pki_transport_token=<hsm_token_name>

############################################################################
# ONLY required if 389 Directory Server for KRA resides on a remote system #
############################################################################
#pki_ds_hostname=<389 hostname>


[OCSP]
#########################################
# Provide OCSP-specific HSM token names #
#########################################
pki_ocsp_signing_token=<hsm_token_name>

#############################################################################
# ONLY required if 389 Directory Server for OCSP resides on a remote system #
#############################################################################
#pki_ds_hostname=<389 hostname>


[TKS]
########################################
# Provide TKS-specific HSM token names #
########################################

############################################################################
# ONLY required if 389 Directory Server for TKS resides on a remote system #
############################################################################
#pki_ds_hostname=<389 hostname>


[TPS]
###################################
# Provide TPS-specific parameters #
###################################
pki_authdb_basedn=<dnsdomainname where hostname.b.c.d is dc=b,dc=c,dc=d>

########################################
# Provide TPS-specific HSM token names #
########################################

############################################################################
# ONLY required if 389 Directory Server for TPS resides on a remote system #
############################################################################
#pki_ds_hostname=<389 hostname>

##########################################################
# ONLY required if TPS requires a CA on a remote machine #
##########################################################
#pki_ca_uri=https://<pki_ca_hostname>:<pki_ca_https_port>

#######################################
# ONLY required if TPS requires a KRA #
#######################################
#pki_enable_server_side_keygen=True

###########################################################
# ONLY required if TPS requires a KRA on a remote machine #
###########################################################
#pki_kra_uri=https://<pki_kra_hostname>:<pki_kra_https_port>

###########################################################
# ONLY required if TPS requires a TKS on a remote machine #
###########################################################
#pki_tks_uri=https://<pki_tks_hostname>:<pki_tks_https_port>
  2. Use the configuration file as described in Section 7.7, “Two-step Installation”. 
    • # pkispawn -s CA -f ./default_hsm.txt -vvv
    • # pkispawn -s KRA -f ./default_hsm.txt -vvv
    • # pkispawn -s OCSP -f ./default_hsm.txt -vvv
    • # pkispawn -s TKS -f ./default_hsm.txt -vvv
    • # pkispawn -s TPS -f ./default_hsm.txt -vvv

8.2.6. Installing a Subsystem Using Gemalto Safenet LunaSA HSM

To install a subsystem instance that use Gemalto Safenet LunaSA HSM, follow the procedure detailed in Section 8.2.5, “Installing a Subsystem Using nCipher nShield HSM”. The override file should be similar to the sample provided in Example 8.1, “An Override File Sample to Use with nCipher HSM”, differing in values related to the particular deployment. The following example provides a sample LunaSA header that is to be substituted for the header of the nCipher override file and to be used with the [DEFAULT], [Tomcat], [CA], [KRA], [OCSP], [TKS], and [TPS] sections provided in the aforementioned nCipher example.

Example 8.2. A Sample of the LunaSA Override File Header


###############################################################################
###############################################################################
###############################################################################
##                                                                           ##
## EXAMPLE: Configuration File used to override '/etc/pki/default.cfg'       ##
##          when using a LunaSA Hardware Security Module (HSM):              ##
##                                                                           ##
##                                                                           ##
##     # modutil -dbdir . -list                                              ##
##                                                                           ##
##     Listing of PKCS #11 Modules                                           ##
##     -----------------------------------------------------------           ##
##       1. NSS Internal PKCS #11 Module                                     ##
##              slots: 2 slots attached                                      ##
##             status: loaded                                                ##
##                                                                           ##
##              slot: NSS Internal Cryptographic Services                    ##
##             token: NSS Generic Crypto Services                            ##
##                                                                           ##
##              slot: NSS User Private Key and Certificate Services          ##
##             token: NSS Certificate DB                                     ##
##                                                                           ##
##      2. lunasa                                                            ##
##            library name: /usr/safenet/lunaclient/lib/libCryptoki2_64.so   ##
##             slots: 4 slots attached                                       ##
##            status: loaded                                                 ##
##                                                                           ##
##             slot: LunaNet Slot                                            ##
##            token: dev-intca                                               ##
##                                                                           ##
##             slot: Luna UHD Slot                                           ##
##            token:                                                         ##
##                                                                           ##
##             slot: Luna UHD Slot                                           ##
##            token:                                                         ##
##                                                                           ##
##             slot: Luna UHD Slot                                           ##
##            token:                                                         ##
##     -----------------------------------------------------------           ##
##                                                                           ##
##                                                                           ##
##     Based on the example above, substitute all password values,           ##
##     as well as the following values:                                      ##
##                                                                           ##
##         <hsm_libfile>=/usr/safenet/lunaclient/lib/libCryptoki2_64.so      ##
##         <hsm_modulename>=lunasa                                           ##
##         <hsm_token_name>=dev-intca                                        ##
##                                                                           ##
###############################################################################
###############################################################################
###############################################################################