rfc2254.txt LDAPv3 Search Filters (PS)
rfc2255.txt LDAPv3 URL Format (PS)
rfc2256.txt X.500(96) Schema for LDAPv3 (PS)
-rfc2279.txt UTF-8 (DS)
rfc2307.txt LDAP Network Information Services Schema (E)
rfc2377.txt LDAP Naming Plan (I)
rfc2596.txt Use of Language Codes in LDAP (PS)
-rfc2696.txt LDAP Simple Paged Result Control (I)
rfc2713.txt LDAP Java schema (I)
rfc2714.txt LDAP CORBA schema (I)
rfc2798.txt LDAP inetOrgPerson schema (I)
-rfc2828.txt Internet Security Glossary (FYI)
rfc2829.txt LDAPv3: Authentication Method (PS)
rfc2830.txt LDAPv3: StartTLS (PS)
rfc2849.txt LDIFv1 (PS)
-rfc2891.txt LDAPv3: Server Side Sorting of Search Results (PS)
rfc3062.txt LDAP Password Modify Extended Operation (PS)
rfc3088.txt OpenLDAP Root Service (E)
-rfc3112.txt LDAP Authentication Password Schema (I)
Legend:
STD Standard
+++ /dev/null
-
-
-
-
-
-
-Network Working Group C. Weider
-Request for Comments: 2696 A. Herron
-Category: Informational A. Anantha
- Microsoft
- T. Howes
- Netscape
- September 1999
-
-
- LDAP Control Extension for Simple Paged Results Manipulation
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-1. Abstract
-
- This document describes an LDAPv3 control extension for simple paging
- of search results. This control extension allows a client to control
- the rate at which an LDAP server returns the results of an LDAP
- search operation. This control may be useful when the LDAP client has
- limited resources and may not be able to process the entire result
- set from a given LDAP query, or when the LDAP client is connected
- over a low-bandwidth connection. Other operations on the result set
- are not defined in this extension. This extension is not designed to
- provide more sophisticated result set management.
-
- The key words "MUST", "SHOULD", and "MAY" used in this document are
- to be interpreted as described in [bradner97].
-
-2. The Control
-
- This control is included in the searchRequest and searchResultDone
- messages as part of the controls field of the LDAPMessage, as defined
- in Section 4.1.12 of [LDAPv3]. The structure of this control is as
- follows:
-
-
-
-
-
-
-
-
-
-Weider, et al. Informational [Page 1]
-\f
-RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
-
-
-pagedResultsControl ::= SEQUENCE {
- controlType 1.2.840.113556.1.4.319,
- criticality BOOLEAN DEFAULT FALSE,
- controlValue searchControlValue
-}
-
-The searchControlValue is an OCTET STRING wrapping the BER-encoded
-version of the following SEQUENCE:
-
-realSearchControlValue ::= SEQUENCE {
- size INTEGER (0..maxInt),
- -- requested page size from client
- -- result set size estimate from server
- cookie OCTET STRING
-}
-
-3. Client-Server Interaction
-
- An LDAP client application that needs to control the rate at which
- results are returned MAY specify on the searchRequest a
- pagedResultsControl with size set to the desired page size and cookie
- set to the zero-length string. The page size specified MAY be greater
- than zero and less than the sizeLimit value specified in the
- searchRequest.
-
- If the page size is greater than or equal to the sizeLimit value, the
- server should ignore the control as the request can be satisfied in a
- single page. If the server does not support this control, the server
- MUST return an error of unsupportedCriticalExtension if the client
- requested it as critical, otherwise the server SHOULD ignore the
- control. The remainder of this section assumes the server does not
- ignore the client's pagedResultsControl.
-
- Each time the server returns a set of results to the client when
- processing a search request containing the pagedResultsControl, the
- server includes the pagedResultsControl control in the
- searchResultDone message. In the control returned to the client, the
- size MAY be set to the server's estimate of the total number of
- entries in the entire result set. Servers that cannot provide such an
- estimate MAY set this size to zero (0). The cookie MUST be set to an
- empty value if there are no more entries to return (i.e., the page of
- search results returned was the last), or, if there are more entries
- to return, to an octet string of the server's choosing,used to resume
- the search.
-
- The client MUST consider the cookie to be an opaque structure and
- make no assumptions about its internal organization or value. When
- the client wants to retrieve more entries for the result set, it MUST
-
-
-
-Weider, et al. Informational [Page 2]
-\f
-RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
-
-
- send to the server a searchRequest with all values identical to the
- initial request with the exception of the messageID, the cookie, and
- optionally a modified pageSize. The cookie MUST be the octet string
- on the last searchResultDone response returned by the server.
- Returning cookies from previous searchResultDone responses besides
- the last one is undefined, as the server implementation may restrict
- cookies from being reused.
-
- The server will then return the next set of results from the whole
- result set. This interaction will continue until the client has
- retrieved all the results, in which case the cookie in the
- searchResultDone field will be empty, or until the client abandons
- the search sequence as described below. Once the paged search
- sequence has been completed, the cookie is no longer valid and MUST
- NOT be used.
-
- A sequence of paged search requests is abandoned by the client
- sending a search request containing a pagedResultsControl with the
- size set to zero (0) and the cookie set to the last cookie returned
- by the server. A client MAY use the LDAP Abandon operation to
- abandon one paged search request in progress, but this is discouraged
- as it MAY invalidate the client's cookie.
-
- If, for any reason, the server cannot resume a paged search operation
- for a client, then it SHOULD return the appropriate error in a
- searchResultDone entry. If this occurs, both client and server should
- assume the paged result set is closed and no longer resumable.
-
- A client may have any number of outstanding search requests pending,
- any of which may have used the pagedResultsControl. A server
- implementation which requires a limit on the number of outstanding
- paged search requests from a given client MAY either return
- unwillingToPerform when the client attempts to create a new paged
- search request, or age out an older result set. If the server
- implementation ages out an older paged search request, it SHOULD
- return "unwilling to perform" if the client attempts to resume the
- paged search that was aged out.
-
- A client may safely assume that all entries that satisfy a given
- search query are returned once and only once during the set of paged
- search requests/responses necessary to enumerate the entire result
- set, unless the result set for that query has changed since the
- searchRequest starting the request/response sequence was processed.
- In that case, the client may receive a given entry multiple times
- and/or may not receive all entries matching the given search
- criteria.
-
-
-
-
-
-Weider, et al. Informational [Page 3]
-\f
-RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
-
-
-4. Example
-
- The following example illustrates the client-server interaction
- between a client doing a search requesting a page size limit of 3.
- The entire result set returned by the server contains 5 entries.
-
- Lines beginning with "C:" indicate requests sent from client to
- server. Lines beginning with "S:" indicate responses sent from server
- to client. Lines beginning with "--" are comments to help explain the
- example.
-
- -- Client sends a search request asking for paged results
- -- with a page size of 3.
- C: SearchRequest + pagedResultsControl(3,"")
- -- Server responds with three entries plus an indication
- -- of 5 total entries in the search result and an opaque
- -- cooking to be used by the client when retrieving subsequent
- -- pages.
- S: SearchResultEntry
- S: SearchResultEntry
- S: SearchResultEntry
- S: SearchResultDone + pagedResultsControl(5, "opaque")
- -- Client sends an identical search request (except for
- -- message id), returning the opaque cooking, asking for
- -- the next page.
- C: SearchRequest + PagedResultsControl(3, "opaque")
- -- Server responds with two entries plus an indication
- -- that there are no more entries (null cookie).
- S: SearchResultEntry
- S: SearchResultEntry
- S: SearchResultDone + pagedResultsControl(5,"")
-
-5. Relationship to X.500
-
- For LDAP servers providing a front end to X.500 (93) directories, the
- paged results control defined in this document may be mapped directly
- onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The
- size parameter may be mapped onto pageSize. The cookie parameter may
- be mapped onto queryReference. The sortKeys and reverse fields in
- the X.500 PagedResultsRequest are excluded.
-
-
-
-
-
-
-
-
-
-
-
-Weider, et al. Informational [Page 4]
-\f
-RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
-
-
-6. Security Considerations
-
- Server implementors should consider the resources used when clients
- send searches with the simple paged control, to ensure that a
- client's misuse of this control does not lock out other legitimate
- operations.
-
- Servers implementations may enforce an overriding sizelimit, to
- prevent the retrieval of large portions of a publically-accessible
- directory.
-
- Clients can, using this control, determine how many entries match a
- particular filter, before the entries are returned to the client.
- This may require special processing in servers which perform access
- control checks on entries to determine whether the existence of the
- entry can be disclosed to the client.
-
-7. References
-
- [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
-
- [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Weider, et al. Informational [Page 5]
-\f
-RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
-
-
-8. Authors' Addresses
-
- Chris Weider
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
-
- Phone: +1 425 882-8080
- EMail: cweider@microsoft.com
-
-
- Andy Herron
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
-
- Phone: +1 425 882-8080
- EMail: andyhe@microsoft.com
-
-
- Anoop Anantha
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
-
- Phone: +1 425 882-8080
- EMail: anoopa@microsoft.com
-
-
- Tim Howes
- Netscape Communications Corp.
- 501 E. Middlefield Road
- Mountain View, CA 94043
- USA
-
- Phone: +1 415 937-2600
- EMail: howes@netscape.com
-
-
-
-
-
-
-
-
-
-
-
-Weider, et al. Informational [Page 6]
-\f
-RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999
-
-
-9. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Weider, et al. Informational [Page 7]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group T. Howes
-Request for Comments: 2891 Loudcloud
-Category: Standards Track M. Wahl
- Sun Microsystems
- A. Anantha
- Microsoft
- August 2000
-
-
- LDAP Control Extension for Server Side Sorting of Search Results
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
-Abstract
-
- This document describes two LDAPv3 control extensions for server side
- sorting of search results. These controls allows a client to specify
- the attribute types and matching rules a server should use when
- returning the results to an LDAP search request. The controls may be
- useful when the LDAP client has limited functionality or for some
- other reason cannot sort the results but still needs them sorted.
- Other permissible controls on search operations are not defined in
- this extension.
-
- The sort controls allow a server to return a result code for the
- sorting of the results that is independent of the result code
- returned for the search operation.
-
- The key words "MUST", "SHOULD", and "MAY" used in this document are
- to be interpreted as described in [bradner97].
-
-
-
-
-
-
-
-
-
-
-
-Howes, et al. Standards Track [Page 1]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
-1. The Controls
-
-1.1 Request Control
-
- This control is included in the searchRequest message as part of the
- controls field of the LDAPMessage, as defined in Section 4.1.12 of
- [LDAPv3].
-
- The controlType is set to "1.2.840.113556.1.4.473". The criticality
- MAY be either TRUE or FALSE (where absent is also equivalent to
- FALSE) at the client's option. The controlValue is an OCTET STRING,
- whose value is the BER encoding of a value of the following SEQUENCE:
-
- SortKeyList ::= SEQUENCE OF SEQUENCE {
- attributeType AttributeDescription,
- orderingRule [0] MatchingRuleId OPTIONAL,
- reverseOrder [1] BOOLEAN DEFAULT FALSE }
-
- The SortKeyList sequence is in order of highest to lowest sort key
- precedence.
-
- The MatchingRuleId, as defined in section 4.1.9 of [LDAPv3], SHOULD
- be one that is valid for the attribute type it applies to. If it is
- not, the server will return inappropriateMatching.
-
- Each attributeType should only occur in the SortKeyList once. If an
- attributeType is included in the sort key list multiple times, the
- server should return an error in the sortResult of
- unwillingToPerform.
-
- If the orderingRule is omitted, the ordering MatchingRule defined for
- use with this attribute MUST be used.
-
- Any conformant implementation of this control MUST allow a sort key
- list with at least one key.
-
-1.2 Response Control
-
- This control is included in the searchResultDone message as part of
- the controls field of the LDAPMessage, as defined in Section 4.1.12
- of [LDAPv3].
-
- The controlType is set to "1.2.840.113556.1.4.474". The criticality
- is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
- value is the BER encoding of a value of the following SEQUENCE:
-
-
-
-
-
-
-Howes, et al. Standards Track [Page 2]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
- SortResult ::= SEQUENCE {
- sortResult ENUMERATED {
- success (0), -- results are sorted
- operationsError (1), -- server internal failure
- timeLimitExceeded (3), -- timelimit reached before
- -- sorting was completed
- strongAuthRequired (8), -- refused to return sorted
- -- results via insecure
- -- protocol
- adminLimitExceeded (11), -- too many matching entries
- -- for the server to sort
- noSuchAttribute (16), -- unrecognized attribute
- -- type in sort key
- inappropriateMatching (18), -- unrecognized or
- -- inappropriate matching
- -- rule in sort key
- insufficientAccessRights (50), -- refused to return sorted
- -- results to this client
- busy (51), -- too busy to process
- unwillingToPerform (53), -- unable to sort
- other (80)
- },
- attributeType [0] AttributeDescription OPTIONAL }
-
-2. Client-Server Interaction
-
- The sortKeyRequestControl specifies one or more attribute types and
- matching rules for the results returned by a search request. The
- server SHOULD return all results for the search request in the order
- specified by the sort keys. If the reverseOrder field is set to TRUE,
- then the entries will be presented in reverse sorted order for the
- specified key.
-
- There are six possible scenarios that may occur as a result of the
- sort control being included on the search request:
-
- 1 - If the server does not support this sorting control and the
- client specified TRUE for the control's criticality field, then
- the server MUST return unavailableCriticalExtension as a return
- code in the searchResultDone message and not send back any other
- results. This behavior is specified in section 4.1.12 of
- [LDAPv3].
-
- 2 - If the server does not support this sorting control and the
- client specified FALSE for the control's criticality field, then
- the server MUST ignore the sort control and process the search
- request as if it were not present. This behavior is specified in
- section 4.1.12 of [LDAPv3].
-
-
-
-Howes, et al. Standards Track [Page 3]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
- 3 - If the server supports this sorting control but for some reason
- cannot sort the search results using the specified sort keys and
- the client specified TRUE for the control's criticality field,
- then the server SHOULD do the following: return
- unavailableCriticalExtension as a return code in the
- searchResultDone message; include the sortKeyResponseControl in
- the searchResultDone message, and not send back any search result
- entries.
-
- 4 - If the server supports this sorting control but for some reason
- cannot sort the search results using the specified sort keys and
- the client specified FALSE for the control's criticality field,
- then the server should return all search results unsorted and
- include the sortKeyResponseControl in the searchResultDone
- message.
-
- 5 - If the server supports this sorting control and can sort the
- search results using the specified sort keys, then it should
- include the sortKeyResponseControl in the searchResultDone
- message with a sortResult of success.
-
- 6 - If the search request failed for any reason and/or there are no
- searchResultEntry messages returned for the search response, then
- the server SHOULD omit the sortKeyResponseControl from the
- searchResultDone message.
-
- The client application is assured that the results are sorted in the
- specified key order if and only if the result code in the
- sortKeyResponseControl is success. If the server omits the
- sortKeyResponseControl from the searchResultDone message, the client
- SHOULD assume that the sort control was ignored by the server.
-
- The sortKeyResponseControl, if included by the server in the
- searchResultDone message, should have the sortResult set to either
- success if the results were sorted in accordance with the keys
- specified in the sortKeyRequestControl or set to the appropriate
- error code as to why it could not sort the data (such as
- noSuchAttribute or inappropriateMatching). Optionally, the server MAY
- set the attributeType to the first attribute type specified in the
- SortKeyList that was in error. The client SHOULD ignore the
- attributeType field if the sortResult is success.
-
- The server may not be able to sort the results using the specified
- sort keys because it may not recognize one of the attribute types,
- the matching rule associated with an attribute type is not
- applicable, or none of the attributes in the search response are of
- these types. Servers may also restrict the number of keys allowed in
- the control, such as only supporting a single key.
-
-
-
-Howes, et al. Standards Track [Page 4]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
- Servers that chain requests to other LDAP servers should ensure that
- the server satisfying the client's request sort the entire result set
- prior to sending back the results.
-
-2.1 Behavior in a chained environment
-
- If a server receives a sort request, the client expects to receive a
- set of sorted results. If a client submits a sort request to a server
- which chains the request and gets entries from multiple servers, and
- the client has set the criticality of the sort extension to TRUE, the
- server MUST merge sort the results before returning them to the
- client or MUST return unwillingToPerform.
-
-2.2 Other sort issues
-
- An entry that meets the search criteria may be missing one or more of
- the sort keys. In that case, the entry is considered to have a value
- of NULL for that key. This standard considers NULL to be a larger
- value than all other valid values for that key. For example, if only
- one key is specified, entries which meet the search criteria but do
- not have that key collate after all the entries which do have that
- key. If the reverseOrder flag is set, and only one key is specified,
- entries which meet the search criteria but do not have that key
- collate BEFORE all the entries which do have that key.
-
- If a sort key is a multi-valued attribute, and an entry happens to
- have multiple values for that attribute and no other controls are
- present that affect the sorting order, then the server SHOULD use the
- least value (according to the ORDERING rule for that attribute).
-
-3. Interaction with other search controls
-
- When the sortKeyRequestControl control is included with the
- pagedResultsControl control as specified in [LdapPaged], then the
- server should send the searchResultEntry messages sorted according to
- the sort keys applied to the entire result set. The server should not
- simply sort each page, as this will give erroneous results to the
- client.
-
- The sortKeyList must be present on each searchRequest message for the
- paged result. It also must not change between searchRequests for the
- same result set. If the server has sorted the data, then it SHOULD
- send back a sortKeyResponseControl control on every searchResultDone
- message for each page. This will allow clients to quickly determine
- if the result set is sorted, rather than waiting to receive the
- entire result set.
-
-
-
-
-
-Howes, et al. Standards Track [Page 5]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
-4. Security Considerations
-
- Implementors and administrators should be aware that allowing sorting
- of results could enable the retrieval of a large number of records
- from a given directory service, regardless of administrative limits
- set on the maximum number of records to return.
-
- A client that desired to pull all records out of a directory service
- could use a combination of sorting and updating of search filters to
- retrieve all records in a database in small result sets, thus
- circumventing administrative limits.
-
- This behavior can be overcome by the judicious use of permissions on
- the directory entries by the administrator and by intelligent
- implementations of administrative limits on the number of records
- retrieved by a client.
-
-5. References
-
- [LDAPv3] Wahl, M, Kille, S. and T. Howes, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
-
- [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [LdapPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP
- Control Extension for Simple Paged Results Manipulation",
- RFC 2696, September 1999.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Howes, et al. Standards Track [Page 6]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
-6. Authors' Addresses
-
- Anoop Anantha
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
-
- Phone: +1 425 882-8080
- EMail: anoopa@microsoft.com
-
-
- Tim Howes
- Loudcloud, Inc.
- 615 Tasman Dr.
- Sunnyvale, CA 94089
- USA
-
- EMail: howes@loudcloud.com
-
-
- Mark Wahl
- Sun Microsystems, Inc.
- 8911 Capital of Texas Hwy Suite 4140
- Austin, TX 78759
- USA
-
- EMail: Mark.Wahl@sun.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Howes, et al. Standards Track [Page 7]
-\f
-RFC 2891 LDAP Control Extension for Server Side Sorting August 2000
-
-
-7. Full Copyright Statement
-
- Copyright (C) The Internet Society (2000). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Howes, et al. Standards Track [Page 8]
-\f
+++ /dev/null
-
-
-
-
-
-
-Network Working Group K. Zeilenga
-Request for Comments: 3112 OpenLDAP Foundation
-Category: Informational May 2001
-
-
- LDAP Authentication Password Schema
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
-Abstract
-
- This document describes schema in support of user/password
- authentication in a LDAP (Lightweight Directory Access Protocol)
- directory including the authPassword attribute type. This attribute
- type holds values derived from the user's password(s) (commonly using
- cryptographic strength one-way hash). authPassword is intended to
- used instead of userPassword.
-
-1. Background and Intended Use
-
- The userPassword attribute type [RFC2256] is intended to be used to
- support the LDAP [RFC2251] "simple" bind operation. However, values
- of userPassword must be clear text passwords. It is often desirable
- to store values derived from the user's password(s) instead of actual
- passwords.
-
- The authPassword attribute type is intended to be used to store
- information used to implement simple password based authentication.
- The attribute type may be used by LDAP servers to implement the LDAP
- Bind operation's "simple" authentication method.
-
- The attribute type supports multiple storage schemes. A matching
- rule is provided for use with extensible search filters to allow
- clients to assert that a clear text password "matches" one of the
- attribute's values.
-
- Storage schemes often use cryptographic strength one-way hashing.
- Though the use of one-way hashing reduces the potential that exposed
- values will allow unauthorized access to the Directory (unless the
-
-
-
-
-Zeilenga Informational [Page 1]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
- hash algorithm/implementation is flawed), the hashing of passwords is
- intended to be as an additional layer of protection. It is
- RECOMMENDED that hashed values be protected as if they were clear
- text passwords.
-
- This attribute may be used in conjunction with server side password
- generation mechanisms (such as the LDAP Password Modify [RFC3062]
- extended operation).
-
- Access to this attribute may governed by administrative controls such
- as those which implement password change policies.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
- to be interpreted as described in RFC 2119 [RFC2119].
-
-2. Schema Definitions
-
- The following schema definitions are described in terms of LDAPv3
- Attribute Syntax Definitions [RFC2252] with specific syntax detailed
- using Augmented BNF [RFC2234].
-
-2.1. authPasswordSyntax
-
- ( 1.3.6.1.4.1.4203.1.1.2
- DESC 'authentication password syntax' )
-
- Values of this syntax are encoded according to:
-
- authPasswordValue = w scheme s authInfo s authValue w
- scheme = %x30-39 / %x41-5A / %x2D-2F / %x5F
- ; 0-9, A-Z, "-", ".", "/", or "_"
- authInfo = schemeSpecificValue
- authValue = schemeSpecificValue
- schemeSpecificValue = *( %x21-23 / %x25-7E )
- ; printable ASCII less "$" and " "
- s = w SEP w
- w = *SP
- SEP = %x24 ; "$"
- SP = %x20 ; " " (space)
-
- where scheme describes the mechanism and authInfo and authValue are a
- scheme specific. The authInfo field is often a base64 encoded salt.
- The authValue field is often a base64 encoded value derived from a
- user's password(s). Values of this attribute are case sensitive.
-
-
-
-
-
-
-Zeilenga Informational [Page 2]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
- Transfer of values of this syntax is strongly discouraged where the
- underlying transport service cannot guarantee confidentiality and may
- result in disclosure of the values to unauthorized parties.
-
- This document describes a number of schemes, as well as requirements
- for the scheme naming, in section 3.
-
-2.2. authPasswordExactMatch
-
- ( 1.3.6.1.4.1.4203.1.2.2
- NAME 'authPasswordExactMatch'
- DESC 'authentication password exact matching rule'
- SYNTAX 1.3.6.1.4.1.4203.1.1.2 )
-
- This matching rule allows a client to assert that an asserted
- authPasswordSyntax value matches authPasswordSyntax values. It is
- meant to be used as the EQUALITY matching rule of attributes whose
- SYNTAX is authPasswordSyntax.
-
- The assertion is "TRUE" if there is an attribute value which has the
- same scheme, authInfo, and authValue components as the asserted
- value; "FALSE" if no attribute value has the same components as the
- asserted value; and "Undefined" otherwise.
-
-2.3. authPasswordMatch
-
- ( 1.3.6.1.4.1.4203.1.2.3
- NAME 'authPasswordMatch'
- DESC 'authentication password matching rule'
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.40{128} )
-
- This matching rule allows a client to assert that a password matches
- values of authPasswordSyntax using an extensibleMatch filter
- component. Each value is matched per its scheme. The assertion is
- "TRUE" if one or more attribute values matches the asserted value,
- "FALSE" if all values do not matches, and "Undefined" otherwise.
-
- Servers which support use of this matching rule SHOULD publish
- appropriate matchingRuleUse values per [RFC2252], 4.4.
-
- Transfer of authPasswordMatch assertion values is strongly
- discouraged where the underlying transport service cannot guarantee
- confidentiality and may result in disclosure of the values to
- unauthorized parties.
-
-
-
-
-
-
-
-Zeilenga Informational [Page 3]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
-2.4. supportedAuthPasswordSchemes
-
- ( 1.3.6.1.4.1.4203.1.3.3
- NAME 'supportedAuthPasswordSchemes'
- DESC 'supported password storage schemes'
- EQUALITY caseExactIA5Match
- SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{32}
- USAGE dSAOperation )
-
- The values of this attribute are names of supported authentication
- password schemes which the server supports. The syntax of a scheme
- name is described in section 2.1. This attribute may only be present
- in the root DSE. If the server does not support any password
- schemes, this attribute will not be present.
-
-2.5. authPassword
-
- ( 1.3.6.1.4.1.4203.1.3.4 NAME 'authPassword'
- DESC 'password authentication information'
- EQUALITY 1.3.6.1.4.1.4203.1.2.2
- SYNTAX 1.3.6.1.4.1.4203.1.1.2 )
-
- The values of this attribute are representative of the user's
- password(s) and conform to the authPasswordSyntax described in 2.1.
- The values of this attribute may be used for authentication purposes.
-
- Transfer of authPassword values is strongly discouraged where the
- underlying transport service cannot guarantee confidentiality and may
- result in disclosure of the values to unauthorized parties.
-
-2.6. authPasswordObject
-
- ( 1.3.6.1.4.1.4203.1.4.7 NAME 'authPasswordObject'
- DESC 'authentication password mix in class'
- MAY 'authPassword'
- AUXILIARY )
-
- Entries of this object class may contain authPassword attribute
- types.
-
-3. Schemes
-
- This section describes the "MD5" and "SHA1" schemes. Other schemes
- may be defined by other documents. Schemes which are not described
- in an RFC SHOULD be named with a leading "X-" to indicate they are a
- private or implementation specific scheme, or may be named using the
- dotted-decimal representation [RFC2252] of an OID assigned to the
- scheme.
-
-
-
-Zeilenga Informational [Page 4]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
-3.1. MD5 scheme
-
- The MD5 [RFC1321] scheme name is "MD5".
-
- The authValue is the base64 encoding of an MD5 digest of the
- concatenation the user password and salt. The base64 encoding of the
- salt is provided in the authInfo field. The salt MUST be at least 64
- bits long. Implementations of this scheme MUST support salts up to
- 128 bits in length.
-
- Example:
- Given a user "joe" who's password is "mary" and a salt of "salt",
- the authInfo field would be the base64 encoding of "salt" and the
- authValue field would be the base64 encoding of the MD5 digest of
- "marysalt".
-
- A match against an asserted password and an attribute value of this
- scheme SHALL be true if and only if the MD5 digest of concatenation
- of the asserted value and the salt is equal to the MD5 digest
- contained in AuthValue. The match SHALL be undefined if the server
- is unable to complete the equality test for any reason. Otherwise
- the match SHALL be false.
-
- Values of this scheme SHOULD only be used to implement simple
- user/password authentication.
-
-3.2. SHA1 scheme
-
- The SHA1 [SHA1] scheme name is "SHA1".
-
- The authValue is the base64 encoding of a SHA1 digest of the
- concatenation the user password and the salt. The base64 encoding of
- the salt is provided in the authInfo field. The salt MUST be at
- least 64 bits long. Implementations of this scheme MUST support
- salts up to 128 bits in length.
-
- Example:
- Given a user "joe" who's password is "mary" and a salt of "salt",
- the authInfo field would be the base64 encoding of "salt" and the
- authValue field would be the base64 encoding of the SHA1 digest of
- "marysalt".
-
- A match against an asserted password and an attribute value of this
- scheme SHALL be true if and only if the SHA1 digest of concatenation
- of the asserted value and the salt is equal to the SHA1 digest
- contained in AuthValue. The match SHALL be undefined if the server
- is unable to complete the equality test for any reason. Otherwise
- the match SHALL be false.
-
-
-
-Zeilenga Informational [Page 5]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
- Values of this scheme SHOULD only be used to implement simple
- user/password authentication.
-
-4. Implementation Issues
-
- For all implementations of this specification:
-
- Servers MAY restrict which schemes are used in conjunction with a
- particular authentication process but SHOULD use all values of
- selected schemes. If the asserted password matches any of the
- stored values, the asserted password SHOULD be considered valid.
- Servers MAY use other authentication storage mechanisms, such as
- userPassword or an external password store, in conjunction with
- authPassword to support the authentication process.
-
- Servers that support simple bind MUST support the SHA1 scheme and
- SHOULD support the MD5 scheme.
-
- Servers SHOULD NOT publish values of authPassword nor allow
- operations which expose authPassword values or AuthPasswordMatch
- assertions to unless confidentiality protection is in place.
-
- Clients SHOULD NOT initiate operations which provide or request
- values of authPassword or make authPasswordMatch assertions unless
- confidentiality protection is in place.
-
- Clients SHOULD NOT assume that a successful AuthPasswordMatch,
- whether by compare or search, is sufficient to gain directory
- access. The bind operation MUST be used to authenticate to the
- directory.
-
-5. Security Considerations
-
- This document describes how authentication information may be stored
- in a directory. Authentication information MUST be adequately
- protected as unintended disclosure will allow attackers to gain
- immediate access to the directory as described by [RFC2829].
-
- As flaws may be discovered in the hashing algorithm or with a
- particular implementation of the algorithm or values could be subject
- to various attacks if exposed, values of AuthPassword SHOULD be
- protected as if they were clear text passwords. When values are
- transferred, privacy protections, such as IPSEC or TLS, SHOULD be in
- place.
-
- Clients SHOULD use strong authentication mechanisms [RFC2829].
-
-
-
-
-
-Zeilenga Informational [Page 6]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
- AuthPasswordMatch matching rule allows applications to test the
- validity of a user password and, hence, may be used to mount an
- attack. Servers SHOULD take appropriate measures to protect the
- directory from such attacks.
-
- Some password schemes may require CPU intensive operations. Servers
- SHOULD take appropriate measures to protect against Denial of Service
- attacks.
-
- AuthPassword does not restrict an authentication identity to a single
- password. An attacker who gains write access to this attribute may
- store additional values without disabling the user's true
- password(s). Use of policy aware clients and servers is RECOMMENDED.
-
- The level of protection offered against various attacks differ from
- scheme to scheme. It is RECOMMENDED that servers support scheme
- selection as a configuration item. This allows for a scheme to be
- easily disabled if a significant security flaw is discovered.
-
-6. Acknowledgment
-
- This document borrows from a number of IETF documents and is based
- upon input from the IETF LDAPext working group.
-
-7. Bibliography
-
- [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
- April 1992
-
- [RFC2219] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2234] Crocker, D., Editor, P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
-
- [RFC2252] Wahl, M., Coulbeck, A., Howes, T., and S. Kille,
- "Lightweight Directory Access Protocol (v3): Attribute
- Syntax Definitions", RFC 2252, December 1997.
-
- [RFC2256] Wahl, A., "A Summary of the X.500(96) User Schema for use
- with LDAPv3", RFC 2256, December 1997.
-
- [RFC2307] Howard, L., "An Approach for Using LDAP as a Network
- Information Service", RFC 2307, March 1998.
-
-
-
-
-Zeilenga Informational [Page 7]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
- [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
- "Authentication Methods for LDAP", RFC 2829, June 2000.
-
- [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation",
- RFC 3062, February 2001.
-
- [SHA1] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995.
-
-8. Author's Address
-
- Kurt D. Zeilenga
- OpenLDAP Foundation
-
- EMail: Kurt@OpenLDAP.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Zeilenga Informational [Page 8]
-\f
-RFC 3112 LDAP Authentication Password Schema May 2001
-
-
-9. Full Copyright Statement
-
- Copyright (C) The Internet Society (2001). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Zeilenga Informational [Page 9]
-\f
projects / openldap / commitdiff