]> git.sur5r.net Git - openldap/blob - doc/guide/admin/security.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / security.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
3 # Portions Copyright 2008 Andrew Findlay.
4 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5
6 H1: Security Considerations
7
8 OpenLDAP Software is designed to run in a wide variety of computing
9 environments from tightly-controlled closed networks to the global
10 Internet.  Hence, OpenLDAP Software supports many different security
11 mechanisms.  This chapter describes these mechanisms and discusses
12 security considerations for using OpenLDAP Software.
13
14 H2: Network Security
15
16 H3: Selective Listening
17
18 By default, {{slapd}}(8) will listen on both the IPv4 and IPv6 "any"
19 addresses.  It is often desirable to have {{slapd}} listen on select
20 address/port pairs.  For example, listening only on the IPv4 address
21 {{EX:127.0.0.1}} will disallow remote access to the directory server.
22 E.g.:
23
24 >       slapd -h ldap://127.0.0.1
25
26 While the server can be configured to listen on a particular interface
27 address, this doesn't necessarily restrict access to the server to
28 only those networks accessible via that interface.   To selective
29 restrict remote access, it is recommend that an {{SECT:IP Firewall}}
30 be used to restrict access.
31
32 See {{SECT:Command-line Options}} and {{slapd}}(8) for more
33 information.
34
35
36 H3: IP Firewall
37
38 {{TERM:IP}} firewall capabilities of the server system can be used
39 to restrict access based upon the client's IP address and/or network
40 interface used to communicate with the client.
41
42 Generally, {{slapd}}(8) listens on port 389/tcp for {{F:ldap://}}
43 sessions and port 636/tcp for {{F:ldaps://}}) sessions.  {{slapd}}(8)
44 may be configured to listen on other ports.
45
46 As specifics of how to configure IP firewall are dependent on the
47 particular kind of IP firewall used, no examples are provided here.
48 See the document associated with your IP firewall.
49
50
51 H3: TCP Wrappers
52
53 {{slapd}}(8) supports {{TERM:TCP}} Wrappers.  TCP Wrappers provide
54 a rule-based access control system for controlling TCP/IP access
55 to the server.  For example, the {{host_options}}(5) rule:
56
57 >       slapd: 10.0.0.0/255.0.0.0 127.0.0.1 : ALLOW
58 >       slapd: ALL : DENY
59
60 allows only incoming connections from the private network {{F:10.0.0.0}}
61 and localhost ({{F:127.0.0.1}}) to access the directory service.
62
63 Note: IP addresses are used as {{slapd}}(8) is not normally
64 configured to perform reverse lookups.
65
66 It is noted that TCP wrappers require the connection to be accepted.
67 As significant processing is required just to deny a connection,
68 it is generally advised that IP firewall protection be used instead
69 of TCP wrappers.
70
71 See {{hosts_access}}(5) for more information on TCP wrapper rules.
72
73
74 H2: Data Integrity and Confidentiality Protection
75
76 {{TERM[expand]TLS}} (TLS) can be used to provide data integrity and
77 confidentiality protection.  OpenLDAP supports negotiation of
78 {{TERM:TLS}} ({{TERM:SSL}}) via both StartTLS and {{F:ldaps://}}.
79 See the {{SECT:Using TLS}} chapter for more information.  StartTLS
80 is the standard track mechanism.
81
82 A number of {{TERM[expand]SASL}} (SASL) mechanisms, such as
83 {{TERM:DIGEST-MD5}} and {{TERM:GSSAPI}}, also provide data integrity
84 and confidentiality protection.  See the {{SECT:Using SASL}} chapter
85 for more information.
86
87
88 H3: Security Strength Factors
89
90 The server uses {{TERM[expand]SSF}}s (SSF) to indicate the relative
91 strength of protection.  A SSF of zero (0) indicates no protections
92 are in place.  A SSF of one (1) indicates integrity protection are
93 in place.  A SSF greater than one (>1) roughly correlates to the
94 effective encryption key length.  For example, {{TERM:DES}} is 56,
95 {{TERM:3DES}} is 112, and {{TERM:AES}} 128, 192, or 256.
96
97 A number of administrative controls rely on SSFs associated with
98 TLS and SASL protection in place on an LDAP session.
99
100 {{EX:security}} controls disallow operations when appropriate
101 protections are not in place.  For example:
102
103 >       security ssf=1 update_ssf=112
104
105 requires integrity protection for all operations and encryption
106 protection, 3DES equivalent, for update operations (e.g. add, delete,
107 modify, etc.).  See {{slapd.conf}}(5) for details.
108
109 For fine-grained control, SSFs may be used in access controls.
110 See the {{SECT:Access Control}} section for more information.
111
112
113 H2: Authentication Methods
114
115 H3: "simple" method
116
117 The LDAP "simple" method has three modes of operation:
118
119 * anonymous,
120 * unauthenticated, and
121 * user/password authenticated.
122
123 Anonymous access is requested by providing no name and no password
124 to the "simple" bind operation.  Unauthenticated access is requested
125 by providing a name but no password.  Authenticated access is
126 requested by providing a valid name and password.
127
128 An anonymous bind results in an {{anonymous}} authorization
129 association.  Anonymous bind mechanism is enabled by default, but
130 can be disabled by specifying "{{EX:disallow bind_anon}}" in
131 {{slapd.conf}}(5).  
132
133 Note: Disabling the anonymous bind mechanism does not prevent 
134 anonymous access to the directory. To require authentication to 
135 access the directory, one should instead specify "{{EX:require authc}}".
136
137 An unauthenticated bind also results in an {{anonymous}} authorization
138 association.  Unauthenticated bind mechanism is disabled by default,
139 but can be enabled by specifying "{{EX:allow bind_anon_cred}}" in
140 {{slapd.conf}}(5).  As a number of LDAP applications mistakenly
141 generate unauthenticated bind request when authenticated access was
142 intended (that is, they do not ensure a password was provided),
143 this mechanism should generally remain disabled.
144
145 A successful user/password authenticated bind results in a user
146 authorization identity, the provided name, being associated with
147 the session.  User/password authenticated bind is enabled by default.
148 However, as this mechanism itself offers no eavesdropping protection
149 (e.g., the password is set in the clear), it is recommended that
150 it be used only in tightly controlled systems or when the LDAP
151 session is protected by other means (e.g., TLS, {{TERM:IPsec}}).
152 Where the administrator relies on TLS to protect the password, it
153 is recommended that unprotected authentication be disabled.  This
154 is done using the {{EX:security}} directive's {{EX:simple_bind}}
155 option, which provides fine grain control over the level of confidential
156 protection to require for {{simple}} user/password authentication.
157 E.g., using {{EX:security simple_bind=56}} would require {{simple}}
158 binds to use encryption of DES equivalent or better.
159
160 The user/password authenticated bind mechanism can be completely
161 disabled by setting "{{EX:disallow bind_simple}}".
162
163 Note: An unsuccessful bind always results in the session having
164 an {{anonymous}} authorization association.
165
166
167 H3: SASL method
168
169 The LDAP {{TERM:SASL}} method allows the use of any SASL authentication
170 mechanism. The {{SECT:Using SASL}} section discusses the use of SASL.
171
172 H2: Password Storage
173
174 LDAP passwords are normally stored in the {{userPassword}} attribute.
175 {{REF:RFC4519}} specifies that passwords are not stored in encrypted
176 (or hashed) form.  This allows a wide range of password-based
177 authentication mechanisms, such as {{EX:DIGEST-MD5}} to be used.
178 This is also the most interoperable storage scheme.
179
180 However, it may be desirable to store a hash of password instead.
181 {{slapd}}(8) supports a variety of storage schemes for the administrator
182 to choose from.
183
184 Note: Values of password attributes, regardless of storage scheme
185 used, should be protected as if they were clear text.  Hashed
186 passwords are subject to {{dictionary attacks}} and {{brute-force
187 attacks}}.
188
189 The {{userPassword}} attribute is allowed to have more than one value,
190 and it is possible for each value to be stored in a different form.
191 During authentication, {{slapd}} will iterate through the values
192 until it finds one that matches the offered password or until it
193 runs out of values to inspect.  The storage scheme is stored as a prefix
194 on the value, so a hashed password using the Salted SHA1 ({{EX:SSHA}})
195 scheme looks like:
196
197 > userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
198
199 The advantage of hashed passwords is that an attacker which
200 discovers the hash does not have direct access to the actual password.
201 Unfortunately, as dictionary and brute force attacks are generally
202 quite easy for attackers to successfully mount, this advantage is
203 marginal at best (this is why all modern Unix systems use shadow
204 password files).
205
206 The disadvantages of hashed storage is that they are non-standard, may
207 cause interoperability problem, and generally preclude the use
208 of stronger than Simple (or SASL/PLAIN) password-based authentication
209 mechanisms such as {{EX:DIGEST-MD5}}.
210
211 H3: SSHA password storage scheme
212
213 This is the salted version of the SHA scheme. It is believed to be the
214 most secure password storage scheme supported by {{slapd}}.
215
216 These values represent the same password:
217
218 > userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
219 > userPassword: {SSHA}d0Q0626PSH9VUld7yWpR0k6BlpQmtczb
220
221 H3: CRYPT password storage scheme
222
223 This scheme uses the operating system's {{crypt(3)}} hash function.
224 It normally produces the traditional Unix-style 13 character hash, but
225 on systems with {{EX:glibc2}} it can also generate the more secure
226 34-byte MD5 hash.
227
228 > userPassword: {CRYPT}aUihad99hmev6
229 > userPassword: {CRYPT}$1$czBJdDqS$TmkzUAb836oMxg/BmIwN.1
230
231 The advantage of the CRYPT scheme is that passwords can be
232 transferred to or from an existing Unix password file without having
233 to know the cleartext form. Both forms of {{crypt}} include salt so
234 they have some resistance to dictionary attacks.
235
236 Note: Since this scheme uses the operating system's {{crypt(3)}}
237 hash function, it is therefore operating system specific.
238
239 H3: MD5 password storage scheme
240
241 This scheme simply takes the MD5 hash of the password and stores it in
242 base64 encoded form:
243
244 > userPassword: {MD5}Xr4ilOzQ4PCOq3aQ0qbuaQ==
245
246 Although safer than cleartext storage, this is not a very secure
247 scheme. The MD5 algorithm is fast, and because there is no salt the
248 scheme is vulnerable to a dictionary attack.
249
250 H3: SMD5 password storage scheme
251
252 This improves on the basic MD5 scheme by adding salt (random data
253 which means that there are many possible representations of a given
254 plaintext password). For example, both of these values represent the
255 same password:
256
257 > userPassword: {SMD5}4QWGWZpj9GCmfuqEvm8HtZhZS6E=
258 > userPassword: {SMD5}g2/J/7D5EO6+oPdklp5p8YtNFk4=
259
260 H3: SHA password storage scheme
261
262 Like the MD5 scheme, this simply feeds the password through an SHA
263 hash process. SHA is thought to be more secure than MD5, but the lack
264 of salt leaves the scheme exposed to dictionary attacks.
265
266 > userPassword: {SHA}5en6G6MezRroT3XKqkdPOmY/BfQ=
267
268 H3: SASL password storage scheme
269
270 This is not really a password storage scheme at all. It uses the
271 value of the {{userPassword}} attribute to delegate password
272 verification to another process. See below for more information.
273
274 Note: This is not the same as using SASL to authenticate the LDAP
275 session.
276
277 H2: Pass-Through authentication
278
279 Since OpenLDAP 2.0 {{slapd}} has had the ability to delegate password
280 verification to a separate process. This uses the {{sasl_checkpass(3)}}
281 function so it can use any back-end server that Cyrus SASL supports for
282 checking passwords. The choice is very wide, as one option is to use
283 {{saslauthd(8)}} which in turn can use local files, Kerberos, an IMAP
284 server, another LDAP server, or anything supported by the PAM mechanism.
285
286 The server must be built with the {{EX:--enable-spasswd}}
287 configuration option to enable pass-through authentication.
288
289 Note: This is not the same as using a SASL mechanism to
290 authenticate the LDAP session.
291
292 Pass-Through authentication works only with plaintext passwords, as 
293 used in the "simple bind" and "SASL PLAIN" authentication mechanisms.}}
294
295 Pass-Through authentication is selective: it only affects users whose
296 {{userPassword}} attribute has a value marked with the "{SASL}"
297 scheme. The format of the attribute is:
298
299 > userPassword: {SASL}username@realm
300
301 The {{username}} and {{realm}} are passed to the SASL authentication
302 mechanism and are used to identify the account whose password is to be
303 verified. This allows arbitrary mapping between entries in OpenLDAP
304 and accounts known to the backend authentication service.
305
306 It would be wise to use access control to prevent users from changing 
307 their passwords through LDAP where they have pass-through authentication 
308 enabled.
309
310
311 H3: Configuring slapd to use an authentication provider
312
313 Where an entry has a "{SASL}" password value, OpenLDAP delegates the
314 whole process of validating that entry's password to Cyrus SASL. All
315 the configuration is therefore done in SASL config files.
316
317 The first
318 file to be considered is confusingly named {{slapd.conf}} and is
319 typically found in the SASL library directory, often
320 {{EX:/usr/lib/sasl2/slapd.conf}} This file governs the use of SASL
321 when talking LDAP to {{slapd}} as well as the use of SASL backends for
322 pass-through authentication. See {{EX:options.html}} in the {{PRD:Cyrus SASL}}
323 docs for full details. Here is a simple example for a server that will
324 use {{saslauthd}} to verify passwords:
325
326 > mech_list: plain
327 > pwcheck_method: saslauthd
328 > saslauthd_path: /var/run/sasl2/mux
329
330 H3: Configuring saslauthd
331
332 {{saslauthd}} is capable of using many different authentication
333 services: see {{saslauthd(8)}} for details. A common requirement is to
334 delegate some or all authentication to another LDAP server. Here is a
335 sample {{EX:saslauthd.conf}} that uses Microsoft Active Directory (AD):
336
337 > ldap_servers: ldap://dc1.example.com/ ldap://dc2.example.com/
338
339 > ldap_search_base: cn=Users,DC=ad,DC=example,DC=com
340 > ldap_filter: (userPrincipalName=%u)
341
342 > ldap_bind_dn: cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com
343 > ldap_password: secret
344
345 In this case, {{saslauthd}} is run with the {{EX:ldap}} authentication
346 mechanism and is set to combine the SASL realm with the login name:
347
348 > saslauthd -a ldap -r
349
350 This means that the "username@realm" string from the {{userPassword}}
351 attribute ends up being used to search AD for
352 "userPrincipalName=username@realm" - the password is then verified by
353 attempting to bind to AD using the entry found by the search and the
354 password supplied by the LDAP client.
355
356 H3: Testing pass-through authentication
357
358 It is usually best to start with the back-end authentication provider
359 and work through {{saslauthd}} and {{slapd}} towards the LDAP client.
360
361 In the AD example above, first check that the DN and password that
362 {{saslauthd}} will use when it connects to AD are valid:
363
364 > ldapsearch -x -H ldap://dc1.example.com/ \
365 >      -D cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com \
366 >      -w secret \
367 >      -b '' \
368 >      -s base
369
370 Next check that a sample AD user can be found:
371
372 > ldapsearch -x -H ldap://dc1.example.com/ \
373 >      -D cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com \
374 >      -w secret \
375 >      -b cn=Users,DC=ad,DC=example,DC=com \
376 >      "(userPrincipalName=user@ad.example.com)"
377
378 Check that the user can bind to AD:
379
380 > ldapsearch -x -H ldap://dc1.example.com/ \
381 >      -D cn=user,cn=Users,DC=ad,DC=example,DC=com \
382 >      -w userpassword \
383 >      -b cn=user,cn=Users,DC=ad,DC=example,DC=com \
384 >      -s base \
385 >       "(objectclass=*)"
386
387 If all that works then {{saslauthd}} should be able to do the same:
388
389 > testsaslauthd -u user@ad.example.com -p userpassword
390 > testsaslauthd -u user@ad.example.com -p wrongpassword
391
392 Now put the magic token into an entry in OpenLDAP:
393
394 > userPassword: {SASL}user@ad.example.com
395
396 It should now be possible to bind to OpenLDAP using the DN of that
397 entry and the password of the AD user.
398