+++ /dev/null
-.\" $Id: slapd-ppolicy.5,v 1.2 2004/03/16 20:40:41 hyc Exp $
-.\" Copyright 2004 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.TH SLAPD_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.SH NAME
-slapd-ppolicy \- Password Policy overlay
-.SH SYNOPSIS
-ETCDIR/slapd.conf
-.SH DESCRIPTION
-.LP
-The
-.B ppolicy
-overlay
-is an implementation of the most recent IETF Password
-Policy proposal for LDAP. When instantiated, it intercepts,
-decodes and applies specific password policy controls to overall
-use of a backend database, changes to user password fields, etc.
-.P
-The overlay provides a variety of password control mechanisms. They
-include password aging--both minimum and maximum ages, password
-reuse and duplication control, account time-outs, mandatory password
-resets, acceptable password content, and even grace logins.
-Different groups of users may be associated with different password
-policies, and there is no limit to the number of password policies
-that may be created.
-
-.SH CONFIGURATION
-These
-.B slapd.conf
-configuration options apply to the ppolicy overlay. They should appear
-after the
-.B overlay
-directive.
-.TP
-.B ppolicy_default <policyDN>
-Specify the DN of the pwdPolicy object to use when no specific policy is
-set on a given user's entry. If there is no specific policy for an entry
-and no default is given, then no policies will be enforced.
-.TP
-.B ppolicy_use_lockout
-A client will always receive an LDAP
-.B InvalidCredentials
-response when
-Binding to a locked account. By default, when a Password Policy control
-was provided on the Bind request, a Password Policy response will be
-included with no special error code set. This option changes the
-Password Policy response to include the
-.B AccountLocked
-error code. Note
-that sending the
-.B AccountLocked
-error code provides useful information
-to an attacker; sites that are sensitive to security issues should not
-enable this option.
-
-.SH OBJECT CLASS
-The
-.B ppolicy
-overlay depends on the
-.B pwdPolicy
-object class. The definition of that class is as follows:
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.2.1
- NAME 'pwdPolicy'
- AUXILIARY
- SUP top
- MUST ( pwdAttribute )
- MAY (
- pwdMinAge $ pwdMaxAge $ pwdInHistory $
- pwdCheckSyntax $ pwdMinLength $
- pwdExpireWarning $ pwdGraceLoginLimit $
- pwdLockout $ pwdLockoutDuration $
- pwdMaxFailure $ pwdFailureCountInterval $
- pwdMustChange $ pwdAllowUserChange $
- pwdSafeModify ) )
-.RE
-
-This implementation also provides an additional
-.B pwdPolicyChecker
-objectclass, used for password quality checking (see below).
-.LP
-.RS 4
-( 1.3.6.1.4.1.4754.2.99.1
- NAME 'pwdPolicyChecker'
- AUXILIARY
- SUP top
- MAY ( pwdCheckModule ) )
-.RE
-.P
-Every account that should be subject to password policy control should
-have a
-.B
-pwdPolicySubentry
-attribute containing the DN of a valid
-.B pwdPolicy
-entry, or they can simply use the configured default.
-In this way different users may be managed according to
-different policies.
-
-.SH OBJECT CLASS ATTRIBUTES
-.P
-Each one of the sections below details the meaning and use of a particular
-attribute of this
-.B pwdPolicy
-object class.
-.P
-
-.B pwdAttribute
-.P
-This attribute contains the name of the attribute to which the password
-policy is applied. For example, the password policy may be applied
-to the
-.B userPassword
-attribute.
-.P
-Note: in this implementation, the only
-value accepted for
-.B pwdAttribute
-is
-.RI " userPassword ".
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.1
- NAME 'pwdAttribute'
- EQUALITY objectIdentifierMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
-.RE
-
-.B pwdMinAge
-.P
-This attribute contains the number of seconds that must elapse
-between modifications allowed to the password. If this attribute
-is not present, zero seconds is assumed (i.e. the password may be
-modified whenever and however often is desired).
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.2
- NAME 'pwdMinAge'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdMaxAge
-.P
-This attribute contains the number of seconds after which a modified
-password will expire. If this attribute is not present, or if its
-value is zero (0), then passwords will not expire.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.3
- NAME 'pwdMaxAge'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdInHistory
-.P
-This attribute is used to specify the maximum number of used
-passwords that will be stored in the
-.B pwdHistory
-attribute. If the
-.B pwdInHistory
-attribute is not present, or if its value is
-zero (0), used passwords will not be stored in
-.B pwdHistory
-and thus any previously-used password may be reused.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.4
- NAME 'pwdInHistory'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdCheckQuality
-.P
-This attribute indicates if and how password syntax will be checked
-while a password is being modified or added. If this attribute is
-not present, or its value is zero (0), no syntax checking will be
-done. If its value is one (1), the server will check the syntax,
-and if the server is unable to check the syntax,
-whether due to a client-side hashed password or some other reason,
-it will be
-accepted. If its value is two (2), the server will check the syntax,
-and if the server is unable to check the syntax it will return an
-error refusing the password.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.5
- NAME 'pwdCheckQuality'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdMinLength
-.P
-When syntax checking is enabled
-(see also the
-.B pwdCheckSyntax
-attribute), this attribute contains the minimum
-number of characters that will be accepted in a password. If this
-attribute is not present, minimum password length is not
-enforced. If the server is unable to check the length of the password,
-whether due to a client-side hashed password or some other reason,
-the server will, depending on the
-value of
-.BR pwdCheckSyntax ,
-either accept the password
-without checking it (if
-.B pwdCheckSyntax
-is zero (0) or one (1)) or refuse it (if
-.B pwdCheckSyntax
-is two (2)).
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.6
- NAME 'pwdMinLength'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdExpireWarning
-.P
-This attribute contains the maximum number of seconds before a
-password is due to expire that expiration warning messages will be
-returned to a user who is authenticating to the directory.
-If this attribute is not
-present, or if the value is zero (0), no warnings will be sent.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.7
- NAME 'pwdExpireWarning'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdGraceLoginLimit
-.P
-This attribute contains the number of times that an expired password
-may be used to authenticate a user to the directory. If this
-attribute is not present or if its value is zero (0), users with
-expired passwords will not be allowed to authenticate to the
-directory.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.8
- NAME 'pwdGraceLoginLimit'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdLockout
-.P
-This attribute specifies the action that should be taken
-by the directory when a user has made a number of failed attempts
-to authenticate to the directory. If
-.B pwdLockout
-is set (its value is "TRUE"), the user will not be allowed to
-attempt to authenticate to the directory after there have been a
-specified number of consecutive failed bind attempts. The maximum
-number of consecutive failed bind attempts allowed is specified by
-the
-.B pwdMaxFailure
-attribute. If
-.B pwdLockout
-is not present, or if its value is "FALSE", the password may be
-used to authenticate no matter how many consecutive failed bind
-attempts have been made.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.9
- NAME 'pwdLockout'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE )
-.RE
-
-.B pwdLockoutDuration
-.P
-This attribute contains the number of seconds during
-which the password cannot be used to authenticate the
-user to the directory due to too many consecutive failed
-bind attempts.
-(See also
-.B pwdLockout
-and
-.BR pwdMaxFailure .)
-If
-.B pwdLockoutDuration
-is not present, or if its value is zero (0), the password
-cannot be used to authenticate the user to the directory
-again until it is reset by an administrator.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.10
- NAME 'pwdLockoutDuration'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdMaxFailure
-.P
-This attribute contains the number of consecutive failed bind
-attempts after which the password may not be used to authenticate
-a user to the directory.
-If
-.B pwdMaxFailure
-is not present, or its value is zero (0), then a user will
-be allowed to continue to attempt to authenticate to
-the directory, no matter how many consecutive failed
-bind attempts have occurred with that user's DN.
-(See also
-.B pwdLockout
-and
-.BR pwdLockoutDuration .)
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.11
- NAME 'pwdMaxFailure'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdFailureCountInterval
-.P
-This attribute contains the number of seconds after which old
-consecutive failed bind attempts are purged from the failure counter,
-even though no successful authentication has occurred.
-If
-.B pwdFailureCountInterval
-is not present, or its value is zero (0), the failure
-counter will only be reset by a successful authentication.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.12
- NAME 'pwdFailureCountInterval'
- EQUALITY integerMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
-.RE
-
-.B pwdMustChange
-.P
-This attribute specifies whether users must change their passwords
-when they first bind to the directory after a password is set or
-reset by the administrator, or not. If
-.B pwdMustChange
-has a value of "TRUE", users must change their passwords when they
-first bind to the directory after a password is set or reset by
-the administrator. If
-.B pwdMustChange
-is not present, or its value is "FALSE",
-users are not required to change their password upon binding after
-the administrator sets or resets the password.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.13
- NAME 'pwdMustChange'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE )
-.RE
-
-.B pwdAllowUserChange
-.P
-This attribute specifies whether users are allowed to change their own
-passwords or not. If
-.B pwdAllowUserChange
-is set to "TRUE", or if the attribute is not present, users will be
-allowed to change their own passwords. If its value is "FALSE",
-users will not be allowed to change their own passwords.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.14
- NAME 'pwdAllowUserChange'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE )
-.RE
-
-.B pwdSafeModify
-.P
-This attribute denotes whether the user's existing password must be sent
-along with their new password when changing a password. If
-.B pwdSafeModify
-is set to "TRUE", the existing password must be sent
-along with the new password. If the attribute is not present, or
-its value is "FALSE", the existing password need not be sent
-along with the new password.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.15
- NAME 'pwdSafeModify'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE )
-.RE
-
-.B pwdCheckModule
-.P
-This attribute names a user-defined loadable module that must
-instantiate the check_password() function. This function
-will be called to further check a new password if
-.B pwdCheckQuality
-is set to one (1) or two (2),
-after all of the built-in password compliance checks have
-been passed. This function will be called according to this
-function prototype:
-.RS 4
-int
-.I check_password
-(char *pPasswd, char **ppErrStr, void *pArg);
-.RE
-The
-.B pPasswd
-parameter contains the clear-text user password, the
-.B ppErrStr
-parameter contains a double pointer that allows the function
-to return human-readable details about any error it encounters.
-The
-.B pArg
-parameter is currently unused.
-If
-.B ppErrStr
-is NULL, then
-.I funcName
-must NOT attempt to use it/them.
-A return value of LDAP_SUCCESS from the called
-function indicates that the password is ok, any other value
-indicates that the password is unacceptable. If the password is
-unacceptable, the server will return an error to the client, and
-.B ppErrStr
-may be used to return a human-readable textual explanation of the
-error.
-.LP
-.RS 4
-( 1.3.6.1.4.1.4754.1.99.1
- NAME 'pwdCheckModule'
- EQUALITY caseExactIA5Match
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
- SINGLE-VALUE )
-.RE
-.P
-Note:
-The user-defined loadable module named by
-.B pwdCheckModule
-must be in
-.B slapd's
-standard executable search PATH.
-.P
-Note:
-.B pwdCheckModule
-is a non-standard extension to the LDAP password
-policy proposal.
-
-.SH OPERATIONAL ATTRIBUTES
-.P
-The operational attributes used by the
-.B passwd_policy
-module are stored in the user's entry. Most of these attributes
-are not intended to be changed directly by users; they are there
-to track user activity. They have been detailed here so that
-administrators and users can both understand the workings of
-the
-.B ppolicy
-module.
-
-.B userPassword
-.P
-The
-.b userPassword
-attribute is not strictly part of the
-.B ppolicy
-module. It is, however, the attribute that is tracked and controlled
-by the module. Please refer to the standard OpenLDAP schema for
-its definition.
-
-.B pwdPolicySubentry
-.P
-This attribute refers directly to the
-.B pwdPolicy
-subentry that is to be used for this particular directory user.
-If
-.B pwdPolicySubentry
-exists, it must contain the DN of a valid
-.B pwdPolicy
-object. If it does not exist, the
-.B ppolicy
-module will enforce the default password policy rules on the
-user associated with this authenticating DN. If there is no
-default, or the referenced subentry does not exist, then no
-policy rules wil be enforced.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.23
- NAME 'pwdPolicySubentry'
- DESC 'The pwdPolicy subentry in effect for
- this object'
- EQUALITY distinguishedNameMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
- SINGLE-VALUE
- USAGE directoryOperation)
-.RE
-
-.B pwdChangedTime
-.P
-This attribute denotes the last time that the entry's password was
-changed. This value is used by the password expiration policy to
-determine whether the password is too old to be allowed to be used
-for user authentication. If
-.B pwdChangedTime
-does not exist, the user's password will not expire.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.16
- NAME 'pwdChangedTime'
- DESC 'The time the password was last changed'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
- EQUALITY generalizedTimeMatch
- ORDERING generalizedTimeOrderingMatch
- SINGLE-VALUE
- USAGE directoryOperation)
-.RE
-
-.B pwdAccountLockedTime
-.P
-This attribute contains the time that the user's account was locked.
-If the account has been locked, the password may no longer be used to
-authenticate the user to the directory. If
-.B pwdAccountLockedTime
-is set to zero (0), the user's account has been permanently locked
-and may only be unlocked by an administrator.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.17
- NAME 'pwdAccountLockedTime'
- DESC 'The time an user account was locked'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
- EQUALITY generalizedTimeMatch
- ORDERING generalizedTimeOrderingMatch
- SINGLE-VALUE
- USAGE directoryOperation)
-.RE
-
-.B pwdExpirationWarned
-.P
-This attribute denotes the time when the first password
-expiration warning was sent to the client regarding this account.
-The amount of time between when this warning is sent and when
-the password actually expires is the amount of time stored in
-the
-.B pwdExpireWarning
-password policy attribute.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.18
- NAME 'pwdExpirationWarned'
- DESC 'The time the user was first warned about the
- coming expiration of their password'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
- EQUALITY generalizedTimeMatch
- ORDERING generalizedTimeOrderingMatch
- SINGLE-VALUE
- USAGE directoryOperation )
-.RE
-
-.B pwdFailureTime
-.P
-This attribute contains the timestamps of each of the consecutive
-authentication failures made upon attempted authentication to this
-DN (i.e. account). If too many timestamps accumulate here (refer to
-the
-.B pwdMaxFailure
-password policy attribute for details),
-and the
-.B pwdLockout
-password policy attribute is set to "TRUE", the
-account may be locked.
-(Please also refer to the
-.B pwdLockout
-password policy attribute.)
-Excess timestamps beyond those allowed by
-.B pwdMaxFailure
-may also be purged. If a successful authentication is made to this
-DN (i.e. to this user account), then
-.B pwdFailureTime
-will be cleansed of entries.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.19
- NAME 'pwdFailureTime'
- DESC 'The timestamps of the last consecutive
- authentication failures'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
- EQUALITY generalizedTimeMatch
- ORDERING generalizedTimeOrderingMatch
- USAGE directoryOperation )
-.RE
-
-.B pwdHistory
-.P
-This attribute contains the history of previously used passwords
-for this DN (i.e. for this user account).
-The values of this attribute are stored in string format as follows:
-
-.RS 4
-
-pwdHistory=
-.RS 4
-time "#" syntaxOID "#" length "#" data
-.RE
-
-time=
-.RS 4
-generalizedTimeString as specified in section 6.14 of [RFC2252]
-.RE
-
-.P
-syntaxOID = numericoid
-.RS 4
-This is the string representation of the dotted-decimal OID that
-defines the syntax used to store the password. numericoid is
-described in section 4.1 of [RFC2252].
-.RE
-
-length = numericstring
-.RS 4
-The number of octets in the data. numericstring is described in
-section 4.1 of [RFC2252].
-.RE
-
-data =
-.RS 4
-Octets representing the password in the format specified by syntaxOID.
-.RE
-
-.RE
-
-This format allows the server to store and transmit a history of
-passwords that have been used. In order for equality matching
-on the values in this attribute to function properly, the time
-field is in GMT format.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.20
- NAME 'pwdHistory'
- DESC 'The history of user passwords'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
- EQUALITY octetStringMatch
- USAGE directoryOperation)
-.RE
-
-.B pwdGraceUseTime
-This attribute contains the list of timestamps of logins made after
-the user password in the DN has expired. These post-expiration
-logins are known as
-.RI " "grace logins" ."
-If too many
-.I grace logins
-have been used (please refer to the
-.B pwdGraceLoginLimit
-password policy attribute), then the DN will no longer be allowed
-to be used to authenticate the user to the directory until the
-administrator changes the DN's
-.B userPassword
-attribute.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.21
- NAME 'pwdGraceUseTime'
- DESC 'The timestamps of the grace login once the password has expired'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
- EQUALITY generalizedTimeMatch
- USAGE directoryOperation)
-.RE
-
-.B pwdReset
-.P
-This attribute indicates whether the user's password has been reset
-by the administrator and thus must be changed upon first use of this
-DN for authentication to the directory. If
-.B pwdReset
-is set to "TRUE", then the password was reset and the user must change
-it upon first authentication. If the attribute does not exist, or
-is set to "FALSE", the user need not change their password due to
-administrative reset.
-.LP
-.RS 4
-( 1.3.6.1.4.1.42.2.27.8.1.22
- NAME 'pwdReset'
- DESC 'The indication that the password has
- been reset'
- EQUALITY booleanMatch
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
- SINGLE-VALUE
- USAGE directoryOperation)
-.RE
-
-.SH EXAMPLES
-.LP
-.RS
-.nf
-database bdb
-suffix dc=example,dc=com
-\...
-overlay ppolicy
-ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
-.fi
-.RE
-
-.SH SEE ALSO
-.BR ldap (3),
-.BR slapd.conf (5),
-.LP
-"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
-.LP
-IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
-Sermersheim: documented in IETF document
-"draft-behera-ldap-password-policy-07.txt".
-
-.SH BUGS
-The LDAP Password Policy specification is not yet an approved standard,
-and it is still evolving. This code will continue to be in flux until the
-specification is finalized.
-
-.SH ACKNOWLEDGEMENTS
-.P
-This module was written in 2004 by Howard Chu of Symas Corporation
-with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
-.P
-This manual page borrows heavily and shamelessly from the specification
-upon which the password policy module it describes is based. This
-source is the
-IETF LDAP password policy proposal by P. Behera, L.
-Poitou and J. Sermersheim.
-The proposal is fully documented in
-the
-IETF document named draft-behera-ldap-password-policy-07.txt,
-written in February of 2004.
-.P
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
--- /dev/null
+.\" $OpenLDAP$
+.\" Copyright 2004 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.TH SLAPD_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.SH NAME
+slapo-ppolicy \- Password Policy overlay
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.SH DESCRIPTION
+.LP
+The
+.B ppolicy
+overlay
+is an implementation of the most recent IETF Password
+Policy proposal for LDAP. When instantiated, it intercepts,
+decodes and applies specific password policy controls to overall
+use of a backend database, changes to user password fields, etc.
+.P
+The overlay provides a variety of password control mechanisms. They
+include password aging--both minimum and maximum ages, password
+reuse and duplication control, account time-outs, mandatory password
+resets, acceptable password content, and even grace logins.
+Different groups of users may be associated with different password
+policies, and there is no limit to the number of password policies
+that may be created.
+
+.SH CONFIGURATION
+These
+.B slapd.conf
+configuration options apply to the ppolicy overlay. They should appear
+after the
+.B overlay
+directive.
+.TP
+.B ppolicy_default <policyDN>
+Specify the DN of the pwdPolicy object to use when no specific policy is
+set on a given user's entry. If there is no specific policy for an entry
+and no default is given, then no policies will be enforced.
+.TP
+.B ppolicy_use_lockout
+A client will always receive an LDAP
+.B InvalidCredentials
+response when
+Binding to a locked account. By default, when a Password Policy control
+was provided on the Bind request, a Password Policy response will be
+included with no special error code set. This option changes the
+Password Policy response to include the
+.B AccountLocked
+error code. Note
+that sending the
+.B AccountLocked
+error code provides useful information
+to an attacker; sites that are sensitive to security issues should not
+enable this option.
+
+.SH OBJECT CLASS
+The
+.B ppolicy
+overlay depends on the
+.B pwdPolicy
+object class. The definition of that class is as follows:
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.2.1
+ NAME 'pwdPolicy'
+ AUXILIARY
+ SUP top
+ MUST ( pwdAttribute )
+ MAY (
+ pwdMinAge $ pwdMaxAge $ pwdInHistory $
+ pwdCheckSyntax $ pwdMinLength $
+ pwdExpireWarning $ pwdGraceLoginLimit $
+ pwdLockout $ pwdLockoutDuration $
+ pwdMaxFailure $ pwdFailureCountInterval $
+ pwdMustChange $ pwdAllowUserChange $
+ pwdSafeModify ) )
+.RE
+
+This implementation also provides an additional
+.B pwdPolicyChecker
+objectclass, used for password quality checking (see below).
+.LP
+.RS 4
+( 1.3.6.1.4.1.4754.2.99.1
+ NAME 'pwdPolicyChecker'
+ AUXILIARY
+ SUP top
+ MAY ( pwdCheckModule ) )
+.RE
+.P
+Every account that should be subject to password policy control should
+have a
+.B
+pwdPolicySubentry
+attribute containing the DN of a valid
+.B pwdPolicy
+entry, or they can simply use the configured default.
+In this way different users may be managed according to
+different policies.
+
+.SH OBJECT CLASS ATTRIBUTES
+.P
+Each one of the sections below details the meaning and use of a particular
+attribute of this
+.B pwdPolicy
+object class.
+.P
+
+.B pwdAttribute
+.P
+This attribute contains the name of the attribute to which the password
+policy is applied. For example, the password policy may be applied
+to the
+.B userPassword
+attribute.
+.P
+Note: in this implementation, the only
+value accepted for
+.B pwdAttribute
+is
+.RI " userPassword ".
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.1
+ NAME 'pwdAttribute'
+ EQUALITY objectIdentifierMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
+.RE
+
+.B pwdMinAge
+.P
+This attribute contains the number of seconds that must elapse
+between modifications allowed to the password. If this attribute
+is not present, zero seconds is assumed (i.e. the password may be
+modified whenever and however often is desired).
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.2
+ NAME 'pwdMinAge'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdMaxAge
+.P
+This attribute contains the number of seconds after which a modified
+password will expire. If this attribute is not present, or if its
+value is zero (0), then passwords will not expire.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.3
+ NAME 'pwdMaxAge'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdInHistory
+.P
+This attribute is used to specify the maximum number of used
+passwords that will be stored in the
+.B pwdHistory
+attribute. If the
+.B pwdInHistory
+attribute is not present, or if its value is
+zero (0), used passwords will not be stored in
+.B pwdHistory
+and thus any previously-used password may be reused.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.4
+ NAME 'pwdInHistory'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdCheckQuality
+.P
+This attribute indicates if and how password syntax will be checked
+while a password is being modified or added. If this attribute is
+not present, or its value is zero (0), no syntax checking will be
+done. If its value is one (1), the server will check the syntax,
+and if the server is unable to check the syntax,
+whether due to a client-side hashed password or some other reason,
+it will be
+accepted. If its value is two (2), the server will check the syntax,
+and if the server is unable to check the syntax it will return an
+error refusing the password.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.5
+ NAME 'pwdCheckQuality'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdMinLength
+.P
+When syntax checking is enabled
+(see also the
+.B pwdCheckSyntax
+attribute), this attribute contains the minimum
+number of characters that will be accepted in a password. If this
+attribute is not present, minimum password length is not
+enforced. If the server is unable to check the length of the password,
+whether due to a client-side hashed password or some other reason,
+the server will, depending on the
+value of
+.BR pwdCheckSyntax ,
+either accept the password
+without checking it (if
+.B pwdCheckSyntax
+is zero (0) or one (1)) or refuse it (if
+.B pwdCheckSyntax
+is two (2)).
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.6
+ NAME 'pwdMinLength'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdExpireWarning
+.P
+This attribute contains the maximum number of seconds before a
+password is due to expire that expiration warning messages will be
+returned to a user who is authenticating to the directory.
+If this attribute is not
+present, or if the value is zero (0), no warnings will be sent.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.7
+ NAME 'pwdExpireWarning'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdGraceLoginLimit
+.P
+This attribute contains the number of times that an expired password
+may be used to authenticate a user to the directory. If this
+attribute is not present or if its value is zero (0), users with
+expired passwords will not be allowed to authenticate to the
+directory.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.8
+ NAME 'pwdGraceLoginLimit'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdLockout
+.P
+This attribute specifies the action that should be taken
+by the directory when a user has made a number of failed attempts
+to authenticate to the directory. If
+.B pwdLockout
+is set (its value is "TRUE"), the user will not be allowed to
+attempt to authenticate to the directory after there have been a
+specified number of consecutive failed bind attempts. The maximum
+number of consecutive failed bind attempts allowed is specified by
+the
+.B pwdMaxFailure
+attribute. If
+.B pwdLockout
+is not present, or if its value is "FALSE", the password may be
+used to authenticate no matter how many consecutive failed bind
+attempts have been made.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.9
+ NAME 'pwdLockout'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+.RE
+
+.B pwdLockoutDuration
+.P
+This attribute contains the number of seconds during
+which the password cannot be used to authenticate the
+user to the directory due to too many consecutive failed
+bind attempts.
+(See also
+.B pwdLockout
+and
+.BR pwdMaxFailure .)
+If
+.B pwdLockoutDuration
+is not present, or if its value is zero (0), the password
+cannot be used to authenticate the user to the directory
+again until it is reset by an administrator.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.10
+ NAME 'pwdLockoutDuration'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdMaxFailure
+.P
+This attribute contains the number of consecutive failed bind
+attempts after which the password may not be used to authenticate
+a user to the directory.
+If
+.B pwdMaxFailure
+is not present, or its value is zero (0), then a user will
+be allowed to continue to attempt to authenticate to
+the directory, no matter how many consecutive failed
+bind attempts have occurred with that user's DN.
+(See also
+.B pwdLockout
+and
+.BR pwdLockoutDuration .)
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.11
+ NAME 'pwdMaxFailure'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdFailureCountInterval
+.P
+This attribute contains the number of seconds after which old
+consecutive failed bind attempts are purged from the failure counter,
+even though no successful authentication has occurred.
+If
+.B pwdFailureCountInterval
+is not present, or its value is zero (0), the failure
+counter will only be reset by a successful authentication.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.12
+ NAME 'pwdFailureCountInterval'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+.RE
+
+.B pwdMustChange
+.P
+This attribute specifies whether users must change their passwords
+when they first bind to the directory after a password is set or
+reset by the administrator, or not. If
+.B pwdMustChange
+has a value of "TRUE", users must change their passwords when they
+first bind to the directory after a password is set or reset by
+the administrator. If
+.B pwdMustChange
+is not present, or its value is "FALSE",
+users are not required to change their password upon binding after
+the administrator sets or resets the password.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.13
+ NAME 'pwdMustChange'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+.RE
+
+.B pwdAllowUserChange
+.P
+This attribute specifies whether users are allowed to change their own
+passwords or not. If
+.B pwdAllowUserChange
+is set to "TRUE", or if the attribute is not present, users will be
+allowed to change their own passwords. If its value is "FALSE",
+users will not be allowed to change their own passwords.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.14
+ NAME 'pwdAllowUserChange'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+.RE
+
+.B pwdSafeModify
+.P
+This attribute denotes whether the user's existing password must be sent
+along with their new password when changing a password. If
+.B pwdSafeModify
+is set to "TRUE", the existing password must be sent
+along with the new password. If the attribute is not present, or
+its value is "FALSE", the existing password need not be sent
+along with the new password.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.15
+ NAME 'pwdSafeModify'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+.RE
+
+.B pwdCheckModule
+.P
+This attribute names a user-defined loadable module that must
+instantiate the check_password() function. This function
+will be called to further check a new password if
+.B pwdCheckQuality
+is set to one (1) or two (2),
+after all of the built-in password compliance checks have
+been passed. This function will be called according to this
+function prototype:
+.RS 4
+int
+.I check_password
+(char *pPasswd, char **ppErrStr, void *pArg);
+.RE
+The
+.B pPasswd
+parameter contains the clear-text user password, the
+.B ppErrStr
+parameter contains a double pointer that allows the function
+to return human-readable details about any error it encounters.
+The
+.B pArg
+parameter is currently unused.
+If
+.B ppErrStr
+is NULL, then
+.I funcName
+must NOT attempt to use it/them.
+A return value of LDAP_SUCCESS from the called
+function indicates that the password is ok, any other value
+indicates that the password is unacceptable. If the password is
+unacceptable, the server will return an error to the client, and
+.B ppErrStr
+may be used to return a human-readable textual explanation of the
+error.
+.LP
+.RS 4
+( 1.3.6.1.4.1.4754.1.99.1
+ NAME 'pwdCheckModule'
+ EQUALITY caseExactIA5Match
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
+ SINGLE-VALUE )
+.RE
+.P
+Note:
+The user-defined loadable module named by
+.B pwdCheckModule
+must be in
+.B slapd's
+standard executable search PATH.
+.P
+Note:
+.B pwdCheckModule
+is a non-standard extension to the LDAP password
+policy proposal.
+
+.SH OPERATIONAL ATTRIBUTES
+.P
+The operational attributes used by the
+.B passwd_policy
+module are stored in the user's entry. Most of these attributes
+are not intended to be changed directly by users; they are there
+to track user activity. They have been detailed here so that
+administrators and users can both understand the workings of
+the
+.B ppolicy
+module.
+
+.B userPassword
+.P
+The
+.b userPassword
+attribute is not strictly part of the
+.B ppolicy
+module. It is, however, the attribute that is tracked and controlled
+by the module. Please refer to the standard OpenLDAP schema for
+its definition.
+
+.B pwdPolicySubentry
+.P
+This attribute refers directly to the
+.B pwdPolicy
+subentry that is to be used for this particular directory user.
+If
+.B pwdPolicySubentry
+exists, it must contain the DN of a valid
+.B pwdPolicy
+object. If it does not exist, the
+.B ppolicy
+module will enforce the default password policy rules on the
+user associated with this authenticating DN. If there is no
+default, or the referenced subentry does not exist, then no
+policy rules wil be enforced.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.23
+ NAME 'pwdPolicySubentry'
+ DESC 'The pwdPolicy subentry in effect for
+ this object'
+ EQUALITY distinguishedNameMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
+ SINGLE-VALUE
+ USAGE directoryOperation)
+.RE
+
+.B pwdChangedTime
+.P
+This attribute denotes the last time that the entry's password was
+changed. This value is used by the password expiration policy to
+determine whether the password is too old to be allowed to be used
+for user authentication. If
+.B pwdChangedTime
+does not exist, the user's password will not expire.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.16
+ NAME 'pwdChangedTime'
+ DESC 'The time the password was last changed'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SINGLE-VALUE
+ USAGE directoryOperation)
+.RE
+
+.B pwdAccountLockedTime
+.P
+This attribute contains the time that the user's account was locked.
+If the account has been locked, the password may no longer be used to
+authenticate the user to the directory. If
+.B pwdAccountLockedTime
+is set to zero (0), the user's account has been permanently locked
+and may only be unlocked by an administrator.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.17
+ NAME 'pwdAccountLockedTime'
+ DESC 'The time an user account was locked'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SINGLE-VALUE
+ USAGE directoryOperation)
+.RE
+
+.B pwdExpirationWarned
+.P
+This attribute denotes the time when the first password
+expiration warning was sent to the client regarding this account.
+The amount of time between when this warning is sent and when
+the password actually expires is the amount of time stored in
+the
+.B pwdExpireWarning
+password policy attribute.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.18
+ NAME 'pwdExpirationWarned'
+ DESC 'The time the user was first warned about the
+ coming expiration of their password'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SINGLE-VALUE
+ USAGE directoryOperation )
+.RE
+
+.B pwdFailureTime
+.P
+This attribute contains the timestamps of each of the consecutive
+authentication failures made upon attempted authentication to this
+DN (i.e. account). If too many timestamps accumulate here (refer to
+the
+.B pwdMaxFailure
+password policy attribute for details),
+and the
+.B pwdLockout
+password policy attribute is set to "TRUE", the
+account may be locked.
+(Please also refer to the
+.B pwdLockout
+password policy attribute.)
+Excess timestamps beyond those allowed by
+.B pwdMaxFailure
+may also be purged. If a successful authentication is made to this
+DN (i.e. to this user account), then
+.B pwdFailureTime
+will be cleansed of entries.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.19
+ NAME 'pwdFailureTime'
+ DESC 'The timestamps of the last consecutive
+ authentication failures'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ USAGE directoryOperation )
+.RE
+
+.B pwdHistory
+.P
+This attribute contains the history of previously used passwords
+for this DN (i.e. for this user account).
+The values of this attribute are stored in string format as follows:
+
+.RS 4
+
+pwdHistory=
+.RS 4
+time "#" syntaxOID "#" length "#" data
+.RE
+
+time=
+.RS 4
+generalizedTimeString as specified in section 6.14 of [RFC2252]
+.RE
+
+.P
+syntaxOID = numericoid
+.RS 4
+This is the string representation of the dotted-decimal OID that
+defines the syntax used to store the password. numericoid is
+described in section 4.1 of [RFC2252].
+.RE
+
+length = numericstring
+.RS 4
+The number of octets in the data. numericstring is described in
+section 4.1 of [RFC2252].
+.RE
+
+data =
+.RS 4
+Octets representing the password in the format specified by syntaxOID.
+.RE
+
+.RE
+
+This format allows the server to store and transmit a history of
+passwords that have been used. In order for equality matching
+on the values in this attribute to function properly, the time
+field is in GMT format.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.20
+ NAME 'pwdHistory'
+ DESC 'The history of user passwords'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
+ EQUALITY octetStringMatch
+ USAGE directoryOperation)
+.RE
+
+.B pwdGraceUseTime
+This attribute contains the list of timestamps of logins made after
+the user password in the DN has expired. These post-expiration
+logins are known as
+.RI " "grace logins" ."
+If too many
+.I grace logins
+have been used (please refer to the
+.B pwdGraceLoginLimit
+password policy attribute), then the DN will no longer be allowed
+to be used to authenticate the user to the directory until the
+administrator changes the DN's
+.B userPassword
+attribute.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.21
+ NAME 'pwdGraceUseTime'
+ DESC 'The timestamps of the grace login once the password has expired'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ EQUALITY generalizedTimeMatch
+ USAGE directoryOperation)
+.RE
+
+.B pwdReset
+.P
+This attribute indicates whether the user's password has been reset
+by the administrator and thus must be changed upon first use of this
+DN for authentication to the directory. If
+.B pwdReset
+is set to "TRUE", then the password was reset and the user must change
+it upon first authentication. If the attribute does not exist, or
+is set to "FALSE", the user need not change their password due to
+administrative reset.
+.LP
+.RS 4
+( 1.3.6.1.4.1.42.2.27.8.1.22
+ NAME 'pwdReset'
+ DESC 'The indication that the password has
+ been reset'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE
+ USAGE directoryOperation)
+.RE
+
+.SH EXAMPLES
+.LP
+.RS
+.nf
+database bdb
+suffix dc=example,dc=com
+\...
+overlay ppolicy
+ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
+.fi
+.RE
+
+.SH SEE ALSO
+.BR ldap (3),
+.BR slapd.conf (5),
+.LP
+"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
+.LP
+IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
+Sermersheim: documented in IETF document
+"draft-behera-ldap-password-policy-07.txt".
+
+.SH BUGS
+The LDAP Password Policy specification is not yet an approved standard,
+and it is still evolving. This code will continue to be in flux until the
+specification is finalized.
+
+.SH ACKNOWLEDGEMENTS
+.P
+This module was written in 2004 by Howard Chu of Symas Corporation
+with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
+.P
+This manual page borrows heavily and shamelessly from the specification
+upon which the password policy module it describes is based. This
+source is the
+IETF LDAP password policy proposal by P. Behera, L.
+Poitou and J. Sermersheim.
+The proposal is fully documented in
+the
+IETF document named draft-behera-ldap-password-policy-07.txt,
+written in February of 2004.
+.P
+.B OpenLDAP
+is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
+.B OpenLDAP
+is derived from University of Michigan LDAP 3.3 Release.
projects / openldap / commitdiff