9.4. Enabling TLS
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: Request and install the certificate: For a certificate issued by a Certificate Authority (CA): Create a Certificate Signing Request (CSR). See Section 9.3.1.1, "Creating a Certificate Signing Request Using the Command Line" Import the CA certificate. See Section 9.3.2.1, "Installing a CA Certificate Using the Command Line" . Import the server certificate issued by the CA. See Section 9.3.4.1, "Installing a Server Certificate Using the Command Line" . For a self-signed certificate, see Section 9.3.5, "Generating and Installing a Self-signed Certificate" . Enable TLS and set the LDAPS port: Display the name of the server certificate in the NSS database: You need the nickname in the step. To enable the RSA cipher family, setting the NSS database security device, and the server certificate name: Note By default, the name of the security device in the NSS database is internal (software) . 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" . Optionally, enable certificate-based authentication. For details, see Section 9.9, "Using Certificate-based Client Authentication" . 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" . Restart the Directory Server instance: 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: Open the Directory Server user interface in the web console. See Section 1.4, "Logging Into Directory Server Using the Web Console" . Select the instance. Create a CSR. See Section 9.3.1, "Creating a Certificate Signing Request" . Import the Certificate Authority (CA) certificate. See Section 9.3.2.2, "Installing a CA Certificate Using the Web Console" . Import the server certificate issued by the CA. See Section 9.3.4.2, "Installing a Server Certificate Using the Web Console" . Open the Server Settings menu, and select the Security entry. On the Security Configuration tab: Click Security Enabled . Select the certificate's nickname in the Server Certificate Name field. Optionally, change the settings for the minimum and maximum TLS version that the server should support. Optionally, configure client authentication to enable users to authenticate using certificates. For details, see Section 9.9, "Using Certificate-based Client Authentication" . Click Save Configuration . 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" . 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: 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: 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: Additionally, you can display the ciphers which are configured to be enabled and disabled: 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: Display the list of currently enabled ciphers. See the section called "Displaying the Ciphers Directory Server Uses" . To enable only specific ciphers, update the nsSSL3Ciphers attribute. For example, to enable only the TLS_RSA_WITH_AES_128_GCM_SHA256 cipher: Restart the Directory Server instance: 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: Open the Directory Server user interface in the web console. See Section 1.4, "Logging Into Directory Server Using the Web Console" . Select the instance. Open the Server Settings menu, and select the Security entry. On the Cipher Preferences tab, Directory Server displays the currently enabled ciphers. 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. Click Save Cipher Preferences . 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: 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: To enter the password, run: 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: 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: If you use a Hardware Security Module (HSM): Set the permissions: 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: Set the nsslapd-validate-cert parameter to on : Restart the Directory Server instance: 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 Client 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 ldapsearch 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: If you do not have a local copy of the CA certificate used by Directory Server: List the certificates in the server's NSS database: Use the nickname of the CA certificate in the NSS database to export the CA certificate: Copy the CA certificate to the /etc/pki/ca-trust/source/anchors/ directory. For example: Rebuild the CA trust database:
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" 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: ,, 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 dsctl instance_name restart /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 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 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 dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers list default +tls_rsa_aes_128_sha +tls_rsa_aes_256_sha dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers set "-all,+TLS_RSA_WITH_AES_128_GCM_SHA256" dsctl instance_name restart systemctl start dirsrv@ instance_name Enter PIN for Internal (Software) Token: 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! systemd-tty-ask-password-agent Enter PIN for Internal (Software) Token: Internal (Software) Token: password name_of_the_token : password chown dirsrv:dirsrv /etc/dirsrv/slapd- instance_name /pin.txt chmod 400 /etc/dirsrv/slapd- instance_name /pin.txt dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-validate-cert=on Successfully replaced "nsslapd-validate-cert" dsctl instance_name restart dsconf -D "cn=Directory Manager" ldaps://server.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 -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) 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 certutil -d /etc/dirsrv/slapd-instance_name/ -L -n " Example CA " -a > /tmp/ds-ca.crt cp /tmp/ds-ca.crt /etc/pki/ca-trust/source/anchors/ update-ca-trust