9.4. Enabling TLS

Directory Server supports encrypted connections between clients and the server, as well as between servers in a replication environment. For this, Directory Server supports:
  • The LDAPS protocol: TLS encryption is used directly after the connection has been established.
  • The STARTTLS command over the LDAP protocol: The connection is unencrypted until the client sends the STARTTLS command.

Important

For security reasons, Red Hat recommends enabling TLS encryption.
You can use TLS with simple authentication using a bind Distinguished Name (DN) and password, or using certificate-based authentication.
Directory Server's cryptographic services are provided by Mozilla Network Security Services (NSS), a library of TLS and base cryptographic functions. NSS includes a software-based cryptographic token which is Federal Information Processing Standard (FIPS) 140-2 certified.

9.4.1. Enabling TLS in Directory Server

This section describes how to enable TLS in Directory Server.

9.4.1.1. Enabling TLS in Directory Server Using the Command Line

To enable TLS using the command line:
  1. Request and install the certificate:
  2. Enable TLS and set the LDAPS port: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-securePort=636 nsslapd-security=on
Successfully replaced "nsslapd-securePort"
Successfully replaced "nsslapd-security"
  3. Display the name of the server certificate in the NSS database: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate list

Certificate Name: Server-Cert
Subject DN: CN=server.example.com
Issuer DN: CN=Example CA
Expires: 2022-07-29 11:10:14
Trust Flags: ,,
    You need the nickname in the next step.
  4. To enable the RSA cipher family, setting the NSS database security device, and the server certificate name: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security rsa set --tls-allow-rsa-certificates on --nss-token "internal (software)" --nss-cert-name Server-Cert

    Note

    By default, the name of the security device in the NSS database is internal (software).
  5. Optionally, update the list of ciphers Directory Server supports. For details, see Section 9.4.1.3.2, “Displaying and Setting the Ciphers Used by Directory Server Using the Command Line”.
  6. Optionally, enable certificate-based authentication. For details, see Section 9.9, “Using Certificate-based Client Authentication”.
  7. Optionally, create a password file to enable Directory Server to start without prompting for the password of the NSS database. For details, see Section 9.4.1.5, “Creating a Password File for Directory Server”.
  8. Restart the Directory Server instance: 
    # dsctl instance_name restart
    If you set a password on the NSS database and did not create a password file, Directory Server prompts for the password of the NSS database. For details, see Section 9.4.1.4, “Starting Directory Server Without a Password File”.

9.4.1.2. Enabling TLS in Directory Server Using the Web Console

To enable TLS in Directory Server using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Create a CSR. See Section 9.3.1, “Creating a Certificate Signing Request”.
  4. Import the Certificate Authority (CA) certificate. See Section 9.3.2.2, “Installing a CA Certificate Using the Web Console”.
  5. Import the server certificate issued by the CA. See Section 9.3.4.2, “Installing a Server Certificate Using the Web Console”.
  6. Open the Server Settings menu, and select the Security entry.
  7. On the Security Configuration tab:
    1. Click Security Enabled.
    2. Select the certificate's nickname in the Server Certificate Name field.
    3. Optionally, change the settings for the minimum and maximum TLS version that the server should support.
    4. Optionally, configure client authentication to enable users to authenticate using certificates. For details, see Section 9.9, “Using Certificate-based Client Authentication”.
  8. Click Save Configuration.
  9. Optionally, create a password file to enable Directory Server to start without prompting for the password of the NSS database. For details, see Section 9.4.1.5, “Creating a Password File for Directory Server”.
  10. Restart the Directory Server instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”
    If you set a password on the NSS database and did not create a password file, Directory Server prompts for the password of the NSS database. For details, see Section 9.4.1.4, “Starting Directory Server Without a Password File”.

9.4.1.3. Setting Encryption Ciphers

