--- /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
+There is one
+.B slapd.conf
+configuration option for the ppolicy overlay. It 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.
+
+.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