7.8. Using Hardware Security Modules

A security module serves as a medium between the Directory Server and the SSL layer. The module stores the keys and certificates used for encryption and decryption. The standard which defines these modules is Public Key Cryptography Standard (PKCS) #11, so these modules are PKCS#11 modules.
By default, Directory Server uses built-in security databases, key3.db and cert8.db, to store the keys and certificates used by the servers.
It is also possible to use external security devices to store Directory Server certificates and keys. For Directory Server to use an external PKCS#11 module, the module's drivers must be installed in Directory Server.

Note

It is possible to install PKCS #11 modules through the Directory Server Console, but it is recommended that administrators use the command line to add modules. Because of differences in the way manufacturers implement their modules, some modules (such as nCipher external tokens) must be loaded through the command line rather than the Directory Server Console. For all modules, using the command line is an easier, more effective way to add modules.

7.8.1. Installing PKCS#11 Modules Through the Command Line

Installing PKCS#11 modules through the command line requires the NSS modutil tool.
  1. Connect the external security device, and install its drivers on the server machine.
  2. Use the -add and -libfile arguments with modutil to load the PKCS#11 module and it associated libraries. The module_name is the name of the module given when the security device's drivers were installed; the library_file is the full path to the module's library. 
    [root@server ~]# modutil -dbdir /etc/dirsrv/slapd-instance_name/ -nocertdb -add module_name -libfile library_file
    For example, for an nCipher hardware security module: 
    [root@server ~]# modutil -dbdir /etc/dirsrv/slapd-instance_name/ -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/libcknfast.so
  3. List the loaded modules to make sure that the new PKCS#11 module was added correctly. 
    [root@server ~]# modutil -list -dbdir /etc/dirsrv/slapd-instance_name/

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. nCipher NetHSM PKCS #11 Module
         slots: 2 slots attached
        status: loaded

         slot: nethsm external cryptographic services
        token: nethsm crypto services

         slot: nethsm user private key and certificate services
        token: nethsm certificate db
-----------------------------------------------------------

7.8.2. Adding Certificates to an HSM

All of the certificates required for secure connections must be imported into the HSM. Because of SELinux requirements, the best method to import certificates into the Directory Server databases is using the certutil command.
At a minimum, you will need to import the Directory Server and Admin Server server certificates, as well as the CA certificate for the CA which issued those certificates. If there are other certificates used by the Directory Server or Admin Server, then those must also be imported.
For example: 
certutil -A -d /etc/dirsrv/slapd-instance_name -n "CA certificate" -t "CT,," -a -i /tmp/cacert.asc

certutil -A -d /etc/dirsrv/slapd-instance_name -n "Server-Cert" -t "u,u,u" -a -i /tmp/cert.asc
certutil is described more in Section 7.6, “Using certutil”.

7.8.3. Setting SELinux Policies for HSMs

In most situations, it will be necessary to create an SELinux policy module to allow the Directory Server to use the certificates stored in the HSM. However, the requirements for writing those policies are different depending on the vendor and model of the HSM.
For a basic primer in writing SELinux policies, see Dan Walsh's article on writing SELinux modules. The Red Hat Enterprise Linux documentation contains information on troubleshooting policy problems in the SELinux Guide. For additional help with writing HSM-related policies, contact Red Hat support.