Directory Server supports different ciphers, and you can enable or disable them. A cipher is the algorithm used in encryption. When a client initiates a TLS connection with a server, the client tells the server what ciphers it prefers to encrypt information. If the server supports at least one of these ciphers, the encrypted connection can be established using this algorithm.
If you enabled encryption according to Section 9.4, “Enabling TLS”, you can display and update the ciphers Directory Server uses.
9.4.1.3.1. Displaying the Default Ciphers
If the nsSSL3Ciphers parameter is not set in the cn=encryption,cn=config entry, Directory Server uses the default ciphers of the Network Security Service (NSS). To display the default ciphers: 
# /usr/lib64/nss/unsupported-tools/listsuites | grep -B1 --no-group-separator "Enabled"         
TLS_AES_128_GCM_SHA256:
  0x1301 TLS 1.3 TLS 1.3 AES-GCM  128 AEAD   Enabled  FIPS Domestic            
TLS_CHACHA20_POLY1305_SHA256:
  0x1303 TLS 1.3 TLS 1.3 CHACHA20POLY1305 256 AEAD   Enabled       Domestic
...
9.4.1.3.2. Displaying and Setting the Ciphers Used by Directory Server Using the Command Line

Displaying all Available Ciphers

To display the list of all available ciphers supported in Directory Server: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers list --supported
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
...
This is only a list of available ciphers you can enable or disable. The list does not display the ciphers Directory Server currently uses.

Displaying the Ciphers Directory Server Uses

To display the ciphers Directory Server currently uses, enter: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers list --enabled
TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
...
Additionally, you can display the ciphers which are configured to be enabled and disabled: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers list
default
+tls_rsa_aes_128_sha
+tls_rsa_aes_256_sha
...
The default keyword refers to the preferred default ciphers provided by the NSS. See Section 9.4.1.3.1, “Displaying the Default Ciphers”.

Important

Directory Server uses the settings from the nsSSL3Ciphers attribute to generate the list of ciphers which are actually used. However, if you enabled weak ciphers in nsSSL3Ciphers, but set the allowWeakCiphers parameter to off, which is the default, Directory Server only uses the strong ciphers and displays them in the nsSSLSupportedCiphers read-only attribute.

Updating the List of Enabled Ciphers

To update the list of enabled ciphers:
  1. Display the list of currently enabled ciphers. See the section called “Displaying the Ciphers Directory Server Uses”.
  2. To enable only specific ciphers, update the nsSSL3Ciphers attribute. For example, to enable only the TLS_RSA_WITH_AES_128_GCM_SHA256 cipher: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers set "-all,+TLS_RSA_WITH_AES_128_GCM_SHA256"
  3. Restart the Directory Server instance: 
    # dsctl instance_name restart
  4. Optionally, display the list of enabled ciphers to verify the result. See the section called “Displaying the Ciphers Directory Server Uses”.
9.4.1.3.3. Displaying and Setting the Ciphers Used by Directory Server Using the Web Console
To select and optionally update the ciphers using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Server Settings menu, and select the Security entry.
  4. On the Cipher Preferences tab, Directory Server displays the currently enabled ciphers.
  5. If you use different ciphers than the default, select Default Ciphers in the Ciphers Suite field to automatically enable the default ciphers. For details, see Section 9.4.1.3.1, “Displaying the Default Ciphers”.
    Alternatively, you can set Ciphers Suite to:
    • All Ciphers to enable all ciphers. Optionally, disable specific ciphers in the Deny Specific Ciphers field.
    • No Ciphers to disable all ciphers. Optionally, enable specific ciphers in the Allow Specific Ciphers field.
  6. Click Save Cipher Preferences.
  7. If you updated the list of ciphers, restart the Directory Server instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”

9.4.1.4. Starting Directory Server Without a Password File

If you start Directory Server with encryption enabled and a password set on the NSS database:
  • If the ns-slapd Directory Server process is started by the systemctl command, systemd prompts for the password and automatically passes the input to the systemd-tty-ask-password-agent utility. For example: 
    # systemctl start dirsrv
Enter PIN for Internal (Software) Token:
  • In rare cases, when the ns-slapd Directory Server process is not started by the systemctl utility and is detached from the terminal, a message is send to all terminals using the wall command. For example: 
    Broadcast message from root@server (Fri 2017-01-01 06:00:00 CET):

Password entry required for 'Enter PIN for Internal (Software) Token:' (PID 1234).
Please enter password with the systemd-tty-ask-password-agent tool!
    To enter the password, run: 
    # systemd-tty-ask-password-agent
