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. Verify if the NSS database for Directory Server already exists:
    # ls -1 /etc/dirsrv/slapd-instance_name/*.db
    Create the databases if they do not exist. See Section 9.3.1.1, “Creating the NSS Database Using the Command Line”.
  2. Request and install the certificate:
  3. Enable TLS and set the LDAPS port:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=config
    changetype: modify
    replace: nsslapd-securePort
    nsslapd-securePort: 636
    -
    replace: nsslapd-security
    nsslapd-security: on
  4. Display the nickname of the server certificate in the NSS database:
    # certutil -L -d /etc/dirsrv/slapd-instance_name/
    Certificate Nickname                Trust Attributes
                                        SSL,S/MIME,JAR/XPI
    
    Example CA                          CT,,
    server-cert                         u,u,u
    You need the nickname in the next step.
  5. To enable the RSA cipher family, setting the NSS database security device, and the server certificate nickname, add the following entry to the directory:
    # ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=RSA,cn=encryption,cn=config
    cn: RSA
    objectClass: top
    objectClass: nsEncryptionModule
    nsSSLToken: internal (software)
    nsSSLPersonalitySSL: server-cert
    nsSSLActivation: on

    Note

    By default, the name of the security device in the NSS database is internal (software).
    If the previous command fails, because the cn=RSA,cn=encryption,cn=config entry already exists, update the corresponding attributes:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=RSA,cn=encryption,cn=config
    changetype: modify
    replace: nsSSLToken
    nsSSLToken: internal (software)
    -
    replace: nsSSLPersonalitySSL
    nsSSLPersonalitySSL: server-cert
    -
    replace: nsSSLActivation
    nsSSLActivation: on
  6. Optionally, update the list of ciphers Directory Server supports. For details, see Section 9.4.1.3.1, “Displaying and Setting the Ciphers Used by Directory Server Using the Command Line”.
  7. Optionally, enable certificate-based authentication. For details, see Section 9.8, “Using Certificate-based Client Authentication”.
  8. 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”.
  9. Restart the Directory Server instance:
    # systemctl restart dirsrv@instance_name
    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”.
  10. Optionally, enable the Directory Server Console to use TLS when connecting to the server. See Section 9.4.2.1, “Enabling TLS for Connections from the Console to Directory Server Using the Command Line”.
  11. Optionally, enable TLS for the Red Hat Identity Management Console to use TLS. See Section 9.4.3, “Enabling TLS in the Administration Server”.

9.4.1.2. Enabling TLS in Directory Server Using the Console

To enable TLS in Directory Server using the Console:
  1. Import the Certificate Authority (CA) certificate. See Section 9.3.3.2, “Installing a CA Certificate Using the Console”.
  2. Import the server certificate issued by the CA. See Section 9.3.4.2, “Installing a Certificate Using the Console”.
  3. Open the Directory Server Console and select the host name on the Configuration tab.
  4. On the Settings tab in the right pane, enter the LDAPS port into the Encrypted port field and click the Save button.
    The default port for LDAPS is 636.

    Note

    The LDAPS port must be different to the one set for unencrypted connections in the Port field.
  5. On the Encryption tab in the right pane:
    1. Select Enable SSL for this server.
    2. Enable Use this cipher family: RSA, select the security device and certificate from the list.
    3. Optionally, click the Settings button to 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 Console”.
    4. Optionally, enable users to authenticate using certificates. For details, see Section 9.8, “Using Certificate-based Client Authentication”.

      Important

      If TLS is only enabled in Directory Server and not in the Directory Server Console, do not select Require client authentication.
    5. Select the Check host name against name in certificate for outbound SSL connections option to verify that the host name matches the cn attribute in the subject name of the certificate the client presents to the server for authentication.

      Important

      Red Hat recommends enabling this option in a replication environment to protect outgoing TLS connections against a man-in-the-middle attack (MITM).
    6. Make sure that the Use SSL in Console option is not selected.

      Warning

      Do not enable the Use SSL in Console option before you finished this procedure, because it takes effect immediately after you save the setting. As a consequence, the Console fails to connect to the server.
      If you accidentally enabled this option and the Console fails to connect to the server, disable the option using the command line:
      # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
      dn: cn=slapd-instance_name,cn=Red Hat Directory Server,
       cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
      changetype: modify
      replace: nsServerSecurity
      nsServerSecurity: off
    7. Click Save.
  6. 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”.
  7. Restart the Directory Server instance:
    # systemctl restart dirsrv@instance_name
    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”.
  8. Optionally, enable the Directory Server Console to use TLS when connecting to the server. See Section 9.4.2.2, “Enabling TLS for Connections from the Console to Directory Server Using the Console”.
  9. Optionally, enable that the Red Hat Identity Management Console uses TLS. See Section 9.4.3, “Enabling TLS in the Administration Server”.

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 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:
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \
     -b 'cn=encryption,cn=config' -s base nsSSLSupportedCiphers -o ldif-wrap=no

