Red Hat Training

A Red Hat training course is available for Red Hat Directory Server

9.3. Managing the NSS Database Used by Directory Server

When you set up TLS encryption or certificate-based authentication, you must manage the certificates which are stored in a Network Security Services (NSS). This section describes the most frequent actions about managing the Directory Server's NSS database.

9.3.1. Creating the NSS Database for a Directory Server Instance

Directory Server stores the certificates in an NSS database in the /etc/dirsrv/slapd-instance_name/ directory. Before you can manage the certificates, you must create the database.

Note

For security reasons, Red Hat recommends setting a strong password on the database.

9.3.1.1. Creating the NSS Database Using the Command Line

To create the NSS database using the command line:
  1. Create the NSS database and set a password: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -N
Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

Enter new password:
Re-enter password:
  2. Set the permissions: 
    # chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/*.db
# chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/pkcs11.txt
# chmod 600 /etc/dirsrv/slapd-instance_name/*.db
# chmod 600 /etc/dirsrv/slapd-instance_name/pkcs11.txt

9.3.1.2. Creating the NSS Database Using the Console

Directory Server automatically creates the NSS database when you open the Manage Certificates task entry in the Directory Server Console the first time.
To open the Manage Certificates task entry:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates, and set a password to protect the database.

9.3.2. Creating a Certificate Signing Request

The Certificate Signing Request (CSR) is a request to the Certificate Authority (CA) to sign the key of the server. This section describes how to create the CSR including the private key.

9.3.2.1. Creating a Certificate Signing Request Using the Command Line

To create the key and a CSR, use the certutil utility: 
# certutil -d instance_directory -R -g key_size -a \
     -o output_file -8 FQDN -s "certificate_subject"

Example 9.1. Creating a Private Key and CSR for a Single Host Name

The following command generates a 4096 bit private key for the server.example.com host and stores the CSR in the /root/instance_name.csr file: 
# certutil -d /etc/dirsrv/slapd-instance_name/ -R -g 4096 -a \
     -o /root/instance_name.csr -8 server.example.com \
     -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
The -8 server.example.com option adds the subject alternative name (SAN) extension with the DNS:server.example.com entry to the CSR. The string specified in the -s parameter must be a valid subject name according to RFC 1485. The CN field is required, and you must set it to the Fully Qualified Domain Name (FQDN) of the server. The other fields are optional.

Example 9.2. Creating a Private Key and CSR for a Multi-homed Host

If a Directory Server host has multiple names, create a CSR with all host names in the SAN extension of the CSR. The following command generates a 4096 bit private key and a CSR for the server.example.com and server.example.net host names. The command stores the CSR in the /root/instance_name.csr file. 
# certutil -d /etc/dirsrv/slapd-instance_name/ -R -g 4096 -a \
     -o /root/instance_name.csr -8 server.example.com,server.example.net \
     -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
The -8 server.example.com,server.example.net option adds the SAN extension with the DNS:server.example.com, DNS:server.example.net entries to the CSR. The string specified in the -s parameter must be a valid subject name according to RFC 1485. The CN field is required, and you must set it to one of the FQDNs of the server. The other fields are optional.
For further details about certutil and extended usage information, see the certutil(1) man page.
After you have generated the CSR, submit it to the CA to get a certificate issued. For further details, see your CA's documentation.

9.3.2.2. Creating a Certificate Signing Request Using the Console

To create the keys and a CSR using the Console:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates.
  3. On the Server Certs tab, click the Request button.
  4. Select if you want to request the certificate manually or from one of the displayed CAs and click Next.
  5. Enter the requested information and click Next.

    Important

    Enter the Fully-qualified Domain Name (FQDN) of the server into the Server name field.
  6. Select the key size and signing algorithm. Click Next.
    For security reasons:
    • an RSA key size of 2048 bits or higher
    • a strong signing algorithm, such as SHA-256 or higher
  7. Enter the password of the Network Security Services (NSS) database and click Done.
    If you use an Hardware Security Module (HSM) to store the certificates, the device is plugged in, and the module has been installed as described in Section 9.7, “Using Hardware Security Modules”, then the module is available in the Active Encryption Token menu.
  8. Copy the CSR to the clipboard or save it into a file.
  9. Click Done.
After you generated the CSR, submit it to the CA to get a certificate issued. For further details, see your CA's documentation.

9.3.3. Installing a CA Certificate

To enable Directory Server to trust the Certificate Authority (CA) you must install the certificate of the CA into the Network Security Services (NSS) database. During this process, you must set which certificates issued by the CA should be trusted:

Table 9.1. CA Trust Options

