Chapter 8. Using Hardware Security Modules for Subsystem Security Databases

A subsystem instance generates and stores its key information in a key store, called a security module or a token. A subsystem instance can be configured for the keys to be generated and stored using the internal NSS token or on a separate cryptographic device, a hardware token.

8.1. Setting up HSMs for Storing Certificate System Subsystem Keys and Certificates

8.1.1. Types of Hardware Tokens

A token is a hardware or software device that performs cryptographic functions and stores public-key certificates, cryptographic keys, and other data. The Certificate System defines two types of tokens, internal and external, for storing key pairs and certificates that belong to the Certificate System subsystems.

8.1.1.1. Internal Tokens

An internal (software) token is a pair of files, usually called the certificate database and key database, that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System automatically generates these files in the filesystem of its host machine when pkicreate is run to create the subsystem instance.

In the Certificate System, the certificate database is named cert8.db; the key database is named key3.db. These files are located in the instanceID/alias directory.

8.1.1.2. External Tokens

An external token refers to an external hardware device, such as a smart card or hardware security module (HSM), that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System supports any hardware tokens that are compliant with PKCS #11.

NOTE

See your specific HSM vendor documentation for installation and configuration instructions for using the HSM.

PKCS #11 is a standard set of APIs and shared libraries which isolate an application from the details of the cryptographic device. This enables the application to provide a unified interface for PKCS #11-compliant cryptographic devices.

The PKCS #11 module implemented in the Certificate System supports cryptographic devices supplied by many different manufacturers. This module allows the Certificate System to plug in shared libraries supplied by manufacturers of external encryption devices and use them for generating and storing keys and certificates for the Certificate System managers.

Consider using external tokens for generating and storing the key pairs and certificates used by Certificate System. These devices are another security measure to safeguard private keys because hardware tokens are sometimes considered more secure than software tokens.

Before using external tokens, plan how the external token is going to be used with the subsystem:

All system keys for a subsystem must be generated on the same token.
The subsystem keys must be installed in an empty HSM slot. If the HSM slot has previously been used to store other keys, then use the HSM vendor's utilities to delete the contents of the slot. The Certificate System has to be able to create certificates and keys on the slot with default nicknames. If not properly cleaned up, the names of these objects may collide with previous instances.
A single HSM can be used to store certificates and keys for mulitple subsystem instances, which may be installed on multiple hosts. When an HSM is used, any certificate nickname for a subsystem must be unique for every subsystem instance managed on the HSM.

The Certificate System automatically discovers Safenet's LunaSA and nCipher's netHSM hardware security modules. The discovery process assumes that the client software installations for these modules are local to the Certificate System subsystem and are in the following locations:

LunaSA: /usr/lunasa/lib/libCryptoki2.so
LunaSA: /usr/lunasa/lib/libCryptoki2_64.so
nCipher: /opt/nfast/toolkits/pkcs11/libcknfast.so

8.1.1.3. Hardware Cryptographic Accelerators

The Certificate System can use hardware cryptographic accelerators with external tokens. Many of the accelerators provide the following security features:

Fast SSL connections. Speed is important to accommodate a high number of simultaneous enrollment or service requests.
Hardware protection of private keys. These devices behave like smart cards by not allowing private keys to be copied or removed from the hardware token. This is important as a precaution against key theft from an active attack of an online Certificate Manager.

8.1.2. Using Hardware Security Modules with Subsystems

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

During configuration, the Key Store panel displays the supported modules, along with the NSS internal software PKCS #11 module. All supported modules that are detected show a status of Found and is individually marked as either Logged in or Not logged in. If a token is found but not logged in, it is possible to log in using the Login under Operations. If the administrator can log into a token successfully, the password is stored in a configuration file. At the next start or restart of the Certificate System instance, the passwords in the password store are used to attempt a login for each corresponding token.

Administrators are allowed to select any of the tokens that are logged in as the default token, which is used to generate system keys.

IMPORTANT

For information on configuring FIPS mode, see the hardware vendor documentation.

8.1.2.1. Adding or Managing the HSM Entry for a Subsystem

When an HSM is selected as the default token, some parameters are added to instance's CS.cfg file to configure the HSM. For example:

#RHCS supported modules
preop.configModules.module0.commonName=NSS Internal PKCS #11 Module
preop.configModules.module0.imagePath=../img/mozilla.png
preop.configModules.module0.userFriendlyName=NSS Internal PKCS #11 Module
preop.configModules.module1.commonName=nfast
preop.configModules.module1.imagePath=../img/ncipher.png
preop.configModules.module1.userFriendlyName=nCipher's nFast Token Hardware Module
preop.configModules.module2.commonName=lunasa
preop.configModules.module2.imagePath=../img/safenet.png
preop.configModules.module2.userFriendlyName=SafeNet's LunaSA Token Hardware Module
#selected token
preop.module.token=Internal Key Storage Token

