14.2. Using TLS/SSL

To provide secure communications over the network, Red Hat Directory Server includes the LDAPS communications protocol. LDAPS is the standard LDAP protocol, running over Transport Layer Security (TLS, formerly Secure Sockets Layer or SSL). Directory Server also allows spontaneous secure connections over otherwise-insecure LDAP ports, using the Start TLS LDAP extended operation.
The Directory Server supports TLS/SSL to secure communications between LDAP clients and the Directory Server, between Directory Servers that are bound by a replication agreement, or between a database link and a remote database. Directory Server can use TLS/SSL with simple authentication (bind DN and password) or with certificate-based authentication.
Directory Server's cryptographic services are provided by Mozilla Network Security Services (NSS), a library of TLS/SSL and base cryptographic functions. NSS includes a software-based cryptographic token which is FIPS 140-2 certified.
Using TLS/SSL with simple authentication ensures confidentiality and data integrity. There are two major benefits to using a certificate — smart card, token, or software-based — to authenticate to the Directory Server instead of a bind DN and password:
  • Improved efficiency. When using applications that prompt once for the certificate database password and then use that certificate for all subsequent bind or authentication operations, it is more efficient than continuously providing a bind DN and password.
  • Improved security. The use of certificate-based authentication is more secure than non-certificate bind operations because certificate-based authentication uses public-key cryptography. Bind credentials cannot be intercepted across the network. If the certificate or device is lost, it is useless without the PIN, so it is immune from third-party interference like phishing attacks.
The Directory Server is capable of simultaneous TLS/SSL and non-SSL communications. This means that you do not have to choose between TLS/SSL or non-SSL communications for the Directory Server; both can be used at the same time. Directory Server can also utilize the Start TLS extended operation to allow TLS/SSL secure communication over a regular (insecure) LDAP port.

14.2.1. Enabling TLS/SSL: Summary of Steps

  1. Obtain and install a certificate for the Directory Server, and configure the Directory Server to trust the certification authority's (CA's) certificate.
  2. Turn on TLS/SSL in the directory.
  3. Configure the Admin Server connect to a TLS-enabled Directory Server.
  4. Optionally, ensure that each user of the Directory Server obtains and installs a personal certificate for all clients that will authenticate with TLS/SSL.

14.2.2. 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 14.2.3, “Configuring the Directory Server to Run in SSL/TLS”.
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.

14.2.2.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 hostname 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 14.2.8, “Using External Security Devices”, 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.

14.2.2.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.

14.2.2.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 -importcert -v /path/to/certificate_file
For more information on using certutil to manage certificates, see Section 14.2.5, “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 14.2.2.1, “Generating a Certificate Request”.
After installing the server certificate, configure the Directory Server to trust the CA which issued the server's certificate.

14.2.2.4. 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.

14.2.2.5. Confirming That The New Certificates Are Installed

  1. Select the Tasks tab, and click Manage Certificates.
  2. Select the Server Certs tab.
    A list of all the installed certificates for the server opens.
  3. Scroll through the list. The certificates installed previously should be listed.
It is now possible to set up the Directory Server to run in TLS/SSL.

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.

14.2.3. Configuring the Directory Server to Run in SSL/TLS

Most of the time, the server should run with TLS/SSL enabled. If TLS/SSL is temporarily disabled, re-enable it before processing transactions that require confidentiality, authentication, or data integrity.
Before TLS/SSL can be activated, first create a certificate database, obtain and install a server certificate, and trust the CA's certificate, as described in Section 14.2.2, “Obtaining and Installing Server Certificates”.
With TLS/SSL enabled, when the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database. Restarting the Directory Server without the password prompt is possible by using use a hardware crypto device or creating a PIN file (Section 14.2.3.3, “Creating a Password File for the Directory Server”).

WARNING

The Directory Server must already be configured to run in SSL (Section 14.2.3.1, “Enabling TLS/SSL Only in the Directory Server”) and the server must already have been restarted before the Directory Server Console can be configured to use SSL. Configuring SSL/TLS for the server requires a server restart to load the new configuration, including the new secure port assignment. However, enabling SSL/TLS for the Console takes effect immediately. Therefore, if the Console has SSL/TLS enabled before the server is running in SSL/TLS, then the Console loses the connection to the server and cannot reconnect.
To disable SSL/TLS in the Directory Server Console, use ldapmodify to edit the nsServerSecurity attribute:
nsServerSecurity: off

NOTE

On TLS-enabled servers, be sure to check the file permissions on certificate database files, key database files, and PIN files to protect the sensitive information they contain. Because the server does not enforce read-only permissions on these files, check the file modes to protect the sensitive information contained in these files.
The files must be owned by the Directory Server user, such as the default nobody. The key and cert databases should be owned by the Directory Server user and should typically have read/write access for the owner with no access allowed to any other user (mode 0600). The PIN file should also be owned by the Directory Server user and set to read-only by this user, with no access to anyone other user (mode 0400).

