Provided by: slapd_2.4.28-1.1ubuntu4_i386 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.

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

       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 )

       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
       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
       University of Michigan LDAP 3.3 Release.