2 # Copyright 1999-2018 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
7 OpenLDAP clients and servers are capable of using the
8 {{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide
9 integrity and confidentiality protections and to support
10 LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism.
11 TLS is defined in {{REF:RFC4346}}.
13 Note: For generating certificates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}}
17 TLS uses {{TERM:X.509}} certificates to carry client and server
18 identities. All servers are required to have valid certificates,
19 whereas client certificates are optional. Clients must have a
20 valid certificate in order to authenticate via SASL EXTERNAL.
21 For more information on creating and managing certificates,
22 see the {{PRD:OpenSSL}}, {{PRD:GnuTLS}}, or {{PRD:MozNSS}} documentation,
23 depending on which TLS implementation libraries you are using.
25 H3: Server Certificates
27 The {{TERM:DN}} of a server certificate must use the {{EX:CN}}
28 attribute to name the server, and the {{EX:CN}} must carry the
29 server's fully qualified domain name. Additional alias names and
30 wildcards may be present in the {{EX:subjectAltName}} certificate
31 extension. More details on server certificate names are in
34 H3: Client Certificates
36 The DN of a client certificate can be used directly as an
38 Since X.509 is a part of the {{TERM:X.500}} standard and LDAP
39 is also based on X.500, both use the same DN formats and
40 generally the DN in a user's X.509 certificate should be
41 identical to the DN of their LDAP entry. However, sometimes
42 the DNs may not be exactly the same, and so the mapping
44 {{SECT:Mapping Authentication Identities}}
45 can be applied to these DNs as well.
49 After obtaining the required certificates, a number of options must
50 be configured on both the client and the server to enable TLS and
51 make use of the certificates. At a minimum, the clients must be
52 configured with the name of the file containing all of the
53 {{TERM[expand]CA}} (CA) certificates it will trust. The server must
54 be configured with the {{TERM:CA}} certificates and also its own
55 server certificate and private key.
57 Typically a single CA will have issued the server certificate
58 and all of the trusted client certificates, so the server only
59 needs to trust that one signing CA. However, a client may wish
60 to connect to a variety of secure servers managed by different
61 organizations, with server certificates generated by many
62 different CAs. As such, a client is likely to need a list of
63 many different trusted CAs in its configuration.
65 H3: Server Configuration
67 The configuration directives for slapd belong in the global directives
68 section of {{slapd.conf}}(5).
70 H4: TLSCACertificateFile <filename>
72 This directive specifies the {{TERM:PEM}}-format file containing
73 certificates for the CA's that slapd will trust. The certificate for
74 the CA that signed the server certificate must be included among
75 these certificates. If the signing CA was not a top-level (root) CA,
76 certificates for the entire sequence of CA's from the signing CA to
77 the top-level CA should be present. Multiple certificates are simply
78 appended to the file; the order is not significant.
80 H4: TLSCACertificatePath <path>
82 This directive specifies the path of a directory that contains
83 individual {{TERM:CA}} certificates in separate files. In addition,
84 this directory must be specially managed using the OpenSSL {{c_rehash}}
85 utility. When using this feature, the OpenSSL library will attempt to
86 locate certificate files based on a hash of their name and serial number.
87 The {{c_rehash}} utility is used to generate symbolic links with the
88 hashed names that point to the actual certificate files. As such,
89 this option can only be used with a filesystem that actually supports
90 symbolic links. In general, it is simpler to use the
91 {{EX:TLSCACertificateFile}} directive instead.
93 When using Mozilla NSS, this directive can be used to specify the
94 path of the directory containing the NSS certificate and key database
95 files. The {{certutil}} command can be used to add a {{TERM:CA}} certificate:
97 > certutil -d <path> -A -n "name of CA cert" -t CT,, -a -i /path/to/cacertfile.pem
99 . This command will add a CA certificate stored in the PEM (ASCII) formatted
100 . file named /path/to/cacertfile.pem. {{EX:-t CT,,}} means that the certificate is
101 . trusted to be a CA issuing certs for use in TLS clients and servers.
103 H4: TLSCertificateFile <filename>
105 This directive specifies the file that contains the slapd server
106 certificate. Certificates are generally public information and
107 require no special protection.
109 When using Mozilla NSS, if using a cert/key database (specified with
110 {{EX:TLSCACertificatePath}}), this directive specifies
111 the name of the certificate to use:
113 > TLSCertificateFile Server-Cert
115 . If using a token other than the internal built in token, specify the
116 . token name first, followed by a colon:
118 > TLSCertificateFile my hardware device:Server-Cert
120 . Use {{EX:certutil -L}} to list the certificates by name:
122 > certutil -d /path/to/certdbdir -L
124 H4: TLSCertificateKeyFile <filename>
126 This directive specifies the file that contains the private key
127 that matches the certificate stored in the {{EX:TLSCertificateFile}}
128 file. Private keys themselves are sensitive data and are usually
129 password encrypted for protection. However, the current implementation
130 doesn't support encrypted keys so the key must not be encrypted
131 and the file itself must be protected carefully.
133 When using Mozilla NSS, this directive specifies the name of
134 a file that contains the password for the key for the certificate specified with
135 {{EX:TLSCertificateFile}}. The modutil command can be used to turn off password
136 protection for the cert/key database. For example, if {{EX:TLSCACertificatePath}}
137 specifies /etc/openldap/certdb as the location of the cert/key database, use
138 modutil to change the password to the empty string:
140 > modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB'
142 . You must have the old password, if any. Ignore the WARNING about the running
143 . browser. Press 'Enter' for the new password.
145 H4: TLSCipherSuite <cipher-suite-spec>
147 This directive configures what ciphers will be accepted and the
148 preference order. {{EX:<cipher-suite-spec>}} should be a cipher
149 specification for OpenSSL. You can use the command
151 > openssl ciphers -v ALL
153 to obtain a verbose list of available cipher specifications.
155 Besides the individual cipher names, the specifiers {{EX:HIGH}},
156 {{EX:MEDIUM}}, {{EX:LOW}}, {{EX:EXPORT}}, and {{EX:EXPORT40}}
157 may be helpful, along with {{EX:TLSv1}}, {{EX:SSLv3}},
160 To obtain the list of ciphers in GnuTLS use:
164 When using Mozilla NSS, the OpenSSL cipher suite specifications are used and
165 translated into the format used internally by Mozilla NSS. There isn't an easy
166 way to list the cipher suites from the command line. The authoritative list
167 is in the source code for Mozilla NSS in the file sslinfo.c in the structure
169 > static const SSLCipherSuiteInfo suiteInfo[]
171 H4: TLSRandFile <filename>
173 This directive specifies the file to obtain random bits from when
174 {{FILE:/dev/urandom}} is not available. If the system provides
175 {{FILE:/dev/urandom}} then this option is not needed, otherwise a
176 source of random data must be configured. Some systems (e.g. Linux)
177 provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris)
178 require the installation of a patch to provide it, and others may
179 not support it at all. In the latter case, EGD or PRNGD should be
180 installed, and this directive should specify the name of the EGD/PRNGD
181 socket. The environment variable {{EX:RANDFILE}} can also be used
182 to specify the filename. Also, in the absence of these options, the
183 {{EX:.rnd}} file in the slapd user's home directory may be used if
184 it exists. To use the {{EX:.rnd}} file, just create the file and
185 copy a few hundred bytes of arbitrary data into the file. The file
186 is only used to provide a seed for the pseudo-random number generator,
187 and it doesn't need very much data to work.
189 This directive is ignored with GnuTLS and Mozilla NSS.
191 H4: TLSDHParamFile <filename>
193 This directive specifies the file that contains parameters for
194 Diffie-Hellman ephemeral key exchange. This is required in order
195 to use DHE-based cipher suites, including all DSA-based suites (i.e.
196 {{EX:TLSCertificateKeyFile}} points to a DSA key), and RSA when the 'key
197 encipherment' key usage is not specified in the certificate. Parameters can be
198 generated using the following command
200 > openssl dhparam [-dsaparam] -out <filename> <numbits>
202 > certtool --generate-dh-params --bits <numbits> --outfile <filename>
204 This directive is ignored with Mozilla NSS.
208 This directive specifies the curve to use for Elliptic Curve
209 Diffie-Hellman ephemeral key exchange. This is required in order
210 to use ECDHE-based cipher suites in OpenSSL. The names of supported
211 curves may be shown using the following command
213 > openssl ecparam -list_curves
215 This directive is not used for GnuTLS and is ignored with Mozilla NSS.
216 For GnuTLS the curves may be specified in the ciphersuite.
218 H4: TLSVerifyClient { never | allow | try | demand }
220 This directive specifies what checks to perform on client certificates
221 in an incoming TLS session, if any. This option is set to {{EX:never}}
222 by default, in which case the server never asks the client for a
223 certificate. With a setting of {{EX:allow}} the server will ask
224 for a client certificate; if none is provided the session proceeds
225 normally. If a certificate is provided but the server is unable to
226 verify it, the certificate is ignored and the session proceeds
227 normally, as if no certificate had been provided. With a setting of
228 {{EX:try}} the certificate is requested, and if none is provided,
229 the session proceeds normally. If a certificate is provided and it
230 cannot be verified, the session is immediately terminated. With a
231 setting of {{EX:demand}} the certificate is requested and a valid
232 certificate must be provided, otherwise the session is immediately
235 Note: The server must request a client certificate in order to
236 use the SASL EXTERNAL authentication mechanism with a TLS session.
237 As such, a non-default {{EX:TLSVerifyClient}} setting must be configured
238 before SASL EXTERNAL authentication may be attempted, and the
239 SASL EXTERNAL mechanism will only be offered to the client if a valid
240 client certificate was received.
242 H3: Client Configuration
244 Most of the client configuration directives parallel the server
245 directives. The names of the directives are different, and they go
246 into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their
247 functionality is mostly the same. Also, while most of these options may
248 be configured on a system-wide basis, they may all be overridden by
249 individual users in their {{.ldaprc}} files.
251 The LDAP Start TLS operation is used in LDAP to initiate TLS
252 negotiation. All OpenLDAP command line tools support a {{EX:-Z}}
253 and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to
254 be issued. The latter flag indicates that the tool is to cease
255 processing if TLS cannot be started while the former allows the
258 In LDAPv2 environments, TLS is normally started using the LDAP
259 Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI
260 scheme ({{EX:ldap://}}). OpenLDAP command line tools allow either
261 scheme to used with the {{EX:-H}} flag and with the {{EX:URI}}
262 {{ldap.conf}}(5) option.
265 H4: TLS_CACERT <filename>
267 This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As
268 noted in the {{SECT:TLS Configuration}} section, a client typically
269 may need to know about more CAs than a server, but otherwise the
270 same considerations apply.
272 H4: TLS_CACERTDIR <path>
274 This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
275 specified directory must be managed with the OpenSSL {{c_rehash}}
276 utility as well. If using Mozilla NSS, <path> may contain a cert/key database.
278 H4: TLS_CERT <filename>
280 This directive specifies the file that contains the client certificate.
281 This is a user-only directive and can only be specified in a user's
284 When using Mozilla NSS, if using a cert/key database (specified with
285 {{EX:TLS_CACERTDIR}}), this directive specifies
286 the name of the certificate to use:
288 > TLS_CERT Certificate for Sam Carter
290 . If using a token other than the internal built in token, specify the
291 . token name first, followed by a colon:
293 > TLS_CERT my hardware device:Certificate for Sam Carter
295 . Use {{EX:certutil -L}} to list the certificates by name:
297 > certutil -d /path/to/certdbdir -L
300 H4: TLS_KEY <filename>
302 This directive specifies the file that contains the private key
303 that matches the certificate stored in the {{EX:TLS_CERT}}
304 file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}}
305 apply here. This is also a user-only directive.
307 H4: TLS_RANDFILE <filename>
309 This directive is the same as the server's {{EX:TLSRandFile}}
312 H4: TLS_REQCERT { never | allow | try | demand }
314 This directive is equivalent to the server's {{EX:TLSVerifyClient}}
315 option. However, for clients the default value is {{EX:demand}}
316 and there generally is no good reason to change this setting.