dn: cn=encryption,cn=config
nsSSLSupportedCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256::AES-GCM::AEAD::128
...
nsSSLSupportedCiphers: SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5::RC2::MD5::128
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

The ciphers Directory Server currently uses are stored in the nsSSLEnabledCiphers read-only attribute. To display them:
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \
     -b 'cn=encryption,cn=config' -s base nsSSLEnabledCiphers -o ldif-wrap=no

dn: cn=encryption,cn=config
nsSSLEnabledCiphers: TLS_RSA_WITH_AES_256_CBC_SHA::AES::SHA1::256
nsSSLEnabledCiphers: TLS_RSA_WITH_AES_128_CBC_SHA::AES::SHA1::128
...
Additionally, you can display the ciphers which are configured to be enabled and disabled:
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \
     -b 'cn=encryption,cn=config' -s base nsSSL3Ciphers -o ldif-wrap=no

dn: cn=encryption,cn=config
nsSSL3Ciphers: -all,+tls_rsa_aes_128_sha,+tls_rsa_aes_256_sha,...

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:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: cn=encryption,cn=config
    changetype: modify
    add: nsSSL3Ciphers
    nsSSL3Ciphers: -all,+TLS_RSA_WITH_AES_128_GCM_SHA256
  3. Restart the Directory Server instance:
    # systemctl restart dirsrv@instance_name
  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.2. Displaying and Setting the Ciphers Used by Directory Server Using the Console
To select and optionally update the ciphers using the Console:
  1. Open the Directory Server Console.
  2. On the Configuration tab, select the server name.
  3. Select the Encryption tab in the right pane and click the Settings button.
  4. Optionally, update the list of ciphers. For example:
  5. Click OK.
  6. Click Save.
  7. If you updated the list of ciphers, restart the Directory Server instance:
    # systemctl restart dirsrv@instance_name

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 attribute in the cn=config entry. 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.1. 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 attribute to on:
    # ldapmodify -D "cn=Directory Manager" -W -p 636 -h server.example.com -x
    dn: cn=config
    changetype: modify
    replace: nsslapd-validate-cert
    nsslapd-validate-cert: on
  2. Restart the Directory Server instance:
    # systemctl restart dirsrv@instance_name

9.4.2. Enabling TLS for Connections from the Console to Directory Server

This section describes how you configure the Directory Server Console to use TLS to access the directory.

Important

Before you can enable TLS in the Console, enable encryption in Directory Server according to Section 9.4.1, “Enabling TLS in Directory Server” and restart the instance.
To configure an encrypted connection to the Red Hat Identity Management Console, see Section 9.4.3, “Enabling TLS in the Administration Server”.

9.4.2.1. Enabling TLS for Connections from the Console to Directory Server Using the Command Line

To enable TLS for connections from the Console to Directory Server:
# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server.example.com -x
dn: cn=slapd-instance_name,cn=Red Hat Directory Server,
 cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
changetype: modify
replace: nsServerSecurity
nsServerSecurity: on
When you start the Console the next time, it automatically uses TLS for connections to Directory Server.

9.4.2.2. Enabling TLS for Connections from the Console to Directory Server Using the Console