14.2.3.1. Enabling TLS/SSL Only in the Directory Server

  1. Obtain and install CA and server certificates.
  2. Set the secure port for the server to use for TLS/SSL communications. In the Configuration area, select the Settings tab, and enter the value in the Encrypted Port field.
    The encrypted port number must not be the same port number used for normal LDAP communications. By default, the standard port number is 389, and the secure port is 636.
  3. Select the Configuration tab, and then select the top entry in the navigation tree in the left pane. Select the Encryption tab in the right pane.
  4. Select the Enable SSL for this Server checkbox.
  5. Check the Use this Cipher Family checkbox.
  6. Select the certificate to use from the drop-down menu.
  7. Click Cipher Settings.
    By default, all ciphers are selected.
  8. Set the preferences for client authentication.
    • Do not allow client authentication. With this option, the server ignores the client's certificate. This does not mean that the bind will fail.
    • Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see Section 14.2.10, “Using Certificate-Based Authentication”.
    • Require client authentication. With this option, the server requests authentication from the client.
    If TLS/SSL is only enabled in the Directory Server and not the Directory Server Console, do not select Require client authentication checkbox.

    NOTE

    To use certificate-based authentication with replication, the consumer server must be configured either to allow or to require client authentication.
  9. To verify the authenticity of requests, select the Check hostname against name in certificate for outbound SSL connections option. The server does this verification by matching the hostname against the value assigned to the common name (cn) attribute of the subject name in the being presented for authentication.
    By default, this feature is disabled. If it's enabled and if the hostname does not match the cn attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:
    [DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 - 
        Unable to communicate securely with peer: requested domain name does not match the server's 
        certificate.)
    [DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication 
        bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)
    Red Hat recommends enabling this option to protect Directory Server's outbound SSL connections against a man-in-the-middle (MITM) attack.
  10. Click Save.
  11. Restart the Directory Server. The Directory Server must be restarted from the command line.
    service dirsrv restart instance
    When the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database.
    To restart the Directory Server without the password prompt, create a PIN file or use a hardware crypto device. See Section 14.2.3.3, “Creating a Password File for the Directory Server” for information on how to create a PIN file.

14.2.3.2. Enabling TLS/SSL in the Directory Server, Admin Server, and Console

  1. Obtain server certificates and CA certs, and install them on the Directory Server. This is described in Section 14.2.2, “Obtaining and Installing Server Certificates”.
  2. Obtain and install server and CA certificates on the Admin Server. This is a similar process as for the Directory Server.

    NOTE

    It is important that the Admin Server and Directory Server have a CA certificate in common so that they can trust the other's certificates.
  3. Configure TLS/SSL for the Directory Server as described in Section 14.2.3.1, “Enabling TLS/SSL Only in the Directory Server”.
  4. Require SSL/TLS to connect to the Directory Server Console.

    WARNING

    The Directory Server must already be configured to run in SSL and the server must already have been restarted before the Directory Server Console can be configured to use SSL. Configuring SSL/TLS for the server requires a server restart to load the new configuration, including the new secure port assignment. However, enabling SSL/TLS for the Console takes effect immediately. Therefore, if the Console has SSL/TLS enabled before the server is running in SSL/TLS, then the Console loses the connection to the server and cannot reconnect.
    To disable SSL/TLS in the Directory Server Console, use ldapmodify to edit the nsServerSecurity attribute:
    nsServerSecurity: off
    1. Reopen the Directory Server Console.
    2. In the Configuration tab, select the server, and open the Encryption tab.
    3. Check the Use SSL in the Console box.
  5. In the Admin Server Console, select the Configuration tab. Select the Encryption tab, check the Enable SSL checkbox, and fill in the appropriate certificate information.
  6. In the Configuration DS tab, change the port number to the new Directory Server secure port information. See Section 1.7, “Changing Directory Server Port Numbers” for more information. Do this even if the default port of 636 is used. Check the Secure Connection checkbox.
  7. In the User DS tab, select the Set User Directory radio button, and fill in the Directory Server secure port information, the LDAP URL, and the user database information. Check the Secure Connection checkbox.
  8. Save the new TLS/SSL settings and Configuration DS and User DS information in the Admin Server Console.
  9. Restart the Admin Server. The server must be restarted from the command line.
    service dirsrv-admin restart
    When the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database.
    To restart the Admin Server without the password prompt, create a PIN file or use a hardware crypto device. See Section 14.2.3.4, “Creating a Password File for the Admin Server” for information on how to create a PIN file.

NOTE

When next logging into the Directory Server Console, be certain that the address reads https; otherwise, the operation will time out, unable to find the server since it is running on a secure connection. After successfully connecting, a dialog box appears to accept the certificate. Click OK to accept the certificate (either only for that current session or permanently).

14.2.3.3. Creating a Password File for the Directory Server

It is possible to store the certificate password in a password file. By placing the certificate database password in a file, the server can be started from the Directory Server Console and also restarted automatically when running unattended.

WARNING

This password is stored in clear text within the password file, so its usage represents a significant security risk. Do not use a password file if the server is running in an unsecured environment.
The password file must be in the same directory where the other key and certificate databases for Directory Server are stored. This is usually the main configuration directory, /etc/dirsrv/slapd-instance_name. The file should be named pin.txt.
Include the token name and password in the file. For example:
Internal (Software) Token:secret
For the NSS software crypto module (the default software database), the token is always called Internal (Software) Token.
The PIN file should be owned by the Directory Server user and set to read-only by the Directory Server user, with no access to anyone other user (mode 0400).

14.2.3.4. Creating a Password File for the Admin Server

Like the Directory Server, the Admin Server can use a password file during login when TLS/SSL is enabled.

WARNING

This password is stored in clear text within the password file, so its usage represents a significant security risk. Do not use a password file if the server is running in an unsecured environment.
  1. Open the Admin Server configuration directory, /etc/dirsrv/admin-serv.
  2. Create a password file named password.conf. The file should include a line with the token name and password, in the form token:password. For example:
    internal:secret
    For the NSS software crypto module (the default software database), the token is always called internal.
    The password file should be owned by the Admin Server user and set to read-only by the Admin Server user, with no access to any other user (mode 0400).

    NOTE

    To find out what the Admin Server user ID is, run grep in the Admin Server configuration directory:
    cd /etc/dirsrv/admin-serv
    
    grep \^User console.conf
  3. In the /etc/dirsrv/admin-serv directory, edit the nss.conf file to point to the location of the new password file.
    #   Pass Phrase Dialog:
    #   Configure the pass phrase gathering process.
    #   The filtering dialog program (`builtin' is a internal
    #   terminal dialog) has to provide the pass phrase on stdout.
    NSSPassPhraseDialog  file://etc/dirsrv/admin-serv/password.conf
  4. Restart the Admin Server.
    service dirsrv-admin restart