Enter PIN for Internal (Software) Token:

9.4.1.5. Creating a Password File for Directory Server

If encryption is enabled and a password set on the NSS database, Directory Server prompts for this password when the service starts. See Section 9.4.1.4, “Starting Directory Server Without a Password File”.
To bypass this prompt, you can store the NSS database password in the /etc/dirsrv/slapd-instance_name/pin.txt file. This enables Directory Server to start automatically without prompting for this password.

Warning

The password is stored in clear text. Do not use a password file if the server is running in an unsecured environment.
To create the password file:
  1. Create the /etc/dirsrv/slapd-instance_name/pin.txt file with the following content:
    • If you use the NSS software cryptography module, which is the default: 
      Internal (Software) Token:password
    • If you use a Hardware Security Module (HSM): 
      name_of_the_token:password
  2. Set the permissions: 
    # chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/pin.txt
# chmod 400 /etc/dirsrv/slapd-instance_name/pin.txt

9.4.1.6. Managing How Directory Server Behaves If the Certificate Has Been Expired

By default, if encryption is enabled and the certificate has expired, Directory Server logs a warning and the service starts. To change this behavior, set the nsslapd-validate-cert parameter. You can set it to the following values:
  • warn: The Directory Server instance starts and log a warning about the expired certificate into the /var/log/dirsrv/slapd-instance_name/error log file. This is the default setting.
  • on: Directory Server validates the certificate and the instance fails to start if the certificate has expired.
  • off: Directory Server does not validate the certificate expiration date. The instance starts and no warning will be logged.

Example 9.3. Preventing Directory Server to Start If the Certificate Has Been Expired

To prevent Directory Server from starting if the certificate has expired:
  1. Set the nsslapd-validate-cert parameter to on: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-validate-cert=on
Successfully replaced "nsslapd-validate-cert"
  2. Restart the Directory Server instance: 
    # dsctl instance_name restart

9.4.2. Adding the CA Certificate Used By Directory Server to the Trust Store of Red Hat Enterprise Linux

When you enabled TLS encryption in Directory Server, you configured the instance to use a certificate issued by a CA. If a client now establishes a connection to the server using the LDAPS protocol or the STARTTLS command over LDAP, Directory Server uses this certificate to encrypt the connection. Client utilities use the CA certificate to verify if the server's certificate is valid. By default, these utilities cancel the connection if they do not trust the certificate of the server.

Example 9.4. Possible Connection Errors If Clients Utilities Do Not Use the CA Certificate

If client utilities do not use the CA certificate, the utilities cannot validate the server's certificate when using TLS encryption. As a consequence, the connection to the server fails. For example:
  • dsconf 
    # dsconf -D "cn=Directory Manager" ldaps://consumer.example.com:636 config get
Error: {'desc': "Can't contact LDAP server", 'info': 'error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed (self signed certificate in certificate chain)'}
  • ldapsearch 
    # ldapsearch -H ldaps://server.example.com:636 -D "cn=Directory Manager" -W -b "dc=example,dc=com" -x
Enter LDAP Password: 
ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
To enable client utilities on Red Hat Enterprise Linux to verify the certificate that Directory Server uses, add the CA certificate to the trust store of the operating system:
  1. If you do not have a local copy of the CA certificate used by Directory Server:
    1. List the certificates in the server's NSS database: 
      # certutil -d /etc/dirsrv/slapd-instance_name/ -L

Certificate Nickname                       Trust Attributes
                                           SSL,S/MIME,JAR/XPI

Example CA                                 C,,  
Server-Cert                                u,u,u
    2. Use the nickname of the CA certificate in the NSS database to export the CA certificate: 
      # certutil -d /etc/dirsrv/slapd-instance_name/ -L -n "Example CA" -a > /tmp/ds-ca.crt
  2. Copy the CA certificate to the /etc/pki/ca-trust/source/anchors/ directory. For example: 
    # cp /tmp/ds-ca.crt /etc/pki/ca-trust/source/anchors/
  3. Rebuild the CA trust database: 
    # update-ca-trust