To enable TLS for connections from the Console to Directory Server:
  1. Open the Directory Server Console and select the host name on the Configuration tab.
  2. On the Encryption tab in the right pane:
    1. Select Use SSL in the Console.
    2. Click Save
  3. Restart the Directory Server Console.

9.4.3. Enabling TLS in the Administration Server

This section describes how to:
  • Enable the HTTPS protocol when connecting to the Red Hat Identity Management Console application
  • Set that the Administration Server stores its data in the o=NetscapeRoot entry using an encrypted connection to Directory Server
  • Enable the Red Hat Identity Management Console application to use the LDAPS protocol to manage users and groups stored in the directory

Important

Before you can enable these features, enable encryption in Directory Server according to Section 9.4.1, “Enabling TLS in Directory Server” and restart the instance.
To enable TLS in the Administration Server:
  1. Import the required certificates. Select one of the following ways:
    The Administration Server and Directory Server must share at least one CA certificate to trust the other's non-shared certificates.
  2. Open the Administration Server Console.
  3. On the Configuration tab, select the Administration Server entry in the left pane.
  4. Select the Encryption tab in the right pane to enable encryption for the Red Hat Identity Management Console:
    1. Select Enable SSL for this server.
    2. Enable Use this cipher family: RSA, select the security device and certificate from the list.
    3. Optionally, click the Settings button to update the list of ciphers the Administration Server supports.
    4. Optionally, enable client authentication using certificates. For details, see Section 9.8, “Using Certificate-based Client Authentication”.
    5. Click Save.
  5. Select the Configuration DS tab in the right pane to configure that the Administration Server stores its data in the o=NetscapeRoot entry using the LDAP protocol:
    1. Set the LDAPS port of the Directory Server instance that stores the o=NetscapeRoot entry. By default, LDAPS uses the 636 port.
    2. Select Secure Connection.
    3. Click Save.
  6. Select the User DS tab in the right pane to configure that the Red Hat Identity Management Console uses an encrypted connection to manage users and groups:
    1. Select Set User Directory and fill the fields. For encrypted connections, the Secure Connections option must be selected and the port port specified in the LDAP Host and Port field must support LDAPS.
    2. Click Save.
  7. Optionally, set the minimum and maximum TLS version for connections from the Console to the server in the ~/.redhat-idm-console/Console.version.Login.preferences file. For example:
    sslVersionMin: TLS1.1
    sslVersionMax: TLS1.2
  8. Optionally, create a password file to enable the Administration Server to start without prompting for the password of the Network Security Services (NSS) database. For details, see Section E.2.7.3, “Creating a Password File for the Administration Server”.
  9. Restart the Administration Server:
    # systemctl restart dirsrv-admin
    If you did not create a password file, the system prompts for the password of the NSS database.
  10. To configure that the Console trusts the certificate, see Section 9.4.3.1, “Managing Certificates Used by the Directory Server Console”.
After you completed this procedure, you can connect to the Red Hat Identity Management Console using the HTTPS protocol. For example:
# redhat-idm-console -a https://server.example.com:9830

9.4.3.1. 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 TLS connections; these certificates are stored in a separate database in the user's home directory. If the Directory Server Console is used to connect to multiple instances of Directory Server over TLS, then it is necessary to trust every CA which issued the certificates for every Directory Server instance.
When TLS is enabled for the Directory Server Console, the Directory Server Console must have a copy of the issuing CA certificate for it to trust the server's 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 certificate is required. The Directory Server Console does not require its own client certificate.

Importing a CA Certificate When Using the Console on Linux

For example, to add the CA certificate stored in the /root/ca.crt file to the database:
# certutil -d ~/.redhat-idm-console/ -A -n "Example CA" -t CT,, -a -i /root/ca.crt

Importing a CA Certificate When Using the Console on Windows

For example, to add the CA certificate stored in the C:\ca.crt file to the database:
> cd C:\Program Files\Red Hat Identity Management Console\
> certutil.exe -d "C:\Documents and Settings\user_name\.389-console\" -A -n "Example CA" -t CT,, -a -i C:\ca.crt

9.4.4. 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.2. Possible Connection Error If a Client Utility Does 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:
# 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