3 LDAPEXT Working Group J. Sermersheim
4 Internet Draft Novell, Inc
5 Document: draft-ietf-ldapext-ldapv3-dupent-06.txt October 2000
6 Intended Category: Standard Track
9 LDAP Control for a Duplicate Entry Representation of Search Results
12 1. Status of this Memo
14 This document is an Internet-Draft and is in full conformance with
15 all provisions of Section 10 of RFC2026 [1].
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
26 The list of current Internet-Drafts can be accessed at
27 http://www.ietf.org/ietf/1id-abstracts.txt
29 The list of Internet-Draft Shadow Directories can be accessed at
30 http://www.ietf.org/shadow.html.
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 attributes. 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
45 The Server-Side Sorting control [RFC2891] allows the server to order
46 search result entries based on attribute values (sort keys). It
47 does not allow one to specify behavior when an attribute contains
48 multiple values. The default behavior, as outlined in 7.9 of
49 [X.511], is to use the smallest value as the sort key.
51 An application may need to produce an ordered list of entries,
52 sorted by a multi-valued attribute, where each attribute value is
53 represented in the list. In order to do this, a separate control is
54 needed which causes the set of entries to be expanded sufficiently
55 to represent each attribute value prior to sorting.
58 Sermersheim Internet-Draft - Expires Apr 2001 Page 1
60 LDAP Control for a Duplicate Entry Representation of Search Results
63 This document describes controls, which allow duplicate entries in
64 the result set of search, where each entry represents a distinct
65 value of a given multiple valued attribute.
67 An example of this would be a sorted list of all telephone numbers
68 in an organization. Because any entry may have multiple telephone
69 numbers, and the list is to be sorted by telephone number, the list
70 must be able to contain duplicate entries, each with its own unique
73 Another example would be an application that needs to display an
74 ordered list of all members of a group. It would use this control
75 to create a result set of duplicate groupOfNames entries, each with
76 a single, unique value in its member attribute.
78 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
79 used in this document carry the meanings described in [RFC2119].
83 Support for the controls is advertised by the presence of their OID
84 in the supportedControl attribute of a server's root DSE. The OID
85 for the request control is "2.16.840.1.113719.1.27.101.1" and the
86 OIDs for the response controls are "2.16.840.1.113719.1.27.101.2"
87 and "2.16.840.1.113719.1.27.101.3".
91 This control is included in the searchRequest message as part of the
92 controls field of the LDAPMessage, as defined in Section 4.1.12 of
95 The controlType is set to "2.16.840.1.113719.1.27.101.1". The
96 criticality MAY be set to either TRUE or FALSE. The controlValue is
97 an OCTET STRING, whose value is the BER encoding of the following
100 DuplicateEntryRequest ::= SEQUENCE {
101 AttributeDescriptionList, -- from [RFC2251]
102 PartialApplicationAllowed BOOLEAN DEFAULT TRUE }
105 4.1.1 AttributeDescriptionList Semantics
107 The AttributeDescriptionList data type is described in 4.1.5 of
108 [RFC2251] and describes a list of zero or more AttributeDescription
109 types as also described in 4.1.5 of [RFC2251]. Both definitions are
110 repeated here for convenience:
112 AttributeDescriptionList ::= SEQUENCE OF
115 AttributeDescription ::= LDAPString
117 Sermersheim Internet-Draft - Expires Jan 2001 Page 2
119 LDAP Control for a Duplicate Entry Representation of Search Results
123 A value of AttributeDescription is based on the following BNF:
125 attributeDescription = AttributeType [ ";" <options> ]
127 While processing a search request, a server implementation examines
128 this list. If a specified attribute or attribute subtype exists in
129 an entry to be returned by search, and that attribute holds multiple
130 values, the server treats the entry as if it were multiple,
131 duplicate entries -- the specified attributes each holding a single,
132 unique value from the original set of values of that attribute.
134 Client implementations SHOULD NOT specify attribute type options
135 that indicate transfer encoding (e.g. ;binary).
137 When two or more attributes are specified by this control, the
138 number of duplicate entries is the combination of all values in each
139 attribute. Because of the potential complexity involved in servicing
140 multiple attributes, server implementations MAY choose to support a
141 limited number of attributes in the control.
143 There is a special case where either no attributes are specified, or
144 an attribute description value of "*" is specified. In this case,
145 all attributes are used. (The "*" allows the client to request all
146 user attributes in addition to specific operational attributes).
148 If an attribute is unrecognized, that attribute is ignored when
149 processing the control.
151 4.1.2 PartialApplicationAllowed Semantics
153 The PartialApplicationAllowed field is used to specify whether the
154 client will allow the server to apply this control to a subset of
155 the search result set. If TRUE, the server is free to arbitrarily
156 apply this control to no, any, or all search results. If FALSE, the
157 server MUST either apply the control to all search results or fail
158 to support the control at all.
160 Client implementations use the DuplicateSearchResult control to
161 discover which search results have been affected by this control
163 4.2 Response Controls
165 Two response controls are defined to provide feedback while the
166 search results are being processed; DuplicateSearchResult and
167 DuplicateEntryResponseDone.
169 The DuplicateSearchResult control is sent with all SearchResultEntry
170 operations that contain search results which have been modified by
171 the DuplicateEntryRequest control.
176 Sermersheim Internet-Draft - Expires Jan 2001 Page 3
178 LDAP Control for a Duplicate Entry Representation of Search Results
181 The DuplicateEntryResponseDone control is sent with the
182 SearchResultDone operation in order to convey completion
185 4.2.1 The DuplicateSearchResult control
187 This control is included in the SearchResultEntry message of any
188 search result that holds an entry that has been modified by the
189 DuplicateEntryRequest control as part of the controls field of the
190 LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. This control
191 is absent on search results that are unaffected by
192 DuplicateEntryRequest control.
194 The controlType is set to "2.16.840.1.113719.1.27.101.2". The
195 criticality is ignored. The controlValue is not included.
197 4.2.2 The DuplicateEntryResponseDone control
199 This control is included in the searchResultDone message as part of
200 the controls field of the LDAPMessage, as defined in Section 4.1.12
203 The controlType is set to "2.16.840.1.113719.1.27.101.3". The
204 criticality is ignored. The controlValue is an OCTET STRING, whose
205 value is the BER encoding of the following SEQUENCE:
207 DuplicateEntryResponseDone ::= SEQUENCE {
208 resultCode, -- From [RFC2251]
209 errorMessage [0] LDAPString OPTIONAL,
210 attribute [1] AttributeDescription OPTIONAL }
212 A result field is provided here to allow the server to convey to the
213 client that an error resulted due to the control being serviced. For
214 example, a search that would ordinarily complete successfully may
215 fail with a sizeLimitExceeded error due to this control being
218 Though any result code that is defined in [RFC2251] MAY be returned
219 the following list assigns special meanings to certain result codes
220 when returned in this control:
222 - success: The control was successful.
223 - timeLimitExceeded Time limit reached before attribute values
225 - sizeLimitExceeded Size limit reached as a result of this
227 - adminLimitExceeded result set too large for server to handle.
228 - unwillingToPerform Server cannot process control.
230 errorMessage MAY be populated with a human-readable string in the
231 event of an erroneous result code.
235 Sermersheim Internet-Draft - Expires Jan 2001 Page 4
237 LDAP Control for a Duplicate Entry Representation of Search Results
240 attribute MAY be set to the value of the first attribute specified
241 by the DuplicateEntryRequest that was in error. The client MUST
242 ignore the attribute field if the result is success.
248 This example will show this control being used to produce a list of
249 all telephone numbers in the dc=example,dc=net container. Let's say
250 the following three entries exist in this container;
252 dn: cn=User1,dc=example,dc=net
253 telephoneNumber: 555-0123
255 dn: cn=User2,dc=example,dc=net
256 telephoneNumber: 555-8854
257 telephoneNumber: 555-4588
258 telephoneNumber: 555-5884
260 dn: cn=User3,dc=example,dc=net
261 telephoneNumber: 555-9425
262 telephoneNumber: 555-7992
264 First an LDAP search is specified with a baseDN of
265 "dc=example,dc=net", subtree scope, filter set to
266 "(telephoneNumber=*)". A DuplicateEntryRequest control is attached
267 to the search, specifying "telephoneNumber" as the attribute
268 description, and the search request is sent to the server.
270 The set of search results returned by the server would then consist
271 of the following entries:
273 dn: cn=User1,dc=example,dc=net
274 telephoneNumber: 555-0123
275 <no DuplicateSearchResult control sent with search result>
277 dn: cn=User2,dc=example,dc=net
278 telephoneNumber: 555-8854
279 control: 2.16.840.1.113719.1.27.101.2
281 dn: cn=User2,dc=example,dc=net
282 telephoneNumber: 555-4588
283 control: 2.16.840.1.113719.1.27.101.2
285 dn: cn=User2,dc=example,dc=net
286 telephoneNumber: 555-5884
287 control: 2.16.840.1.113719.1.27.101.2
289 dn: cn=User3,dc=example,dc=net
290 telephoneNumber: 555-9425
291 control: 2.16.840.1.113719.1.27.101.2
294 Sermersheim Internet-Draft - Expires Jan 2001 Page 5
296 LDAP Control for a Duplicate Entry Representation of Search Results
299 dn: cn=User3,dc=example,dc=net
300 telephoneNumber: 555-7992
301 control: 2.16.840.1.113719.1.27.101.2
303 All but the first entry are accompanied by the DuplicateSearchResult
304 control when sent from the server.
306 Note that it is not necessary to use an attribute in this control
307 that is specified in the search filter. This example only does so,
308 because the result was to obtain a list of telephone numbers.
310 5.2 Specifying multiple attributes
312 A more complicated example involving multiple attributes will result
313 in more entries. If we assume these entries in the directory:
315 dn: cn=User1,dc=example,dc=net
317 mail: user1@example.net
319 dn: cn=User2,dc=example,dc=net
322 mail: user2@example.net
323 mail: usertwo@example.net
325 And both "mail" and "givenName" are specified as attributes in this
326 control, the resulting set of entries would be this:
328 dn: cn=User1,dc=example,dc=net
330 mail: user1@example.net
332 dn: cn=User2,dc=example,dc=net
334 mail: user2@example.net
335 control: 2.16.840.1.113719.1.27.101.2
337 dn: cn=User2,dc=example,dc=net
339 mail: usertwo@example.net
340 control: 2.16.840.1.113719.1.27.101.2
342 dn: cn=User2,dc=example,dc=net
344 mail: user2@example.net
345 control: 2.16.840.1.113719.1.27.101.2
347 dn: cn=User2,dc=example,dc=net
349 mail: usertwo@example.net
350 control: 2.16.840.1.113719.1.27.101.2
353 Sermersheim Internet-Draft - Expires Jan 2001 Page 6
355 LDAP Control for a Duplicate Entry Representation of Search Results
358 5.3 Listing the members of a groupOfNames
360 This example shows how the controls can be used to turn a single
361 groupOfNames entry into multiple duplicate entries. Let's say this
362 is our groupOfNames entry:
364 dn: cn=Administrators,dc=example,dc=net
366 member: cn=aBaker,dc=example,dc=net
367 member: cn=cDavis,dc=example,dc=net
368 member: cn=bChilds,dc=example,dc=net
369 member: cn=dEvans,dc=example,dc=net
371 We could set our search base to "cn=Administrators,dc=example,dc=net
372 ", filter to "(objectClass=*)", use an object scope (to restrict it
373 to this entry) and send the duplicateEntryRequest control with
374 "member" as its attribute value. The resulting set would look like
377 dn: cn=Administrators,dc=example,dc=net
378 member: cn=aBaker,dc=example,dc=net
379 control: 2.16.840.1.113719.1.27.101.2
381 dn: cn=Administrators,dc=example,dc=net
382 member: cn=cDavis,dc=example,dc=net
383 control: 2.16.840.1.113719.1.27.101.2
385 dn: cn=Administrators,dc=example,dc=net
386 member: cn=bChilds,dc=example,dc=net
387 control: 2.16.840.1.113719.1.27.101.2
389 dn: cn=Administrators,dc=example,dc=net
390 member: cn=dEvans,dc=example,dc=net
391 control: 2.16.840.1.113719.1.27.101.2
393 This list can then be sorted by member and displayed (also by
396 6 Relationship to other controls
398 This control is intended (but not limited) to be used with the
399 Server Side Sorting control [RFC2891]. By pairing this control with
400 the Server Side Sorting control, One can produce a set of entries,
401 sorted by attribute values, where each attribute value is
402 represented in the sorted set. Server implementations MUST ensure
403 that this control is processed before sorting the result of a
404 search, as this control alters the result set of search.
406 This control MAY also be used with the Virtual List View [VLV]
407 control (which has a dependency on the Server Side Sort control).
408 The nature of the dependency between the VLV control and the Sort
409 control is such that the Sorting takes place first. Because the sort
410 happens first, and because this control is processed before the sort
412 Sermersheim Internet-Draft - Expires Jan 2001 Page 7
414 LDAP Control for a Duplicate Entry Representation of Search Results
417 control, the impact of this control on the VLV control is minimal.
418 Some server implementations may need to carefully consider how to
419 handle the typedown functionality of the VLV control when paired
420 with this control. The details of this are heavily implementation
421 dependent and are beyond the scope of this document.
423 7. Notes for Implementers
425 Both client and server implementations MUST be aware that using this
426 control could potentially result in a very large set of search
427 results. Servers MAY return an adminLimitExceeded result in the
428 response control due to inordinate consumption of resources. This
429 may be due to some a priori knowledge such as a server restriction
430 of the number of attribute in the request control that it's willing
431 to service, or it may be due to the server attempting to service the
432 control and running out of resources.
434 Client implementations MUST be aware that when using this control,
435 search entries returned will contain a subset of the values of any
438 If this control is used in a chained environment, servers SHOULD NOT
439 pass this control to other servers. Instead they SHOULD gather
440 results and apply this control themselves.
442 8. Security Considerations
444 This control allows finer control of the result set returned by an
445 LDAP search operation and as such may be used in a denial of service
446 attack. See Section 7 for more information on how this is detected
451 The author gratefully thanks the input and support of participants
452 of the LDAP-EXT working group.
457 Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
458 Protocol (v3)", Internet RFC, December, 1997.
459 Available as RFC 2251.
462 Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
463 Side Sorting of Search Results", Internet RFC, August, 2000.
464 Available as RFC 2891.
467 Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
468 for Scrolling View Browsing of Search Results", Internet Draft,
471 Sermersheim Internet-Draft - Expires Jan 2001 Page 8
473 LDAP Control for a Duplicate Entry Representation of Search Results
476 Available as draft-ietf-ldapext-ldapv3-vlv-04.txt.
479 ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
483 Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
484 Levels", Internet Draft, March, 1997.
485 Available as RFC 2119.
491 1800 South Novell Place
492 Provo, Utah 84606, USA
530 Sermersheim Internet-Draft - Expires Jan 2001 Page 9