git.sur5r.net Git - openldap/blob - doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt

   1
   2
   3 LDAPEXT Working Group                                    J. Sermersheim
   4 Internet Draft                                              Novell, Inc
   5 Document: draft-ietf-ldapext-ldapv3-dupent-03.txt            March 2000
   6 Category: Proposed Standard
   7
   8
   9   LDAP Control for a Duplicate Entry Representation of Search Results
  10
  11
  12 1. Status of this Memo
  13
  14    This document is an Internet-Draft and is in full conformance with
  15       all provisions of Section 10 of RFC2026 [1].
  16
  17    Internet-Drafts are working documents of the Internet Engineering
  18    Task Force (IETF), its areas, and its working groups. Note that
  19    other groups may also distribute working documents as Internet-
  20    Drafts. Internet-Drafts are draft documents valid for a maximum of
  21    six months and may be updated, replaced, or obsoleted by other
  22    documents at any time. It is inappropriate to use Internet- Drafts
  23    as reference material or to cite them other than as "work in
  24    progress."
  25
  26    The list of current Internet-Drafts can be accessed at
  27    http://www.ietf.org/ietf/1id-abstracts.txt
  28
  29    The list of Internet-Draft Shadow Directories can be accessed at
  30    http://www.ietf.org/shadow.html.
  31
  32 2. Abstract
  33
  34    This document describes a Duplicate Entry Representation control
  35    extension for the LDAP Search operation. By using the control with
  36    an LDAP search, a client requests that the server return separate
  37    entries for each value held in the specified attributes. For
  38    instance, if a specified attribute of an entry holds multiple
  39    values, the search operation will return multiple instances of that
  40    entry, each instance holding a separate single value in that
  41    attribute.
  42
  43 3. Overview
  44
  45    The Server-Side Sorting control [SSS] allows the server to order
  46    search result entries based on attribute values (sort keys).  It
  47    does not allow one to specify behavior when an attribute contains
  48    multiple values.  The default behavior, as outlined in 7.9 of
  49    [X.511], is to use the smallest value as the sort key.
  50
  51    An application may need to produce an ordered list of entries,
  52    sorted by a multi-valued attribute, where each attribute value is
  53    represented in the list.  In order to do this, a separate control is
  54    needed which causes the set of entries to be expanded sufficiently
  55    to represent each attribute value prior to sorting.
  56
  57
  58  Sermersheim      Standards Track - Expires Sep 2000            Page 1
  59 \f
  60 LDAP Control for a Duplicate Entry Representation of Search Results
  61
  62
  63    This document describes controls, which allow duplicate entries in
  64    the result set of search, where each entry represents a distinct
  65    value of a given multiple valued attribute.
  66
  67    An example of this would be a sorted list of all telephone numbers
  68    in an organization.  Because any entry may have multiple telephone
  69    numbers, and the list is to be sorted by telephone number, the list
  70    must be able to contain duplicate entries, each with its own unique
  71    telephone number.
  72
  73    Another example would be an application that needs to display an
  74    ordered list of all members of a group.  It would use this control
  75    to create a result set of duplicate groupOfNames entries, each with
  76    a single, unique value in its member attribute.
  77
  78    The key words "MUST", "SHOULD", and "MAY" used in this document
  79    carry the meanings described in [Bradner97].
  80
  81 4. The Controls
  82
  83    Support for the controls is advertised by the presence of their OID
  84    in the supportedControl attribute of a server's root DSE.  The OID
  85    for the request control is "2.16.840.1.113719.1.27.101.1" and the
  86    OID for the response control is "2.16.840.1.113719.1.27.101.2".
  87
  88 4.1 Request Control
  89
  90    This control is included in the searchRequest message as part of the
  91    controls field of the LDAPMessage, as defined in Section 4.1.12 of
  92    [LDAPv3].
  93
  94    The controlType is set to "2.16.840.1.113719.1.27.101.1". The
  95    criticality MAY be set to either TRUE or FALSE.  The controlValue is
  96    an OCTET STRING, whose value is the BER encoding of the following
  97    type:
  98
  99    DuplicateEntryRequest ::= AttributeDescriptionList
 100
 101    The "AttributeDescriptionList" data type is described in 4.1.5 of
 102    [LDAPv3] and describes a list of 0 or more AttributeDescription
 103    types as also described in 4.1.5 of [LDAPv3]. Both definitions are
 104    repeated here for convenience:
 105
 106         AttributeDescriptionList ::= SEQUENCE OF
 107                 AttributeDescription
 108
 109         AttributeDescription ::= <AttributeType> [ ";" <options> ]
 110
 111    While processing a search request, a server implementation examines
 112    this list.  If a specified attribute exists in an entry to be
 113    returned by search, one instance of that entry per attribute value
 114    is returned. In this case, the specified attribute in each entry
 115
 116
 117 Sermersheim       Standards Track - Expires Sep 2000            Page 2
 118 \f
 119 LDAP Control for a Duplicate Entry Representation of Search Results
 120
 121
 122    holds a single, unique value from the original set of values of that
 123    attribute.
 124
 125    An AttributeDescription should only occur once in the list.  If an
 126    AttributeDescription is included in the DuplicateEntryRequest
 127    multiple times, the server should return an unwillingToPerform error
 128    in the DuplicateEntryResponse.
 129
 130    When two or more attribute types are specified by this control, the
 131    number of duplicate entries is the combination of all values in each
 132    attribute. Because of the potential complexity involved in servicing
 133    multiple attribute types, server implementations MAY choose to
 134    support a limited number of attribute types in the control.
 135
 136    There is a special case where either no attributes are specified, or
 137    an attribute description value of "*" is specified.  In this case,
 138    all attributes are used.  (The "*" allows the client to request all
 139    user attributes in addition to specific operational attributes).
 140
 141 4.2 Response Control
 142
 143    This control is included in the searchResultDone message as part of
 144    the controls field of the LDAPMessage, as defined in Section 4.1.12
 145    of [LDAPv3].
 146
 147    The controlType is set to "2.16.840.1.113719.1.27.101.2". The
 148    criticality is FALSE (MAY be absent). The controlValue is an OCTET
 149    STRING, whose value is the BER encoding of the following SEQUENCE:
 150
 151       DuplicateEntryResponse ::= SEQUENCE {
 152           result   ENUMERATED {
 153              success             (0),
 154              operations error    (1),  -- server internal failure
 155              timeLimitExceeded   (3),  -- time limit reached before
 156                                         -- attribute values could be
 157                                         -- processed
 158              sizeLimitExceeded   (4),  -- size limit reached as a
 159                                         -- result of this control
 160              adminLimitExceeded  (11), -- result set too large for
 161                                         -- server to handle
 162              noSuchAttribute     (16), -- unrecognized attribute
 163                                         -- description
 164              busy                (51),
 165              unwillingToPerform  (53),
 166              other               (80) },
 167           attributeType   AttributeDescription OPTIONAL }
 168
 169    A result field is provided here to allow feedback in the case where
 170    the criticality of the request control is FALSE, and the server
 171    could not process the control - yet it could complete the search
 172    operation successfully. If the request control's criticality is
 173    TRUE, and the server cannot process the control, the resultCode of
 174    the LDAPResult is used to report the error.
 175
 176 Sermersheim       Standards Track - Expires Sep 2000            Page 3
 177 \f
 178 LDAP Control for a Duplicate Entry Representation of Search Results
 179
 180
 181
 182    attributeType MAY be set to the value of the first attribute type
 183    specified by the DuplicateEntryRequest that was in error.  The
 184    client MUST ignore the attributeType field if the result is success.
 185
 186 5. Protocol Examples
 187
 188 5.1 Simple example
 189
 190    This example will show this control being used to produce a list of
 191    all telephone numbers in the "Acting" organizational unit of "Looney
 192    Tunes".  Let's say the following three entries exist in this
 193    organization;
 194
 195    dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
 196    telephoneNumber: 555-0123
 197
 198    dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
 199    telephoneNumber: 555-8854
 200    telephoneNumber: 555-4588
 201    telephoneNumber: 555-5884
 202
 203    dn: cn=Porky Pig,ou=Acting,o=Looney Tunes
 204    telephoneNumber: 555-9425
 205    telephoneNumber: 555-7992
 206
 207    First an LDAP search is specified with a baseDN of "ou=Acting,
 208    o=Looney Tunes ", subtree scope, filter set to "telephoneNumber=*".
 209    A DuplicateEntryRequest control is attached to the search,
 210    specifying "telephoneNumber" as the attribute description, and the
 211    search request is sent to the server.
 212
 213    The set of search results returned by the server would then consist
 214    of the following entries:
 215
 216    dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
 217    telephoneNumber: 555-0123
 218
 219    dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
 220    telephoneNumber: 555-8854
 221
 222    dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
 223    telephoneNumber: 555-4588
 224
 225    dn: cn=Daffy Duck,ou=Acting,o=Looney Tunes
 226    telephoneNumber: 555-5884
 227
 228    dn: cn=Porky Pig,ou=Acting,o=Looney Tunes
 229    telephoneNumber: 555-9425
 230
 231    dn: cn=Porky Pig,ou=Acting,o=Looney Tunes
 232    telephoneNumber: 555-7992
 233
 234
 235 Sermersheim       Standards Track - Expires Sep 2000            Page 4
 236 \f
 237 LDAP Control for a Duplicate Entry Representation of Search Results
 238
 239
 240    Note that it is not necessary to use an attribute type in this
 241    control that is specified in the search filter.  This example only
 242    does so, because the result was to obtain a list of telephone
 243    numbers.
 244
 245 5.2 Specifying multiple attributes
 246
 247    A more complicated example involving multiple attributes will result
 248    in more entries.  If we assume these entries in the directory:
 249
 250    dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
 251    givenName: Bugs
 252    mail: bbunny@looneytunes.com
 253
 254    dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
 255    givenName: Elmer
 256    givenName: Doc
 257    mail: efudd@looneytunes.com
 258    mail: bunnyhunter@nra.org
 259
 260    And both "mail" and "givenName" are specified as attribute types in
 261    this control, the resulting set of entries would be this:
 262
 263    dn: cn=Bugs Bunny,ou=Acting,o=Looney Tunes
 264    givenName: Bugs
 265    mail: bbunny@looneytunes.com
 266
 267    dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
 268    givenName: Elmer
 269    mail: efudd@looneytunes.com
 270
 271    dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
 272    givenName: Elmer
 273    mail: bunnyhunter@nra.org
 274
 275    dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
 276    givenName: Doc
 277    mail: efudd@looneytunes.com
 278
 279    dn: cn=Elmer Fudd,ou=Acting,o=Looney Tunes
 280    givenName: Doc
 281    mail: bunnyhunter@nra.org
 282
 283 5.3 Listing the members of a groupOfNames
 284
 285    This example shows how the controls can be used to turn a single
 286    groupOfNames entry into multiple duplicate entries.  LetÆs say this
 287    is our groupOfNames entry:
 288
 289    dn: cn=Administrators,o=acme
 290    cn: Administrators
 291    member: cn=aBaker,o=acme
 292    member: cn=cDavis,o=acme
 293
 294 Sermersheim       Standards Track - Expires Sep 2000            Page 5
 295 \f
 296 LDAP Control for a Duplicate Entry Representation of Search Results
 297
 298
 299    member: cn=bChilds,o=acme
 300    member: cn=dEvans,o=acme
 301
 302    We could set our search base to "cn=Administrators,o=acme", filter
 303    to "objectClass=*", use an object scope (to restrict it to this
 304    entry) and send the duplicateEntryRequest control with "member" as
 305    its attribute value.  The resulting set would look like this:
 306
 307    dn: cn=Administrators,o=acme
 308    member: cn=aBaker,o=acme
 309
 310    dn: cn=Administrators,o=acme
 311    member: cn=cDavis,o=acme
 312
 313    dn: cn=Administrators,o=acme
 314    member: cn=bChilds,o=acme
 315
 316    dn: cn=Administrators,o=acme
 317    member: cn=dEvans,o=acme
 318
 319    This list can then be sorted by member and displayed (also by
 320    member) in a list.
 321
 322 6 Relationship to other controls
 323
 324    This control is intended (but not limited) to be used with the
 325    Server Side Sorting control [SSS].  By pairing this control with the
 326    Server Side Sorting control, One can produce a set of entries,
 327    sorted by attribute values, where each attribute value is
 328    represented in the sorted set.  Server implementations should ensure
 329    that this control is processed before sorting the result of a
 330    search, as this control alters the result set of search.
 331
 332    This control may also be used with the Virtual List View [VLV]
 333    control (which has a dependency on the Server Side Sort control).
 334    The nature of the dependency between the VLV control and the Sort
 335    control is such that the Sorting takes place first. Because the sort
 336    happens first, and because this control is processed before the sort
 337    control, the impact of this control on the VLV control is minimal.
 338    Some server implementations may need to carefully consider how to
 339    handle the typedown functionality of the VLV control when paired
 340    with this control. The details of this are heavily implementation
 341    dependent and are beyond the scope of this document.
 342
 343 7. Notes for Implementers
 344
 345    Both client and server implementations should be aware that using
 346    this control could potentially result in a very large set of search
 347    results. Servers MAY return an adminLimitExceeded result in the
 348    response control due to inordinate consumption of resources. This
 349    may be due to some a priori knowledge such as a server restriction
 350    of the number of attribute types in the request control that it's
 351
 352
 353 Sermersheim       Standards Track - Expires Sep 2000            Page 6
 354 \f
 355 LDAP Control for a Duplicate Entry Representation of Search Results
 356
 357
 358    willing to service, or it may be due to the server attempting to
 359    service the control and running out of resources.
 360
 361    Client implementations must be aware that search entries returned,
 362    when using this control will contain a subset of the values of any
 363    specified attribute.
 364
 365 8. Acknowledgments
 366
 367    The author gratefully thanks the input and support of participants
 368    of the LDAP-EXT working group.
 369
 370 9. References
 371
 372    [LDAPv3]
 373    Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
 374    Protocol (v3)", Internet Standard, December, 1997.
 375    Available as RFC2251.
 376
 377    [SSS]
 378    Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
 379    Side Sorting of Search Results", Internet Draft, March, 1998.
 380    Available as draft-ietf-ldapext-sorting-02.txt.
 381
 382    [VLV]
 383    Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
 384    for Scrolling View Browsing of Search Results", Internet Draft,
 385    June, 1999.
 386    Available as draft-ietf-ldapext-ldapv3-vlv-03.txt.
 387
 388
 389    [X.511]
 390    ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
 391    1993.
 392
 393    [Bradner97]
 394    Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
 395    Levels", Internet Draft, March, 1997.
 396    Available as RFC2119.
 397
 398 10. Author's Address
 399
 400    Jim Sermersheim
 401    Novell, Inc.
 402    122 East 1700 South
 403    Provo, Utah 84606, USA
 404    jimse@novell.com
 405    +1 801 861-3088
 406
 407
 408
 409
 410
 411
 412 Sermersheim       Standards Track - Expires Sep 2000            Page 7