]> git.sur5r.net Git - openldap/blob - doc/guide/admin/tls.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / tls.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Using TLS
6
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}}.
12
13 Note: For generating certifcates, please reference {{URL:http://www.openldap.org/faq/data/cache/185.html}}
14
15 H2: TLS Certificates
16
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.
24
25 H3: Server Certificates
26
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
32 {{REF:RFC4513}}.
33
34 H3: Client Certificates
35
36 The DN of a client certificate can be used directly as an
37 authentication DN.
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
43 facility described in 
44 {{SECT:Mapping Authentication Identities}}
45 can be applied to these DNs as well.
46
47 H2: TLS Configuration
48
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.
56
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.
64
65 H3: Server Configuration
66
67 The configuration directives for slapd belong in the global directives
68 section of {{slapd.conf}}(5). 
69
70 H4: TLSCACertificateFile <filename>
71
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.
79
80 H4: TLSCACertificatePath <path>
81
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.
92
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:
96
97 >       certutil -d <path> -A -n "name of CA cert" -t CT,, -a -i /path/to/cacertfile.pem
98
99 . This command will add a CA certficate 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.
102
103 H4: TLSCertificateFile <filename>
104
105 This directive specifies the file that contains the slapd server
106 certificate. Certificates are generally public information and
107 require no special protection.
108
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:
112
113 >       TLSCertificateFile Server-Cert
114
115 . If using a token other than the internal built in token, specify the
116 . token name first, followed by a colon:
117
118 >       TLSCertificateFile my hardware device:Server-Cert
119
120 . Use {{EX:certutil -L}} to list the certificates by name:
121
122 >       certutil -d /path/to/certdbdir -L
123
124 H4: TLSCertificateKeyFile <filename>
125
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.
132
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 specifes /etc/openldap/certdb as the location of the cert/key database, use
138 modutil to change the password to the empty string:
139
140 >       modutil -dbdir /etc/openldap/certdb -changepw 'NSS Certificate DB'
141
142 . You must have the old password, if any.  Ignore the WARNING about the running
143 . browser.  Press 'Enter' for the new password.
144
145 H4: TLSCipherSuite <cipher-suite-spec>
146
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
150
151 >       openssl ciphers -v ALL
152
153 to obtain a verbose list of available cipher specifications.
154
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}},
158 and {{EX:SSLv2}}.
159
160 To obtain the list of ciphers in GnuTLS use:
161
162 >       gnutls-cli -l
163
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
168
169 >       static const SSLCipherSuiteInfo suiteInfo[]
170
171 H4: TLSRandFile <filename>
172
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.
188
189 This directive is ignored with GnuTLS and Mozilla NSS.
190
191 H4: TLSEphemeralDHParamFile <filename>
192
193 This directive specifies the file that contains parameters for
194 Diffie-Hellman ephemeral key exchange.  This is required in order
195 to use a DSA certificate on the server side (i.e.
196 {{EX:TLSCertificateKeyFile}} points to a DSA key).  Multiple sets
197 of parameters can be included in the file; all of them will be
198 processed.  Parameters can be generated using the following command
199
200 >       openssl dhparam [-dsaparam] -out <filename> <numbits>
201
202 This directive is ignored with GnuTLS and Mozilla NSS.
203
204 H4: TLSVerifyClient { never | allow | try | demand }
205
206 This directive specifies what checks to perform on client certificates
207 in an incoming TLS session, if any. This option is set to {{EX:never}}
208 by default, in which case the server never asks the client for a
209 certificate. With a setting of {{EX:allow}} the server will ask
210 for a client certificate; if none is provided the session proceeds
211 normally. If a certificate is provided but the server is unable to
212 verify it, the certificate is ignored and the session proceeds
213 normally, as if no certificate had been provided. With a setting of
214 {{EX:try}} the certificate is requested, and if none is provided,
215 the session proceeds normally. If a certificate is provided and it
216 cannot be verified, the session is immediately terminated. With a
217 setting of {{EX:demand}} the certificate is requested and a valid
218 certificate must be provided, otherwise the session is immediately
219 terminated.
220
221 Note: The server must request a client certificate in order to
222 use the SASL EXTERNAL authentication mechanism with a TLS session.
223 As such, a non-default {{EX:TLSVerifyClient}} setting must be configured
224 before SASL EXTERNAL authentication may be attempted, and the
225 SASL EXTERNAL mechanism will only be offered to the client if a valid
226 client certificate was received.
227
228 H3: Client Configuration
229
230 Most of the client configuration directives parallel the server
231 directives. The names of the directives are different, and they go
232 into {{ldap.conf}}(5) instead of {{slapd.conf}}(5), but their
233 functionality is mostly the same. Also, while most of these options may
234 be configured on a system-wide basis, they may all be overridden by
235 individual users in their {{.ldaprc}} files.
236
237 The LDAP Start TLS operation is used in LDAP to initiate TLS
238 negotiation.  All OpenLDAP command line tools support a {{EX:-Z}}
239 and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to
240 be issued.  The latter flag indicates that the tool is to cease
241 processing if TLS cannot be started while the former allows the
242 command to continue.
243
244 In LDAPv2 environments, TLS is normally started using the LDAP
245 Secure URI scheme ({{EX:ldaps://}}) instead of the normal LDAP URI
246 scheme ({{EX:ldap://}}).  OpenLDAP command line tools allow either
247 scheme to used with the {{EX:-H}} flag and with the {{EX:URI}}
248 {{ldap.conf}}(5) option.
249
250
251 H4: TLS_CACERT <filename>
252
253 This is equivalent to the server's {{EX:TLSCACertificateFile}} option. As
254 noted in the {{SECT:TLS Configuration}} section, a client typically
255 may need to know about more CAs than a server, but otherwise the
256 same considerations apply.
257
258 H4: TLS_CACERTDIR <path>
259
260 This is equivalent to the server's {{EX:TLSCACertificatePath}} option. The
261 specified directory must be managed with the OpenSSL {{c_rehash}}
262 utility as well.  If using Mozilla NSS, <path> may contain a cert/key database.
263
264 H4: TLS_CERT <filename>
265
266 This directive specifies the file that contains the client certificate.
267 This is a user-only directive and can only be specified in a user's
268 {{.ldaprc}} file.
269
270 When using Mozilla NSS, if using a cert/key database (specified with
271 {{EX:TLS_CACERTDIR}}), this directive specifies
272 the name of the certificate to use:
273
274 >       TLS_CERT Certificate for Sam Carter
275
276 . If using a token other than the internal built in token, specify the
277 . token name first, followed by a colon:
278
279 >       TLS_CERT my hardware device:Certificate for Sam Carter
280
281 . Use {{EX:certutil -L}} to list the certificates by name:
282
283 >       certutil -d /path/to/certdbdir -L
284
285
286 H4: TLS_KEY <filename>
287
288 This directive specifies the file that contains the private key
289 that matches the certificate stored in the {{EX:TLS_CERT}}
290 file. The same constraints mentioned for {{EX:TLSCertificateKeyFile}}
291 apply here. This is also a user-only directive.
292
293 H4: TLS_RANDFILE <filename>
294
295 This directive is the same as the server's {{EX:TLSRandFile}}
296 option.
297
298 H4: TLS_REQCERT { never | allow | try | demand }
299
300 This directive is equivalent to the server's {{EX:TLSVerifyClient}}
301 option. However, for clients the default value is {{EX:demand}}
302 and there generally is no good reason to change this setting.
303