14.2.4. Command-Line Functions for Start TLS

LDAP operations such as ldapmodify, ldapsearch, and ldapdelete can use TLS/SSL when communicating with an SSL-enabled server or to use certificate authentication. Command-line options also specify or enforce Start TLS, which which allows a secure connection to be enabled on a clear text port after a session has been initiated.

IMPORTANT

These options to use Start TLS applies only for the Mozilla LDAP tools provided with Red Hat Directory Server.
In the following example, a network administrator enforces Start TLS for a search for Mike Connor's identification number:
ldapsearch -p 389 -ZZZ -P certificateDB -s base 
    -b "uid=mconnors,ou=people,dc=example,dc=com" "(attribute=govIdNumber)"
-ZZZ enforces Start TLS, and certificateDB gives the filename and path to the certificate database.

NOTE

The -ZZZ option enforces the use of Start TLS, and the server must respond that a Start TLS command was successful. If the -ZZZ command is used and the server does not support Start TLS, the operation is aborted immediately.
For information on the command-line options available, see the Directory Server Configuration and Command-Line Tool Reference.
With the -ZZ option, the following errors could occur:
With the -ZZZ option, the following errors could occur, causing the Start TLS operation to fail:
For SDK libraries used in client programs, if a session is already in TLS mode and Start TLS is requested, then the connection continues to be in secure mode but prints the error "DSA is unwilling to perform".

14.2.5. Using certutil

The Directory Server has a command-line tool, certutil, which locally creates self-signed CA and client certificates, certificate databases, and keys. The default location for the Directory Server certutil tool is /usr/bin.
certutil can also be downloaded from ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/.

14.2.5.1. Creating Directory Server Certificates through the Command Line

The following steps outline how to make the databases, key, CA certificate, server/client certificate, and convert the certificates into pkcs12 format.
  1. Open the directory where the Directory Server certificate databases are stored.
    cd /etc/dirsrv/slapd-instance_name
  2. Make a backup copy of all of the filed in the directory as a precaution. If something goes awry with while managing certificates, the databases can then be restored. For example:
    tar -cf /tmp/db-backup.tar *
  3. Create a password file for the security token password.
    vi /tmp/pwdfile
    
    secretpw
    This password locks the server's private key in the key database and is used when the keys and certificates are first created. The password in this file is also the default password to encrypt PK12 files used by pk12util. Because this password is stored in plaintext, the password file should be owned by the user as which Directory Server runs, by default nobody, and it must be set as read-only for the Directory Server user and allow no access to anyone else (mode 0400). It's a good idea to have a secure backup of this file.
  4. Set the environment variable for the shell to include the certutil directory path. For example:
    export PATH=/usr/bin/:$PATH
    The command varies depending on the shell.
  5. Create the key and certificate databases databases.
    certutil -N -d . -f /tmp/pwdfile
  6. Generate the self-signed CA certificate. certutil creates the required key pairs and the certificate. This certificate is used to generate the other server certificates and can be exported for use with other servers and clients.
    certutil -S -n "CA certificate" -s "cn=My Org CA cert,dc=example,dc=com" -2 -x -t "CT,," -m 1000 -v 120 -d . -k rsa -f /tmp/pwdfile
  7. Generate the Directory Server client certificate.
    certutil -S -n "Server-Cert" -s "cn=FQDN" -c "CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa -f /tmp/pwdfile
    The value of the -s argument is very important. The leftmost RDN must be cn=FQDN (where FQDN is the fully-qualified host and domain name of the Directory Server). For example, to issue a certificate for a server with the name ldap.example.com, specify at least -s "cn=ldap.example.com"; it is beneficial to have a more descriptive name to help with server identification, such as "cn=ldap.example.com,ou=DS1". The FQDN must be available for DNS and reverse DNS lookups to Directory Server clients because certificate validation may fail if the clients cannot properly resolve the FQDN, and some clients refuse to connect if a server certificate does not have its FQDN in the subject. Additionally, using the format cn=hostname.domain is essential for Directory Server clients to protect themselves from man in the middle attacks.

    NOTE

    There should only be one cn in a certificate subject name. To add detail to the subject name, use cn as the RDN and another attribute — like ou, l, or c — for the other subject name elements.
    To provide a subjectAltName, as well as the nickname, use the -8 argument in addition to the -s argument.
    To use the Directory Server behind a DNS round robin or any other scheme which aliases a single server certificate to multiple hostnames, see the TLS/SSL information about server name wildcards or subjectAltName.
    Server certificates for other servers are created using a similar command as for the Directory Server certificate. Make sure that every -n option (nickname) and -m option (serial number) is unique for every certificate, and make sure that the -s option gives the correct FQDN for the server.

    NOTE

    Keep careful track on the numbers set with the -m option. The -m option sets the unique identifier for the server certificate, and a CA cannot issue two certificates with the same ID. Keep a log of issued serial numbers so that no number is ever duplicated.
  8. Export the CA certificate for use with other servers and clients. A client usually requires the CA certificate to validate the server certificate in an TLS/SSL connection. Use certutil to export the CA certificate in ASCII/PEM format:
    certutil -d . -L -n "CA certificate" -a > cacert.asc
    The way that the CA certificate is imported is different for every client. For example, certutil can import a CA certificate into another Directory Server certificate database:
    cd /etc/dirsrv/slapd-otherserver
    certutil -A -d . -n "CA certificate" -t "CT,," -a -i cacert.asc
  9. Use pk12util to export other server certificates and keys created with certutil so that they can be used on a remote server.
    pk12util -d . -o ldap1.p12 -n Server-Cert -w /tmp/pwdfile -k /tmp/pwdfile
    The -w argument is the password used to encrypt the .p12 file for transport. The -k argument specifies the password for the key database containing the server certificate being exported to .p12.
  10. If the Directory Server will run with TLS/SSL enabled, then create a password file (pin.txt) for the server to use so it will not prompt you for a password every time it restarts. Creating the password file is described in Section 14.2.3.3, “Creating a Password File for the Directory Server”.
