Chapter 1. Enabling TLS-encrypted connections to Directory Server By default, Red Hat Directory Server provides the LDAP service without encryption. To improve the security, you can configure TLS in Directory Server to enable your clients or other hosts in a replication environment to use encrypted connections. They can then use the STARTTLS command on port 389 or the LDAPS protocol on port 636 for secure connections. 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. 1.1. The different options for encrypted connections to Directory Server To connect to Directory Server with an encrypted connection, you can use the following protocols and framework: LDAPS When you use the LDAPS protocol, the connection starts using encryption and either succeeds or fails. However, no unencrypted data is ever sent over the network. For this reason, prefer LDAPS instead of using STARTTLS over unencrypted LDAP. STARTTLS over LDAP Clients establish an unencrypted connection over the LDAP protocol and then send the STARTTLS command. If the command succeeds, all further communication is encrypted. Warning If the STARTTLS command fails and the client does not cancel the connection, all further data, including authentication information, is sent unencrypted over the network. SASL The Simple Authentication and Security Layer (SASL) framework enables you to authenticate a user using external authentication methods, such as Kerberos. 1.2. How Directory Server unlocks the NSS database Directory Server stores certificate signing requests (CSR), private keys, and certificates in a network security services (NSS) database. When you install a new instance, the installer automatically creates the NSS database and protects it with a random password. The installer stores this password in the following files: /etc/dirsrv/slapd- instance_name /pwdfile.txt : The dsconf tls command uses this file to access the NSS database. /etc/dirsrv/slapd- instance_name /pin.txt : This file contains the token and password to automatically unlock the NSS database when Directory Server starts. If you want Directory Server to prompt for the NSS database password each time you start the instance, remove this file. If you want the instance to start automatically without prompting for the password, keep this file and update it when you change the NSS database password. If the /etc/dirsrv/slapd- instance_name /pin.txt file does not exist, you start Directory Server with encryption enabled and set a password on the NSS database, the the behavior is as follows: If the systemctl or dsctl utilities start the ns-slapd Directory Server process, the systemd service prompts for the password and automatically passes the input to the systemd-tty-ask-password-agent utility: # dsctl instance_name start Enter PIN for Internal (Software) Token: (press TAB for no echo) In rare cases, when the ns-slapd Directory Server process is not started by the systemctl or dsctl utilities, and the process is detached from the terminal, ns-slapd sends a message to all terminals using the wall command: Broadcast message from root@server (Fri 2021-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: # systemd-tty-ask-password-agent Enter PIN for Internal (Software) Token: Additional resources Changing the password of the NSS database 1.3. Enabling TLS-encrypted connections to Directory Server using the command line To use TLS encryption or certificate-based authentication, you must manage the certificates in a network security services (NSS) database. When you created the instance, the dscreate utility automatically created this database in the /etc/dirsrv/slapd- instance_name / directory and protected it with a strong password. Procedure Create a private key and a certificate signing request (CSR). Skip this step if you want to create them using an external utility. If your host is reachable only by one name, enter: # dsctl instance_name tls generate-server-cert-csr -s " CN=server.example.com,O=example_organization " If your host is reachable by multiple names: # dsctl instance_name tls generate-server-cert-csr -s " CN=server.example.com,O=example_organization " server.example.com server.example.net If you specify the host names as the last parameter, the command adds the Subject Alternative Name (SAN) extension with the DNS:server.example.com, DNS:server.example.net entries to the CSR. The string specified in the -s subject parameter must be a valid subject name according to RFC 1485. The CN field in the subject is required, and you must set it to one of the fully-qualified domain names (FQDN) of the server. The command stores the CSR in the /etc/dirsrv/slapd- instance_name /Server-Cert.csr file. Submit the CSR to the certificate authority (CA) to get a certificate issued. For further details, see your CA's documentation. Import the server certificate issued by the CA to the NSS database: If you created the private key using the dsctl tls generate-server-cert-csr command, enter: # dsconf -D " cn=Directory Manager " ldap://server.example.com security certificate add --file /root/instance_name.crt --name " server-cert " --primary-cert Remember the name of the certificate you set in the --name _certificate_nickname parameter. You require it in a later step. If you created the private key using an external utility, import the server certificate and the private key: # dsctl instance_name tls import-server-key-cert /root/server.crt /root/server.key Note that the command requires you to specify the path to the server certificate first and then the path to the private key. This method always sets the nickname of the certificate to Server-Cert . Import the CA certificate to the NSS database: # dsconf -D " cn=Directory Manager " ldap://server.example.com security ca-certificate add --file /root/ca.crt --name " Example CA " Set the trust flags of the CA certificate: # dsconf -D " cn=Directory Manager " ldap://server.example.com security ca-certificate set-trust-flags " Example CA " --flags " CT,, " This configures Directory Server to trust the CA for TLS encryption and certificate-based authentication. Enable TLS and set the LDAPS port: # dsconf -D " cn=Directory Manager " ldap://server.example.com config replace nsslapd-securePort= 636 nsslapd-security= on Open the LDAPS port in the firewalld service: # firewall-cmd --permanent --add-port= 636 /tcp # firewall-cmd --reload Enable the RSA cipher family, set 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 By default, the name of the security device in the NSS database is internal (software) Optional: Disable the plain text LDAP port: # dsconf inst security disable_plain_port Restart the instance # dsctl instance_name restart Verification Establish a connection to Directory Server using the LDAPS protocol. For example, run a query: # ldapsearch -H ldaps://server.example.com:636 -D " cn=Directory Manager " -W -b " dc=example,dc=com " -x -s base If the command fails, with an ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1) error, re-run the command with debug level 1: # ldapsearch -H ldaps://server.example.com:636 -D " cn=Directory Manager " -W -b " dc=example,dc=com " -x -s base -d 1 steps Add the CA certificate used by Directory Server to the trust store of Red Hat Enterprise Linux Optional: Change the password of the NSS database Optional: Updating the list of ciphers Directory Server supports Additional resources Changing the CA trust flags using the command line 1.4. Enabling TLS-encrypted connections to Directory Server using the web console You can configure TLS encryption using the web console. Prerequisites You are logged in to the instance in the web console. Procedure Navigate to Server Security Certificate Management Certificate Signing Request , and click Create Certificate Signing Request . Set a name for certificate signing request (CSR), common name (CN), and organization (O): If your host is reachable by multiple names, set the alternative names in the Subject Alternative Names filed. Click Create Certificate Signing Request . View the CSR text and copy it: Click Node options icon for the CSR you want to view and select View CSR . Copy the CSR content. Submit the CSR file to the certificate authority (CA) to get a certificate issued. For further details, see your CA's documentation. When you get the certificate from your CA, navigate to Server Security Certificate Management TLS Certificates , and click Add Server Certificate . Set a unique nickname for the server certificate, upload the issued certificate, and click Add Certificate . Remember the certificate nickname, because a later step requires it. Navigate to Server Security Certificate Management Trusted Certificate Authorities , and click Add CA Certificate . Set a unique nickname for the CA certificate, upload the CA certificate file, and click Add Certificate . Optional: If you did not enable TLS encryption during the Directory Server instance installation, enable it: Navigate to Server Security Settings , and enable the security switch. On the pop-up window, click Enable Security . Click Save Configuration on the Security Setting page. Configure the Server Certificate Name on the Security Configuration page: Navigate to Server Security Security Configuration . Select the server certificate nickname in the Server Certificate Name drop-down list, and click Save Configuration . Optional: If you do not see the certificate nickname in the drop-down list, refresh the Security Settings page and perform the step again. Optional: If you want to use an LDAPS port other than 636 , navigate to the Server Server Settings , set the LDAPS port, and click Save . Open the LDAPS port in the firewalld service: Optional: Navigate to Server Security Security Configuration , check Require Secure Connections checkbox, and click Save Configuration . Directory Server disables the plain text LDAP port. Click Actions in the top right corner, and select Restart Instance . steps Add the CA certificate used by Directory Server to the trust store of Red Hat Enterprise Linux Optional: Change the password of the NSS database Optional: Updating the list of ciphers Directory Server supports 1.5. Managing how Directory Server behaves if the certificate has 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 : Directory Server starts and logs 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. If the certificate has expired, the instance fails to start. off : Directory Server does not validate the certificate expiration date. The instance starts and no warning will be logged. Prerequisites You configured TLS encryption. Procedure Use the following command to change the nsslapd-validate-cert parameter: # dsconf -D " cn=Directory Manager " ldap://server.example.com config replace nsslapd-validate-cert= <value> 1.6. Changing the password of the NSS database You can change the password of the network security services (NSS) database. For example, change it when the password becomes known to unauthorized persons. Prerequisites You know the current NSS database password. If you use a password file to automatically unlock the database when Directory Server starts, the password is stored non-encrypted in plain text in the /etc/dirsrv/slapd- instance_name /pin.txt file. Procedure Use the following command to change the NSS database password: # certutil -d /etc/dirsrv/slapd- instance_name / -W Enter Password or Pin for "NSS Certificate DB": Enter a password which will be used to encrypt your keys. The password should be at least 8 characters long, and should contain at least one non-alphabetic character. Enter new password: Re-enter password: Password changed successfully. If you use a password file to start Directory Server automatically without prompting for the NSS database password, replace the old password with the new one in the /etc/dirsrv/slapd-instance_name/pin.txt : 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 Verification Perform an operation on the NSS database that requires entering the password. For example, list the private keys of your instance: # certutil -d /etc/dirsrv/slapd- instance_name / -K certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services" Enter Password or Pin for "NSS Certificate DB": < 0> rsa 72cb03f87381abfbb6b9e78234e2e4502ad1bfc0 NSS Certificate DB:Server-Cert If the command displays the expected output after you entered the new password, changing the password was successful. Additional resources How Directory Server unlocks the NSS database 1.7. Creating a password file to start an instance without being prompted for the NSS database password When you create a new instance, the installer automatically creates the /etc/dirsrv/slapd-instance_name/pin.txt file to enable Directory Server to start without prompting for the network security services (NSS) password. However, if you remove this file, you can recreate it. Warning The password is stored in plain text. Do not use a password file if the server is running in an unsecured environment. Prerequisites You know the NSS database password. Procedure 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 Set the file permissions: # chown dirsrv:root /etc/dirsrv/slapd- instance_name /pin.txt # chmod 400 /etc/dirsrv/slapd- instance_name /pin.txt Verification Restart the instance: # dsctl instance_name restart If the system does not prompt for the NSS database password, Directory Server uses the password file. Additional resources How Directory Server unlocks the NSS database 1.8. Adding the CA certificate used by Directory Server to the trust store of Red Hat Enterprise Linux When you enable TLS encryption in Directory Server, you configure 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 1.1. Possible connection errors if client utilities do not use the CA certificate dsconf # 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 # 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 Directory Server uses, add the CA certificate to the trust store of the operating system. Prerequisites You know the password of the network security services (NSS) database. If you still use the password that was generated during the installation of the Directory Server instance, you find this password in plain text in the /etc/dirsrv/slapd-instance_name/pwdfile.txt file. Procedure If you do not have a local copy of the CA certificate used by Directory Server: List the certificates in the server's network security services (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 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 Copy the CA certificate to the /etc/pki/ca-trust/source/anchors/ directory: # cp /tmp/ds-ca.crt /etc/pki/ca-trust/source/anchors/ Rebuild the CA trust database: # update-ca-trust Verification Establish a connection to Directory Server using the LDAPS protocol. For example, run a query: # ldapsearch -H ldaps://server.example.com:636 -D " cn=Directory Manager " -W -b " dc=example,dc=com " -x -s base Additional resources The update-ca-trust(8) man page

