git.sur5r.net Git - openldap/blob - doc/drafts/draft-ietf-ldapext-sorting-xx.txt

   1 Network Working Group                               T. Howes, Netscape
   2 INTERNET DRAFT                             M. Wahl, Critical Angle Inc
   3 Intended Category: Standards Track               A. Anantha, Microsoft
   4 Expires: December 5, 2000                                 June 5, 2000
   5
   6
   7    LDAP Control Extension for Server Side Sorting of Search Results
   8                draft-ietf-ldapext-sorting-03.txt
   9
  10
  11 1.  Status of this Memo
  12
  13 This document is an Internet-Draft and is in full conformance with all
  14 provisions of Section 10 of RFC2026.  Internet-Drafts are working
  15 documents of the Internet Engineering Task Force (IETF), its areas, and
  16 its working groups.  Note that other groups may also distribute working
  17 documents as Internet-Drafts.
  18
  19 Internet-Drafts are draft documents valid for a maximum of six months
  20 and may be updated, replaced, or obsoleted by other documents at any
  21 time.  It is inappropriate to use Internet-Drafts as reference material
  22 or to cite them other than as "work in progress."
  23
  24 The list of current Internet-Drafts can be accessed at
  25 http://www.ietf.org/ietf/1id-abstracts.txt.
  26
  27 The list of Internet-Draft Shadow Directories can be accessed at
  28 http://www.ietf.org/shadow.html.
  29
  30 This draft document will be submitted to the RFC Editor as a Standards
  31 Track document. Distribution of this memo is unlimited. Technical
  32 discussion of this document will take place on the IETF LDAP Extension
  33 Working Group mailing list <ietf-ldapext@netscape.com>.  Please send
  34 editorial comments directly to the authors.
  35
  36 2.  Abstract
  37
  38 This document describes two LDAPv3 control extensions for server side
  39 sorting of search results. These controls allows a client to specify the
  40 attribute types and matching rules a server should use when returning
  41 the results to an LDAP search request. The controls may be useful when
  42 the LDAP client has limited functionality or for some other reason
  43 cannot sort the results but still needs them sorted. Other permissible
  44 controls on search operations are not defined in this extension.
  45
  46 The sort controls allow a server to return a result code for the sorting
  47 of the results that is independent of the result code returned for the
  48 search operation.
  49
  50 The key words "MUST", "SHOULD", and "MAY" used in this document are to
  51 be interpreted as described in [bradner97].
  52
  53 3.  The Controls
  54
  55 3.1 Request Control
  56
  57 This control is included in the searchRequest message as part of the
  58 controls field of the LDAPMessage, as defined in Section 4.1.12 of
  59 \f
  60 [LDAPv3].
  61
  62 The controlType is set to "1.2.840.113556.1.4.473". The criticality
  63 MAY be either TRUE or FALSE (where absent is also equivalent to
  64 FALSE) at the client's option. The controlValue is an OCTET STRING,
  65 whose value is the BER encoding of a value of the following SEQUENCE:
  66
  67      SortKeyList ::= SEQUENCE OF SEQUENCE {
  68                 attributeType   AttributeDescription,
  69                 orderingRule    [0] MatchingRuleId OPTIONAL,
  70                 reverseOrder    [1] BOOLEAN DEFAULT FALSE }
  71
  72 The SortKeyList sequence is in order of highest to lowest sort key
  73 precedence.
  74
  75 The MatchingRuleID SHOULD be one that is valid for the attribute type it
  76 applies to. If it is not, the server will return inappropriateMatching.
  77
  78 Each attributeType should only occur in the SortKeyList once. If an
  79 attributeType is included in the sort key list multiple times, the
  80 server should return an error in the sortResult of unwillingToPerform.
  81
  82 If the orderingRule is omitted, the ordering MatchingRule defined for
  83 use with this attribute MUST be used.
  84
  85 Any conformant implementation of this control MUST allow a sort key list
  86 with at least one key.
  87
  88 3.2 Response Control
  89
  90 This control is included in the searchResultDone message as part of the
  91 controls field of the LDAPMessage, as defined in Section  4.1.12 of
  92 [LDAPv3].
  93
  94 The controlType is set to "1.2.840.113556.1.4.474". The criticality is
  95 FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
  96 value is the BER encoding of a value of the following SEQUENCE:
  97
  98      SortResult ::= SEQUENCE {
  99         sortResult  ENUMERATED {
 100             success                   (0), -- results are sorted
 101             operationsError           (1), -- server internal failure
 102             timeLimitExceeded         (3), -- timelimit reached before
 103                                            -- sorting was completed
 104             strongAuthRequired        (8), -- refused to return sorted
 105                                            -- results via insecure
 106                                            -- protocol
 107             adminLimitExceeded       (11), -- too many matching entries
 108                                            -- for the server to sort
 109             noSuchAttribute          (16), -- unrecognized attribute
 110                                            -- type in sort key
 111             inappropriateMatching    (18), -- unrecognized or
 112                                            -- inappropriate matching
 113                                            -- rule in sort key
 114             insufficientAccessRights (50), -- refused to return sorted
 115                                            -- results to this client
 116             busy                     (51), -- too busy to process
 117 \f
 118             unwillingToPerform       (53), -- unable to sort
 119             other                    (80)
 120             },
 121       attributeType [0] AttributeDescription OPTIONAL }
 122
 123
 124 4.  Client-Server Interaction
 125
 126 The sortKeyRequestControl specifies one or more attribute types and
 127 matching rules for the results returned by a search request. The server
 128 SHOULD return all results for the search request in the order specified
 129 by the sort keys. If the reverseOrder field is set to TRUE, then the
 130 entries will be presented in reverse sorted order for the specified
 131 key.
 132
 133 There are six possible scenarios that may occur as a result of the sort
 134 control being included on the search request :
 135
 136 1 - If the server does not support this sorting control and the client
 137 specified TRUE for the control's criticality field, then the server
 138 MUST return unavailableCriticalExtension as a return code in the
 139 searchResultDone message and not send back any other results. This
 140 behavior is specified in section 4.1.12 of [LDAPv3].
 141
 142 2 - If the server does not support this sorting control and the client
 143 specified FALSE for the control's criticality field, then the server
 144 MUST ignore the sort control and process the search request as if it
 145 were not present. This behavior is specified in section 4.1.12 of
 146 [LDAPv3].
 147
 148 3 - If the server supports this sorting control but for some reason
 149 cannot sort the search results using the specified sort keys and the
 150 client specified TRUE for the control's criticality field, then the
 151 server SHOULD do the following: return unavailableCriticalExtension as
 152 a return code in the searchResultDone message; include the
 153 sortKeyResponseControl in the searchResultDone message, and not send
 154 back any search result entries.
 155
 156 4 - If the server supports this sorting control but for some reason
 157 cannot sort the search results using the specified sort keys and the
 158 client specified FALSE for the control's criticality field, then the
 159 server should return all search results unsorted and include the
 160 sortKeyResponseControl in the searchResultDone message.
 161
 162 5 - If the server supports this sorting control and can sort the search
 163 results using the specified sort keys, then it should include the
 164 sortKeyResponseControl in the searchResultDone message with a
 165 sortResult of success.
 166
 167 6 - If the search request failed for any reason and/or there are no
 168 searchResultEntry messages returned for the search response, then the
 169 server SHOULD omit the sortKeyResponseControl from the
 170 searchResultDone message.
 171
 172 The client application is assured that the results are sorted in the
 173 specified key order if and only if the result code in the
 174 sortKeyResponseControl is success. If the server omits the
 175 \f
 176 sortKeyResponseControl from the searchResultDone message, the client
 177 SHOULD assume that the sort control was ignored by the server.
 178
 179 The sortKeyResponseControl, if included by the server in the
 180 searchResultDone message, should have the sortResult set to either
 181 success if the results were sorted in accordance with the keys
 182 specified in the sortKeyRequestControl or set to the appropriate error
 183 code as to why it could not sort the data (such as noSuchAttribute or
 184 inappropriateMatching). Optionally, the server MAY set the
 185 attributeType to the first attribute type specified in the SortKeyList
 186 that was in error. The client SHOULD ignore the attributeType field if
 187 the sortResult is success.
 188
 189 The server may not be able to sort the results using the specified sort
 190 keys because it may not recognize one of the attribute types, the
 191 matching rule associated with an attribute type is not applicable, or
 192 none of the attributes in the search response are of these types.
 193 Servers may also restrict the number of keys allowed in the control,
 194 such as only supporting a single key.
 195
 196 Servers that chain requests to other LDAP servers should ensure that
 197 the server satisfying the client's request sort the entire result set
 198 prior to sending back the results.
 199
 200 4.1 Behavior in a chained environment
 201
 202 If a server receives a sort request, the client expects to receive a
 203 set of sorted results. If a client submits a sort request to a server
 204 which chains the request and gets entries from multiple servers, and
 205 the client has set the criticality of the sort extension to TRUE, the
 206 server MUST merge sort the results before returning them to the client
 207 or MUST return unwillingToPerform.
 208
 209 4.2 Other sort issues
 210
 211 An entry that meets the search criteria may be missing one or more of
 212 the sort keys. In that case, the entry is considered to have a value of
 213 NULL for that key. This standard considers NULL to be a larger value
 214 than all other valid values for that key. For example, if only one key
 215 is specified, entries which meet the search criteria but do not have
 216 that key collate after all the entries which do have that key. If the
 217 reverseOrder flag is set, and only one key is specified, entries which
 218 meet the search criteria but do not have that key collate BEFORE all
 219 the entries which do have that key.
 220
 221 If a sort key is a multi-valued attribute, and an entry happens to have
 222 multiple values for that attribute and no other controls are present
 223 that affect the sorting order, then the server SHOULD use the least
 224 value (according to the ORDERING rule for that attribute).
 225
 226 5.  Interaction with other search controls
 227
 228 When the sortKeyRequestControl control is included with the
 229 pagedResultsControl control as specified in [LdapPaged], then the
 230 server should send the searchResultEntry messages sorted according to
 231 the sort keys applied to the entire result set. The server should not
 232 simply sort each page, as this will give erroneous results to the
 233 \f
 234 client.
 235
 236 The sortKeyList must be present on each searchRequest message for the
 237 paged result. It also must not change between searchRequests for the
 238 same result set. If the server has sorted the data, then it SHOULD
 239 send back a sortKeyResponseControl control on every searchResultDone
 240 message for each page. This will allow clients to quickly determine
 241 if the result set is sorted, rather than waiting to receive the entire
 242 result set.
 243
 244
 245 6.  Security Considerations
 246
 247 Implementors and administrators should be aware that allowing sorting of
 248 results could enable the retrieval of a large number of records from
 249 a given directory service, regardless of administrative limits set on
 250 the maximum number of records to return.
 251
 252 A client that desired to pull all records out of a directory service
 253 could use a combination of sorting and updating of search filters to
 254 retrieve all records in a database in small result sets, thus
 255 circumventing administrative limits.
 256
 257 This behavior can be overcome by the judicious use of permissions on
 258 the directory entries by the administrator and by intelligent
 259 implementations of administrative limits on the number of records
 260 retrieved by a client.
 261
 262
 263 7.  References
 264
 265 [LDAPv3]
 266      Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
 267      Protocol (v3)",  RFC 2251, December, 1997.
 268
 269 [Bradner97]
 270      Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
 271      Levels", RFC 2119,  March,  1997.
 272
 273 [LdapPaged]
 274       C. Weider, A. Herron, A. Anantha and T. Howes, "LDAP Control
 275       Extension for Simple Paged Results Manipulation", RFC 2696,
 276       September 1999.
 277
 278
 279 8.  Author's Address
 280
 281 Anoop Anantha
 282 Microsoft Corp.
 283 1 Microsoft Way
 284 Redmond, WA 98052
 285 USA
 286 anoopa@microsoft.com
 287 +1 425 882-8080
 288 \f
 289 Tim Howes
 290 Loudcloud, Inc.
 291 615 Tasman Dr.
 292 Sunnyvale, CA 94089
 293 USA
 294 howes@loudcloud.com
 295
 296 Mark Wahl
 297 Sun Microsystems, Inc.
 298 8911 Capital of Texas Hwy Suite 4140
 299 Austin, TX 78759
 300 USA
 301 M.Wahl@innosoft.com
 302