latest dupent I-D

doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt

@@ -2,7 +2,7 @@
 
 LDAPEXT Working Group                                    J. Sermersheim 
 Internet Draft                                              Novell, Inc 
-Document: draft-ietf-ldapext-ldapv3-dupent-06.txt          October 2000
+Document: draft-ietf-ldapext-ldapv3-dupent-08.txt             Sept 2002 
 Intended Category: Standard Track                                       
  
  
@@ -34,35 +34,40 @@ Intended Category: Standard Track
    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
+   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. Overview
+3. Introduction 
     
-   The Server-Side Sorting control [RFC2891] allows the server to order
+   This document describes controls, which allow duplicate entries to 
-   search result entries based on attribute values (sort keys).  It
+   be returned in the result set of search operation. Each duplicated 
-   does not allow one to specify behavior when an attribute contains
+   entry represents a distinct value (or combination of values) of the 
-   multiple values.  The default behavior, as outlined in 7.9 of
+   set of specified multi-valued attributes. 
-   [X.511], is to use the smallest value as the sort key.
     
-   An application may need to produce an ordered list of entries,
+   For example, an application may need to produce an ordered list of 
-   sorted by a multi-valued attribute, where each attribute value is
+   entries, sorted by a multi-valued attribute, where each attribute 
-   represented in the list.  In order to do this, a separate control is
+   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. 
     
     
-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 
@@ -75,10 +80,15 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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]. 
     
-4. The Controls
+   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 
@@ -86,7 +96,7 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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
+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 
@@ -94,15 +104,19 @@ LDAP Control for a Duplicate Entry Representation of Search Results
     
    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
+   defined as the following DuplicateEntryRequest: 
-   type:
     
    DuplicateEntryRequest ::= SEQUENCE { 
         AttributeDescriptionList, -- from [RFC2251] 
         PartialApplicationAllowed BOOLEAN DEFAULT TRUE } 
          
     
-4.1.1 AttributeDescriptionList Semantics
+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 
@@ -114,25 +128,29 @@ LDAP Control for a Duplicate Entry Representation of Search Results
     
         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 [ ";" <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
+   an entry to be returned by the search operation, and that attribute 
-   values, the server treats the entry as if it were multiple,
+   holds multiple values, the server treats the entry as if it were 
-   duplicate entries -- the specified attributes each holding a single,
+   multiple, duplicate entries -- the specified attributes each holding 
-   unique value from the original set of values of that attribute.
+   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. 
     
-   Client implementations SHOULD NOT specify attribute type options
+   Specifying an attribute supertype has the effect of treating all 
-   that indicate transfer encoding (e.g. ;binary).
+   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 
@@ -148,19 +166,24 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    If an attribute is unrecognized, that attribute is ignored when 
    processing the control. 
     
-4.1.2 PartialApplicationAllowed Semantics
+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
+   discover which search results have been affected by this control. 
     
-4.2 Response Controls
+5.2 Response Controls 
     
    Two response controls are defined to provide feedback while the 
    search results are being processed; DuplicateSearchResult and 
@@ -170,19 +193,11 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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
+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 
@@ -192,58 +207,45 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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.
+   controlValue is not included. 
     
-4.2.2 The DuplicateEntryResponseDone control
+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 
-   criticality is ignored. The controlValue is an OCTET STRING, whose
+   controlValue is defined as the following DuplicateEntryResponseDone: 
-   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
+   A resultCode field is provided here to allow the server to convey to 
-   client that an error resulted due to the control being serviced. For
+   the client that an error resulted due to the control being serviced. 
-   example, a search that would ordinarily complete successfully may
+   For example, a search that would ordinarily complete successfully 
-   fail with a sizeLimitExceeded error due to this control being
+   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 Mar 2003            Page 4 
-Sermersheim       Internet-Draft - Expires Jan 2001            Page 4
-
 LDAP Control for a Duplicate Entry Representation of Search Results 
  
  
-   attribute MAY be set to the value of the first attribute specified
+   processed. If the operation is successfull, the value will be 
-   by the DuplicateEntryRequest that was in error.  The client MUST
+   success (0). 
-   ignore the attribute field if the result is success.
  
-5. Protocol Examples
+   The errorMessage field MAY be populated with a human-readable string 
+   in the event of an erroneous result code. 
     
-5.1 Simple example
+   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 
@@ -284,18 +286,17 @@ LDAP Control for a Duplicate Entry Representation of Search Results
     
    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 
     
-
-Sermersheim       Internet-Draft - Expires Jan 2001            Page 5
-
-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 
@@ -307,55 +308,62 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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
+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 
-   givenName: User1
+   cn: User1 
+   givenName: User One 
    mail: user1@example.net 
     
    dn: cn=User2,dc=example,dc=net 
-   givenName: User2
+   cn: User2 
    givenName: User Two 
    mail: user2@example.net  
    mail: usertwo@example.net 
     
-   And both "mail" and "givenName" are specified as attributes in this
+   In this example, we specify mail and name in the attribute list. By 
-   control, the resulting set of entries would be this:
+   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 
-   givenName: User1
+   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 
-   givenName: User2
+   cn: 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
+Sermersheim       Internet-Draft - Expires Mar 2003            Page 6 
-   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
-
 LDAP Control for a Duplicate Entry Representation of Search Results 
  
  
-5.3 Listing the members of a groupOfNames
+   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 
@@ -393,7 +401,12 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    This list can then be sorted by member and displayed (also by 
    member) in a list. 
     
-6 Relationship to other controls
+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 
@@ -408,26 +421,20 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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
-
-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
+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 attribute in the request control that it's willing
+   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. 
     
@@ -439,19 +446,24 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    pass this control to other servers. Instead they SHOULD gather 
    results and apply this control themselves. 
     
-8. Security Considerations
+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 7 for more information on how this is detected
+   attack. See Section 8 for more information on how this is detected 
    and handled. 
     
-9. Acknowledgments
+10. Acknowledgments 
     
    The author gratefully thanks the input and support of participants 
    of the LDAP-EXT working group. 
     
-10. References
+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 
@@ -467,13 +479,7 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    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. 
-Sermersheim       Internet-Draft - Expires Jan 2001            Page 8
-
-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", 
@@ -484,7 +490,7 @@ LDAP Control for a Duplicate Entry Representation of Search Results
    Levels", Internet Draft, March, 1997.  
    Available as RFC 2119. 
     
-11. Author's Address
+12. Author's Address 
     
    Jim Sermersheim 
    Novell, Inc. 
@@ -513,19 +519,4 @@ LDAP Control for a Duplicate Entry Representation of Search Results
 
 
   
-
+Sermersheim       Internet-Draft - Expires Mar 2003            Page 9 
-
-
-
-
-
-
-
-
-
-
-
-
-
-Sermersheim       Internet-Draft - Expires Jan 2001            Page 9
-