In addition, a parameter is added to the password.conf file for the HSM password. For example:

hardware-nethsm=caPassword

8.1.2.2. Using Chrysalis LunaSA HSM

To make sure that a LunaSA HSM works with Certificate System, edit the configuration files for the HSM before configuring the subsystems:

Check that the LunaSA module has been properly installed:

modutil -dbdir /var/lib/instance_name/alias -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/lunasa/lib/libCryptoki2_64.so
         slots: 1 slot attached
        status: loaded

         slot: LunaNet Slot
        token: lunasa3-ca

If the LunaSA module isn't listed, then install the module manually:

Stop the subsystem.
```
service instance_name stop
```

Load the module.

modutil -dbdir /var/lib/instance_name/alias -nocertdb -add lunasa -libfile /usr/lunasa/lib/libCryptoki2_64.so

Verify that the module has been loaded.

modutil -dbdir /var/lib/instance_name/alias -list

Start the subsystem.
```
service instance_name start
```

Open the /etc/Chrystoki.conf configuration file.
Add this configuration parameter.
```
Misc { NetscapeCustomize=1023; }
```
If they are there, remove these two configuration lines for the applet version.
```
AppIdMajor=2;
AppIdMinor=4;
```

Then, after going through the subsystem configuration, but before restarting the server when completing the configuration wizard, edit the subsystem configuration to recognize the token:

Stop the server.
```
service instance_name stop
```
Edit the instance's serverCertNick.conf file in the /var/lib/instance_name/conf directory. Add the HSM token name to the serverCert parameter.
The original value only points to the server:
```
Server-Cert instanceID
```
The new value includes a reference to the LunaSA HSM:
```
lunasa3-ca:Server-Cert instanceID
```
Start the server.
```
service instance_name start
```

8.1.2.3. Installing External Tokens and Unsupported HSM

To use HSMs which are not officially supported by the Certificate System, add the module to the subsystem database manually. If the desired HSM does not appear in the Security Modules panel during the subsystem configuration, check that the HSM is installed and activated correctly. Then run modutil manually to add the module to the secmod.db database.

Install the cryptographic device, using the manufacturer's instructions. Be sure to name the token something that will help identify it easily later.
Install the PKCS #11 module using the modutil command-line utility.
1. Open the alias directory for the subsystem which is being configured with the PKCS #11 module. For example:
```
cd /var/lib/pki-ca/alias
```
2. The required security module database file, secmod.db, should be created by default when the subsystem is created. If it does not exist, use the modutil utility to create secmod.db.
```
modutil -dbdir . -nocertdb -create
```
3. Use the modutil utility to set the library information.
```
modutil -dbdir . -nocertdb /  -add module_name -libfile library_file
```
  library_file specifies the path to the library file containing the PKCS #11 interface module and module_name gives the name of the PKCS #11 module which was set when the drivers were installed.
  - For the LunaSA HSM, the library can be /usr/lunasa/lib/libCryptoki2_64.so or /usr/lunasa/lib/libCryptoki2.so:
    modutil -dbdir . -nocertdb -add lunasa -libfile /usr/lunasa/lib/libCryptoki2.so
  - For an nCipher HSM:
    modutil -dbdir . -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/libcknfast.so

IMPORTANT

To enable FIPS mode on an nCipher HSM, open the security UI:

/opt/nfast/bin/ksafe

In the 'Security World' tab, make sure that "Strict FIPS 140-2 Level III" is set to 'yes'.

For more information on configuring FIPS mode, see the hardware vendor documentation.

8.1.2.4. Setting up SELinux on nCiper netHSM 2000

SELinux policies are created and configured automatically for all Certificate System instances, so Certificate System can run with SELinux in enforcing or permissive modes.

If SELinux is in enforcing mode, then any hardware tokens to be used with the Certificate System instances must also be configured to run with SELinux in enforcing mode, or the HSM will not be available during subsystem installation.

IMPORTANT

SELinux must be configured for the HSM before installing any Certificate System instances.

Install the SELinux packages for Certificate System.
```
yum install pki-selinux
```
Reset the context of files in /dev/nfast and /opt/nfast to match the newly-installed policy.
```
/sbin/restorecon -R /dev/nfast
/sbin/restorecon -R /opt/nfast
```
Restart the netHSM software.

8.1.3. Viewing Tokens

To view a list of the tokens currently installed for a Certificate System instance, use the modutil utility.

Open the instance alias directory. For example:
```
cd /var/lib/pki-ca/alias
```
Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the modutil tool.
```
modutil -dbdir . -nocertdb -list
```

8.1.4. Detecting Tokens

To see if a token can be detected by Certificate System, use the TokenInfo utility, pointing to the alias directory for the subsystem instance. This is a Certificate System tool which is available after the Certificate System packages are installed.

For example:

TokenInfo /var/lib/pki-ca/alias

This utility will return all tokens which can be detected by the Certificate System, not only tokens which are installed in the Certificate System.