Chapter 6. OpenLDAP ldap.conf
The ldap.conf configuration file contains information and configuration directives used by OpenLDAP clients including where appropriate OpenLDAP utilities and is read and used by slapd when operating in client-mode, such as when acting as a consumer in a master-slave or multi-master replication configuration, the provider function in these configurations uses the values defined in cn=config (slapd.conf).
Note: Incomplete list covers only those parameters used by olcSyncrepl/syncrepl.
TLS Directives
Which TLS Client directives are used depends upon whether the TLS Client will send an X.509 certificate and validate a TLS Server certificate in which case most of the directives are required - or only validate a TLS Server certificate in which case only the TLS_CACERT and optionally the TLS_CIPHER_SUITE directives are required. The required directives used when sending a client certificate are indicated by the keyword MUTUAL (since the server will always send a certificate) and if the client only needs to validate a server certificate CLIENT.
TLS_CACERT
TLS_CACERT /path/to/file.ext
CLIENT+MUTUAL. Defines the file containing the Certicate Authority (CA) certificate (a.k.a the root certificate) and allows the client to valdate the LDAP Server certificate. This file is required if either a self-signed or a commercial certicate is being used and the root certicate must be obtained from the X.509 certificate supplier or, if self-signed, copied from an appropriate location. This file is normally in PEM (Privacy enhanced Mail) format (and typically has a .pem suffix/extension or , if obtained from an MSIE browser installation, have a .cer suffix/extension). If the operational X.509 certificate (defined in TLSCertificateFile) is signed by intermediate authorities then all these certificates must be present within this PEM format file. PEM is a text format and multiple certificates can be edited into the same file in any order - see PEM format notes and samples. OpenLDAP self-signed certificate configuration examples. This file contains no sensitive information (an X.509 certificate contains only a public key).
TLS_CACERTDIR
TLS_CACERTDIR /path/to/directory
CLIENT+MUTUAL. Defines the path to a Trusted Keystore managed either by Mozilla's NSS or OpenSSL. Unnecessary if TLS_CACERT defined, but if both are present TLS_CACERT is tried first.
TLS_CERT
TLS_CERT /path/to/file.ext
MUTUAL. Defines the path to an X.509 certificate file that will be sent to the server in a mutual authetication exchange. Typically in PEM format (with .pem or .cer suffix/extension). This file contains no sensitive information (an X.509 certificate contains only a public key).
TLS_CIPHER_SUITE
TLS_CIPHER_SUITE cipher-list
CLIENT+MUTUAL. This is an optional directive and defaults to the value ALL (equivalent of openssl ciphers -v ALL). Defines one or more cipher suites to be used during the TLS handshake negotiation. During this negotiation the TLS Client offers a list of cipher suites and the TLS server will accept the first cipher suite defined in its list that matches one from the client. The term cipher-list used in this directive description defines a list (in OpenSSL format) that will be converted by OpenSSL libraries to a list of cipher suites in TLS/SSL format. More information about the cipher-list format may be obtained from the OpenSSL ciphers documentation. OpenLDAP self-signed certificate configuration examples.
The list of acceptable cipher-suites (and hence the cipher-list) is determined by the format of the public key contained within the X.509 certificate defined by the TLS_CERT directive if the TLS Client will send a certificate or will be obtained from the TLS Servers certificate if only Server certificate validation is to be performed or by both if mutual cerrtificate exchange takes place. Thus if the certificate(s) contain an RSA public key then only RSA public key cipher suites can be used for the key-exchange/authentication parts of the TLS handshake. If the incoming TLS Server certificate public-key encryption algorithm is unknown then ALL should be used (see commands below). Individual items in the cipher-list are separated by a colon (:), comma or space. The following is a subset of RSA TLSv1 names that could appear in a cipher-list and their equivalent TLS cipher suite text values (they are converted to hex values when sent on the wire). Note: The word EXPORT (or EXP) that appears in some of the following names refers to export strength ciphers, that is, some ciphers are only permitted in certain countries (see US Dept of Commerce Bureau of Industry and Security(BIS) and the Wassenaar Arrangement) and should be considered when configuring TLS systems that will be used internationally.
TLS CIPHER-SUITE NAME OPENSSL CIPHER-LIST NAME
============================== ===================
TLS_RSA_WITH_NULL_MD5 NULL-MD5
TLS_RSA_WITH_NULL_SHA NULL-SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
TLS_RSA_WITH_RC4_128_SHA RC4-SHA
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA
TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA
To list the cipher-list values supported by the local OpenSSL installation use:
# ALL valid ciphers
openssl ciphers -v ALL
# ALL valid ciphers for TLSv1 only
openssl ciphers -v -tls1 ALL
# valid ciphers for TLSv1 only that use RSA
# key exchange/authentication algorithm
openssl ciphers -v -tls1 RSA
# valid ciphers for TLSv1 only that use RSA
# key exchange/authentication algorithm
# exclude export strength ciphers
openssl ciphers -v -tls1 RSA:!EXP
# NOTE: on certain shells you need to escape !
openssl ciphers -v -tls1 RSA:\!EXP
# as above but also exclude NULL suites
openssl ciphers -v -tls1 RSA:!EXP:!NULL
# NOTE: on certain shells you need to escape !
openssl ciphers -v -tls1 RSA:\!EXP:\!NULL
# valid ciphers for TLSv1 only that use RSA
# key exchange/authentication algorithm
# only export strength ciphers
openssl ciphers -v -tls1 RSA:EXP
# OR
openssl ciphers -v TLSv1+RSA:EXP
When used with TLS_CIPHER_SUITE either the generic parameters, for example RSA, shown with the openssl ciphers command above can be used (in which case the order of preference is defined by openssl) or an explicit list of ciphers can be defined in order of preference. One or more of the supported items in the cipher-list must be supported by the TLS Server. The cipher suite matching algorithm (which cipher suite is selected) is the first (highest preference) cipher suite provided by the client which is also supported by the server becomes the negotiated (session) cipher suite. The following examples use the TLSv1 (SSLv3) subset only:
# Cipher-list contains only RSA based
# authentication and key-exchange suites
# supported by TLSv1 (and SSLv3)
TLS_CIPHER_SUITE TLSv1+RSA
# Cipher-list contains only RSA based
# authentication and key-exchange suites
# supported by TLSv1 (and SSLv3)
# excludes EXPORT and NULL suites
TLS_CIPHER_SUITE TLSv1+RSA:!EXPORT:!NULL
# Ordered list of RSA based
# authentication and key-exchange suites
TLS_CIPHER_SUITE DES-CBC-SHA:DES-CBC3-SHA:RC4-SHA:RC4-MD5
# All ciphers excluding NULL
TLS_CIPHER_SUITE ALL:!NULL
# Default equivalent value if not defined
TLS_CIPHER_SUITE ALL
Note: OpenSSL supports a number of cipher suites which will result in a NULL bulk data cipher and MAC. This means that while authentication is performed securely all data is subsequently sent in the clear. To prevent this from occurring either use the !NULL value in the cipher-list or define an explicit list that excludes NULL ciphers.
TLS_CRLCHECK
TLS_CRLCHECK none|peer|all
CLIENT+MUTUAL. Only relevant if OpenLDAP built with OpenSSl's CRL processing option. May take the value none (default - no CRL checking), peer (only the peer certificate is checked) or all (the whole certificate chain is checked).
TLS_CRLFILE
TLS_CRLFILE /path/to/crl/file.ext
CLIENT+MUTUAL. Only relevant if OpenLDAP built with GNU utils. Defines the path to a Certificate Revokation List (CRL).
TLS_KEY
TLS_CRLKEY /path/to/key/file.ext
MUTUAL. Only relevant if the client sends a certificate to the peer in a mutual authentication sequence - it must be present if TLS_CERT is present. It defines the path to a file containing the private key associate with the certficate defined in TLS_CERT. May be in PEM (typically .pem or .key). When used with OpenSSL this file must NOT be password protected (key file are typically password protected due to the nature of their content). To remove the password, use a command similar to that shown:
# PEM format files
# password is requested to perform key removal
# copy file2.key to OpenLAP server location
# with minimal permssions
openssl rsa -in [file1.key] -out [file2.key]
Note: A password-less key file is extremely dangerous - if knowningly read the certificate is compromised. It should be secured with minimal access permissions on the server (0640 for user/group that runs slapd).
TLS_REQCERT
TLS_REQCERT never|allow|try|demand|hard
CLIENT+MUTUAL. Optional, if omitted it defaults to demand. Indicates how the client handles receipt (or not) of the server's certificate. May be never (client will not request a server certificate but if received will ignore and continue connection), allow (client wiil request a certificate but connection will continue if none received and will ignore any certificate validation failure), try (client will request a certicate but connection will continue if none received but will terminate cconnection if there is a certificate validation failure), demand (client will request a certicate but connection will be terminated if none received or there is a certificate validation failure) or hard (synonym for demand).
Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.