Console Option certutil Option Description
Accepting connections from clients (Client Authentication) T,, The server trusts this CA certificate for issuing client certificates suitable for TLS EXTERNAL binds.
Accepting connections to other servers (Server Authentication) C,, The server verifies that certificates, used to establish an encrypted connection to a replication partner, have been issued by a trusted CA.
You can set both options for a CA. When you use certutil, pass the -T "CT,," parameter to the utility.

9.3.3.1. Installing a CA Certificate Using the Command Line

To install a CA certificate in the Directory Server's NSS database, use the certutil utility. For example, to import the CA certificate stored in the /etc/pki/CA/nss/ca.crt file: 
# certutil -d /etc/dirsrv/slapd-instance_name/ -A -n "certificate_nickname" \
     -t "C,," -i /etc/pki/CA/nss/ca.crt
The -t trust_options parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
For further details about the parameters used in the previous command, see the certutil(1) man page.

9.3.3.2. Installing a CA Certificate Using the Console

To install a CA certificate using the Directory Server Console:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates.
  3. Select the CA Certs tab and click the Install button.
  4. Either select the file that contains the server certificate or paste the certificate into the field. Click Next.
  5. Verify the certificate details and click Next.
  6. Verify the certificate nickname and click Next.
  7. Set which certificates issued by the CA should be trusted. You can select one or both of the options. See Table 9.1, “CA Trust Options”.

9.3.4. Installing a Certificate

After the Certificate Authority (CA) issued the requested certificate, you must install it in the Network Security Services (NSS) database.

9.3.4.1. Installing a Server Certificate Using the Command Line

To install a server certificate in the Directory Server's NSS database, use the certutil utility. For example:
  1. Install the CA certificate. See Section 9.3.3, “Installing a CA Certificate”.
  2. Import the certificate. For example to import the certificate stored in the /root/instance_name.crt file: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -A \
     -n "server-cert" -t ",," -a -i /root/instance_name.crt
  3. Optionally, verify the certificate: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -V -n "server-cert" -u V
For further details about the parameters used in the previous certutil commands, see the certutil(1) man page.

9.3.4.2. Installing a Certificate Using the Console

To install a server certificate using the Console:
  1. Install the CA certificate. See Section 9.3.3, “Installing a CA Certificate”.
  2. Open the Directory Server Console.
  3. On the Tasks tab, click Manage Certificates.
  4. Click the Install button.
  5. Select the file that contains the server certificate or, alternatively, paste the certificate into the field. Click Next.
  6. Verify the certificate details and click Next.
  7. Set a certificate nickname and click Next.

    Note

    The Directory Server Console does not support installing a certificate that uses the same nickname as an existing one. To work around the problem, install the certificate using the command line. See Section 9.3.4.1, “Installing a Server Certificate Using the Command Line”.
  8. Enter the password of the NSS database and click Done.

9.3.5. Generating and Installing a Self-signed Certificate

In certain situations, administrators want to use a self-signed certificate for encrypted connections to Directory Server.

Note

You can only perform this operation using the command line.
To create and install a self-signed certificate:
  1. Verify if the Network Security Services (NSS) database is already initialized: 
    # certutil -d /etc/dirsrv/slapd-instance_name -L
    If the command fails, initalize the database. For details, see Section 9.3.1, “Creating the NSS Database for a Directory Server Instance”.
  2. Generate a noise file with random data. For example, to generate a file with a size of 4096 bits: 
    # openssl rand -out /tmp/noise.bin 4096
  3. Create the self-signed certificate and add it to the NSS database: 
    # certutil -S -x -d /etc/dirsrv/slapd-instance_name/ -z /tmp/noise.bin \
     -n "server-cert" -s "CN=$HOSTNAME" -t "CT,C,C" -m $RANDOM \
     --keyUsage digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
    Red Hat Enterprise Linux automatically replaces the $HOSTNAME variable with the Fully Qualified Domain Name (FQDN) and $RANDOM with a randomly-generated number. For further details about the parameters used in the previous commands, see the certutil(1) man page.
  4. Optionally, verify that the generated certificate is self-signed: 
    # certutil -L -d /etc/dirsrv/slapd-instance_name/ -n "server-cert" | egrep "Issuer|Subject"
        Issuer: "CN=server.example.com"
        Subject: "CN=server.example.com"
    The output of this command must display the FQDN of the Directory Server host for both the issuer and subject of the certificate.

9.3.6. Renewing a Certificate

If a certificate will expire in the near future, you must renew it in time to continue establishing secure connections.

9.3.6.1. Renewing a Certificate Using the Command Line

To renew a certificate:
  1. Create a new Certificate Signing Request (CSR) with the same options, such as key size, host name, and subject. For details about creating a CSR, see Section 9.3.2.1, “Creating a Certificate Signing Request Using the Command Line”
  2. After you received the issued certificate from your CA, install it in the database using the same nickname. See Section 9.3.3.1, “Installing a CA Certificate Using the Command Line”.