The certificates created by certutil are automatically available in the Encryption tab of the Console. There is no need to import them because they are already in the certificate database.

14.2.5.2. certutil Usage

certutil can be used for a variety of tasks to manage certificates and keys, such as generating certificate requests and removing certificates from the certificate database. Some of the most common options are listed in Table 14.1, “certutil Options”. For the full list of commands and arguments, run certutil -H from the command line.

Table 14.1. certutil Options

Options Description
-x Creates a self-signed CA certificate.
-S Creates a server or client certificate.
-R Generates a certificate request.
-N Creates new security databases.
-L Lists all of the certificates in the database.
-A Adds a certificate to the certificate database.
-n Gives the name of the certificate.
-d Certificate database directory; this is the directory for the subsystem instance.
-m The serial number for the certificate.
-k The key type to use; the only option is rsa.
-g The key size. The recommended size for RSA keys is 2048.
-s The subject name of the certificate.
-t The trust arguments for the certificate, meaning the purposes for which the certificate is allowed to be used.
-v The validity period, in months.
numbers 1-8 These set the available certificate extensions. Only eight can be specified through the certutil tool:
  • Key Usage: 1
  • Basic Constraints: 2
  • Certificate Authority Key ID: 3
  • CRL Distribution Point: 4
  • Netscape Certificate Type: 5
  • Extended Key Usage: 6
  • Email Subject Alternative Name: 7
  • DNS Subject Alternative Name: 8
-a Outputs the certificate request to an ASCII file instead of binary.
-o The output file to which to save the certificate request.
-i An input file containing a certificate.
-f The path to a password file for the security databases password.

Table 14.2, “certutil Examples” has some of the common uses for the certutil command.

Table 14.2. certutil Examples

Example Description
certutil -L -d . Lists the certificates in the database.
certutil -N -d . Creates new key (key3.db) and certificate (cert8.db) databases.
certutil -S -n "CA certificate" -s "cn=My Org CA cert,dc=example,dc=com" -2 -x -t "CT,," -m 1000 -v 120 -d . -k rsa Creates a self-signed CA certificate.
certutil -S -n "Server-Cert" -s "cn=FQDN" -c "CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa Creates a client certificate.
certutil -L -d . -n "cert_name" "Pretty prints" the specified certificate; the cert_name can specify either a CA certificate or a client certificate.
certutil -L -d . -n "cert_name" > certfile.asc Exports the specified certificate out of the database to ASCII (PEM) format.
certutil -L -d . -n "cert_name" -r > certfile.bin Exports the specified certificate out of the database to binary format; this can be used with Directory Server attributes such as usercertificate;binary.

14.2.6. 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 a separate location, $HOME/.redhat-idm-console. 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 14.2.3.2, “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 14.2.5, “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

14.2.7. Updating Attribute Encryption for New SSL/TLS Certificates

When TLS/SSL is first configured, there is no problem with attribute encryption. However, if the TLS/SSL certificate is changed, then attribute encryption fails, with messages like these:
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init
This is because the previously-generated keys do not work with the new server certificate. To correct these errors, force the server to generate new keys for attribute encryption:
  1. Stop the server.
    service dirsrv stop
  2. Open the dse.ldif file.
    vim /etc/dirsrv/dse.ldif
  3. There are special encryption key entries for the encryption ciphers used for attribute encryption under the database configuration. For example:
    dn: cn=AES,cn=encrypted attribute keys,cn=userRoot,cn=ldbm database,cn=plugins,cn=config
    objectClass: top
    objectClass: extensibleObject
    cn: AES
    nssymmetrickey:: mSLm/RlCLvPZrSdARHPowedF9zKx+kjVTww5ARE4w0lbl2YlYvrIg6mUlSsmzMfdhc1BBURhFDNwwUDisHWwiMJRIvHXstx5EGstWE9xokIU+xeMZF8cPJrY1udFSPFc0iKyiCOaPacWpomn/XPaVxkQqBWk4vJzrHHhH1o3bNg=
    Delete these entries.
  4. Start the server again.
    service dirsrv start
    As soon as the server restarts, it generates new encryption keys for the encrypted attribute keys.

14.2.8. Using External Security Devices

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 build 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.

14.2.8.1. Installing PKCS#11 Modules Through the Directory Server Console

  1. Connect the external security device, and install its drivers on the server machine.
  2. Open the Directory Server Console for the server instance with which to use the security device.
  3. Open the Console in the top navigation menu, and select the Security and then the Configure Security Modules item.
  4. In the window, click the Install button.
  5. In the configuration box, enter the full path to the driver file for the device and the name for the module.
  6. Click OK to save the new module driver.

14.2.8.2. Installing PKCS#11 Modules Through the Command Line

Installing PKCS#11 modules through the command line requires the NSS modutil tool. Because if 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.
  1. Connect the external security device, and install its drivers on the server machine.
  2. Open the security module database directory for the Directory Server instance. For example:
    cd /etc/dirsrv/slapd-instance_name
  3. 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.
    modutil -dbdir . -nocertdb -add module_name -libfile library_file
    For example, for an nCipher hardware security module:
    modutil -dbdir . -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/libcknfast.so
  4. List the loaded modules to make sure that the new PKCS#11 module was added correctly.
    modutil -list -dbdir .
    
    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
    -----------------------------------------------------------

