idnits 2.17.1 draft-ietf-ldapext-sorting-02.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 303 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 12 has weird spacing: '...fts are worki...' == Line 13 has weird spacing: '...ments of the ...' == Line 14 has weird spacing: '...t other group...' == Line 18 has weird spacing: '...and may be ...' == Line 22 has weird spacing: '...atus of any ...' == (14 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 5, 1999) is 9152 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 112 -- Looks like a reference, but probably isn't: '1' on line 62 == Unused Reference: 'Bradner97' is defined on line 256, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2251 (ref. 'LDAPv3') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) == Outdated reference: A later version (-03) exists of draft-ietf-asid-ldapv3-simplepaged-00 ** Downref: Normative reference to an Informational draft: draft-ietf-asid-ldapv3-simplepaged (ref. 'LdapPaged') Summary: 13 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group A. Herron, Microsoft 2 INTERNET DRAFT T. Howes, Netscape 3 Expire in six months M. Wahl, Critical Angle Inc 4 A. Anantha, Microsoft 5 April 5, 1999 7 LDAP Control Extension for Server Side Sorting of Search Results 8 draft-ietf-ldapext-sorting-02.txt 10 1. Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working docu- 13 ments of the Internet Engineering Task Force (IETF), its areas, and its 14 working groups. Note that other groups may also distribute working 15 documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet- Drafts as reference material 20 or to cite them other than as ``work in progress.'' 22 To learn the current status of any Internet-Draft, please check the 23 ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow 24 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 25 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 27 This document expires on October 5, 1999. 29 2. Abstract 31 This document describes two LDAPv3 control extensions for server side 32 sorting of search results. These controls allows a client to specify the 33 attribute types and matching rules a server should use when returning 34 the results to an LDAP search request. The controls may be useful when 35 the LDAP client has limited functionality or for some other reason 36 cannot sort the results but still needs them sorted. Other permissible 37 controls on search operations are not defined in this extension. 39 The sort controls allow a server to return a result code for the sorting 40 of the results that is independent of the result code returned for the 41 search operation. 43 The key words "MUST", "SHOULD", and "MAY" used in this document are to 44 be interpreted as described in [bradner97]. 46 3. The Controls 48 3.1 Request Control 50 This control is included in the searchRequest message as part of the 51 controls field of the LDAPMessage, as defined in Section 4.1.12 of 52 [LDAPv3]. 54 The controlType is set to "1.2.840.113556.1.4.473". The criticality 55 MAY be either TRUE or FALSE (where absent is also equivalent to 56 FALSE) at the client's option. The controlValue is an OCTET STRING, 57 whose value is the BER encoding of a value of the following SEQUENCE: 59 SortKeyList ::= SEQUENCE OF SEQUENCE { 60 attributeType AttributeDescription, 61 orderingRule [0] MatchingRuleId OPTIONAL, 62 reverseOrder [1] BOOLEAN DEFAULT FALSE } 64 The SortKeyList sequence is in order of highest to lowest sort key 65 precedence. 67 The MatchingRuleID SHOULD be one that is valid for the attribute type 68 it applies to. If it is not, the server MUST return unwillingToPerform. 70 Each attributeType should only occur in the SortKeyList once. If an 71 attributeType is included in the sort key list multiple times, the 72 server should return an error in the sortResult of unwillingToPerform. 74 If the orderingRule is omitted, the ordering MatchingRule defined for use 75 with this attribute MUST be used. 77 Any conformant implementation of this control MUST allow a sort key 78 list with at least one key. 80 3.2 Response Control 82 This control is included in the searchResultDone message as part of the 83 controls field of the LDAPMessage, as defined in Section 4.1.12 of 84 [LDAPv3]. 86 The controlType is set to "1.2.840.113556.1.4.474". The criticality is 87 FALSE (MAY be absent). The controlValue is an OCTET STRING, whose 88 value is the BER encoding of a value of the following SEQUENCE: 90 SortResult ::= SEQUENCE { 91 sortResult ENUMERATED { 92 success (0), -- results are sorted 93 operationsError (1), -- server internal failure 94 timeLimitExceeded (3), -- timelimit reached before 95 -- sorting was completed 96 strongAuthRequired (8), -- refused to return sorted 97 -- results via insecure 98 -- protocol 99 adminLimitExceeded (11), -- too many matching entries 100 -- for the server to sort 101 noSuchAttribute (16), -- unrecognized attribute 102 -- type in sort key 103 inappropriateMatching (18), -- unrecognized or inappro- 104 -- priate matching rule in 105 -- sort key 106 insufficientAccessRights (50), -- refused to return sorted 107 -- results to this client 108 busy (51), -- too busy to process 109 unwillingToPerform (53), -- unable to sort 110 other (80) 111 }, 112 attributeType [0] AttributeDescription OPTIONAL } 114 4. Client-Server Interaction 116 The sortKeyRequestControl specifies one or more attribute types and 117 matching rules for the results returned by a search request. The server 118 SHOULD return all results for the search request in the order specified 119 by the sort keys. If the reverseOrder field is set to TRUE, then the 120 entries will be presented in reverse sorted order for the specified 121 key. 123 There are six possible scenarios that may occur as a result of the sort 124 control being included on the search request : 126 1 - If the server does not support this sorting control and the client 127 specified TRUE for the control's criticality field, then the server 128 MUST return unavailableCriticalExtension as a return code in the 129 searchResultDone message and not send back any other results. This 130 behavior is specified in section 4.1.12 of [LDAPv3]. 132 2 - If the server does not support this sorting control and the client 133 specified FALSE for the control's criticality field, then the server 134 MUST ignore the sort control and process the search request as if it 135 were not present. This behavior is specified in section 4.1.12 of 136 [LDAPv3]. 138 3 - If the server supports this sorting control but for some reason 139 cannot sort the search results using the specified sort keys and the 140 client specified TRUE for the control's criticality field, then the 141 server SHOULD do the following: return unavailableCriticalExtension as 142 a return code in the searchResultDone message; include the 143 sortKeyResponseControl in the searchResultDone message, and not send 144 back any search result entries. 146 4 - If the server supports this sorting control but for some reason 147 cannot sort the search results using the specified sort keys and the 148 client specified FALSE for the control's criticality field, then the 149 server should return all search results unsorted and include the 150 sortKeyResponseControl in the searchResultDone message. 152 5 - If the server supports this sorting control and can sort the search 153 results using the specified sort keys, then it should include the 154 sortKeyResponseControl in the searchResultDone message with a 155 sortResult of success. 157 6 - If the search request failed for any reason and/or there are no 158 searchResultEntry messages returned for the search response, then the 159 server SHOULD omit the sortKeyResponseControl from the 160 searchResultDone message. 162 The client application is assured that the results are sorted in the 163 specified key order if and only if the result code in the 164 sortKeyResponseControl is success. If the server omits the 165 sortKeyResponseControl from the searchResultDone message, the client 166 SHOULD assume that the sort control was ignored by the server. 168 The sortKeyResponseControl, if included by the server in the 169 searchResultDone message, should have the sortResult set to either 170 success if the results were sorted in accordance with the keys 171 specified in the sortKeyRequestControl or set to the appropriate error 172 code as to why it could not sort the data (such as noSuchAttribute or 173 inappropriateMatching). Optionally, the server MAY set the 174 attributeType to the first attribute type specified in the SortKeyList 175 that was in error. The client SHOULD ignore the attributeType field if 176 the sortResult is success. 178 The server may not be able to sort the results using the specified sort 179 keys because it may not recognize one of the attribute types, the 180 matching rule associated with an attribute type is not applicable, or 181 none of the attributes in the search response are of these types. 182 Servers may also restrict the number of keys allowed in the control, 183 such as only supporting a single key. 185 Servers that chain requests to other LDAP servers should ensure that 186 the server satisfying the client's request sort the entire result set 187 prior to sending back the results. 189 4.1 Behavior in a chained environment 191 If a server receives a sort request, the client expects to receive a 192 set of sorted results. If a client submits a sort request to a server 193 which chains the request and gets entries from multiple servers, and 194 the client has set the criticality of the sort extension to TRUE, the 195 server MUST merge sort the results before returning them to the client 196 or MUST return unwillingToPerform. 198 4.2 Other sort issues 200 An entry that meets the search criteria may be missing one or more of 201 the sort keys. In that case, the entry is considered to have a value of 202 NULL for that key. This standard considers NULL to be a larger value 203 than all other valid values for that key. For example, if only one key 204 is specified, entries which meet the search criteria but do not have 205 that key collate after all the entries which do have that key. If the 206 reverseOrder flag is set, and only one key is specified, entries which 207 meet the search criteria but do not have that key collate BEFORE all 208 the entries which do have that key. 210 If a sort key is a multi-valued attribute, and an entry happens to have 211 multiple values for that attribute and no other controls are present that 212 affect the sorting order, then the server SHOULD use the least value 213 (according to the ORDERING rule for that attribute). 215 5. Interaction with other search controls 217 When the sortKeyRequestControl control is included with the 218 pagedResultsControl control as specified in [LdapPaged], then the 219 server should send the searchResultEntry messages sorted according to 220 the sort keys applied to the entire result set. The server should not 221 simply sort each page, as this will give erroneous results to the 222 client. 224 The sortKeyList must be present on each searchRequest message for the 225 paged result. It also must not change between searchRequests for the 226 same result set. If the server has sorted the data, then it SHOULD 227 send back a sortKeyResponseControl control on every searchResultDone 228 message for each page. This will allow clients to quickly determine 229 if the result set is sorted, rather than waiting to receive the entire 230 result set. 232 6. Security Considerations 234 Implementors and administrators should be aware that allowing sorting 235 of results could enable the retrieval of a large number of records from 236 a given directory service, irregardless of administrative limits set on 237 the maximum number of records to return. 239 A client that desired to pull all records out of a directory service 240 could use a combination of sorting and updating of search filters to 241 retrieve all records in a database in small result sets, thus 242 circumventing administrative limits. 244 This behavior can be overcome by the judicious use of permissions on 245 the directory entries by the administrator and by intelligent 246 implementations of administrative limits on the number of records 247 retrieved by a client. 249 7. References 251 [LDAPv3] 252 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access 253 Pro- 254 tocol (v3)", RFC 2251, December, 1997. 256 [Bradner97] 257 Bradner, Scott, "Key Words for use in RFCs to Indicate 258 Requirement 259 Levels", RFC 2119, March, 1997. 261 [LdapPaged] 262 C. Weider, A. Herron, and T. Howes, "LDAP Control Extension for 263 Simple Paged Results Manipulation", Internet Draft, February, 1997. 264 Available as draft-ietf-asid-ldapv3-simplepaged-00.txt. 266 8. Author's Address 268 Anoop Anantha 269 Microsoft Corp. 270 1 Microsoft Way 271 Redmond, WA 98052 272 USA 273 Anoopa@microsoft.com 274 +1 425 882-8080 276 Andy Herron 277 Microsoft Corp. 278 1 Microsoft Way 279 Redmond, WA 98052 280 USA 281 andyhe@microsoft.com 282 +1 425 882-8080 284 Tim Howes 285 Netscape Communications Corp. 286 501 E. Middlefield Road 287 Mountain View, CA 94043 288 USA 289 howes@netscape.com 290 +1 415 937-2600 292 Mark Wahl 293 Critical Angle Inc. 294 4815 W Braker Lane #502-385 295 Austin, TX 78759 296 USA 297 M.Wahl@critical-angle.com