Provided by: slapd_2.4.21-0ubuntu5_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.

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