7.3. Managing Certificates Used by the Directory Server

7.3.1. Obtaining and Installing Server Certificates

Before the Directory Server can be set to run in TLS/SSL, server and CA certificates must be properly configured in the Directory Server. If a server certificate has already been generated for the Directory Server instance and the issuing certificate authority (CA) is already trusted by the Directory Server, begin setting up TLS/SSL as described in Section 7.4, “Setting up TLS/SSL”.
Obtaining and installing certificates consists of the following steps:
  1. Generate a certificate request.
  2. Send the certificate request to a certificate authority.
  3. Install the server certificate.
  4. Set the Directory Server to trust the certificate authority.
  5. Confirm that the certificates are installed.
Two wizards automate the process of creating a certificate database and of installing the key-pair. The Certificate Request Wizard in the Directory Server Console can generate a certificate request and send it to a certificate authority. The Certificate Install Wizard in the Directory Server Console can then install the server certificate and the CA certificate.

7.3.1.1. Generating a Certificate Request

Generate a certificate request, and send it to a CA. The Directory Server Console has a tool, the Certificate Request Wizard, which generates a valid certificate request to submit to any certificate authority (CA).
  1. Select the Tasks tab, and click Manage Certificates.
  2. Select the Server Certs tab, and click the Request button.
  3. Enter the Requester Information in the blank text fields, then click Next.
    • Server Name. Enter the fully qualified host name of the Directory Server as it is used in DNS and reverse DNS lookups; for example, dir.example.com. The server name is critical for client-side validation to work, which prevents man-in-the-middle attacks.
    • Organization. Enter the legal name of the company or institution. Most CAs require this information to be verified with legal documents such as a copy of a business license.
    • Organizational Unit. Optional. Enter a descriptive name for the organization within the company.
    • Locality. Optional. Enter the company's city name.
    • State or Province. Enter the full name of the company's state or province (no abbreviations).
    • Country. Select the two-character abbreviation for the country's name (ISO format). The country code for the United States is US.
  4. If an external security device is to be used to store the Directory Server certificates, the device is plugged in, and the module has been installed as described in Section 7.8, “Using Hardware Security Modules”, then the module is available in the Active Encryption Token menu. The default is to use the software databases with Directory Server, internal (software).
  5. Enter the password that will be used to protect the private key, and click Next.
    The Next button is grayed out until a password is supplied.
  6. The Request Submission dialog box provides two ways to submit a request: directly to the CA (if there is one internally) or manually. To submit the request manually, select Copy to Clipboard or Save to File to save the certificate request which will be submitted to the CA.
  7. Click Done to dismiss the Certificate Request Wizard.
After generating the certificate request, send it to the CA.

7.3.1.2. Sending a Certificate Request

After the certificate request is generated, send it to a certificate authority (CA); the CA will generate return a server certificate.
  1. Most certificate requests are emailed to the CA, so open a new message.
  2. Copy the certificate request information from the clipboard or the saved file into the body of the message.
    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1J
    OSUExLDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF
    0aW9uMRwwGgYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSI
    b3DQEBAQUAA4GNADCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7
    ug0EfgSLR0f+K41eNqqRftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n
    /zMyahxtV7+mT8GOFFigFfuxaxMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N
    9YdbjveMVXW0v4XwIDAQABoAAwDQYK
    ------END NEW CERTIFICATE REQUEST-----
  3. Send the email message to the CA.
After emailing the certificate request, wait for the CA to respond with the server certificate. Response time for requests varies. For example, if the CA is internal to the company, it may only take a day or two to respond to the request. If the selected CA is a third-party, it could take several weeks to respond to the request.
After receiving the certificate, install it in the Directory Server's certificate database. When the CA sends a response, be sure to save the information in a text file. The certificate must be available to install in the Directory Server.
Also, keep a backup of the certificate data in a safe location. If the system ever loses the certificate data, the certificate can be reinstalled using the backup file.

7.3.1.3. Installing the Certificate

Note

If an existing certificate has the same name as the new certificate you are attempting to install, you cannot use the Directory Server Console to install the certificate. It fails with the error Internal error: Fail to install certificate -8169.
You can use certutil to install the certificate.
certutil -A -n nickname -t trust-settings -d certDB -f /path/to/certificate_file
For more information on using certutil to manage certificates, see Section 7.6, “Using certutil”.
  1. Select the Tasks tab, and click Manage Certificates.
  2. Select the Server Certs tab, and click Install.
  3. Give the certificate location or paste the certificate text in the text box, then click Next.
    • In this file. Enter the absolute path to the certificate in this field.
    • In the following encoded text block. Copy the text from the CA's email or from the created text file, and paste it in this field.
  4. Check that the certificate information displayed is correct, and click Next.
  5. Give a name to the certificate, and click Next.
  6. Provide the password that protects the private key. This password is the same as the one provided in step 5 in Section 7.3.1.1, “Generating a Certificate Request”.
After installing the server certificate, configure the Directory Server to trust the CA which issued the server's certificate, Section 7.3.2, “Trusting the Certificate Authority”.

7.3.2. Trusting the Certificate Authority