14.2.9. Setting Security Preferences

The Directory Server supported several different ciphers, and the type of ciphers to use for TLS/SSL communications are set by the user. A cipher is the algorithm used in encryption. Some ciphers are more secure, or stronger, than others. Generally speaking, the more bits a cipher uses during encryption, the more difficult it is to decrypt the key.
When a client initiates an TLS/SSL connection with a server, the client tells the server what ciphers it prefers to use to encrypt information. In any two-way encryption process, both parties must use the same ciphers. There are a number of ciphers available. The server needs to be able to use the ciphers that will be used by client applications connecting to the server.

14.2.9.1. Available Ciphers

This section lists information about the available ciphers for Directory Server encryption. Each cipher has the following information:
  • Directory Server name. The name of the cipher suite used when configuring the Directory Server. The Directory Server uses this name both internally and in the Directory Server Console.
  • Key exchange. The key exchange algorithm. DHE stands for Diffie-Hellman; DSS stands for Digital Signature Standard. The 1024 bit ciphers are lower strength ciphers formerly used for export control.
  • Encryption Algorithm. AES stands for the American Encryption Standard. DES stands for Data Encryption Standard.
  • Symmetric Key Bit Size. The size in bits of the key used for the actual transport data encryption.
  • Message Authentication. SHA stands for Secure Hash Algorithm.
The Mozilla site, http://www.mozilla.org/projects/security/pki/nss/nss-3.11/nss-3.11-algorithms.html for definitions and explanations of the encryption algorithms.

NOTE

Directory Server supports ciphers for TLSv1 (recommended) and SSLv3. SSLv2 support is deprecated and not enabled by default in Directory Server.
Directory Server provides the following TLSv1 ciphers:

Table 14.3. TLSv1 Ciphers

Directory Server Name Key Exchange Encryption Algorithm Symmetric Key Bit Size Message Authentication
tls_dhe_dss_aes_128_sha DHE with DHS AES 128 SHA
tls_dhe_rsa_aes_128_sha DHE with RSA AES 128 SHA
tls_rsa_aes_256_sha RSA AES 256 SHA
tls_dhe_dss_aes_256_sha DHE with DSS AES 256 SHA
tls_dhe_rsa_aes_256_sha DHE with RSA AES 256 SHA
tls_dhe_dss_1024_rc4_sha DHE with DSS 1024 bit public key RC4 56 SHA
tls_dhe_dss_rc4_128_sha DHE with DSS RC4 128 SHA
tls_rsa_export1024_with_rc4_56_sha RSA with 1024 bit public key RC4 56 SHA
tls_rsa_export1024_with_des_cbc_sha RSA with 1024 bit public key DES 56 SHA

Directory Server provides the following SSLv3 ciphers:

Table 14.4. SSLv3 Ciphers

Directory Server Name Key Exchange Encryption Algorithm Symmetric Key Bit Size Message Authentication
dhe_rsa_3des_sha DHE with RSA 3DES 168 SHA
dhe_rsa_des_sha DHE with RSA DES 56 SHA
dhe_dss_3des_sha DHE with DSS 3DES 168 SHA
dhe_dss_des_sha DHE with DSS DES 56 SHA
rsa_des_sha RSA DES 56 SHA
rsa_3des_sha RSA 3DES 168 SHA
rsa_fips_des_sha RSA DES 56 SHA
rsa_fips_3des_sha RSA 3DES 168 SHA
rsa_rc4_128_md5 RSA RC4 128 MD5
rsa_rc4_40_md5 RSA RC4 40 MD5
rsa_rc2_40_md5 RSA RC2 40 MD5
rsa_null_md5 RSA null (none) N/A MD5
fortezza fortezza fortezza 80 SHA
fortezza_rc4_128_sha fortezza RC4 128 SHA
fortezza_null fortezza null (none) N/A SHA

14.2.9.2. Selecting the Encryption Cipher

  1. Make sure TLS/SSL is enabled for the server. For instructions on enabling TLS/SSL, see Section 14.2.3, “Configuring the Directory Server to Run in SSL/TLS”.
  2. Select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane.
  3. Select the Encryption tab in the right pane.
  4. Click the Cipher Setting button.
  5. In the Cipher Preference dialog box, specify which ciphers for the Directory Server to use by selecting them from the list, and click OK.
    Unless there is a security reason not to use a specific cipher, select all of the ciphers, except for none,MD5.

    WARNING

    Avoid selecting the none,MD5 cipher because the server will use this option if no other ciphers are available on the client, instead of refusing the connection. The none,MD5 cipher is not secure because encryption does not occur.

14.2.10. Using Certificate-Based Authentication

Directory Server allows certificate-based authentication for the command-line tools (which are LDAP clients) and for server-to-server connections (replication and chaining).

NOTE

