-LDAPEXT Working Group J. Sermersheim
-Internet Draft Novell, Inc
-Document: draft-ietf-ldapext-ldapv3-dupent-06.txt October 2000
-Intended Category: Standard Track
-
-
- LDAP Control for a Duplicate Entry Representation of Search Results
-
-
-1. Status of this Memo
-
- This document is an Internet-Draft and is in full conformance with
- all provisions of Section 10 of RFC2026 [1].
-
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
+LDAPEXT Working Group J. Sermersheim
+Internet Draft Novell, Inc
+Document: draft-ietf-ldapext-ldapv3-dupent-08.txt Sept 2002
+Intended Category: Standard Track
+
+
+ LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+1. Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026 [1].
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
- Drafts. Internet-Drafts are draft documents valid for a maximum of
- six months and may be updated, replaced, or obsoleted by other
- documents at any time. It is inappropriate to use Internet- Drafts
- as reference material or to cite them other than as "work in
- progress."
-
- The list of current Internet-Drafts can be accessed at
- http://www.ietf.org/ietf/1id-abstracts.txt
-
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
-2. Abstract
-
- This document describes a Duplicate Entry Representation control
- extension for the LDAP Search operation. By using the control with
- an LDAP search, a client requests that the server return separate
- entries for each value held in the specified attributes. For
- instance, if a specified attribute of an entry holds multiple
- values, the search operation will return multiple instances of that
- entry, each instance holding a separate single value in that
- attribute.
-
-3. Overview
-
- The Server-Side Sorting control [RFC2891] allows the server to order
- search result entries based on attribute values (sort keys). It
- does not allow one to specify behavior when an attribute contains
- multiple values. The default behavior, as outlined in 7.9 of
- [X.511], is to use the smallest value as the sort key.
-
- An application may need to produce an ordered list of entries,
- sorted by a multi-valued attribute, where each attribute value is
- represented in the list. In order to do this, a separate control is
- needed which causes the set of entries to be expanded sufficiently
- to represent each attribute value prior to sorting.
-
-
-Sermersheim Internet-Draft - Expires Apr 2001 Page 1
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
- This document describes controls, which allow duplicate entries in
- the result set of search, where each entry represents a distinct
- value of a given multiple valued attribute.
-
- An example of this would be a sorted list of all telephone numbers
- in an organization. Because any entry may have multiple telephone
- numbers, and the list is to be sorted by telephone number, the list
- must be able to contain duplicate entries, each with its own unique
- telephone number.
-
- Another example would be an application that needs to display an
- ordered list of all members of a group. It would use this control
- to create a result set of duplicate groupOfNames entries, each with
- a single, unique value in its member attribute.
-
- The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
- used in this document carry the meanings described in [RFC2119].
-
-4. The Controls
-
- Support for the controls is advertised by the presence of their OID
- in the supportedControl attribute of a server's root DSE. The OID
- for the request control is "2.16.840.1.113719.1.27.101.1" and the
- OIDs for the response controls are "2.16.840.1.113719.1.27.101.2"
- and "2.16.840.1.113719.1.27.101.3".
-
-4.1 Request Control
-
- This control is included in the searchRequest message as part of the
- controls field of the LDAPMessage, as defined in Section 4.1.12 of
- [RFC2251].
-
- The controlType is set to "2.16.840.1.113719.1.27.101.1". The
- criticality MAY be set to either TRUE or FALSE. The controlValue is
- an OCTET STRING, whose value is the BER encoding of the following
- type:
-
- DuplicateEntryRequest ::= SEQUENCE {
- AttributeDescriptionList, -- from [RFC2251]
- PartialApplicationAllowed BOOLEAN DEFAULT TRUE }
-
-
-4.1.1 AttributeDescriptionList Semantics
-
- The AttributeDescriptionList data type is described in 4.1.5 of
- [RFC2251] and describes a list of zero or more AttributeDescription
- types as also described in 4.1.5 of [RFC2251]. Both definitions are
- repeated here for convenience:
-
- AttributeDescriptionList ::= SEQUENCE OF
- AttributeDescription
-
- AttributeDescription ::= LDAPString
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 2
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
-
- A value of AttributeDescription is based on the following BNF:
-
- attributeDescription = AttributeType [ ";" <options> ]
-
- While processing a search request, a server implementation examines
- this list. If a specified attribute or attribute subtype exists in
- an entry to be returned by search, and that attribute holds multiple
- values, the server treats the entry as if it were multiple,
- duplicate entries -- the specified attributes each holding a single,
- unique value from the original set of values of that attribute.
-
- Client implementations SHOULD NOT specify attribute type options
- that indicate transfer encoding (e.g. ;binary).
-
- When two or more attributes are specified by this control, the
- number of duplicate entries is the combination of all values in each
- attribute. Because of the potential complexity involved in servicing
- multiple attributes, server implementations MAY choose to support a
- limited number of attributes in the control.
-
- There is a special case where either no attributes are specified, or
- an attribute description value of "*" is specified. In this case,
- all attributes are used. (The "*" allows the client to request all
- user attributes in addition to specific operational attributes).
-
- If an attribute is unrecognized, that attribute is ignored when
- processing the control.
-
-4.1.2 PartialApplicationAllowed Semantics
-
- The PartialApplicationAllowed field is used to specify whether the
- client will allow the server to apply this control to a subset of
- the search result set. If TRUE, the server is free to arbitrarily
- apply this control to no, any, or all search results. If FALSE, the
- server MUST either apply the control to all search results or fail
- to support the control at all.
-
- Client implementations use the DuplicateSearchResult control to
- discover which search results have been affected by this control
-
-4.2 Response Controls
-
- Two response controls are defined to provide feedback while the
- search results are being processed; DuplicateSearchResult and
- DuplicateEntryResponseDone.
-
- The DuplicateSearchResult control is sent with all SearchResultEntry
- operations that contain search results which have been modified by
- the DuplicateEntryRequest control.
-
-
-
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 3
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
- The DuplicateEntryResponseDone control is sent with the
- SearchResultDone operation in order to convey completion
- information.
-
-4.2.1 The DuplicateSearchResult control
-
- This control is included in the SearchResultEntry message of any
- search result that holds an entry that has been modified by the
- DuplicateEntryRequest control as part of the controls field of the
- LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. This control
- is absent on search results that are unaffected by
- DuplicateEntryRequest control.
-
- The controlType is set to "2.16.840.1.113719.1.27.101.2". The
- criticality is ignored. The controlValue is not included.
-
-4.2.2 The DuplicateEntryResponseDone control
-
- This control is included in the searchResultDone message as part of
- the controls field of the LDAPMessage, as defined in Section 4.1.12
- of [RFC2251].
-
- The controlType is set to "2.16.840.1.113719.1.27.101.3". The
- criticality is ignored. The controlValue is an OCTET STRING, whose
- value is the BER encoding of the following SEQUENCE:
-
- DuplicateEntryResponseDone ::= SEQUENCE {
- resultCode, -- From [RFC2251]
- errorMessage [0] LDAPString OPTIONAL,
- attribute [1] AttributeDescription OPTIONAL }
-
- A result field is provided here to allow the server to convey to the
- client that an error resulted due to the control being serviced. For
- example, a search that would ordinarily complete successfully may
- fail with a sizeLimitExceeded error due to this control being
- processed.
-
- Though any result code that is defined in [RFC2251] MAY be returned
- the following list assigns special meanings to certain result codes
- when returned in this control:
-
- - success: The control was successful.
- - timeLimitExceeded Time limit reached before attribute values
- could be processed.
- - sizeLimitExceeded Size limit reached as a result of this
- control.
- - adminLimitExceeded result set too large for server to handle.
- - unwillingToPerform Server cannot process control.
-
- errorMessage MAY be populated with a human-readable string in the
- event of an erroneous result code.
-
-
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 4
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
- attribute MAY be set to the value of the first attribute specified
- by the DuplicateEntryRequest that was in error. The client MUST
- ignore the attribute field if the result is success.
-
-5. Protocol Examples
-
-5.1 Simple example
-
- This example will show this control being used to produce a list of
- all telephone numbers in the dc=example,dc=net container. Let's say
- the following three entries exist in this container;
-
- dn: cn=User1,dc=example,dc=net
- telephoneNumber: 555-0123
-
- dn: cn=User2,dc=example,dc=net
- telephoneNumber: 555-8854
- telephoneNumber: 555-4588
- telephoneNumber: 555-5884
-
- dn: cn=User3,dc=example,dc=net
- telephoneNumber: 555-9425
- telephoneNumber: 555-7992
-
- First an LDAP search is specified with a baseDN of
- "dc=example,dc=net", subtree scope, filter set to
- "(telephoneNumber=*)". A DuplicateEntryRequest control is attached
- to the search, specifying "telephoneNumber" as the attribute
- description, and the search request is sent to the server.
-
- The set of search results returned by the server would then consist
- of the following entries:
-
- dn: cn=User1,dc=example,dc=net
- telephoneNumber: 555-0123
- <no DuplicateSearchResult control sent with search result>
-
- dn: cn=User2,dc=example,dc=net
- telephoneNumber: 555-8854
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=User2,dc=example,dc=net
- telephoneNumber: 555-4588
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=User2,dc=example,dc=net
- telephoneNumber: 555-5884
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=User3,dc=example,dc=net
- telephoneNumber: 555-9425
- control: 2.16.840.1.113719.1.27.101.2
-
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 5
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
- dn: cn=User3,dc=example,dc=net
- telephoneNumber: 555-7992
- control: 2.16.840.1.113719.1.27.101.2
-
- All but the first entry are accompanied by the DuplicateSearchResult
- control when sent from the server.
-
- Note that it is not necessary to use an attribute in this control
- that is specified in the search filter. This example only does so,
- because the result was to obtain a list of telephone numbers.
-
-5.2 Specifying multiple attributes
-
- A more complicated example involving multiple attributes will result
- in more entries. If we assume these entries in the directory:
-
- dn: cn=User1,dc=example,dc=net
- givenName: User1
- mail: user1@example.net
-
- dn: cn=User2,dc=example,dc=net
- givenName: User2
- givenName: User Two
- mail: user2@example.net
- mail: usertwo@example.net
-
- And both "mail" and "givenName" are specified as attributes in this
- control, the resulting set of entries would be this:
-
- dn: cn=User1,dc=example,dc=net
- givenName: User1
- mail: user1@example.net
-
- dn: cn=User2,dc=example,dc=net
- givenName: User2
- mail: user2@example.net
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=User2,dc=example,dc=net
- givenName: User2
- mail: usertwo@example.net
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=User2,dc=example,dc=net
- givenName: User Two
- mail: user2@example.net
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=User2,dc=example,dc=net
- givenName: User Two
- mail: usertwo@example.net
- control: 2.16.840.1.113719.1.27.101.2
-
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 6
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
-5.3 Listing the members of a groupOfNames
-
- This example shows how the controls can be used to turn a single
- groupOfNames entry into multiple duplicate entries. Let's say this
- is our groupOfNames entry:
-
- dn: cn=Administrators,dc=example,dc=net
- cn: Administrators
- member: cn=aBaker,dc=example,dc=net
- member: cn=cDavis,dc=example,dc=net
- member: cn=bChilds,dc=example,dc=net
- member: cn=dEvans,dc=example,dc=net
-
- We could set our search base to "cn=Administrators,dc=example,dc=net
- ", filter to "(objectClass=*)", use an object scope (to restrict it
- to this entry) and send the duplicateEntryRequest control with
- "member" as its attribute value. The resulting set would look like
- this:
-
- dn: cn=Administrators,dc=example,dc=net
- member: cn=aBaker,dc=example,dc=net
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=Administrators,dc=example,dc=net
- member: cn=cDavis,dc=example,dc=net
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=Administrators,dc=example,dc=net
- member: cn=bChilds,dc=example,dc=net
- control: 2.16.840.1.113719.1.27.101.2
-
- dn: cn=Administrators,dc=example,dc=net
- member: cn=dEvans,dc=example,dc=net
- control: 2.16.840.1.113719.1.27.101.2
-
- This list can then be sorted by member and displayed (also by
- member) in a list.
-
-6 Relationship to other controls
-
- This control is intended (but not limited) to be used with the
- Server Side Sorting control [RFC2891]. By pairing this control with
- the Server Side Sorting control, One can produce a set of entries,
- sorted by attribute values, where each attribute value is
- represented in the sorted set. Server implementations MUST ensure
- that this control is processed before sorting the result of a
- search, as this control alters the result set of search.
-
- This control MAY also be used with the Virtual List View [VLV]
- control (which has a dependency on the Server Side Sort control).
- The nature of the dependency between the VLV control and the Sort
- control is such that the Sorting takes place first. Because the sort
- happens first, and because this control is processed before the sort
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 7
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
- control, the impact of this control on the VLV control is minimal.
- Some server implementations may need to carefully consider how to
- handle the typedown functionality of the VLV control when paired
- with this control. The details of this are heavily implementation
- dependent and are beyond the scope of this document.
-
-7. Notes for Implementers
-
- Both client and server implementations MUST be aware that using this
- control could potentially result in a very large set of search
- results. Servers MAY return an adminLimitExceeded result in the
- response control due to inordinate consumption of resources. This
- may be due to some a priori knowledge such as a server restriction
- of the number of attribute in the request control that it's willing
- to service, or it may be due to the server attempting to service the
- control and running out of resources.
-
- Client implementations MUST be aware that when using this control,
- search entries returned will contain a subset of the values of any
- specified attribute.
-
- If this control is used in a chained environment, servers SHOULD NOT
- pass this control to other servers. Instead they SHOULD gather
- results and apply this control themselves.
-
-8. Security Considerations
-
- This control allows finer control of the result set returned by an
- LDAP search operation and as such may be used in a denial of service
- attack. See Section 7 for more information on how this is detected
- and handled.
-
-9. Acknowledgments
-
- The author gratefully thanks the input and support of participants
- of the LDAP-EXT working group.
-
-10. References
-
- [RFC2251]
- Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
- Protocol (v3)", Internet RFC, December, 1997.
- Available as RFC 2251.
-
- [RFC2891]
- Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
- Side Sorting of Search Results", Internet RFC, August, 2000.
- Available as RFC 2891.
-
- [VLV]
- Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
- for Scrolling View Browsing of Search Results", Internet Draft,
- April, 2000.
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 8
-\f
-LDAP Control for a Duplicate Entry Representation of Search Results
-
-
- Available as draft-ietf-ldapext-ldapv3-vlv-04.txt.
-
- [X.511]
- ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
- 1993.
-
- [RFC2119]
- Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
- Levels", Internet Draft, March, 1997.
- Available as RFC 2119.
-
-11. Author's Address
-
- Jim Sermersheim
- Novell, Inc.
- 1800 South Novell Place
- Provo, Utah 84606, USA
- jimse@novell.com
- +1 801 861-3088
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Sermersheim Internet-Draft - Expires Jan 2001 Page 9
-\f
\ No newline at end of file
+ Drafts. Internet-Drafts are draft documents valid for a maximum of
+ six months and may be updated, replaced, or obsoleted by other
+ documents at any time. It is inappropriate to use Internet- Drafts
+ as reference material or to cite them other than as "work in
+ progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+2. Abstract
+
+ This document describes a Duplicate Entry Representation control
+ extension for the LDAP Search operation. By using the control with
+ an LDAP search, a client requests that the server return separate
+ entries for each value held in the specified attribute(s). For
+ instance, if a specified attribute of an entry holds multiple
+ values, the search operation will return multiple instances of that
+ entry, each instance holding a separate single value in that
+ attribute.
+
+3. Introduction
+
+ This document describes controls, which allow duplicate entries to
+ be returned in the result set of search operation. Each duplicated
+ entry represents a distinct value (or combination of values) of the
+ set of specified multi-valued attributes.
+
+ For example, an application may need to produce an ordered list of
+ entries, sorted by a multi-valued attribute, where each attribute
+ value is represented in the list. The Server-Side Sorting control
+ [RFC2891] allows the server to order search result entries based on
+ attribute values (sort keys). But it does not allow one to specify
+ behavior when an attribute contains multiple values. The default
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 1 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ behavior, as outlined in 7.9 of [X.511], is to use the smallest
+ order value as the sort key.
+
+ In order to produce an ordered list, where each value of a multi-
+ valued attribute is sorted into the list, a separate control is
+ needed which causes the set of entries to be expanded sufficiently
+ to represent each attribute value prior to sorting.
+
+
+
+ An example of this would be a sorted list of all telephone numbers
+ in an organization. Because any entry may have multiple telephone
+ numbers, and the list is to be sorted by telephone number, the list
+ must be able to contain duplicate entries, each with its own unique
+ telephone number.
+
+ Another example would be an application that needs to display an
+ ordered list of all members of a group. It would use this control
+ to create a result set of duplicate groupOfNames entries, each with
+ a single, unique value in its member attribute.
+
+4. Conventions
+
+ The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
+ used in this document carry the meanings described in [RFC2119].
+
+ All controlValue data is represented as ASN.1 in this document, and
+ is to be BER encoded as stated in Section 5.1 of [RFC2251].
+
+5. The Controls
+
+ Support for the controls is advertised by the presence of their OID
+ in the supportedControl attribute of a server's root DSE. The OID
+ for the request control is "2.16.840.1.113719.1.27.101.1" and the
+ OIDs for the response controls are "2.16.840.1.113719.1.27.101.2"
+ and "2.16.840.1.113719.1.27.101.3".
+
+5.1 Request Control
+
+ This control is included in the searchRequest message as part of the
+ controls field of the LDAPMessage, as defined in Section 4.1.12 of
+ [RFC2251].
+
+ The controlType is set to "2.16.840.1.113719.1.27.101.1". The
+ criticality MAY be set to either TRUE or FALSE. The controlValue is
+ defined as the following DuplicateEntryRequest:
+
+ DuplicateEntryRequest ::= SEQUENCE {
+ AttributeDescriptionList, -- from [RFC2251]
+ PartialApplicationAllowed BOOLEAN DEFAULT TRUE }
+
+
+5.1.1 AttributeDescriptionList Semantics
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 2 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+
+ The AttributeDescriptionList data type is described in 4.1.5 of
+ [RFC2251] and describes a list of zero or more AttributeDescription
+ types as also described in 4.1.5 of [RFC2251]. Both definitions are
+ repeated here for convenience:
+
+ AttributeDescriptionList ::= SEQUENCE OF
+ AttributeDescription
+
+ AttributeDescription ::= LDAPString
+
+ A value of AttributeDescription is based on the following BNF:
+
+ attributeDescription = AttributeType [ ";" <options> ]
+
+ While processing a search request, a server implementation examines
+ this list. If a specified attribute or attribute subtype exists in
+ an entry to be returned by the search operation, and that attribute
+ holds multiple values, the server treats the entry as if it were
+ multiple, duplicate entries -- the specified attributes each holding
+ a single, unique value from the original set of values of that
+ attribute. Note that this may result in search result entries that
+ no longer match the search filter.
+
+ Specifying an attribute supertype has the effect of treating all
+ values of that attribute's subtypes as if they were values of the
+ specified attribute supertype. See Section 6.2 for an example of
+ this.
+
+ When attribute descriptions contain subtyping options, they are
+ treated in the same manner as is described in Section 4.1.5 of
+ [RFC2251]. Semantics are undefined if an attribute description
+ contains a non-subtyping option, and SHOULD NOT be specified by
+ clients.
+
+ When two or more attributes are specified by this control, the
+ number of duplicate entries is the combination of all values in each
+ attribute. Because of the potential complexity involved in servicing
+ multiple attributes, server implementations MAY choose to support a
+ limited number of attributes in the control.
+
+ There is a special case where either no attributes are specified, or
+ an attribute description value of "*" is specified. In this case,
+ all attributes are used. (The "*" allows the client to request all
+ user attributes in addition to specific operational attributes).
+
+ If an attribute is unrecognized, that attribute is ignored when
+ processing the control.
+
+5.1.2 PartialApplicationAllowed Semantics
+
+ The PartialApplicationAllowed field is used to specify whether the
+ client will allow the server to apply this control to a subset of
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 3 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ the search result set. If TRUE, the server is free to arbitrarily
+ apply this control to no, any, or all search results. If FALSE, the
+ server MUST either apply the control to all search results or fail
+ to support the control at all.
+
+ Client implementations use the DuplicateSearchResult control to
+ discover which search results have been affected by this control.
+
+5.2 Response Controls
+
+ Two response controls are defined to provide feedback while the
+ search results are being processed; DuplicateSearchResult and
+ DuplicateEntryResponseDone.
+
+ The DuplicateSearchResult control is sent with all SearchResultEntry
+ operations that contain search results which have been modified by
+ the DuplicateEntryRequest control.
+
+ The DuplicateEntryResponseDone control is sent with the
+ SearchResultDone operation in order to convey completion
+ information.
+
+5.2.1 The DuplicateSearchResult control
+
+ This control is included in the SearchResultEntry message of any
+ search result that holds an entry that has been modified by the
+ DuplicateEntryRequest control as part of the controls field of the
+ LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. This control
+ is absent on search results that are unaffected by
+ DuplicateEntryRequest control.
+
+ The controlType is set to "2.16.840.1.113719.1.27.101.2". The
+ controlValue is not included.
+
+5.2.2 The DuplicateEntryResponseDone control
+
+ This control is included in the searchResultDone message as part of
+ the controls field of the LDAPMessage, as defined in Section 4.1.12
+ of [RFC2251].
+
+ The controlType is set to "2.16.840.1.113719.1.27.101.3". The
+ controlValue is defined as the following DuplicateEntryResponseDone:
+
+ DuplicateEntryResponseDone ::= SEQUENCE {
+ resultCode, -- From [RFC2251]
+ errorMessage [0] LDAPString OPTIONAL,
+ attribute [1] AttributeDescription OPTIONAL }
+
+ A resultCode field is provided here to allow the server to convey to
+ the client that an error resulted due to the control being serviced.
+ For example, a search that would ordinarily complete successfully
+ may fail with a sizeLimitExceeded error due to this control being
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 4 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ processed. If the operation is successfull, the value will be
+ success (0).
+
+ The errorMessage field MAY be populated with a human-readable string
+ in the event of an erroneous result code.
+
+ The attribute field MAY be set to the value of the first attribute
+ specified by the DuplicateEntryRequest that was in error. The
+ client MUST ignore the attribute field if the result is success.
+
+6. Protocol Examples
+
+6.1 Simple example
+
+ This example will show this control being used to produce a list of
+ all telephone numbers in the dc=example,dc=net container. Let's say
+ the following three entries exist in this container;
+
+ dn: cn=User1,dc=example,dc=net
+ telephoneNumber: 555-0123
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-8854
+ telephoneNumber: 555-4588
+ telephoneNumber: 555-5884
+
+ dn: cn=User3,dc=example,dc=net
+ telephoneNumber: 555-9425
+ telephoneNumber: 555-7992
+
+ First an LDAP search is specified with a baseDN of
+ "dc=example,dc=net", subtree scope, filter set to
+ "(telephoneNumber=*)". A DuplicateEntryRequest control is attached
+ to the search, specifying "telephoneNumber" as the attribute
+ description, and the search request is sent to the server.
+
+ The set of search results returned by the server would then consist
+ of the following entries:
+
+ dn: cn=User1,dc=example,dc=net
+ telephoneNumber: 555-0123
+ <no DuplicateSearchResult control sent with search result>
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-8854
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-4588
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-5884
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 5 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User3,dc=example,dc=net
+ telephoneNumber: 555-9425
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User3,dc=example,dc=net
+ telephoneNumber: 555-7992
+ control: 2.16.840.1.113719.1.27.101.2
+
+ All but the first entry are accompanied by the DuplicateSearchResult
+ control when sent from the server.
+
+ Note that it is not necessary to use an attribute in this control
+ that is specified in the search filter. This example only does so,
+ because the result was to obtain a list of telephone numbers.
+
+6.2 Specifying multiple attributes
+
+ A more complicated example involving multiple attributes will result
+ in more entries. If we assume these entries in the directory:
+
+ dn: cn=User1,dc=example,dc=net
+ cn: User1
+ givenName: User One
+ mail: user1@example.net
+
+ dn: cn=User2,dc=example,dc=net
+ cn: User2
+ givenName: User Two
+ mail: user2@example.net
+ mail: usertwo@example.net
+
+ In this example, we specify mail and name in the attribute list. By
+ specifying name, all attribute subtypes of name will also be
+ considered. Following is the resulting set of entries:
+
+ dn: cn=User1,dc=example,dc=net
+ cn: User1
+ mail: user1@example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User1,dc=example,dc=net
+ givenName: User One
+ mail: user1@example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ cn: User2
+ mail: user2@example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 6 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ cn: User2
+ mail: usertwo@example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ givenName: User Two
+ mail: user2@example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ givenName: User Two
+ mail: usertwo@example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+6.3 Listing the members of a groupOfNames
+
+ This example shows how the controls can be used to turn a single
+ groupOfNames entry into multiple duplicate entries. Let's say this
+ is our groupOfNames entry:
+
+ dn: cn=Administrators,dc=example,dc=net
+ cn: Administrators
+ member: cn=aBaker,dc=example,dc=net
+ member: cn=cDavis,dc=example,dc=net
+ member: cn=bChilds,dc=example,dc=net
+ member: cn=dEvans,dc=example,dc=net
+
+ We could set our search base to "cn=Administrators,dc=example,dc=net
+ ", filter to "(objectClass=*)", use an object scope (to restrict it
+ to this entry) and send the duplicateEntryRequest control with
+ "member" as its attribute value. The resulting set would look like
+ this:
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=aBaker,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=cDavis,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=bChilds,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=dEvans,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ This list can then be sorted by member and displayed (also by
+ member) in a list.
+
+7. Relationship to other controls
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 7 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+
+ This control is intended (but not limited) to be used with the
+ Server Side Sorting control [RFC2891]. By pairing this control with
+ the Server Side Sorting control, One can produce a set of entries,
+ sorted by attribute values, where each attribute value is
+ represented in the sorted set. Server implementations MUST ensure
+ that this control is processed before sorting the result of a
+ search, as this control alters the result set of search.
+
+ This control MAY also be used with the Virtual List View [VLV]
+ control (which has a dependency on the Server Side Sort control).
+ The nature of the dependency between the VLV control and the Sort
+ control is such that the Sorting takes place first. Because the sort
+ happens first, and because this control is processed before the sort
+ control, the impact of this control on the VLV control is minimal.
+ Some server implementations may need to carefully consider how to
+ handle the typedown functionality of the VLV control when paired
+ with this control. The details of this are heavily implementation
+ dependent and are beyond the scope of this document.
+
+8. Notes for Implementers
+
+ Both client and server implementations MUST be aware that using this
+ control could potentially result in a very large set of search
+ results. Servers MAY return an adminLimitExceeded result in the
+ response control due to inordinate consumption of resources. This
+ may be due to some a priori knowledge such as a server restriction
+ of the number of attributes in the request control that it's willing
+ to service, or it may be due to the server attempting to service the
+ control and running out of resources.
+
+ Client implementations MUST be aware that when using this control,
+ search entries returned will contain a subset of the values of any
+ specified attribute.
+
+ If this control is used in a chained environment, servers SHOULD NOT
+ pass this control to other servers. Instead they SHOULD gather
+ results and apply this control themselves.
+
+9. Security Considerations
+
+ This control allows finer control of the result set returned by an
+ LDAP search operation and as such may be used in a denial of service
+ attack. See Section 8 for more information on how this is detected
+ and handled.
+
+10. Acknowledgments
+
+ The author gratefully thanks the input and support of participants
+ of the LDAP-EXT working group.
+
+11. References
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 8 \f
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ [RFC2251]
+ Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
+ Protocol (v3)", Internet RFC, December, 1997.
+ Available as RFC 2251.
+
+ [RFC2891]
+ Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
+ Side Sorting of Search Results", Internet RFC, August, 2000.
+ Available as RFC 2891.
+
+ [VLV]
+ Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
+ for Scrolling View Browsing of Search Results", Internet Draft,
+ April, 2000.
+ Available as draft-ietf-ldapext-ldapv3-vlv-xx.txt.
+
+ [X.511]
+ ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
+ 1993.
+
+ [RFC2119]
+ Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
+ Levels", Internet Draft, March, 1997.
+ Available as RFC 2119.
+
+12. Author's Address
+
+ Jim Sermersheim
+ Novell, Inc.
+ 1800 South Novell Place
+ Provo, Utah 84606, USA
+ jimse@novell.com
+ +1 801 861-3088
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 9 \f
projects / openldap / commitdiff