Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



SLAPO_PPOLICY(5)                                                                            SLAPO_PPOLICY(5)



NAME
       slapo-ppolicy - Password Policy overlay to slapd

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  pass-word password
       word  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  con-straints, constraints,
       straints, 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  fail-ures, failures,
              ures,  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 con-sumer, consumer,
              sumer,  and  also requires the updateref setting and chain overlay to be appropriately config-ured. configured.
              ured.

       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 Pass-word Password
              word 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 fol-lows: follows:
       lows:

           (  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 qual-ity quality
       ity 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 pwdPol-icy pwdPolicy
       icy object class.


       pwdAttribute

       This attribute contains the name of the attribute to which the password policy is applied. For  exam-ple, example,
       ple, 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  modi-fied modified
       fied 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  modi-fied modified
       fied 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 expira-tion expiration
       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 num-ber number
       ber 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  authenti-cate authenticate
       cate  the user to the directory due to too many consecutive failed bind attempts.  (See also pwdLock-out pwdLockout
       out and pwdMaxFailure.)  If pwdLockoutDuration is not present, or if its value is zero (0), the pass-word password
       word  cannot be used to authenticate the user to the directory again until it is reset by an adminis-trator. administrator.
       trator.

           (  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 pwd-Lockout pwdLockout
       Lockout 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 pwdFail-ureCountInterval pwdFailureCountInterval
       ureCountInterval 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 direc-tory directory
       tory 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 pwdAllowUserChange
       lowUserChange  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  pass-words. passwords.
       words.

       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  modifi-cations modifications
       cations  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  pass-word password
       word 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() func-tion. function.
       tion.  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  pwdAccountLocked-Time pwdAccountLockedTime
       Time 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 administra-tor administrator
       tor 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 admin-istrative administrative
       istrative 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 pol-icy policy
       icy 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.



OpenLDAP 2.4.28                                  2011/11/24                                 SLAPO_PPOLICY(5)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback