The basic LDAP "ldap:///" network protocol performs all communication unencrypted between a client and server. This means sensitive information like passwords and personal data can easily be intercepted and used by unauthorized third parties.  To overcome this, OpenLDAP supports communications utilizing TLS (Transport Layer Security).  

TLS uses X.509 security certificates that provide the identity of the server to the client. When the client verifies the authenticity of the server's certificate, the client and server can begin encrypted communications.

To implement TLS, an LDAP server needs at minimum, three items installed and configured:

CA Certificate File

This certificate file provides the verified identity of the certificate authority used to issue certificates for the server. In production environments CA certificates should be from publicly recognized certificate authorities like Entrust, VeriSign, Let's Encrypt, etc.  For testing purposes, you can create your own certificate authority and issue self-signed certificates. See: Creating Self-Signed Certificates

Server Certificate File

An X.509 certificate issued by the Certificate Authority. The certificate contains information about the identity of the server, the certificate authority and the public encryption key used by LDAP clients to establish encrypted communications.

Server Certificate Key File

The server certificate key file contains a private encryption key that can only be used to decrypt data that's been encrypted by the public encryption key.

Server Configuration

Note: The default behavior of slapd is to reject the use of self-signed certificates so the slapd configuration will also need to be modified to accept the certificate. The setting is “TLSVerifyClient” or “olcTLSVerifyClient” and must have a value of “never”, “try” or “allow”.

slapd.conf

The TLS certificate settings (that start with "TLS") in slapd.conf must be defined early in the configuration file, before any backend definitions are made. The best place to put the TLS* settings is immediately after the “moduleload” settings. 

A restart of slapd must be performed for the settings to be applied.

TLSCACertificateFile  /opt/symas/ssl/demoCA/cacert.pem
TLSCertificateFile    /opt/symas/ssl/demoCA/certs/server-cert.pem
TLSCertificateKeyFile /opt/symas/ssl/demoCA/certs/server-key.pem
# If using self-signed certificates, include the following:
TLSVerifyClient       never

cn=config

The olcTLS settings in cn=config should be in the base cn=config entry. The following LDIF can be used with ldapmodify to add the new settings:

dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /opt/symas/ssl/demoCA/cacert.pem
-
add: olcTLSCertificateFile
TLSCertificateFile: /opt/symas/ssl/demoCA/certs/server-cert.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /opt/symas/ssl/demoCA/certs/server-key.pem
# If using self-signed certificates, include the following:
-
add: olcTLSVerifyClient
olcTLSVerifyClient: never

Listener Configuration

TLS connections may be made on two types of listeners, “ldaps:///” and “ldap:///” + StartTLS.

The difference between the two listeners is the timing of when encryption is established. With “ldaps:///”, encryption is started immediately when the connection is established. When using “ldap:///” + StartTLS, an unencrypted connection is established first and then the StartTLS control is sent to start the encryption. 

Care must be used when using StartTLS. If the client fails to send the StartTLS control, a user's credentials will pass over the network unencrypted.

To configure slapd to use the “ldaps:///” interface, add or modify the file /etc/default/symas-openldap with the following line, run “systemctl daemon-reload” and restart slapd:

SLAPD_URLS="ldap:/// ldaps:///" 

Client Configuration

When using certificates issued by valid public certificate authorities, LDAP clients are able to verify the authenticity of a certificate and don't need any additional configuration to work with TLS connections.

When using self-signed certificates, the client is unable verify the authenticity of the certificate. The default behavior of most LDAP clients is to refuse to make a connection in this case. Clients can be configured to not request a certificate and bypass certificate validation but still establish an encrypted connection. Remember, bypassing certificate validation should be used for testing purposes only and is not recommended in production environments or anywhere data may be considered sensitive.

Testing Self-Signed Certificates

With the OpenLDAP command line clients (ldapsearch, ldapmodify, etc.), the client looks for an environment variable named “TLS_REQCERT” with a value of “never”. This can be permanently set in an ldaprc, .ldaprc or ldap.conf file. See the ldap.conf man page. This can also be set on a temporary basis in a terminal setting by using the command:

export LDAPTLS_REQCERT=never

Once the client is configured to not request a certificate, you can use the ldapwhoami command to make a test connection.

Using ldaps:/// (-W prompts for password):

ldapwhoami -xH ldaps://<hostname>/ -D <bind-dn> -W

Using ldap:///+StartTLS (-Z sends the StartTLS, -W prompts for password):

ldapwhoami -x -Z -H ldap://<hostname>/ -D <bind-dn> -W

If the command is successful, the ldapwhoami command will return with the DN used in the request.

Troubleshooting

Validate a Certificate With the CA

Server certificates may be validated against the CA certificate with the openssl command:

/opt/symas/ssl> openssl verify -verbose -CAfile <ca-certificate-path>.pem <server-certificate-path>.pem

The command will return “OK” or provide messages indicating the problem with the certificate.

Check for Valid Certificate Dates

Certificates have a limited life span. If a certificate is used before the start date or after the end date, TLS connections will fail. The following command will display the start and end dates of a certificate:

/opt/symas/ssl> openssl x509 -startdate -enddate -noout -in <certificate-filename>.pem

Self-Signed Certificates

When there's a problem connecting with self-signed certificates, the LDAP client will return the message “ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)”. To troubleshoot the issue, add “-d 8” to the ldap* command. This setting prints connection related diagnostic messages.

When the message “TLS: can't connect: SSLHandshake() failed: misc. bad certificate (-9825)” is presented:

1. Make sure that the “TLSVerifyClient” setting in the slapd configuration is set to “allow”, “never” or “try”. 

2. Check the client configuration file (~/.ldaprc, /opt/symas/etc/openldap/ldap.conf, etc.) have the setting “TLS_REQCERT” set to “allow”, “never” or “try”. Alternatively. check your shell environment variables with the command "/usr/bin/env" for the setting “LDAPTLS_REQCERT” and if present, has a value of “allow”, “try” or “never” 

3. On the server, make sure “ldaps:///” is in the SLAPD_URLS variable in /etc/default/symas-openldap. If it's not present, add it, save the file, run “systemctl daemon-reload” and restart slapd.