1 2 3LDAPEXT Working Group J. Sermersheim 4Internet Draft Novell, Inc 5Document: draft-ietf-ldapext-ldapv3-dupent-08.txt Sept 2002 6Intended Category: Standard Track 7 8 9 LDAP Control for a Duplicate Entry Representation of Search Results 10 11 121. Status of this Memo 13 14 This document is an Internet-Draft and is in full conformance with 15 all provisions of Section 10 of RFC2026 [1]. 16 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. Internet-Drafts are draft documents valid for a maximum of 21 six months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet- Drafts 23 as reference material or to cite them other than as "work in 24 progress." 25 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 28 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 31 322. Abstract 33 34 This document describes a Duplicate Entry Representation control 35 extension for the LDAP Search operation. By using the control with 36 an LDAP search, a client requests that the server return separate 37 entries for each value held in the specified attribute(s). For 38 instance, if a specified attribute of an entry holds multiple 39 values, the search operation will return multiple instances of that 40 entry, each instance holding a separate single value in that 41 attribute. 42 433. Introduction 44 45 This document describes controls, which allow duplicate entries to 46 be returned in the result set of search operation. Each duplicated 47 entry represents a distinct value (or combination of values) of the 48 set of specified multi-valued attributes. 49 50 For example, an application may need to produce an ordered list of 51 entries, sorted by a multi-valued attribute, where each attribute 52 value is represented in the list. The Server-Side Sorting control 53 [RFC2891] allows the server to order search result entries based on 54 attribute values (sort keys). But it does not allow one to specify 55 behavior when an attribute contains multiple values. The default 56 57 58Sermersheim Internet-Draft - Expires Mar 2003 Page 1 59LDAP Control for a Duplicate Entry Representation of Search Results 60 61 62 behavior, as outlined in 7.9 of [X.511], is to use the smallest 63 order value as the sort key. 64 65 In order to produce an ordered list, where each value of a multi- 66 valued attribute is sorted into the list, a separate control is 67 needed which causes the set of entries to be expanded sufficiently 68 to represent each attribute value prior to sorting. 69 70 71 72 An example of this would be a sorted list of all telephone numbers 73 in an organization. Because any entry may have multiple telephone 74 numbers, and the list is to be sorted by telephone number, the list 75 must be able to contain duplicate entries, each with its own unique 76 telephone number. 77 78 Another example would be an application that needs to display an 79 ordered list of all members of a group. It would use this control 80 to create a result set of duplicate groupOfNames entries, each with 81 a single, unique value in its member attribute. 82 834. Conventions 84 85 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 86 used in this document carry the meanings described in [RFC2119]. 87 88 All controlValue data is represented as ASN.1 in this document, and 89 is to be BER encoded as stated in Section 5.1 of [RFC2251]. 90 915. The Controls 92 93 Support for the controls is advertised by the presence of their OID 94 in the supportedControl attribute of a server's root DSE. The OID 95 for the request control is "2.16.840.1.113719.1.27.101.1" and the 96 OIDs for the response controls are "2.16.840.1.113719.1.27.101.2" 97 and "2.16.840.1.113719.1.27.101.3". 98 995.1 Request Control 100 101 This control is included in the searchRequest message as part of the 102 controls field of the LDAPMessage, as defined in Section 4.1.12 of 103 [RFC2251]. 104 105 The controlType is set to "2.16.840.1.113719.1.27.101.1". The 106 criticality MAY be set to either TRUE or FALSE. The controlValue is 107 defined as the following DuplicateEntryRequest: 108 109 DuplicateEntryRequest ::= SEQUENCE { 110 AttributeDescriptionList, -- from [RFC2251] 111 PartialApplicationAllowed BOOLEAN DEFAULT TRUE } 112 113 1145.1.1 AttributeDescriptionList Semantics 115 116Sermersheim Internet-Draft - Expires Mar 2003 Page 2 117LDAP Control for a Duplicate Entry Representation of Search Results 118 119 120 121 The AttributeDescriptionList data type is described in 4.1.5 of 122 [RFC2251] and describes a list of zero or more AttributeDescription 123 types as also described in 4.1.5 of [RFC2251]. Both definitions are 124 repeated here for convenience: 125 126 AttributeDescriptionList ::= SEQUENCE OF 127 AttributeDescription 128 129 AttributeDescription ::= LDAPString 130 131 A value of AttributeDescription is based on the following BNF: 132 133 attributeDescription = AttributeType [ ";" <options> ] 134 135 While processing a search request, a server implementation examines 136 this list. If a specified attribute or attribute subtype exists in 137 an entry to be returned by the search operation, and that attribute 138 holds multiple values, the server treats the entry as if it were 139 multiple, duplicate entries -- the specified attributes each holding 140 a single, unique value from the original set of values of that 141 attribute. Note that this may result in search result entries that 142 no longer match the search filter. 143 144 Specifying an attribute supertype has the effect of treating all 145 values of that attribute's subtypes as if they were values of the 146 specified attribute supertype. See Section 6.2 for an example of 147 this. 148 149 When attribute descriptions contain subtyping options, they are 150 treated in the same manner as is described in Section 4.1.5 of 151 [RFC2251]. Semantics are undefined if an attribute description 152 contains a non-subtyping option, and SHOULD NOT be specified by 153 clients. 154 155 When two or more attributes are specified by this control, the 156 number of duplicate entries is the combination of all values in each 157 attribute. Because of the potential complexity involved in servicing 158 multiple attributes, server implementations MAY choose to support a 159 limited number of attributes in the control. 160 161 There is a special case where either no attributes are specified, or 162 an attribute description value of "*" is specified. In this case, 163 all attributes are used. (The "*" allows the client to request all 164 user attributes in addition to specific operational attributes). 165 166 If an attribute is unrecognized, that attribute is ignored when 167 processing the control. 168 1695.1.2 PartialApplicationAllowed Semantics 170 171 The PartialApplicationAllowed field is used to specify whether the 172 client will allow the server to apply this control to a subset of 173 174Sermersheim Internet-Draft - Expires Mar 2003 Page 3 175LDAP Control for a Duplicate Entry Representation of Search Results 176 177 178 the search result set. If TRUE, the server is free to arbitrarily 179 apply this control to no, any, or all search results. If FALSE, the 180 server MUST either apply the control to all search results or fail 181 to support the control at all. 182 183 Client implementations use the DuplicateSearchResult control to 184 discover which search results have been affected by this control. 185 1865.2 Response Controls 187 188 Two response controls are defined to provide feedback while the 189 search results are being processed; DuplicateSearchResult and 190 DuplicateEntryResponseDone. 191 192 The DuplicateSearchResult control is sent with all SearchResultEntry 193 operations that contain search results which have been modified by 194 the DuplicateEntryRequest control. 195 196 The DuplicateEntryResponseDone control is sent with the 197 SearchResultDone operation in order to convey completion 198 information. 199 2005.2.1 The DuplicateSearchResult control 201 202 This control is included in the SearchResultEntry message of any 203 search result that holds an entry that has been modified by the 204 DuplicateEntryRequest control as part of the controls field of the 205 LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. This control 206 is absent on search results that are unaffected by 207 DuplicateEntryRequest control. 208 209 The controlType is set to "2.16.840.1.113719.1.27.101.2". The 210 controlValue is not included. 211 2125.2.2 The DuplicateEntryResponseDone control 213 214 This control is included in the searchResultDone message as part of 215 the controls field of the LDAPMessage, as defined in Section 4.1.12 216 of [RFC2251]. 217 218 The controlType is set to "2.16.840.1.113719.1.27.101.3". The 219 controlValue is defined as the following DuplicateEntryResponseDone: 220 221 DuplicateEntryResponseDone ::= SEQUENCE { 222 resultCode, -- From [RFC2251] 223 errorMessage [0] LDAPString OPTIONAL, 224 attribute [1] AttributeDescription OPTIONAL } 225 226 A resultCode field is provided here to allow the server to convey to 227 the client that an error resulted due to the control being serviced. 228 For example, a search that would ordinarily complete successfully 229 may fail with a sizeLimitExceeded error due to this control being 230 231 232Sermersheim Internet-Draft - Expires Mar 2003 Page 4 233LDAP Control for a Duplicate Entry Representation of Search Results 234 235 236 processed. If the operation is successfull, the value will be 237 success (0). 238 239 The errorMessage field MAY be populated with a human-readable string 240 in the event of an erroneous result code. 241 242 The attribute field MAY be set to the value of the first attribute 243 specified by the DuplicateEntryRequest that was in error. The 244 client MUST ignore the attribute field if the result is success. 245 2466. Protocol Examples 247 2486.1 Simple example 249 250 This example will show this control being used to produce a list of 251 all telephone numbers in the dc=example,dc=net container. Let's say 252 the following three entries exist in this container; 253 254 dn: cn=User1,dc=example,dc=net 255 telephoneNumber: 555-0123 256 257 dn: cn=User2,dc=example,dc=net 258 telephoneNumber: 555-8854 259 telephoneNumber: 555-4588 260 telephoneNumber: 555-5884 261 262 dn: cn=User3,dc=example,dc=net 263 telephoneNumber: 555-9425 264 telephoneNumber: 555-7992 265 266 First an LDAP search is specified with a baseDN of 267 "dc=example,dc=net", subtree scope, filter set to 268 "(telephoneNumber=*)". A DuplicateEntryRequest control is attached 269 to the search, specifying "telephoneNumber" as the attribute 270 description, and the search request is sent to the server. 271 272 The set of search results returned by the server would then consist 273 of the following entries: 274 275 dn: cn=User1,dc=example,dc=net 276 telephoneNumber: 555-0123 277 <no DuplicateSearchResult control sent with search result> 278 279 dn: cn=User2,dc=example,dc=net 280 telephoneNumber: 555-8854 281 control: 2.16.840.1.113719.1.27.101.2 282 283 dn: cn=User2,dc=example,dc=net 284 telephoneNumber: 555-4588 285 control: 2.16.840.1.113719.1.27.101.2 286 287 dn: cn=User2,dc=example,dc=net 288 telephoneNumber: 555-5884 289 290Sermersheim Internet-Draft - Expires Mar 2003 Page 5 291LDAP Control for a Duplicate Entry Representation of Search Results 292 293 294 control: 2.16.840.1.113719.1.27.101.2 295 296 dn: cn=User3,dc=example,dc=net 297 telephoneNumber: 555-9425 298 control: 2.16.840.1.113719.1.27.101.2 299 300 dn: cn=User3,dc=example,dc=net 301 telephoneNumber: 555-7992 302 control: 2.16.840.1.113719.1.27.101.2 303 304 All but the first entry are accompanied by the DuplicateSearchResult 305 control when sent from the server. 306 307 Note that it is not necessary to use an attribute in this control 308 that is specified in the search filter. This example only does so, 309 because the result was to obtain a list of telephone numbers. 310 3116.2 Specifying multiple attributes 312 313 A more complicated example involving multiple attributes will result 314 in more entries. If we assume these entries in the directory: 315 316 dn: cn=User1,dc=example,dc=net 317 cn: User1 318 givenName: User One 319 mail: user1@example.net 320 321 dn: cn=User2,dc=example,dc=net 322 cn: User2 323 givenName: User Two 324 mail: user2@example.net 325 mail: usertwo@example.net 326 327 In this example, we specify mail and name in the attribute list. By 328 specifying name, all attribute subtypes of name will also be 329 considered. Following is the resulting set of entries: 330 331 dn: cn=User1,dc=example,dc=net 332 cn: User1 333 mail: user1@example.net 334 control: 2.16.840.1.113719.1.27.101.2 335 336 dn: cn=User1,dc=example,dc=net 337 givenName: User One 338 mail: user1@example.net 339 control: 2.16.840.1.113719.1.27.101.2 340 341 dn: cn=User2,dc=example,dc=net 342 cn: User2 343 mail: user2@example.net 344 control: 2.16.840.1.113719.1.27.101.2 345 346 dn: cn=User2,dc=example,dc=net 347 348Sermersheim Internet-Draft - Expires Mar 2003 Page 6 349LDAP Control for a Duplicate Entry Representation of Search Results 350 351 352 cn: User2 353 mail: usertwo@example.net 354 control: 2.16.840.1.113719.1.27.101.2 355 356 dn: cn=User2,dc=example,dc=net 357 givenName: User Two 358 mail: user2@example.net 359 control: 2.16.840.1.113719.1.27.101.2 360 361 dn: cn=User2,dc=example,dc=net 362 givenName: User Two 363 mail: usertwo@example.net 364 control: 2.16.840.1.113719.1.27.101.2 365 3666.3 Listing the members of a groupOfNames 367 368 This example shows how the controls can be used to turn a single 369 groupOfNames entry into multiple duplicate entries. Let's say this 370 is our groupOfNames entry: 371 372 dn: cn=Administrators,dc=example,dc=net 373 cn: Administrators 374 member: cn=aBaker,dc=example,dc=net 375 member: cn=cDavis,dc=example,dc=net 376 member: cn=bChilds,dc=example,dc=net 377 member: cn=dEvans,dc=example,dc=net 378 379 We could set our search base to "cn=Administrators,dc=example,dc=net 380 ", filter to "(objectClass=*)", use an object scope (to restrict it 381 to this entry) and send the duplicateEntryRequest control with 382 "member" as its attribute value. The resulting set would look like 383 this: 384 385 dn: cn=Administrators,dc=example,dc=net 386 member: cn=aBaker,dc=example,dc=net 387 control: 2.16.840.1.113719.1.27.101.2 388 389 dn: cn=Administrators,dc=example,dc=net 390 member: cn=cDavis,dc=example,dc=net 391 control: 2.16.840.1.113719.1.27.101.2 392 393 dn: cn=Administrators,dc=example,dc=net 394 member: cn=bChilds,dc=example,dc=net 395 control: 2.16.840.1.113719.1.27.101.2 396 397 dn: cn=Administrators,dc=example,dc=net 398 member: cn=dEvans,dc=example,dc=net 399 control: 2.16.840.1.113719.1.27.101.2 400 401 This list can then be sorted by member and displayed (also by 402 member) in a list. 403 4047. Relationship to other controls 405 406Sermersheim Internet-Draft - Expires Mar 2003 Page 7 407LDAP Control for a Duplicate Entry Representation of Search Results 408 409 410 411 This control is intended (but not limited) to be used with the 412 Server Side Sorting control [RFC2891]. By pairing this control with 413 the Server Side Sorting control, One can produce a set of entries, 414 sorted by attribute values, where each attribute value is 415 represented in the sorted set. Server implementations MUST ensure 416 that this control is processed before sorting the result of a 417 search, as this control alters the result set of search. 418 419 This control MAY also be used with the Virtual List View [VLV] 420 control (which has a dependency on the Server Side Sort control). 421 The nature of the dependency between the VLV control and the Sort 422 control is such that the Sorting takes place first. Because the sort 423 happens first, and because this control is processed before the sort 424 control, the impact of this control on the VLV control is minimal. 425 Some server implementations may need to carefully consider how to 426 handle the typedown functionality of the VLV control when paired 427 with this control. The details of this are heavily implementation 428 dependent and are beyond the scope of this document. 429 4308. Notes for Implementers 431 432 Both client and server implementations MUST be aware that using this 433 control could potentially result in a very large set of search 434 results. Servers MAY return an adminLimitExceeded result in the 435 response control due to inordinate consumption of resources. This 436 may be due to some a priori knowledge such as a server restriction 437 of the number of attributes in the request control that it's willing 438 to service, or it may be due to the server attempting to service the 439 control and running out of resources. 440 441 Client implementations MUST be aware that when using this control, 442 search entries returned will contain a subset of the values of any 443 specified attribute. 444 445 If this control is used in a chained environment, servers SHOULD NOT 446 pass this control to other servers. Instead they SHOULD gather 447 results and apply this control themselves. 448 4499. Security Considerations 450 451 This control allows finer control of the result set returned by an 452 LDAP search operation and as such may be used in a denial of service 453 attack. See Section 8 for more information on how this is detected 454 and handled. 455 45610. Acknowledgments 457 458 The author gratefully thanks the input and support of participants 459 of the LDAP-EXT working group. 460 46111. References 462 463 464Sermersheim Internet-Draft - Expires Mar 2003 Page 8 465LDAP Control for a Duplicate Entry Representation of Search Results 466 467 468 [RFC2251] 469 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access 470 Protocol (v3)", Internet RFC, December, 1997. 471 Available as RFC 2251. 472 473 [RFC2891] 474 Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server 475 Side Sorting of Search Results", Internet RFC, August, 2000. 476 Available as RFC 2891. 477 478 [VLV] 479 Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions 480 for Scrolling View Browsing of Search Results", Internet Draft, 481 April, 2000. 482 Available as draft-ietf-ldapext-ldapv3-vlv-xx.txt. 483 484 [X.511] 485 ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 486 1993. 487 488 [RFC2119] 489 Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement 490 Levels", Internet Draft, March, 1997. 491 Available as RFC 2119. 492 49312. Author's Address 494 495 Jim Sermersheim 496 Novell, Inc. 497 1800 South Novell Place 498 Provo, Utah 84606, USA 499 jimse@novell.com 500 +1 801 861-3088 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522Sermersheim Internet-Draft - Expires Mar 2003 Page 9 523