slapo-ppolicy(5)
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
NAME
slapo-ppolicy - Password Policy overlay
SYNOPSIS
/etc/openldap/slapd.conf
DESCRIPTION
The 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. 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. Note that some of
the policies do not take effect when the operation is per-
formed with the rootdn identity; all the operations, when
performed with any other identity, may be subjected to con-
straints, like access control.
CONFIGURATION
These slapd.conf configuration options apply to the ppolicy
overlay. They should appear after the overlay directive.
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.
ppolicy_hash_cleartext
Specify that cleartext passwords present in Add and
Modify requests should be hashed before being stored in
the database. This violates the X.500/LDAP information
model, but may be needed to compensate for LDAP clients
that don't use the Password Modify extended operation
to manage passwords. It is recommended that when this
option is used that compare, search, and read access be
denied to all directory users.
ppolicy_use_lockout
A client will always receive an LDAP 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 AccountLocked
OpenLDAP 2.3.27 Last change: 2006/08/19 1
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
error code. Note that sending the AccountLocked error
code provides useful information to an attacker; sites
that are sensitive to security issues should not enable
this option.
OBJECT CLASS
The ppolicy overlay depends on the pwdPolicy object class.
The definition of that class is as follows:
( 1.3.6.1.4.1.42.2.27.8.2.1
NAME 'pwdPolicy'
AUXILIARY
SUP top
MUST ( pwdAttribute )
MAY (
pwdMinAge $ pwdMaxAge $ pwdInHistory $
pwdCheckQuality $ pwdMinLength $
pwdExpireWarning $ pwdGraceAuthnLimit $
pwdLockout $ pwdLockoutDuration $
pwdMaxFailure $ pwdFailureCountInterval $
pwdMustChange $ pwdAllowUserChange $
pwdSafeModify ) )
This implementation also provides an additional pwdPoli-
cyChecker objectclass, used for password quality checking
(see below).
( 1.3.6.1.4.1.4754.2.99.1
NAME 'pwdPolicyChecker'
AUXILIARY
SUP top
MAY ( pwdCheckModule ) )
Every account that should be subject to password policy con-
trol should have a pwdPolicySubentry attribute containing
the DN of a valid pwdPolicy entry, or they can simply use
the configured default. In this way different users may be
managed according to different policies.
OBJECT CLASS ATTRIBUTES
Each one of the sections below details the meaning and use
of a particular attribute of this pwdPolicy object class.
pwdAttribute This attribute contains the name of the attri-
bute to which the password policy is applied. For example,
the password policy may be applied to the userPassword
attribute. Note: in this implementation, the only value
accepted for pwdAttribute is userPassword .
( 1.3.6.1.4.1.42.2.27.8.1.1
NAME 'pwdAttribute'
OpenLDAP 2.3.27 Last change: 2006/08/19 2
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
EQUALITY objectIdentifierMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
pwdMinAge 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).
( 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 )
pwdMaxAge This attribute contains the number of seconds
after which a modified password will expire. If this attri-
bute is not present, or if its value is zero (0), then pass-
words will not expire.
( 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 )
pwdInHistory This attribute is used to specify the maximum
number of used passwords that will be stored in the pwdHis-
tory attribute. If the pwdInHistory attribute is not
present, or if its value is zero (0), used passwords will
not be stored in pwdHistory and thus any previously-used
password may be reused. No history checking occurs if the
password is being modified by the rootdn, although the pass-
word is saved in the history.
( 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 )
pwdCheckQuality 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.
OpenLDAP 2.3.27 Last change: 2006/08/19 3
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
( 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 )
pwdMinLength When syntax checking is enabled (see also the
pwdCheckQuality 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 pwdCheckQuality, either accept the password
without checking it (if pwdCheckQuality is zero (0) or one
(1)) or refuse it (if pwdCheckQuality is two (2)).
( 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 )
pwdExpireWarning This attribute contains the maximum number
of seconds before a password is due to expire that expira-
tion 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.
( 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 )
pwdGraceAuthnLimit 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.
( 1.3.6.1.4.1.42.2.27.8.1.8
NAME 'pwdGraceAuthnLimit'
EQUALITY integerMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
SINGLE-VALUE )
pwdLockout 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
pwdLockout is set (its value is "TRUE"), the user will not
OpenLDAP 2.3.27 Last change: 2006/08/19 4
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
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 pwdMaxFailure
attribute. If 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.
( 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 )
pwdLockoutDuration This attribute contains the number of
seconds during which the password cannot be used to authen-
ticate the user to the directory due to too many consecutive
failed bind attempts. (See also pwdLockout and pwdMax-
Failure.) If pwdLockoutDuration is not present, or if its
value is zero (0), the password cannot be used to authenti-
cate the user to the directory again until it is reset by an
administrator.
( 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 )
pwdMaxFailure This attribute contains the number of consecu-
tive failed bind attempts after which the password may not
be used to authenticate a user to the directory. If pwdMax-
Failure 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
pwdLockout and pwdLockoutDuration.)
( 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 )
pwdFailureCountInterval This attribute contains the number
of seconds after which old consecutive failed bind attempts
are purged from the failure counter, even though no success-
ful authentication has occurred. If pwdFailureCountInterval
is not present, or its value is zero (0), the failure
counter will only be reset by a successful authentication.
OpenLDAP 2.3.27 Last change: 2006/08/19 5
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
( 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 )
pwdMustChange 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 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
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.
( 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 )
pwdAllowUserChange This attribute specifies whether users
are allowed to change their own passwords or not. If pwdAl-
lowUserChange is set to "TRUE", or if the attribute is not
present, users will be allowed to change their own pass-
words. If its value is "FALSE", users will not be allowed
to change their own passwords.
( 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 )
pwdSafeModify This attribute denotes whether the user's
existing password must be sent along with their new password
when changing a password. If 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.
( 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 )
pwdCheckModule 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
OpenLDAP 2.3.27 Last change: 2006/08/19 6
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
if 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 pro-
totype:
int check_password (char *pPasswd, char **ppErrStr,
Entry *pEntry);
The pPasswd parameter contains the clear-text user password,
the ppErrStr parameter contains a double pointer that allows
the function to return human-readable details about any
error it encounters. The optional pEntry parameter, if
non-NULL, carries a pointer to the entry whose password is
being checked. If ppErrStr is NULL, then 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 ppErrStr may be used to return a
human-readable textual explanation of the error. The error
string must be dynamically allocated as it will be free()'d
by slapd.
( 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 )
Note: The user-defined loadable module named by pwdCheckMo-
dule must be in slapd's standard executable search PATH.
Note: pwdCheckModule is a non-standard extension to the
LDAP password policy proposal.
OPERATIONAL ATTRIBUTES
The operational attributes used by the 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 ppolicy module.
userPassword The attribute is not strictly part of the ppol-
icy module. It is, however, the attribute that is tracked
and controlled by the module. Please refer to the standard
OpenLDAP schema for its definition.
pwdPolicySubentry This attribute refers directly to the
pwdPolicy subentry that is to be used for this particular
directory user. If pwdPolicySubentry exists, it must con-
tain the DN of a valid pwdPolicy object. If it does not
exist, the 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
OpenLDAP 2.3.27 Last change: 2006/08/19 7
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
not exist, then no policy rules will be enforced.
( 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
NO-USER-MODIFICATION
USAGE directoryOperation)
pwdChangedTime 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 pwdChangedTime does not exist, the user's password will
not expire.
( 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
NO-USER-MODIFICATION
USAGE directoryOperation)
pwdAccountLockedTime 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 pwdAccountLockedTime is set
to zero (0), the user's account has been permanently locked
and may only be unlocked by an administrator.
( 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
NO-USER-MODIFICATION
USAGE directoryOperation)
pwdFailureTime 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 pwdMaxFailure
password policy attribute for details), and the pwdLockout
password policy attribute is set to "TRUE", the account may
OpenLDAP 2.3.27 Last change: 2006/08/19 8
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
be locked. (Please also refer to the pwdLockout password
policy attribute.) Excess timestamps beyond those allowed
by pwdMaxFailure may also be purged. If a successful
authentication is made to this DN (i.e. to this user
account), then pwdFailureTime will be cleansed of entries.
( 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
NO-USER-MODIFICATION
USAGE directoryOperation )
pwdHistory 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:
pwdHistory=
time "#" syntaxOID "#" length "#" data
time=
generalizedTimeString as specified in section 6.14
of [RFC2252]
syntaxOID = numericoid
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].
length = numericstring
The number of octets in the data. numericstring is
described in section 4.1 of [RFC2252].
data =
Octets representing the password in the format
specified by syntaxOID.
This format allows the server to store and transmit a his-
tory of passwords that have been used. In order for equal-
ity matching on the values in this attribute to function
properly, the time field is in GMT format.
( 1.3.6.1.4.1.42.2.27.8.1.20
NAME 'pwdHistory'
DESC 'The history of user passwords'
OpenLDAP 2.3.27 Last change: 2006/08/19 9
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
EQUALITY octetStringMatch
NO-USER-MODIFICATION
USAGE directoryOperation)
pwdGraceUseTime This attribute contains the list of times-
tamps of logins made after the user password in the DN has
expired. These post-expiration logins are known as "grace
logins". If too many grace logins have been used (please
refer to the pwdGraceLoginLimit password policy attribute),
then the DN will no longer be allowed to be used to authen-
ticate the user to the directory until the administrator
changes the DN's userPassword attribute.
( 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
NO-USER-MODIFICATION
USAGE directoryOperation)
pwdReset This attribute indicates whether the user's pass-
word has been reset by the administrator and thus must be
changed upon first use of this DN for authentication to the
directory. If pwdReset is set to "TRUE", then the password
was reset and the user must change it upon first authentica-
tion. If the attribute does not exist, or is set to
"FALSE", the user need not change their password due to
administrative reset.
( 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)
EXAMPLES
database bdb
suffix dc=example,dc=com
overlay ppolicy
ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
SEE ALSO
ldap(3), slapd.conf(5),
OpenLDAP 2.3.27 Last change: 2006/08/19 10
SLAPO_PPOLICY(5) FILE FORMATS SLAPO_PPOLICY(5)
"OpenLDAP Administrator's Guide"
(http://www.OpenLDAP.org/doc/admin/)
IETF LDAP password policy proposal by P. Behera, L. Poitou
and J. Sermersheim: documented in IETF document "draft-
behera-ldap-password-policy-09.txt".
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.
ACKNOWLEDGEMENTS
This module was written in 2004 by Howard Chu of Symas Cor-
poration with significant input from Neil Dunbar and Kartik
Subbarao of Hewlett-Packard. 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-09.txt, written in July of 2005.
OpenLDAP is developed and maintained by The OpenLDAP Project
(http://www.openldap.org/). OpenLDAP is derived from
University of Michigan LDAP 3.3 Release.
OpenLDAP 2.3.27 Last change: 2006/08/19 11
Man(1) output converted with
man2html