A single configuration parameter, nsslapd-certdir, in cn=config in dse.ldif lists the directory containing the key, certificate, and security files. The directory name should be unique and specific to the server. For example, the /etc/dirsrv/slapd-instance_name directory contains the key and certificate databases only for the Directory Server instance called instance_name. That directory will not contain key and certificate databases for any other server or client, nor will any of the key, certificate, or other security-related files for instance_name be located in any other directory.
Directory Server used to keep separate files for the key and certificate databases. With the change to Filesystem Hierarchy Standard, the certificate and key files have been consolidated into a single file, specified in the nsslapd-certdir parameter, and the key and certificate file is stored in the /etc/dirsrv/slapd-instance_name directory.
Previous versions of Directory Server used a single directory, /opt/redhat-ds/slapd-instance/alias, for all security-related files for all servers, and required a unique prefix, such as slapd-instance-, for the key, certificate, and security-related files. The Directory Server used the attributes nsCertFile and nsKeyFile to give the locations for the key and certificate databases.
When a server receives a request from a client, it can ask for the client's certificate before proceeding.
After checking that a client certificate chain ends with a trusted CA, the server can optionally determine which user is identified by the client certificate and then look up that user's entry in the directory. Each certificate has the name of the identity it verifies in a subject name, called the subject DN. The server authenticates the user by comparing the information in the subject DN with the DN of the user's directory entry.
In order to locate user entries in the directory, a server must know how to interpret the subject names of certificates from different CAs. The mapping between the subject names of the certificates and the user DNs is defined in the certmap.conf file. This file provides three kinds of information for each listed CA:
  • It maps the distinguished name (DN) in the certificate to a branch point in the LDAP directory.
  • It specifies which DN values from the certificate (user name, email address, and so on) the server should use for the purpose of searching the directory.
  • It specifies whether the server should go through an additional verification process. This process involves comparing the certificate presented for authentication with the certificate stored in the user's directory entry. By comparing the certificate, the server determines whether to allow access or whether to revoke a certificate by removing it from the user's entry.
If more than one directory entry contains the information in the user's certificate, the server can examine all matching entries in order to determine which user is trying to authenticate. When examining a directory entry, the server compares the presented certificate with the one stored in the entry. If the presented certificate does not match any certificates or if the matching entries do not contain certificates, client authentication fails.
After the server finds a matching entry and certificate in the directory, it can determine the appropriate kind of authorization for the client. For example, some servers use information from a user's entry to determine group membership, which in turn can be used during evaluation of ACIs to determine what resources the user is authorized to access.
Three things are required for the Directory Server to allow client authentication:

14.2.10.1. Configuring Directory Server to Accept Certificate-Based Authentication from LDAP Clients

Client authentication to the Directory Server will require or allow a user to use a certificate to establish its identity, in addition to the server having to present a certification. This is also called certificate-based authentication.
  1. On the client system, obtain a client certificate from the CA.
  2. Install the client certificate on the client system.
    Regardless of how the certificate is sent (either in email or on a web page), there should be a link to click to install the certificate.
    Record the certificate information that is sent from the CA, especially the subject DN of the certificate because the server must be configured to map it to an entry in the directory. The client certificate resembles the following:
    -----BEGIN CERTIFICATE----- 
    MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBh 
    MCVVMxIzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0w 
    GwYDVQQLExRXaWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdC 
    BUZXN0IFRlc3QgVGVzdCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3 
    WhcNOTgwMzI2MDIzMzU3WjBPMQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTm 
    V0c2NhcGUgRGlyZWN0b3 
    ------END CERTIFICATE-----
  3. Convert the client certificate into binary format using the certutil utility.
    certutil -L -d certdbPath -n userCertName -r > userCert.bin
    certdbPath is the directory which contains the certificate database; for example, a user certificate for Mozilla Thunderbird is stored in $HOME/.thunderbird. userCertName is the name of the certificate, and userCert.bin is the name of the output file for binary format.
  4. On the server, map the subject DN of the certificate to the appropriate directory entry by editing the certmap.conf file.

    NOTE

    Do not map a certificate-based authentication certificate to a distinguished name under cn=monitor. Mapping a certificate to a DN under cn=monitor causes the bind operation to fail. Map the certificate to a target located elsewhere in the directory information tree. Make sure that the verifyCert parameter is set to on in the certmap.conf file. If this parameter is not set to on, Directory Server simply searches for an entry in the directory that matches the information in the certmap.conf file. If the search is successful, it grants access without actually checking the value of the userCertification and usercertificate;binary attributes.
  5. In the Directory Server, modify the directory entry for the user or identity (if it is another server) who owns the client certificate to add the usercertificate attribute.
    1. Select the Directory tab, and navigate to the user entry.
    2. Double-click the user entry, and use the Property Editor to add the usercertificate attribute, with the binary subtype.
      When adding this attribute, instead of an editable field, the server provides a Set Value button.
    3. Click Set Value.
      A file selector opens. Use it to select the binary file created in step 3.
    For information on using the Directory Server Console to edit entries, see Section 3.1.3, “Modifying Directory Entries”.
For information on how to use TLS/SSL with ldapmodify, ldapdelete, and ldapsearch, see Section 14.2.10.6, “Connecting to the Directory Server with Certificate-Based Authentication” and the Directory Server Configuration and Command-Line Tool Reference.

14.2.10.2. Mapping DNs to Certificates

When a server performs client authentication, it interprets a certificate, extracts user information, and then searches the directory for that information. In order to process certificates from different CAs, the server uses a file called certmap.conf. This file contains instructions on how to interpret different certificates and how to search the directory for the information that those certificates contain.
In the Directory Server, a user entry has a format like the following:
dn: uid=jsmith,ou=People,dc=example,dc=com
...

cn: John Smith
mail: jsmith@example.com
A subject DN, however, is almost always formatted differently than an LDAP DN. For example:
cn=John Smith,e=jsmith@example.com,c=US,o=Example.com
The email attribute in the directory is almost always unique within the organization, as is the common name of the user. These attributes are also indexed by default, so they are easily searched, and are common attributes to be used in the subject names of certificates. The certmap.conf file can be configured so that the server looks for any mail or common name elements in the subject DN and matches them against the entries in the directory. Much like an ldapsearch, the cert mapping defines a search base (DNComps) and search filter (FilterComps).
certmap Example     o=Example.com,c=US
Example:DNComps     dc
Example:FilterComps mail,cn
The certmap.conf file is stored in the /etc/dirsrv/config folder. The file contains a default mapping as well as mappings for specific CAs.
The default mapping specifies what the server should do if a client certificate was issued by a CA that is not listed in certmap.conf. The mappings for specific CAs specify what the server should do for client certificates issued by those CAs. All mappings define the following:
  • Where in the directory the server should begin its search
  • What certificate attributes the server should use as search criteria
  • Whether the server should verify the certificate with one that is stored in the directory
