bionic (5) slapo-ppolicy.5.gz

Provided by: slapd_2.4.45+dfsg-1ubuntu1.11_amd64 bug

NAME

       slapo-ppolicy - Password Policy overlay to slapd

SYNOPSIS

       /etc/ldap/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 performed with the rootdn
       identity; all the operations, when performed with any other identity, may be  subjected  to  constraints,
       like access control.  This overlay requires a rootdn to be configured on the database.

       Note  that  the  IETF  Password  Policy  proposal  for  LDAP makes sense when considering a single-valued
       password attribute, while  the  userPassword  attribute  allows  multiple  values.   This  implementation
       enforces a single value for the userPassword attribute, despite its specification.

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_forward_updates
              Specify that policy state changes that result from Bind operations (such  as  recording  failures,
              lockout,  etc.)  on  a  consumer should be forwarded to a master instead of being written directly
              into the consumer's local database. This setting is only useful on  a  replication  consumer,  and
              also requires the updateref setting and chain overlay to be appropriately configured.

       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 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 $ pwdMaxRecordedFailure ) )

       This implementation also provides an additional pwdPolicyChecker 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 control 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 attribute 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'
              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
       attribute is not present, or if its value is zero (0), then passwords 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
       pwdHistory  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 password 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.

           (  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  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.

           (  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 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  authenticate
       the  user  to  the  directory due to too many consecutive failed bind attempts.  (See also pwdLockout and
       pwdMaxFailure.)  If 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.

           (  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 consecutive failed bind attempts after which the password may not
       be used to authenticate a user to the directory.  If 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  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 )

       pwdMaxRecordedFailure

       This  attribute  contains  the  maximum  number  of  failed bind attempts to store in a user's entry.  If
       pwdMaxRecordedFailure is not present, or its value is  zero  (0),  then  it  defaults  to  the  value  of
       pwdMaxFailure.  If that value is also 0, the default is 5.

           (  1.3.6.1.4.1.42.2.27.8.1.16
              NAME 'pwdMaxRecordedFailure'
              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   successful   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.

           (  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
       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.

       Note: this implies that when pwdAllowUserChange is set to "TRUE", users will still be able to change  the
       password of another user, subjected to access control.  This restriction only applies to modifications of
       ones's own password.  It should also be noted that pwdAllowUserChange was defined in the specification to
       provide  rough  access  control to the password attribute in implementations that do not allow fine-grain
       access control.  Since OpenLDAP provides  fine-grain  access  control,  the  use  of  this  attribute  is
       discouraged; ACLs should be used instead (see slapd.access(5) for details).

           (  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 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 prototype:
           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 pwdCheckModule 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 ppolicy 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.

       Note that the current IETF Password Policy proposal does not define how these operational attributes  are
       expected  to  behave  in a replication environment. In general, authentication attempts on a slave server
       only affect the copy of the operational attributes on that slave and will not affect any attributes for a
       user's  entry  on the master server. Operational attribute changes resulting from authentication attempts
       on a master server will usually replicate to the slaves (and also overwrite any changes  that  originated
       on  the slave).  These behaviors are not guaranteed and are subject to change when a formal specification
       emerges.

       userPassword

       The userPassword attribute is not strictly part of the 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.

       pwdPolicySubentry

       This attribute refers directly to the pwdPolicy subentry that is to be used for this particular directory
       user.   If  pwdPolicySubentry exists, it must contain 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 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 000001010000Z, the user's account has  been  permanently  locked  and  may  only  be  unlocked  by  an
       administrator.  Note that account locking only takes effect when the pwdLockout password policy attribute
       is set to "TRUE".

           (  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 be locked.  (Please also refer to the pwdLockout password policy attribute.)
       Excess timestamps beyond those allowed by pwdMaxFailure or pwdMaxRecordedFailure 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=
               GeneralizedTime as specified in section 3.3.13 of [RFC4517]

           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 1.4 of [RFC4512].

           length = NumericString
               The number of octets in the data.  NumericString is described in section 3.3.23 of [RFC4517].

           data =
               Octets representing the password in the format specified by syntaxOID.

       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.

           (  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
              NO-USER-MODIFICATION
              USAGE directoryOperation)

       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 "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 authenticate 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 password 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 authentication.  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), slapd-config(5), slapo-chain(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 Corporation 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  Software  is  developed  and  maintained  by  The  OpenLDAP Project <http://www.openldap.org/>.
       OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.