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 nCipher HSM

To enable FIPS mode on an nCipher HSM:
  1. Open the security UI:
    # /opt/nfast/bin/ksafe
  2. In the Security World tab, select Strict FIPS 140-2 Level III.
  3. Click yes to confirm.
  4. Optionally, verify that FIPS mode is enabled. For details, see Section 8.2.2, “Verifying if FIPS Mode is Enabled on an nCipher HSM”.
For further details on configuring FIPS mode, see the hardware vendor documentation.

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

To verify if the FIPS mode is enabled on an nCipher HSM, enter:
# /opt/nfast/bin/nfkminfo
If the StrictFIPS140 is listed in the state flag, the FIPS mode is enabled.

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.6, “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                                        ##
##                                                                           ##
###############################################################################
###############################################################################
###############################################################################