2 .\" Copyright 2004-2005 The OpenLDAP Foundation All Rights Reserved.
3 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
4 .TH SLAPO_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
6 slapo-ppolicy \- Password Policy overlay
14 is an implementation of the most recent IETF Password
15 Policy proposal for LDAP. When instantiated, it intercepts,
16 decodes and applies specific password policy controls to overall
17 use of a backend database, changes to user password fields, etc.
19 The overlay provides a variety of password control mechanisms. They
20 include password aging--both minimum and maximum ages, password
21 reuse and duplication control, account time-outs, mandatory password
22 resets, acceptable password content, and even grace logins.
23 Different groups of users may be associated with different password
24 policies, and there is no limit to the number of password policies
30 configuration options apply to the ppolicy overlay. They should appear
35 .B ppolicy_default <policyDN>
36 Specify the DN of the pwdPolicy object to use when no specific policy is
37 set on a given user's entry. If there is no specific policy for an entry
38 and no default is given, then no policies will be enforced.
40 .B ppolicy_hash_cleartext
41 Specify that cleartext passwords present in Add and Modify requests should
42 be hashed before being stored in the database. This violates the X.500
43 information model, but may be needed to compensate for LDAP clients that
44 don't use the PasswordModify exop to manage passwords.
46 .B ppolicy_use_lockout
47 A client will always receive an LDAP
50 Binding to a locked account. By default, when a Password Policy control
51 was provided on the Bind request, a Password Policy response will be
52 included with no special error code set. This option changes the
53 Password Policy response to include the
58 error code provides useful information
59 to an attacker; sites that are sensitive to security issues should not
65 overlay depends on the
67 object class. The definition of that class is as follows:
70 ( 1.3.6.1.4.1.42.2.27.8.2.1
76 pwdMinAge $ pwdMaxAge $ pwdInHistory $
77 pwdCheckSyntax $ pwdMinLength $
78 pwdExpireWarning $ pwdGraceLoginLimit $
79 pwdLockout $ pwdLockoutDuration $
80 pwdMaxFailure $ pwdFailureCountInterval $
81 pwdMustChange $ pwdAllowUserChange $
85 This implementation also provides an additional
87 objectclass, used for password quality checking (see below).
90 ( 1.3.6.1.4.1.4754.2.99.1
91 NAME 'pwdPolicyChecker'
94 MAY ( pwdCheckModule ) )
97 Every account that should be subject to password policy control should
101 attribute containing the DN of a valid
103 entry, or they can simply use the configured default.
104 In this way different users may be managed according to
107 .SH OBJECT CLASS ATTRIBUTES
109 Each one of the sections below details the meaning and use of a particular
117 This attribute contains the name of the attribute to which the password
118 policy is applied. For example, the password policy may be applied
123 Note: in this implementation, the only
127 .RI " userPassword ".
130 ( 1.3.6.1.4.1.42.2.27.8.1.1
132 EQUALITY objectIdentifierMatch
133 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
138 This attribute contains the number of seconds that must elapse
139 between modifications allowed to the password. If this attribute
140 is not present, zero seconds is assumed (i.e. the password may be
141 modified whenever and however often is desired).
144 ( 1.3.6.1.4.1.42.2.27.8.1.2
146 EQUALITY integerMatch
147 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
153 This attribute contains the number of seconds after which a modified
154 password will expire. If this attribute is not present, or if its
155 value is zero (0), then passwords will not expire.
158 ( 1.3.6.1.4.1.42.2.27.8.1.3
160 EQUALITY integerMatch
161 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
167 This attribute is used to specify the maximum number of used
168 passwords that will be stored in the
172 attribute is not present, or if its value is
173 zero (0), used passwords will not be stored in
175 and thus any previously-used password may be reused.
178 ( 1.3.6.1.4.1.42.2.27.8.1.4
180 EQUALITY integerMatch
181 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
187 This attribute indicates if and how password syntax will be checked
188 while a password is being modified or added. If this attribute is
189 not present, or its value is zero (0), no syntax checking will be
190 done. If its value is one (1), the server will check the syntax,
191 and if the server is unable to check the syntax,
192 whether due to a client-side hashed password or some other reason,
194 accepted. If its value is two (2), the server will check the syntax,
195 and if the server is unable to check the syntax it will return an
196 error refusing the password.
199 ( 1.3.6.1.4.1.42.2.27.8.1.5
200 NAME 'pwdCheckQuality'
201 EQUALITY integerMatch
202 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
208 When syntax checking is enabled
211 attribute), this attribute contains the minimum
212 number of characters that will be accepted in a password. If this
213 attribute is not present, minimum password length is not
214 enforced. If the server is unable to check the length of the password,
215 whether due to a client-side hashed password or some other reason,
216 the server will, depending on the
219 either accept the password
220 without checking it (if
222 is zero (0) or one (1)) or refuse it (if
227 ( 1.3.6.1.4.1.42.2.27.8.1.6
229 EQUALITY integerMatch
230 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
236 This attribute contains the maximum number of seconds before a
237 password is due to expire that expiration warning messages will be
238 returned to a user who is authenticating to the directory.
239 If this attribute is not
240 present, or if the value is zero (0), no warnings will be sent.
243 ( 1.3.6.1.4.1.42.2.27.8.1.7
244 NAME 'pwdExpireWarning'
245 EQUALITY integerMatch
246 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
250 .B pwdGraceLoginLimit
252 This attribute contains the number of times that an expired password
253 may be used to authenticate a user to the directory. If this
254 attribute is not present or if its value is zero (0), users with
255 expired passwords will not be allowed to authenticate to the
259 ( 1.3.6.1.4.1.42.2.27.8.1.8
260 NAME 'pwdGraceLoginLimit'
261 EQUALITY integerMatch
262 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
268 This attribute specifies the action that should be taken
269 by the directory when a user has made a number of failed attempts
270 to authenticate to the directory. If
272 is set (its value is "TRUE"), the user will not be allowed to
273 attempt to authenticate to the directory after there have been a
274 specified number of consecutive failed bind attempts. The maximum
275 number of consecutive failed bind attempts allowed is specified by
280 is not present, or if its value is "FALSE", the password may be
281 used to authenticate no matter how many consecutive failed bind
282 attempts have been made.
285 ( 1.3.6.1.4.1.42.2.27.8.1.9
287 EQUALITY booleanMatch
288 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
292 .B pwdLockoutDuration
294 This attribute contains the number of seconds during
295 which the password cannot be used to authenticate the
296 user to the directory due to too many consecutive failed
303 .B pwdLockoutDuration
304 is not present, or if its value is zero (0), the password
305 cannot be used to authenticate the user to the directory
306 again until it is reset by an administrator.
309 ( 1.3.6.1.4.1.42.2.27.8.1.10
310 NAME 'pwdLockoutDuration'
311 EQUALITY integerMatch
312 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
318 This attribute contains the number of consecutive failed bind
319 attempts after which the password may not be used to authenticate
320 a user to the directory.
323 is not present, or its value is zero (0), then a user will
324 be allowed to continue to attempt to authenticate to
325 the directory, no matter how many consecutive failed
326 bind attempts have occurred with that user's DN.
330 .BR pwdLockoutDuration .)
333 ( 1.3.6.1.4.1.42.2.27.8.1.11
335 EQUALITY integerMatch
336 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
340 .B pwdFailureCountInterval
342 This attribute contains the number of seconds after which old
343 consecutive failed bind attempts are purged from the failure counter,
344 even though no successful authentication has occurred.
346 .B pwdFailureCountInterval
347 is not present, or its value is zero (0), the failure
348 counter will only be reset by a successful authentication.
351 ( 1.3.6.1.4.1.42.2.27.8.1.12
352 NAME 'pwdFailureCountInterval'
353 EQUALITY integerMatch
354 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
360 This attribute specifies whether users must change their passwords
361 when they first bind to the directory after a password is set or
362 reset by the administrator, or not. If
364 has a value of "TRUE", users must change their passwords when they
365 first bind to the directory after a password is set or reset by
366 the administrator. If
368 is not present, or its value is "FALSE",
369 users are not required to change their password upon binding after
370 the administrator sets or resets the password.
373 ( 1.3.6.1.4.1.42.2.27.8.1.13
375 EQUALITY booleanMatch
376 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
380 .B pwdAllowUserChange
382 This attribute specifies whether users are allowed to change their own
384 .B pwdAllowUserChange
385 is set to "TRUE", or if the attribute is not present, users will be
386 allowed to change their own passwords. If its value is "FALSE",
387 users will not be allowed to change their own passwords.
390 ( 1.3.6.1.4.1.42.2.27.8.1.14
391 NAME 'pwdAllowUserChange'
392 EQUALITY booleanMatch
393 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
399 This attribute denotes whether the user's existing password must be sent
400 along with their new password when changing a password. If
402 is set to "TRUE", the existing password must be sent
403 along with the new password. If the attribute is not present, or
404 its value is "FALSE", the existing password need not be sent
405 along with the new password.
408 ( 1.3.6.1.4.1.42.2.27.8.1.15
410 EQUALITY booleanMatch
411 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
417 This attribute names a user-defined loadable module that must
418 instantiate the check_password() function. This function
419 will be called to further check a new password if
421 is set to one (1) or two (2),
422 after all of the built-in password compliance checks have
423 been passed. This function will be called according to this
428 (char *pPasswd, char **ppErrStr, Entry *pEntry);
432 parameter contains the clear-text user password, the
434 parameter contains a double pointer that allows the function
435 to return human-readable details about any error it encounters.
438 parameter, if non-NULL, carries a pointer to the
439 entry whose password is being checked.
444 must NOT attempt to use it/them.
445 A return value of LDAP_SUCCESS from the called
446 function indicates that the password is ok, any other value
447 indicates that the password is unacceptable. If the password is
448 unacceptable, the server will return an error to the client, and
450 may be used to return a human-readable textual explanation of the
451 error. The error string must be dynamically allocated as it will
452 be free()'d by slapd.
455 ( 1.3.6.1.4.1.4754.1.99.1
456 NAME 'pwdCheckModule'
457 EQUALITY caseExactIA5Match
458 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
463 The user-defined loadable module named by
467 standard executable search PATH.
471 is a non-standard extension to the LDAP password
474 .SH OPERATIONAL ATTRIBUTES
476 The operational attributes used by the
478 module are stored in the user's entry. Most of these attributes
479 are not intended to be changed directly by users; they are there
480 to track user activity. They have been detailed here so that
481 administrators and users can both understand the workings of
490 attribute is not strictly part of the
492 module. It is, however, the attribute that is tracked and controlled
493 by the module. Please refer to the standard OpenLDAP schema for
498 This attribute refers directly to the
500 subentry that is to be used for this particular directory user.
503 exists, it must contain the DN of a valid
505 object. If it does not exist, the
507 module will enforce the default password policy rules on the
508 user associated with this authenticating DN. If there is no
509 default, or the referenced subentry does not exist, then no
510 policy rules wil be enforced.
513 ( 1.3.6.1.4.1.42.2.27.8.1.23
514 NAME 'pwdPolicySubentry'
515 DESC 'The pwdPolicy subentry in effect for
517 EQUALITY distinguishedNameMatch
518 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
520 USAGE directoryOperation)
525 This attribute denotes the last time that the entry's password was
526 changed. This value is used by the password expiration policy to
527 determine whether the password is too old to be allowed to be used
528 for user authentication. If
530 does not exist, the user's password will not expire.
533 ( 1.3.6.1.4.1.42.2.27.8.1.16
534 NAME 'pwdChangedTime'
535 DESC 'The time the password was last changed'
536 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
537 EQUALITY generalizedTimeMatch
538 ORDERING generalizedTimeOrderingMatch
540 USAGE directoryOperation)
543 .B pwdAccountLockedTime
545 This attribute contains the time that the user's account was locked.
546 If the account has been locked, the password may no longer be used to
547 authenticate the user to the directory. If
548 .B pwdAccountLockedTime
549 is set to zero (0), the user's account has been permanently locked
550 and may only be unlocked by an administrator.
553 ( 1.3.6.1.4.1.42.2.27.8.1.17
554 NAME 'pwdAccountLockedTime'
555 DESC 'The time an user account was locked'
556 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
557 EQUALITY generalizedTimeMatch
558 ORDERING generalizedTimeOrderingMatch
560 USAGE directoryOperation)
563 .B pwdExpirationWarned
565 This attribute denotes the time when the first password
566 expiration warning was sent to the client regarding this account.
567 The amount of time between when this warning is sent and when
568 the password actually expires is the amount of time stored in
571 password policy attribute.
574 ( 1.3.6.1.4.1.42.2.27.8.1.18
575 NAME 'pwdExpirationWarned'
576 DESC 'The time the user was first warned about the
577 coming expiration of their password'
578 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
579 EQUALITY generalizedTimeMatch
580 ORDERING generalizedTimeOrderingMatch
582 USAGE directoryOperation )
587 This attribute contains the timestamps of each of the consecutive
588 authentication failures made upon attempted authentication to this
589 DN (i.e. account). If too many timestamps accumulate here (refer to
592 password policy attribute for details),
595 password policy attribute is set to "TRUE", the
596 account may be locked.
597 (Please also refer to the
599 password policy attribute.)
600 Excess timestamps beyond those allowed by
602 may also be purged. If a successful authentication is made to this
603 DN (i.e. to this user account), then
605 will be cleansed of entries.
608 ( 1.3.6.1.4.1.42.2.27.8.1.19
609 NAME 'pwdFailureTime'
610 DESC 'The timestamps of the last consecutive
611 authentication failures'
612 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
613 EQUALITY generalizedTimeMatch
614 ORDERING generalizedTimeOrderingMatch
615 USAGE directoryOperation )
620 This attribute contains the history of previously used passwords
621 for this DN (i.e. for this user account).
622 The values of this attribute are stored in string format as follows:
628 time "#" syntaxOID "#" length "#" data
633 generalizedTimeString as specified in section 6.14 of [RFC2252]
637 syntaxOID = numericoid
639 This is the string representation of the dotted-decimal OID that
640 defines the syntax used to store the password. numericoid is
641 described in section 4.1 of [RFC2252].
644 length = numericstring
646 The number of octets in the data. numericstring is described in
647 section 4.1 of [RFC2252].
652 Octets representing the password in the format specified by syntaxOID.
657 This format allows the server to store and transmit a history of
658 passwords that have been used. In order for equality matching
659 on the values in this attribute to function properly, the time
660 field is in GMT format.
663 ( 1.3.6.1.4.1.42.2.27.8.1.20
665 DESC 'The history of user passwords'
666 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
667 EQUALITY octetStringMatch
668 USAGE directoryOperation)
672 This attribute contains the list of timestamps of logins made after
673 the user password in the DN has expired. These post-expiration
675 .RI " "grace logins" ."
678 have been used (please refer to the
679 .B pwdGraceLoginLimit
680 password policy attribute), then the DN will no longer be allowed
681 to be used to authenticate the user to the directory until the
682 administrator changes the DN's
687 ( 1.3.6.1.4.1.42.2.27.8.1.21
688 NAME 'pwdGraceUseTime'
689 DESC 'The timestamps of the grace login once the password has expired'
690 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
691 EQUALITY generalizedTimeMatch
692 USAGE directoryOperation)
697 This attribute indicates whether the user's password has been reset
698 by the administrator and thus must be changed upon first use of this
699 DN for authentication to the directory. If
701 is set to "TRUE", then the password was reset and the user must change
702 it upon first authentication. If the attribute does not exist, or
703 is set to "FALSE", the user need not change their password due to
704 administrative reset.
707 ( 1.3.6.1.4.1.42.2.27.8.1.22
709 DESC 'The indication that the password has
711 EQUALITY booleanMatch
712 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
714 USAGE directoryOperation)
722 suffix dc=example,dc=com
725 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
733 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
735 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
736 Sermersheim: documented in IETF document
737 "draft-behera-ldap-password-policy-07.txt".
740 The LDAP Password Policy specification is not yet an approved standard,
741 and it is still evolving. This code will continue to be in flux until the
742 specification is finalized.
746 This module was written in 2004 by Howard Chu of Symas Corporation
747 with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
749 This manual page borrows heavily and shamelessly from the specification
750 upon which the password policy module it describes is based. This
752 IETF LDAP password policy proposal by P. Behera, L.
753 Poitou and J. Sermersheim.
754 The proposal is fully documented in
756 IETF document named draft-behera-ldap-password-policy-07.txt,
757 written in February of 2004.
760 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
762 is derived from University of Michigan LDAP 3.3 Release.