Directory Server will automatically use the newer issued certificate.

9.3.6.2. Renewing a Certificate Using the Console

The process for renewing is similar to generating a Certificate Signing Request (CSR). Follow the procedure in Section 9.3.3.2, “Installing a CA Certificate Using the Console”, but click the Renew instead of the Request button in the Manage Certificates task.

9.3.7. Removing a Certificate

If a certificate is no longer needed, for example, because it has been exposed, remove it from the database.

9.3.7.1. Removing a Certificate Using the Command Line

To remove a certificate using the command line:
  1. Remove the private key. See Section 9.3.8, “Removing a Private Key”.
  2. Optionally, display the certificates in the database: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -L
Certificate Nickname                     Trust Attributes
                                         SSL,S/MIME,JAR/XPI

Example CA                               CT,,
server-cert                              u,u,u
  3. Remove the certificate. For example, to remove the certificate with the server-cert nickname: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -D -n "server-cert"

9.3.7.2. Removing a Certificate Using the Console

To remove a certificate using the Console:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates.
  3. On the Server Certs tab, select the certificate and click the Delete button.
  4. Click Yes to confirm.

9.3.8. Removing a Private Key

If a private key is no longer needed, for example, because you created a stronger key, remove it from the database.

Warning

If you remove a private key, certificates based on this key are no longer working.

9.3.8.1. Removing a Private Key Using the Command Line

To remove a private key:
  1. Remove all certificates based on the key you want to delete. See Section 9.3.7, “Removing a Certificate”.
  2. Optionally, display the keys in the database: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -K
certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services"
Enter Password or Pin for "NSS Certificate DB":
< 0> rsa      7a2fb6c269d83c4036eac7e4edb6aaf2ed08bc4a   server-cert
< 1> rsa      662b826aa3dd4ca7fd7e6883558cf3866c42f4e2   example-cert
  3. Remove the private key. For example, to remove the private key with the example-cert nickname: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -F -n "example-cert"

9.3.8.2. Removing a Private Key Using the Console

Removing a private key using the Console is not supported. However, if you request a new certificate using the Console according to Section 9.3.2.2, “Creating a Certificate Signing Request Using the Console”, the Console automatically generates a new private key and uses it.

9.3.9. Changing the CA Trust Options

In certain situations you need to update the trust option of a Certificate Authority (CA). This section describes this procedure.

9.3.9.1. Changing the CA Trust Options Using the Command Line

To change the trust options of a CA, pass the new options in the -t parameter to the certutil utility.
For example, to set that Directory Server trusts only client authentication certificates issued by the CA named example-CA: 
# certutil -d /etc/dirsrv/slapd-instance_name/ -M -t "T,," -n "example-CA"
The -t trust_options parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
For further details about the parameters and trust options, see the certutil(1) man page.

9.3.9.2. Changing the CA Trust Options Using the Console

To change the trust options of a CA using the Console:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates.
  3. Select the CA Certs tab.
  4. Select the CA to edit, click the Edit Trust button, and set which certificates issued by the CA should be trusted. You can select one or both of the options. See Table 9.1, “CA Trust Options”.

9.3.10. Changing the Password of the NSS Database

In certain situations, administrators want to change the password of the Network Security Services (NSS) database. This section describes this process.

Important

If you use a password file to enable Directory Server to automatically open the Network Security Services (NSS) database, you must update the file after you set the new password. See Section 9.4.1.5, “Creating a Password File for Directory Server”.

9.3.10.1. Changing the Password of the NSS Database Using the Command Line

To change the password of the NSS database: 
# certutil -d /etc/dirsrv/slapd-instance_name -W
Enter Password or Pin for "NSS Certificate DB":
Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

Enter new password: 
Re-enter password: 
Password changed successfully.

9.3.10.2. Changing the Password of the NSS Database Using the Console

To change the password of the NSS database using the Console:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates.
  3. Click the Change Password button.
  4. Enter the current and the new password and click OK

9.3.11. Adding a Certificate Revocation List

If a Certificate Authority (CA) revokes a certificate, the CA adds the certificate to its Certificate Revocation Lists (CRL). Directory Server can use this list to identify which certificates are no longer trusted by the CA and to deny access.

9.3.11.1. Adding a Certificate Revocation List Using the Command Line

To add a CRL using certutil, pass the -4 URL_to_CRL_file parameter to the utility when you install the CA certificate.
For details about installing a CA certificate, see Section 9.3.3.1, “Installing a CA Certificate Using the Command Line”.

9.3.11.2. Adding a Certificate Revocation List Using the Console

To add a CRL using the Console:
  1. Open the Directory Server Console.
  2. On the Tasks tab, click Manage Certificates.
  3. Select the Revoked Certs tab and click the Add button.
  4. Enter the path to the file, select the list format, and click OK.