2 .\" Copyright 2004-2006 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
27 Note that some of the policies do not take effect when the operation
30 identity; all the operations, when performed with any other identity,
31 may be subjected to constraints, like access control.
36 configuration options apply to the ppolicy overlay. They should appear
41 .B ppolicy_default <policyDN>
42 Specify the DN of the pwdPolicy object to use when no specific policy is
43 set on a given user's entry. If there is no specific policy for an entry
44 and no default is given, then no policies will be enforced.
46 .B ppolicy_hash_cleartext
47 Specify that cleartext passwords present in Add and Modify requests should
48 be hashed before being stored in the database. This violates the X.500/LDAP
49 information model, but may be needed to compensate for LDAP clients that
50 don't use the Password Modify extended operation to manage passwords. It
51 is recommended that when this option is used that compare, search, and
52 read access be denied to all directory users.
54 .B ppolicy_use_lockout
55 A client will always receive an LDAP
58 Binding to a locked account. By default, when a Password Policy control
59 was provided on the Bind request, a Password Policy response will be
60 included with no special error code set. This option changes the
61 Password Policy response to include the
66 error code provides useful information
67 to an attacker; sites that are sensitive to security issues should not
73 overlay depends on the
75 object class. The definition of that class is as follows:
78 ( 1.3.6.1.4.1.42.2.27.8.2.1
84 pwdMinAge $ pwdMaxAge $ pwdInHistory $
85 pwdCheckSyntax $ pwdMinLength $
86 pwdExpireWarning $ pwdGraceAuthnLimit $
87 pwdLockout $ pwdLockoutDuration $
88 pwdMaxFailure $ pwdFailureCountInterval $
89 pwdMustChange $ pwdAllowUserChange $
93 This implementation also provides an additional
95 objectclass, used for password quality checking (see below).
98 ( 1.3.6.1.4.1.4754.2.99.1
99 NAME 'pwdPolicyChecker'
102 MAY ( pwdCheckModule ) )
105 Every account that should be subject to password policy control should
109 attribute containing the DN of a valid
111 entry, or they can simply use the configured default.
112 In this way different users may be managed according to
115 .SH OBJECT CLASS ATTRIBUTES
117 Each one of the sections below details the meaning and use of a particular
125 This attribute contains the name of the attribute to which the password
126 policy is applied. For example, the password policy may be applied
131 Note: in this implementation, the only
135 .IR " userPassword ".
138 ( 1.3.6.1.4.1.42.2.27.8.1.1
140 EQUALITY objectIdentifierMatch
141 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
146 This attribute contains the number of seconds that must elapse
147 between modifications allowed to the password. If this attribute
148 is not present, zero seconds is assumed (i.e. the password may be
149 modified whenever and however often is desired).
152 ( 1.3.6.1.4.1.42.2.27.8.1.2
154 EQUALITY integerMatch
155 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
161 This attribute contains the number of seconds after which a modified
162 password will expire. If this attribute is not present, or if its
163 value is zero (0), then passwords will not expire.
166 ( 1.3.6.1.4.1.42.2.27.8.1.3
168 EQUALITY integerMatch
169 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
175 This attribute is used to specify the maximum number of used
176 passwords that will be stored in the
180 attribute is not present, or if its value is
181 zero (0), used passwords will not be stored in
183 and thus any previously-used password may be reused.
184 No history checking occurs if the password is being modified by the
186 although the password is saved in the history.
189 ( 1.3.6.1.4.1.42.2.27.8.1.4
191 EQUALITY integerMatch
192 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
198 This attribute indicates if and how password syntax will be checked
199 while a password is being modified or added. If this attribute is
200 not present, or its value is zero (0), no syntax checking will be
201 done. If its value is one (1), the server will check the syntax,
202 and if the server is unable to check the syntax,
203 whether due to a client-side hashed password or some other reason,
205 accepted. If its value is two (2), the server will check the syntax,
206 and if the server is unable to check the syntax it will return an
207 error refusing the password.
210 ( 1.3.6.1.4.1.42.2.27.8.1.5
211 NAME 'pwdCheckQuality'
212 EQUALITY integerMatch
213 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
219 When syntax checking is enabled
222 attribute), this attribute contains the minimum
223 number of characters that will be accepted in a password. If this
224 attribute is not present, minimum password length is not
225 enforced. If the server is unable to check the length of the password,
226 whether due to a client-side hashed password or some other reason,
227 the server will, depending on the
230 either accept the password
231 without checking it (if
233 is zero (0) or one (1)) or refuse it (if
238 ( 1.3.6.1.4.1.42.2.27.8.1.6
240 EQUALITY integerMatch
241 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
247 This attribute contains the maximum number of seconds before a
248 password is due to expire that expiration warning messages will be
249 returned to a user who is authenticating to the directory.
250 If this attribute is not
251 present, or if the value is zero (0), no warnings will be sent.
254 ( 1.3.6.1.4.1.42.2.27.8.1.7
255 NAME 'pwdExpireWarning'
256 EQUALITY integerMatch
257 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
261 .B pwdGraceAuthnLimit
263 This attribute contains the number of times that an expired password
264 may be used to authenticate a user to the directory. If this
265 attribute is not present or if its value is zero (0), users with
266 expired passwords will not be allowed to authenticate to the
270 ( 1.3.6.1.4.1.42.2.27.8.1.8
271 NAME 'pwdGraceAuthnLimit'
272 EQUALITY integerMatch
273 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
279 This attribute specifies the action that should be taken
280 by the directory when a user has made a number of failed attempts
281 to authenticate to the directory. If
283 is set (its value is "TRUE"), the user will not be allowed to
284 attempt to authenticate to the directory after there have been a
285 specified number of consecutive failed bind attempts. The maximum
286 number of consecutive failed bind attempts allowed is specified by
291 is not present, or if its value is "FALSE", the password may be
292 used to authenticate no matter how many consecutive failed bind
293 attempts have been made.
296 ( 1.3.6.1.4.1.42.2.27.8.1.9
298 EQUALITY booleanMatch
299 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
303 .B pwdLockoutDuration
305 This attribute contains the number of seconds during
306 which the password cannot be used to authenticate the
307 user to the directory due to too many consecutive failed
314 .B pwdLockoutDuration
315 is not present, or if its value is zero (0), the password
316 cannot be used to authenticate the user to the directory
317 again until it is reset by an administrator.
320 ( 1.3.6.1.4.1.42.2.27.8.1.10
321 NAME 'pwdLockoutDuration'
322 EQUALITY integerMatch
323 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
329 This attribute contains the number of consecutive failed bind
330 attempts after which the password may not be used to authenticate
331 a user to the directory.
334 is not present, or its value is zero (0), then a user will
335 be allowed to continue to attempt to authenticate to
336 the directory, no matter how many consecutive failed
337 bind attempts have occurred with that user's DN.
341 .BR pwdLockoutDuration .)
344 ( 1.3.6.1.4.1.42.2.27.8.1.11
346 EQUALITY integerMatch
347 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
351 .B pwdFailureCountInterval
353 This attribute contains the number of seconds after which old
354 consecutive failed bind attempts are purged from the failure counter,
355 even though no successful authentication has occurred.
357 .B pwdFailureCountInterval
358 is not present, or its value is zero (0), the failure
359 counter will only be reset by a successful authentication.
362 ( 1.3.6.1.4.1.42.2.27.8.1.12
363 NAME 'pwdFailureCountInterval'
364 EQUALITY integerMatch
365 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
371 This attribute specifies whether users must change their passwords
372 when they first bind to the directory after a password is set or
373 reset by the administrator, or not. If
375 has a value of "TRUE", users must change their passwords when they
376 first bind to the directory after a password is set or reset by
377 the administrator. If
379 is not present, or its value is "FALSE",
380 users are not required to change their password upon binding after
381 the administrator sets or resets the password.
384 ( 1.3.6.1.4.1.42.2.27.8.1.13
386 EQUALITY booleanMatch
387 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
391 .B pwdAllowUserChange
393 This attribute specifies whether users are allowed to change their own
395 .B pwdAllowUserChange
396 is set to "TRUE", or if the attribute is not present, users will be
397 allowed to change their own passwords. If its value is "FALSE",
398 users will not be allowed to change their own passwords.
401 ( 1.3.6.1.4.1.42.2.27.8.1.14
402 NAME 'pwdAllowUserChange'
403 EQUALITY booleanMatch
404 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
410 This attribute denotes whether the user's existing password must be sent
411 along with their new password when changing a password. If
413 is set to "TRUE", the existing password must be sent
414 along with the new password. If the attribute is not present, or
415 its value is "FALSE", the existing password need not be sent
416 along with the new password.
419 ( 1.3.6.1.4.1.42.2.27.8.1.15
421 EQUALITY booleanMatch
422 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
428 This attribute names a user-defined loadable module that must
429 instantiate the check_password() function. This function
430 will be called to further check a new password if
432 is set to one (1) or two (2),
433 after all of the built-in password compliance checks have
434 been passed. This function will be called according to this
439 (char *pPasswd, char **ppErrStr, Entry *pEntry);
443 parameter contains the clear-text user password, the
445 parameter contains a double pointer that allows the function
446 to return human-readable details about any error it encounters.
449 parameter, if non-NULL, carries a pointer to the
450 entry whose password is being checked.
455 must NOT attempt to use it/them.
456 A return value of LDAP_SUCCESS from the called
457 function indicates that the password is ok, any other value
458 indicates that the password is unacceptable. If the password is
459 unacceptable, the server will return an error to the client, and
461 may be used to return a human-readable textual explanation of the
462 error. The error string must be dynamically allocated as it will
463 be free()'d by slapd.
466 ( 1.3.6.1.4.1.4754.1.99.1
467 NAME 'pwdCheckModule'
468 EQUALITY caseExactIA5Match
469 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
474 The user-defined loadable module named by
478 standard executable search PATH.
482 is a non-standard extension to the LDAP password
485 .SH OPERATIONAL ATTRIBUTES
487 The operational attributes used by the
489 module are stored in the user's entry. Most of these attributes
490 are not intended to be changed directly by users; they are there
491 to track user activity. They have been detailed here so that
492 administrators and users can both understand the workings of
501 attribute is not strictly part of the
503 module. It is, however, the attribute that is tracked and controlled
504 by the module. Please refer to the standard OpenLDAP schema for
509 This attribute refers directly to the
511 subentry that is to be used for this particular directory user.
514 exists, it must contain the DN of a valid
516 object. If it does not exist, the
518 module will enforce the default password policy rules on the
519 user associated with this authenticating DN. If there is no
520 default, or the referenced subentry does not exist, then no
521 policy rules will be enforced.
524 ( 1.3.6.1.4.1.42.2.27.8.1.23
525 NAME 'pwdPolicySubentry'
526 DESC 'The pwdPolicy subentry in effect for
528 EQUALITY distinguishedNameMatch
529 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
532 USAGE directoryOperation)
537 This attribute denotes the last time that the entry's password was
538 changed. This value is used by the password expiration policy to
539 determine whether the password is too old to be allowed to be used
540 for user authentication. If
542 does not exist, the user's password will not expire.
545 ( 1.3.6.1.4.1.42.2.27.8.1.16
546 NAME 'pwdChangedTime'
547 DESC 'The time the password was last changed'
548 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
549 EQUALITY generalizedTimeMatch
550 ORDERING generalizedTimeOrderingMatch
553 USAGE directoryOperation)
556 .B pwdAccountLockedTime
558 This attribute contains the time that the user's account was locked.
559 If the account has been locked, the password may no longer be used to
560 authenticate the user to the directory. If
561 .B pwdAccountLockedTime
562 is set to zero (0), the user's account has been permanently locked
563 and may only be unlocked by an administrator.
566 ( 1.3.6.1.4.1.42.2.27.8.1.17
567 NAME 'pwdAccountLockedTime'
568 DESC 'The time an user account was locked'
569 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
570 EQUALITY generalizedTimeMatch
571 ORDERING generalizedTimeOrderingMatch
574 USAGE directoryOperation)
579 This attribute contains the timestamps of each of the consecutive
580 authentication failures made upon attempted authentication to this
581 DN (i.e. account). If too many timestamps accumulate here (refer to
584 password policy attribute for details),
587 password policy attribute is set to "TRUE", the
588 account may be locked.
589 (Please also refer to the
591 password policy attribute.)
592 Excess timestamps beyond those allowed by
594 may also be purged. If a successful authentication is made to this
595 DN (i.e. to this user account), then
597 will be cleansed of entries.
600 ( 1.3.6.1.4.1.42.2.27.8.1.19
601 NAME 'pwdFailureTime'
602 DESC 'The timestamps of the last consecutive
603 authentication failures'
604 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
605 EQUALITY generalizedTimeMatch
606 ORDERING generalizedTimeOrderingMatch
608 USAGE directoryOperation )
613 This attribute contains the history of previously used passwords
614 for this DN (i.e. for this user account).
615 The values of this attribute are stored in string format as follows:
621 time "#" syntaxOID "#" length "#" data
626 generalizedTimeString as specified in section 6.14 of [RFC2252]
630 syntaxOID = numericoid
632 This is the string representation of the dotted-decimal OID that
633 defines the syntax used to store the password. numericoid is
634 described in section 4.1 of [RFC2252].
637 length = numericstring
639 The number of octets in the data. numericstring is described in
640 section 4.1 of [RFC2252].
645 Octets representing the password in the format specified by syntaxOID.
650 This format allows the server to store and transmit a history of
651 passwords that have been used. In order for equality matching
652 on the values in this attribute to function properly, the time
653 field is in GMT format.
656 ( 1.3.6.1.4.1.42.2.27.8.1.20
658 DESC 'The history of user passwords'
659 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
660 EQUALITY octetStringMatch
662 USAGE directoryOperation)
666 This attribute contains the list of timestamps of logins made after
667 the user password in the DN has expired. These post-expiration
668 logins are known as "\fIgrace logins\fP".
671 have been used (please refer to the
672 .B pwdGraceLoginLimit
673 password policy attribute), then the DN will no longer be allowed
674 to be used to authenticate the user to the directory until the
675 administrator changes the DN's
680 ( 1.3.6.1.4.1.42.2.27.8.1.21
681 NAME 'pwdGraceUseTime'
682 DESC 'The timestamps of the grace login once the password has expired'
683 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
684 EQUALITY generalizedTimeMatch
686 USAGE directoryOperation)
691 This attribute indicates whether the user's password has been reset
692 by the administrator and thus must be changed upon first use of this
693 DN for authentication to the directory. If
695 is set to "TRUE", then the password was reset and the user must change
696 it upon first authentication. If the attribute does not exist, or
697 is set to "FALSE", the user need not change their password due to
698 administrative reset.
701 ( 1.3.6.1.4.1.42.2.27.8.1.22
703 DESC 'The indication that the password has
705 EQUALITY booleanMatch
706 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
708 USAGE directoryOperation)
716 suffix dc=example,dc=com
719 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
727 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
729 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
730 Sermersheim: documented in IETF document
731 "draft-behera-ldap-password-policy-09.txt".
734 The LDAP Password Policy specification is not yet an approved standard,
735 and it is still evolving. This code will continue to be in flux until the
736 specification is finalized.
740 This module was written in 2004 by Howard Chu of Symas Corporation
741 with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
743 This manual page borrows heavily and shamelessly from the specification
744 upon which the password policy module it describes is based. This
746 IETF LDAP password policy proposal by P. Behera, L.
747 Poitou and J. Sermersheim.
748 The proposal is fully documented in
750 IETF document named draft-behera-ldap-password-policy-09.txt,
751 written in July of 2005.
754 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
756 is derived from University of Michigan LDAP 3.3 Release.