11. Using TLS
OpenLDAP clients and servers are capable of using the
11.1. TLS Certificates
TLS uses
11.1.1. Server Certificates
The DN of a server certificate must use the CN attribute to name the server, and the CN must carry the server's fully qualified domain name. Additional alias names and wildcards may be present in the subjectAltName certificate extension. More details on server certificate names are in RFC2830.
11.1.2. Client Certificates
The DN of a client certificate can be used directly as an authentication DN. Since X.509 is a part of the
11.2. TLS Configuration
After obtaining the required certificates, a number of options must be configured on both the client and the server to enable TLS and make use of the certificates. At a minimum, the clients must be configured with the filename containing all of the
Typically a single CA will have issued the server certificate and all of the trusted client certificates, so the server only needs to trust that one signing CA. However, a client may wish to connect to a variety of secure servers managed by different organizations, with server certificates generated by many different CAs. As such, a client is likely to need a list of many different trusted CAs in its configuration.
11.2.1. Server Configuration
The configuration directives for slapd belong in the global directives section of slapd.conf(5).
11.2.1.1. TLSCACertificateFile <filename>
This directive specifies the
11.2.1.2. TLSCACertificatePath <path>
This directive specifies the path of a directory that contains individual
11.2.1.3. TLSCertificateFile <filename>
This directive specifies the file that contains the slapd server certificate. Certificates are generally public information and require no special protection.
11.2.1.4. TLSCertificateKeyFile <filename>
This directive specifies the file that contains the private key that matches the certificate stored in the TLSCertificateFile file. Private keys themselves are sensitive data and are usually password encrypted for protection. However, the current implementation doesn't support encrypted keys so the key must not be encrypted and the file itself must be protected carefully.
11.2.1.5. TLSCipherSuite <cipher-suite-spec>
This directive configures what ciphers will be accepted and the preference order. <cipher-suite-spec> should be a cipher specification for OpenSSL. You can use the command
openssl ciphers -v ALL
to obtain a verbose list of available cipher specifications. Besides the individual cipher names, the specifiers HIGH, MEDIUM, LOW, EXPORT, and EXPORT40 may be helpful, along with TLSv1, SSLv3, and SSLv2.
11.2.1.6. TLSRandFile <filename>
This directive specifies the file to obtain random bits from when /dev/urandom is not available. If the system provides /dev/urandom then this option is not needed, otherwise a source of random data must be configured. Some systems (e.g. Linux) provide /dev/urandom by default, while others (e.g. Solaris) require the installation of a patch to provide it, and others may not support it at all. In the latter case, EGD or PRNGD should be installed, and this directive should specify the name of the EGD/PRNGD socket. The environment variable RANDFILE can also be used to specify the filename. Also, in the absence of these options, the .rnd file in the slapd user's home directory may be used if it exists. To use the .rnd file, just create the file and copy a few hundred bytes of arbitrary data into the file. The file is only used to provide a seed for the pseudo-random number generator, and it doesn't need very much data to work.
11.2.1.7. TLSVerifyClient { never | allow | try | demand }
This directive specifies what checks to perform on client certificates in an incoming TLS session, if any. This option is set to never by default, in which case the server never asks the client for a certificate. With a setting of allow the server will ask for a client certificate; if none is provided the session proceeds normally. If a certificate is provided but the server is unable to verify it, the certificate is ignored and the session proceeds normally, as if no certificate had been provided. With a setting of try the certificate is requested, and if none is provided, the session proceeds normally. If a certificate is provided and it cannot be verified, the session is immediately terminated. With a setting of demand the certificate is requested and a valid certificate must be provided, otherwise the session is immediately terminated.
Note: The server must request a client certificate in order to use the SASL EXTERNAL authentication mechanism with a TLS session. As such, a non-default TLSVerifyClient setting must be configured before SASL EXTERNAL authentication may be attempted, and the SASL EXTERNAL mechanism will only be offered to the client if a valid client certificate was received.
11.2.2. Client Configuration
Most of the client configuration directives parallel the server directives. The names of the directives are different, and they go into ldap.conf(5) instead of slapd.conf(5), but their functionality is mostly the same. Also, while most of these options may be configured on a system-wide basis, they may all be overridden by individual users in their .ldaprc files.
11.2.2.1. TLS_CACERT <filename>
This is equivalent to the server's TLSCACertificateFile option. As noted in the TLS Configuration section, a client typically may need to know about more CAs than a server, but otherwise the same considerations apply.
11.2.2.2. TLS_CACERTDIR <path>
This is equivalent to the server's TLSCACertificatePath option. The specified directory must be managed with the OpenSSL c_rehash utility as well.
11.2.2.3. TLS_CERT <filename>
This directive specifies the file that contains the client certificate. This is a user-only directive and can only be specified in a user's .ldaprc file.
11.2.2.4. TLS_KEY <filename>
This directive specifies the file that contains the private key that matches the certificate stored in the TLS_CERT file. The same constraints mentioned for TLSCertificateKeyFile apply here. This is also a user-only directive.
11.2.2.5. TLS_RANDFILE <filename>
This directive is the same as the server's TLSRandFile option.
11.2.2.6. TLS_REQCERT { never | allow | try | demand }
This directive is equivalent to the server's TLSVerifyClient option. However, for clients the default value is demand and there generally is no good reason to change this setting.
11.2.2.7. TLS { never | hard }
This directive specifies whether client connections should use TLS by default. The default setting is never which specifies that connections will be opened in the clear unless TLS is explicitly specified using an "ldaps://" URL. When set to hard all connections will be established with TLS, as if an "ldaps://" URL was specified. Note that the use of ldaps is a holdover from LDAPv2 and this setting is incompatible with the LDAPv3 StartTLS request. As such, it's best not to use this option.