doc: Add RFC documents

1 files changed, 451 insertions, 0 deletions

diff --git a/doc/rfc/rfc2891.txt b/doc/rfc/rfc2891.txt
new file mode 100644
index 0000000..1d91e07
--- /dev/null
+++ b/doc/rfc/rfc2891.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+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]
+
+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]
+
+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]
+
+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]
+
+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]
+
+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]
+
+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]
+
+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]
+