Commands:
dsctl instance_name start Enter PIN for Internal (Software) Token: (press TAB for no echo)
Broadcast message from root@server (Fri 2021-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:
dsctl instance_name tls generate-server-cert-csr -s " CN=server.example.com,O=example_organization "
dsctl instance_name tls generate-server-cert-csr -s " CN=server.example.com,O=example_organization " server.example.com server.example.net
dsconf -D " cn=Directory Manager " ldap://server.example.com security certificate add --file /root/instance_name.crt --name " server-cert " --primary-cert
dsctl instance_name tls import-server-key-cert /root/server.crt /root/server.key
dsconf -D " cn=Directory Manager " ldap://server.example.com security ca-certificate add --file /root/ca.crt --name " Example CA "
dsconf -D " cn=Directory Manager " ldap://server.example.com security ca-certificate set-trust-flags " Example CA " --flags " CT,, "
dsconf -D " cn=Directory Manager " ldap://server.example.com config replace nsslapd-securePort= 636 nsslapd-security= on
firewall-cmd --permanent --add-port= 636 /tcp firewall-cmd --reload
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
dsconf inst security disable_plain_port
dsctl instance_name restart
ldapsearch -H ldaps://server.example.com:636 -D " cn=Directory Manager " -W -b " dc=example,dc=com " -x -s base
ldapsearch -H ldaps://server.example.com:636 -D " cn=Directory Manager " -W -b " dc=example,dc=com " -x -s base -d 1
firewall-cmd --permanent --add-port= 636 /tcp firewall-cmd --reload
dsconf -D " cn=Directory Manager " ldap://server.example.com config replace nsslapd-validate-cert= <value>
certutil -d /etc/dirsrv/slapd- instance_name / -W Enter Password or Pin for "NSS Certificate DB": Enter a password which will be used to encrypt your keys. The password should be at least 8 characters long, and should contain at least one non-alphabetic character. Enter new password: Re-enter password: Password changed successfully.
Internal (Software) Token: password
name_of_the_token : password
certutil -d /etc/dirsrv/slapd- instance_name / -K certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services" Enter Password or Pin for "NSS Certificate DB": < 0> rsa 72cb03f87381abfbb6b9e78234e2e4502ad1bfc0 NSS Certificate DB:Server-Cert
Internal (Software) Token: password
name_of_the_token : password
chown dirsrv:root /etc/dirsrv/slapd- instance_name /pin.txt chmod 400 /etc/dirsrv/slapd- instance_name /pin.txt
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
ldapsearch -H ldaps://server.example.com:636 -D " cn=Directory Manager " -W -b " dc=example,dc=com " -x -s base