DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

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