X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fdrafts%2Fdraft-ietf-ldapext-ldapv3-dupent-xx.txt;h=45f9ddcee51846b2f6e3ec783ba0bdc0888716d5;hb=e071488c85a4918bbf73e09f3ffe15fcf4f344e3;hp=49dd48ed8589473086dd2e654fbe6fa90c10fc98;hpb=35843c6d98e2d7345dc09e96c4baa103b83f85de;p=openldap diff --git a/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt b/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt index 49dd48ed85..45f9ddcee5 100644 --- a/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt +++ b/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt @@ -1,531 +1,522 @@ -LDAPEXT Working Group J. Sermersheim -Internet Draft Novell, Inc -Document: draft-ietf-ldapext-ldapv3-dupent-05.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 [SSS] 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 - -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 - OID for the response control is "2.16.840.1.113719.1.27.101.2". - -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 0 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 - -LDAP Control for a Duplicate Entry Representation of Search Results - - - A value of AttributeDescription is based on the following BNF: - - attributeDescription = AttributeType [ ";" ] - - 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. - - An AttributeDescription MUST only occur once in the list. If an - AttributeDescription is included in the DuplicateEntryRequest - multiple times, the server MUST return a protocolError error in the - DuplicateEntryResponseDone control. - - Client implementations SHOULD NOT specify attribute type options - that indicate transfer encoding. - - When two or more attribute types 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 attribute types, server implementations MAY choose to - support a limited number of attribute types 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). - -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 - -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, - attributeType [1] AttributeDescription OPTIONAL } - - A result field is provided here to allow feedback in the case where - the criticality of the request control is FALSE, and the server - could not process the control - yet it could complete the search - operation successfully. If the request control's criticality is - TRUE, and the server cannot process the control, the resultCode of - the LDAPResult is used to report the error. - - 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. - - protocolError Invalid data in request control. - - 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. - - noSuchAttribute unrecognized attribute description. - - unwillingToPerform Server cannot process control. - - - -Sermersheim Internet-Draft - Expires Jan 2001 Page 4 - -LDAP Control for a Duplicate Entry Representation of Search Results - - - errorMessage MAY be populated with a human-readable string in the - event of an erroneous result code. - - attributeType MAY be set to the value of the first attribute type - specified by the DuplicateEntryRequest that was in error. The - client MUST ignore the attributeType 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 - - - dn: cn=User2,dc=example,dc=net - telephoneNumber: 555-8854 - - dn: cn=User2,dc=example,dc=net - telephoneNumber: 555-4588 - - dn: cn=User2,dc=example,dc=net - telephoneNumber: 555-5884 - - dn: cn=User3,dc=example,dc=net - telephoneNumber: 555-9425 - - dn: cn=User3,dc=example,dc=net - -Sermersheim Internet-Draft - Expires Jan 2001 Page 5 - -LDAP Control for a Duplicate Entry Representation of Search Results - - - telephoneNumber: 555-7992 - - 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 type 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 attribute types 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 - - dn: cn=User2,dc=example,dc=net - givenName: User2 - mail: usertwo@example.net - - dn: cn=User2,dc=example,dc=net - givenName: User Two - mail: user2@example.net - - dn: cn=User2,dc=example,dc=net - givenName: User Two - mail: usertwo@example.net - -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: - -Sermersheim Internet-Draft - Expires Jan 2001 Page 6 - -LDAP Control for a Duplicate Entry Representation of Search Results - - - - 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 - - dn: cn=Administrators,dc=example,dc=net - member: cn=cDavis,dc=example,dc=net - - dn: cn=Administrators,dc=example,dc=net - member: cn=bChilds,dc=example,dc=net - - dn: cn=Administrators,dc=example,dc=net - member: cn=dEvans,dc=example,dc=net - - 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 [SSS]. 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. - -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 - -Sermersheim Internet-Draft - Expires Jan 2001 Page 7 - -LDAP Control for a Duplicate Entry Representation of Search Results - - - 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 types 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 Standard, December, 1997. - Available as RFC2251. - - [SSS] - Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server - Side Sorting of Search Results", Internet Draft, June, 2000. - Available as draft-ietf-ldapext-sorting-03.txt. - - [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-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 RFC2119. - -Sermersheim Internet-Draft - Expires Jan 2001 Page 8 - -LDAP Control for a Duplicate Entry Representation of Search Results - - - -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 - \ 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 +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 +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 [ ";" ] + + 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 +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 +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 + + + 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 +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 +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 +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 +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