7.4. Setting up 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.

7.4.1. TLS/SSL in Directory Server

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.
There are four steps to enable TLS/SSL:
  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.
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 7.3.1, “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 7.4.4, “Creating a Password File for the Directory Server”).

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. If you set a different account during the installation, like Red Hat recommends, use this user and group for a better security instead. 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).

Warning

The Directory Server must already be configured to run in SSL (Section 7.4.2, “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

7.4.2. 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 check box.
  5. Check the Use this Cipher Family check box.
  6. Select the certificate to use from the drop-down menu.
  7. Click Cipher Settings.
    By default, ALL in the TLS tab is selected. When ALL is set, the server selects safe ciphers internally.
  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 7.10, “Using Client (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 check box.

    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 host name against name in certificate for outbound SSL connections option. The server does this verification by matching the host name 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 is enabled and if the host name 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 host name does not 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 (Cannot 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 7.4.4, “Creating a Password File for the Directory Server” for information on how to create a PIN file.

7.4.3. 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 7.3.1, “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 7.4.2, “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 check box, 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.6, “Changing Directory Server Port Numbers” for more information. Do this even if the default port of 636 is used. Check the Secure Connection check box.
  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 check box.
  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 E.2.9.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).

7.4.4. 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).

7.4.5. Starting the Directory Server with Expired Certificates

If the Directory Server is configured to run in SSL and its certificate expires, then the Directory Server cannot be started. Because this can cut off access to user and authentication information, as well as other directory data, Directory Server has an option to set how it handles an expired certificate.
The nsslapd-validate-cert parameter sets how the Directory Server should respond when it attempts to start with an expired certificate:
  • warn allows the Directory Server to start successfully with an expired certificate, but it sends a warning message that the certificate has expired. This is the default setting.
  • on validates the certificate and will prevent the server from restarting if the certificate is expired. This sets a hard failure for expired certificates.
  • off disables all certificate expiration validation, so the server can start with an expired certificate without logging a warning.
To change the behavior of the expired certificate setting, edit the nsslapd-validate-cert parameter under cn=config:
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x -D "cn=directory manager" -w secret -p 636 -h server.example.com -x

dn: cn=config
changetype: modify
replace: nsslapd-validate-cert
nsslapd-validate-cert: on