Mappings have the following syntax:
 certmap name issuer DN   
 name:property [value]   
 name:property [value]   
 ...
The first line of a mapping specifies the mapping's name as well as the DN for the issuer of the client certificate. The mapping can have any name, but the issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuerDN lines differ only in the number of spaces they contain, but the server would treat these two entries as different:
certmap moz ou=Example CA,o=Example,c=US
certmap moz ou=Example CA,o=Example,c=US
The second and subsequent lines of a mapping identify the rules that the server should use when searching the directory for information extracted from a certificate. These rules are specified through the use of one or more of the following properties:
  • DNComps
  • FilterComps
  • VerifyCert
  • CmapLdapAttr
  • Library
  • InitFn
DNComps
DNComps is a comma-separated list of relative distinguished name (RDN) keywords used to determine where in the user directory the server should start searching for entries that match the information for the owner of the client certificate. The server gathers values for these keywords from the client certificate and uses the values to form a DN, which determines where the server starts its search in the directory.
For example, if the DNComps is set to use the o and c RDN keywords, the server starts the search from the o=org, c=country entry in the directory, where org and country are replaced with values from the DN in the certificate.
  • If there is not a DNComps entry in the mapping, the server uses either the CmapLdapAttr setting or the entire subject DN in the client certificate to determine where to start searching.
  • If the DNComps entry is present but has no value, the server searches the entire directory tree for entries matching the filter specified by FilterComps.
The following RDN keywords are supported for DNComps:
  • cn
  • ou
  • o
  • c
  • l
  • st
  • e or mail (but not both)
  • mail
Keywords can be in either lower case or upper case.
FilterComps
FilterComps is a comma-separated list of RDN keywords used to create a filter by gathering information from the user's DN in the client certificate. The server uses the values for these keywords to form the search criteria for matching entries in the LDAP directory. If the server finds one or more entries in the directory that match the user's information gathered from the certificate, the search is successful and the server performs a verification (if verifycert is set to on).
For example, if FilterComps is set to use the e and uid attribute keywords (FilterComps=e,uid), the server searches the directory for an entry whose values for e and uid match the user's information gathered from the client certificate. Email addresses and user IDs are good filters because they are usually unique entries in the directory.
The filter needs to be specific enough to match one and only one entry in the directory.
The following RDN keywords are supported for FilterComps:
  • cn
  • ou
  • o
  • c
  • l
  • st
  • e or mail (but not both)
  • mail
Keywords can be in either lower case or upper case.
VerifyCert
verifycert tells the server whether it should compare the client's certificate with the certificate found in the user's directory entry. The value is either on or off. Setting the value to on ensures that the server will not authenticate the client unless the certificate presented exactly matches the certificate stored in the directory. Setting the value to off disables the verification process.
CmapLdapAttr
CmapLdapAttr is the name of the attribute in the directory that contains subject DNs from all certificates belonging to the user. Because this attribute is not a standard LDAP attribute, this attribute must be added to the schema. See Section 6.4.2, “Creating Attributes” for information on adding schema elements.
If the CmapLdapAttr property exists in a certmap.conf mapping, the server searches the entire directory for an entry that contains the subject's full DN. The search criteria are the attribute named by CmapLdapAttr and the subject's full DN as listed in the certificate. If the search doesn't yield any entries, the server retries the search using the DNComps and FilterComps mappings. The search will take place more quickly if the attribute specified by CmapLdapAttr is indexed. For more information on indexing attributes, see Chapter 7, Managing Indexes.
Using CmapLdapAttr to match a certificate to a directory entry is useful when it is difficult to match entries using DNComps and FilterComps.
Library
Library is the pathname to a shared library or DLL. Use this property only to extend or replace the standard functions that map information in certmap.conf to entries in the directory. This property is typically not necessary unless there are very specialized mapping requirements.
InitFn
InitFn is the name of an init function from a custom library. You need to use this property only if you want to extend or replace the functions that map information in certmap.conf to entries in the directory. This property is typically not necessary unless you have very specialized mapping requirements.

14.2.10.3. Editing the certmap.conf File

  1. In a text editor, open /etc/dirsrv/config/certmap.conf
  2. If necessary, make changes to the default mapping.
    For example, change the value for DNComps or FilterComps. To comment out a line, insert a # before it.
  3. If desired, create a mapping for a specific CA.
    The mapping should take the form certmap mappingName issuerDN.
    For example, to create a mapping named Example CA which has the issuer DN ou=example CA,o=example,c=US, enter the following:
    certmap example CA ou=example CA,o=example,c=US
  4. Add property settings for a specific CA's mapping.
    Specify the Library and InitFn properties before adding any additional properties.
    When adding a property, use the form mappingName:propertyName value.
    For example, add a DNComps value of o, c for Example CA by entering the following line:
    example CA:DNComps o, c
    For the Library and InitFn properties, a complete mapping looks like this:
    certmap Example CA ou=example CA,o=example,c=US
    Example CA:Library /ldapserver/ldap/servers/slapd/plugin.c
    Example CA:InitFn plugin_init_dn
    Example CA:DNComps o, c
    Example CA:FilterComps e, uid
    Example CA:VerifyCert on
    Example CA:CmapLdapAttr certSubjectDN
  5. Save the certmap.conf file.

14.2.10.4. Example certmap.conf Mappings

In Example 14.1, “Default Mapping”, the server starts its search at the directory branch point containing the entry ou=organizationalUnit, o=organization, c=country, where the italics represent values from the subject's DN in the client certificate.

Example 14.1. Default Mapping

certmap default     default
default:DNComps     ou, o, c
default:FilterComps e, uid
default:verifycert  on

The server then uses the values for e (email address) and uid (user ID) from the certificate to search for a match in the directory before authenticating the user. When it finds a matching entry, the server verifies the certificate by comparing the certificate the client sent to the certificate stored in the directory.
Example 14.2, “An Additional Mapping” shows the contents of a sample certmap.conf file that defines a default mapping as well as a mapping for MyCA:

Example 14.2. An Additional Mapping

certmap default     default
default:DNComps
default:FilterComps e, uid
certmap MyCA        ou=MySpecialTrust,o=MyOrg,c=US
MyCA:DNComps        ou,o,c
MyCA:FilterComps    e
MyCA:verifycert     on

When the server gets a certificate from a CA other than MyCA, the server uses the default mapping, which starts at the top of the directory tree and searches for an entry matching the client's email address (e) and user ID (uid). If the certificate is from MyCA, the server starts its search at the directory branch containing the organizational unit specified in the subject DN and searches for email addresses (e) that match the one specified in the certificate. If the certificate is from MyCA, the server verifies the certificate. If the certificate is from another CA, the server does not verify it.
Example 14.3, “A Mapping with an Attribute Search” uses the CmapLdapAttr property to search the directory for an attribute called certSubjectDN whose value exactly matches the entire subject DN in the client certificate:

Example 14.3. A Mapping with an Attribute Search

certmap MyCo        ou=My Company Inc,o=MyCo,c=US
MyCo:CmapLdapAttr   certSubjectDN
MyCo:DNComps        o, c
MyCo:FilterComps    mail, uid 
MyCo:verifycert     on

If the subject DN in the client certificate is uid=jsmith,o=example Inc,c=US, then the server searches for entries that have certSubjectDN=uid=jsmith,o=example Inc,c=US.
If one or more matching entries are found, the server proceeds to verify the entries. If no matching entries are found, the server uses DNComps and FilterComps to search for matching entries. For the client certificate described above, the server would search for uid=jsmith in all entries under o=example Inc,c=US.

14.2.10.5. Allowing and Requiring Client Authentication to the Console

Client authentication must be explicitly set in the Directory Server.
  1. Click the Configuration tab.
  2. With the top server entry highlighted in the left navigation pane, click the Encryption tab in the main window.
  3. Set whether to require or allow client authentication to the Directory Server.
    • Do not allow client authentication. With this option, the server ignores the client's certificate. This does not mean that the bind will fail.
    • Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request.
    • Require client authentication. With this option, the server requests authentication from the client.
      If client authentication is required, then SSL cannot be used with the Console because The Directory Server Console does not support client authentication.

    NOTE

    To use certificate-based authentication with replication, configure the consumer server either to allow or to require client authentication.

    NOTE

    The Directory Server must already be configured to run over TLS/SSL or Start TLS for client authentication to be enabled.
  4. Save the changes, and restart the server. For example:
    service dirsrv restart
To change the server configuration from requiring client authentication to allowing it through the command line, reset the nsSSLClientAuth parameter:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -D "cn=directory manager" -N "Server-Cert" -p 636 -host server.example.com

dn: cn=encryption,cn=config
changetype: modify
replace: nsSSLClientAuth
nsSSLClientAuth: allowed
The nsSSLClientAuth parameter can be set to off, allowed, and required.

14.2.10.6. Connecting to the Directory Server with Certificate-Based Authentication

The Directory Server can connect to another Directory Server instance for chaining or replication using certificate-based authentication, as configured in the database link or replication agreement.
Users can connect to the Directory Server with certificate-based authentication when using LDAP tools such as ldapsearch. This requires four parameters:
  • -P to give certificate database's filename and path
  • -N to give the SSL certificate name
  • -K to specify the private key database's filename and path
  • -W to give the password to the private key database
For example:
/usr/lib64/mozldap/ldapsearch -p 389 -h server.example.com -D "uid=jsmith,ou=people,dc=example,dc=com" -P /home/jsmith/alias/cert8.db -N "My Cert" -K /home/jsmith/alias/key3.db -W secret
For information on how to use TLS/SSL with ldapmodify, ldapdelete, and ldapsearch, see the Directory Server Configuration and Command-Line Tool Reference.

14.2.10.7. Forcing SASL/EXTERNAL Mechanisms for BIND Requests

The assumption with certificate-based authentication is that the Directory Server will use the identity in the presented certificate to process the BIND request.
There are two steps that the client takes at the beginning of an SSL session to use certificate authentication. First, the client sends its certificate to the Directory Server. Then, it sends its bind request. Most clients issues the bind request using the SASL/EXTERNAL mechanism, which is important because it signals to the Directory Server that it needs to use the identity in the certificate for the bind, not any credentials in the bind request.
However, some clients use simple authentication or anonymous credentials when they send the bind request. The client still assumes that the Directory Server will use the identity in the certificate for the bind identity, but there is nothing in the bind request to tell the Directory Server that that's what it should do. In that case, the SSL session fails with invalid credentials, even if the certificate and the client identity in that certificate are valid.
A configuration option in the Directory Server (nsslapd-force-sasl-external) forces clients in certificate-based authentication to send the bind request using the SASL/EXTERNAL method.
This attribute is off by default, but it can be turned on:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -D "cn=directory manager" -w secret -p 636 -h server.example.com

dn: cn=config
changetype: modify
replace: nsslapd-force-sasl-external
nsslapd-force-sasl-external: on

14.2.11. Managing Certificates for the Directory Server

After installing certificates, it can be necessary to renew the certificates, adjust the settings, or manage the security databases which store them.

14.2.11.1. 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.
  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.

14.2.11.2. 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.

14.2.11.3. 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.

14.2.11.4. 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.