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

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