From 9e39c5e0b6e12cb8cd163272272ca9aede825a79 Mon Sep 17 00:00:00 2001 From: Howard Chu Date: Tue, 16 Mar 2004 22:00:30 +0000 Subject: [PATCH] Docs for ppolicy overlay --- doc/man/man5/slapd-ppolicy.5 | 738 +++++++++++++++++++++++++++++++++++ 1 file changed, 738 insertions(+) create mode 100644 doc/man/man5/slapd-ppolicy.5 diff --git a/doc/man/man5/slapd-ppolicy.5 b/doc/man/man5/slapd-ppolicy.5 new file mode 100644 index 0000000000..a4ec53563d --- /dev/null +++ b/doc/man/man5/slapd-ppolicy.5 @@ -0,0 +1,738 @@ +.\" $Id: slapd-ppolicy.5,v 1.2 2004/03/16 20:40:41 hyc Exp $ +.\" Copyright 2004 The OpenLDAP Foundation All Rights Reserved. +.\" Copying restrictions apply. See COPYRIGHT/LICENSE. +.TH SLAPD_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.SH NAME +slapd-ppolicy \- Password Policy overlay +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +.LP +The +.B 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. +.P +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. + +.SH CONFIGURATION +There is one +.B slapd.conf +configuration option for the ppolicy overlay. It should appear +after the +.B overlay +directive. +.TP +.B ppolicy_default +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. + +.SH OBJECT CLASS +The +.B ppolicy +overlay depends on the +.B pwdPolicy +object class. The definition of that class is as follows: +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.2.1 + NAME 'pwdPolicy' + AUXILIARY + SUP top + MUST ( pwdAttribute ) + MAY ( + pwdMinAge $ pwdMaxAge $ pwdInHistory $ + pwdCheckSyntax $ pwdMinLength $ + pwdExpireWarning $ pwdGraceLoginLimit $ + pwdLockout $ pwdLockoutDuration $ + pwdMaxFailure $ pwdFailureCountInterval $ + pwdMustChange $ pwdAllowUserChange $ + pwdSafeModify ) ) +.RE + +This implementation also provides an additional +.B pwdPolicyChecker +objectclass, used for password quality checking (see below). +.LP +.RS 4 +( 1.3.6.1.4.1.4754.2.99.1 + NAME 'pwdPolicyChecker' + AUXILIARY + SUP top + MAY ( pwdCheckModule ) ) +.RE +.P +Every account that should be subject to password policy control should +have a +.B +pwdPolicySubentry +attribute containing the DN of a valid +.B pwdPolicy +entry, or they can simply use the configured default. +In this way different users may be managed according to +different policies. + +.SH OBJECT CLASS ATTRIBUTES +.P +Each one of the sections below details the meaning and use of a particular +attribute of this +.B pwdPolicy +object class. +.P + +.B pwdAttribute +.P +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 +.B userPassword +attribute. +.P +Note: in this implementation, the only +value accepted for +.B pwdAttribute +is +.RI " userPassword ". +.LP +.RS 4 +( 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 ) +.RE + +.B pwdMinAge +.P +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). +.LP +.RS 4 +( 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 ) +.RE + +.B pwdMaxAge +.P +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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdInHistory +.P +This attribute is used to specify the maximum number of used +passwords that will be stored in the +.B pwdHistory +attribute. If the +.B pwdInHistory +attribute is not present, or if its value is +zero (0), used passwords will not be stored in +.B pwdHistory +and thus any previously-used password may be reused. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdCheckQuality +.P +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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdMinLength +.P +When syntax checking is enabled +(see also the +.B pwdCheckSyntax +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 +.BR pwdCheckSyntax , +either accept the password +without checking it (if +.B pwdCheckSyntax +is zero (0) or one (1)) or refuse it (if +.B pwdCheckSyntax +is two (2)). +.LP +.RS 4 +( 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 ) +.RE + +.B pwdExpireWarning +.P +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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdGraceLoginLimit +.P +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. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.8 + NAME 'pwdGraceLoginLimit' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 + SINGLE-VALUE ) +.RE + +.B pwdLockout +.P +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 +.B 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 +.B pwdMaxFailure +attribute. If +.B 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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdLockoutDuration +.P +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 +.B pwdLockout +and +.BR pwdMaxFailure .) +If +.B 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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdMaxFailure +.P +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 +.B 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 +.B pwdLockout +and +.BR pwdLockoutDuration .) +.LP +.RS 4 +( 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 ) +.RE + +.B pwdFailureCountInterval +.P +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 +.B pwdFailureCountInterval +is not present, or its value is zero (0), the failure +counter will only be reset by a successful authentication. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdMustChange +.P +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 +.B 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 +.B 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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdAllowUserChange +.P +This attribute specifies whether users are allowed to change their own +passwords or not. If +.B 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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdSafeModify +.P +This attribute denotes whether the user's existing password must be sent +along with their new password when changing a password. If +.B 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. +.LP +.RS 4 +( 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 ) +.RE + +.B pwdCheckModule +.P +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 +.B 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: +.RS 4 +int +.I check_password +(char *pPasswd, char **ppErrStr, void *pArg); +.RE +The +.B pPasswd +parameter contains the clear-text user password, the +.B ppErrStr +parameter contains a double pointer that allows the function +to return human-readable details about any error it encounters. +The +.B pArg +parameter is currently unused. +If +.B ppErrStr +is NULL, then +.I 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 +.B ppErrStr +may be used to return a human-readable textual explanation of the +error. +.LP +.RS 4 +( 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 ) +.RE +.P +Note: +The user-defined loadable module named by +.B pwdCheckModule +must be in +.B slapd's +standard executable search PATH. +.P +Note: +.B pwdCheckModule +is a non-standard extension to the LDAP password +policy proposal. + +.SH OPERATIONAL ATTRIBUTES +.P +The operational attributes used by the +.B 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 +.B ppolicy +module. + +.B userPassword +.P +The +.b userPassword +attribute is not strictly part of the +.B 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. + +.B pwdPolicySubentry +.P +This attribute refers directly to the +.B pwdPolicy +subentry that is to be used for this particular directory user. +If +.B pwdPolicySubentry +exists, it must contain the DN of a valid +.B pwdPolicy +object. If it does not exist, the +.B 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 wil be enforced. +.LP +.RS 4 +( 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 + USAGE directoryOperation) +.RE + +.B pwdChangedTime +.P +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 +.B pwdChangedTime +does not exist, the user's password will not expire. +.LP +.RS 4 +( 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 + USAGE directoryOperation) +.RE + +.B pwdAccountLockedTime +.P +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 +.B pwdAccountLockedTime +is set to zero (0), the user's account has been permanently locked +and may only be unlocked by an administrator. +.LP +.RS 4 +( 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 + USAGE directoryOperation) +.RE + +.B pwdExpirationWarned +.P +This attribute denotes the time when the first password +expiration warning was sent to the client regarding this account. +The amount of time between when this warning is sent and when +the password actually expires is the amount of time stored in +the +.B pwdExpireWarning +password policy attribute. +.LP +.RS 4 +( 1.3.6.1.4.1.42.2.27.8.1.18 + NAME 'pwdExpirationWarned' + DESC 'The time the user was first warned about the + coming expiration of their password' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SINGLE-VALUE + USAGE directoryOperation ) +.RE + +.B pwdFailureTime +.P +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 +.B pwdMaxFailure +password policy attribute for details), +and the +.B pwdLockout +password policy attribute is set to "TRUE", the +account may be locked. +(Please also refer to the +.B pwdLockout +password policy attribute.) +Excess timestamps beyond those allowed by +.B pwdMaxFailure +may also be purged. If a successful authentication is made to this +DN (i.e. to this user account), then +.B pwdFailureTime +will be cleansed of entries. +.LP +.RS 4 +( 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 + USAGE directoryOperation ) +.RE + +.B pwdHistory +.P +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: + +.RS 4 + +pwdHistory= +.RS 4 +time "#" syntaxOID "#" length "#" data +.RE + +time= +.RS 4 +generalizedTimeString as specified in section 6.14 of [RFC2252] +.RE + +.P +syntaxOID = numericoid +.RS 4 +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]. +.RE + +length = numericstring +.RS 4 +The number of octets in the data. numericstring is described in +section 4.1 of [RFC2252]. +.RE + +data = +.RS 4 +Octets representing the password in the format specified by syntaxOID. +.RE + +.RE + +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. +.LP +.RS 4 +( 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 + USAGE directoryOperation) +.RE + +.B 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 +.RI " "grace logins" ." +If too many +.I grace logins +have been used (please refer to the +.B 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 +.B userPassword +attribute. +.LP +.RS 4 +( 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 + USAGE directoryOperation) +.RE + +.B pwdReset +.P +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 +.B 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. +.LP +.RS 4 +( 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) +.RE + +.SH EXAMPLES +.LP +.RS +.nf +database bdb +suffix dc=example,dc=com +\... +overlay ppolicy +ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com" +.fi +.RE + +.SH SEE ALSO +.BR ldap (3), +.BR slapd.conf (5), +.LP +"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/) +.LP +IETF LDAP password policy proposal by P. Behera, L. Poitou and J. +Sermersheim: documented in IETF document +"draft-behera-ldap-password-policy-07.txt". + +.SH 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. + +.SH ACKNOWLEDGEMENTS +.P +This module was written in 2004 by Howard Chu of Symas Corporation +with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard. +.P +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-07.txt, +written in February of 2004. +.P +.B OpenLDAP +is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). +.B OpenLDAP +is derived from University of Michigan LDAP 3.3 Release. -- 2.39.5