Configuring the Directory Server to trust the certificate authority consists of obtaining the CA's certificate and installing it into the server's certificate database. This process differs depending on the certificate authority. Some commercial CAs provide a web site that allow users to automatically download the certificate. Others will email it back to users.
After receiving the CA certificate, use the Certificate Install Wizard to configure the Directory Server to trust the certificate authority.
  1. Select the Tasks tab, and click Manage Certificates.
  2. Go to the CA Certs tab, and click Install.
  3. If the CA's certificate is saved to a file, enter the path in the field provided. Alternatively, copy and paste the certificate, including the headers, into the text box. Click Next.
  4. Check that the certificate information that opens is correct, and click Next.
  5. Name the certificate, and click Next.
  6. Select the purpose of trusting this certificate authority; it is possible to select both options.
    • Accepting connections from clients (Client Authentication). The server checks that the client's certificate has been issued by a trusted certificate authority.
    • Accepting connections to other servers (Server Authentication). This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted certificate authority.
Once both the server and CA certificates are installed, it is possible to configure the Directory Server to run in TLS/SSL. However, Red Hat recommends verifying that the certificates have been installed correctly.

7.3.3. Renewing Certificates

As with any issued identification — drivers' licenses, student IDs — certificates are valid for a predefined period and then expire and must be renewed. To renew a certificate, regenerate a certificate request, using the same information that was used to create the original, submit the request to a CA, and re-install the renewed certificate.

Note

When renewing a certificate using the Certificate Wizard, the text on the introduction screen does not clearly indicate that the process is renewal and not requesting a new certificate. Also, the requester information is not filled in automatically.
  1. Open the Directory Server Console.
  2. In the Tasks tab, click the Manage Certificates button.
  3. Click the Server Certs tab.
  4. Select the certificate to renew from the list of certificates, and click the Renew button.
  5. Go through the request wizard, using the same information used for requesting the original certificate.
  6. Submit the request to a certificate authority.
  7. Once the certificate is issued, reinstall it in the Directory Server.
    1. In the Tasks tab, click the Manage Certificates button.
    2. Click the Server Certs tab.
    3. Click the Install button.
    4. Paste in the renewed certificate, and continue through the installation wizard.

7.3.4. Changing the CA Trust Options

It is sometimes necessary to reject certificates issued by a generally trusted CA. The trust settings on CA certificates installed in the Directory Server can be untrusted, trusted, or change the operations for which it is trusted.
  1. In the Tasks tab, click the Manage Certificates button.
  2. Click the CA Certs tab.
  3. Select the CA certificate to edit.
  4. Click the Edit Trust button.
  5. Set the CA trust options.
    • Accepting connections from clients (Client Authentication). This option sets whether to accept client, or user, certificates issued by the CA.
    • Making connections to other servers (Server Authentication). This option sets whether to accept server certificates issued by the CA.
    • Click OK.

7.3.5. Changing Security Device Passwords

Periodically change the settings for the security databases or devices.
  1. In the Tasks tab, click the Manage Certificates button.
  2. In the top of the window, choose a security device from the drop-down list.
  3. Click the Password button.
  4. In the Change Security Device Password dialog box, enter the old password, and then enter and confirm the new password.
  5. Click OK.

7.3.6. Adding Certificate Revocation Lists

Certificate revocation lists (CRLs) allow CAs to specify certificates that client or server users should no longer trust. If data in a certificate changes, a CA can revoke the certificate and list it in a CRL. CRLs are produced and periodically updated by a CA, so updated CRLs can be added to the Directory Server.
  1. Obtain the CRL from the CA; these can usually be downloaded from the CA's website.
  2. In the Tasks tab, click the Manage Certificates button.
  3. Select the Revoked Certs tab.
  4. To add a CRL, click Add at the bottom of the window, and enter the full path to the CRL file.
  5. Click OK.

7.3.7. Managing Certificates Used by the Directory Server Console

The certificates and keys used by the server are stored in NSS security databases in the /etc/dirsrv/slapd-instance_name directory. The Directory Server Console itself also uses certificates and keys for SSL/TLS connections; these certificates are stored in a separate database in the user's home directory. If the Directory Server Console is used to connect to multiple instances of Directory Server over SSL, then it is necessary to trust every CA which issued the certificates for every Directory Server instance.
When SSL/TLS is enabled for the Directory Server Console (Section 7.4.3, “Enabling TLS/SSL in the Directory Server, Admin Server, and Console”), the Directory Server Console must have a copy of the issuing CA certificate for it to trust the server's SSL client certificates. Otherwise, the Console will return errors about not trusting the CA which issued the certificate.

Note

Only the CA certificates for the CA which issued the server's SSL certificate is required. The Directory Server Console does not require its own SSL client certificate.
The Console's security databases are managed directly using certutil. The certutil tool is described in more detail in Section 7.6, “Using certutil” and in the NSS tool manpages.
To list the certificates in the security database:
certutil -d $HOME/.redhat-idm-console -L
To add a CA certificate to the database:
certutil -d $HOME/.redhat-idm-console -A -t CT,, -a -i /path/to/cacert.asc

Note

If you are running the Directory Server Console on Windows,
  • the security database is located in the C:\Documents and Settings\user_name\.389-console\ directory.
  • change to the C:\Program Files\Red Hat Identity Management Console\ directory to run the certutil.exe command.