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-06.txt          October 2000
   6 Intended Category: Standard Track
   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 [RFC2891] allows the server to order
  46    search result entries based on attribute values (sort keys).  It
  47    does not allow one to specify behavior when an attribute contains
  48    multiple values.  The default behavior, as outlined in 7.9 of
  49    [X.511], is to use the smallest value as the sort key.
  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       Internet-Draft - Expires Apr 2001            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", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
  79    used in this document carry the meanings described in [RFC2119].
  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    OIDs for the response controls are "2.16.840.1.113719.1.27.101.2"
  87    and "2.16.840.1.113719.1.27.101.3".
  88
  89 4.1 Request Control
  90
  91    This control is included in the searchRequest message as part of the
  92    controls field of the LDAPMessage, as defined in Section 4.1.12 of
  93    [RFC2251].
  94
  95    The controlType is set to "2.16.840.1.113719.1.27.101.1". The
  96    criticality MAY be set to either TRUE or FALSE.  The controlValue is
  97    an OCTET STRING, whose value is the BER encoding of the following
  98    type:
  99
 100    DuplicateEntryRequest ::= SEQUENCE {
 101         AttributeDescriptionList, -- from [RFC2251]
 102         PartialApplicationAllowed BOOLEAN DEFAULT TRUE }
 103
 104
 105 4.1.1 AttributeDescriptionList Semantics
 106
 107    The AttributeDescriptionList data type is described in 4.1.5 of
 108    [RFC2251] and describes a list of zero or more AttributeDescription
 109    types as also described in 4.1.5 of [RFC2251]. Both definitions are
 110    repeated here for convenience:
 111
 112         AttributeDescriptionList ::= SEQUENCE OF
 113                 AttributeDescription
 114
 115         AttributeDescription ::= LDAPString
 116
 117 Sermersheim       Internet-Draft - Expires Jan 2001            Page 2
 118 \f
 119 LDAP Control for a Duplicate Entry Representation of Search Results
 120
 121
 122
 123    A value of AttributeDescription is based on the following BNF:
 124
 125         attributeDescription = AttributeType [ ";" <options> ]
 126
 127    While processing a search request, a server implementation examines
 128    this list.  If a specified attribute or attribute subtype exists in
 129    an entry to be returned by search, and that attribute holds multiple
 130    values, the server treats the entry as if it were multiple,
 131    duplicate entries -- the specified attributes each holding a single,
 132    unique value from the original set of values of that attribute.
 133
 134    Client implementations SHOULD NOT specify attribute type options
 135    that indicate transfer encoding (e.g. ;binary).
 136
 137    When two or more attributes are specified by this control, the
 138    number of duplicate entries is the combination of all values in each
 139    attribute. Because of the potential complexity involved in servicing
 140    multiple attributes, server implementations MAY choose to support a
 141    limited number of attributes in the control.
 142
 143    There is a special case where either no attributes are specified, or
 144    an attribute description value of "*" is specified.  In this case,
 145    all attributes are used.  (The "*" allows the client to request all
 146    user attributes in addition to specific operational attributes).
 147
 148    If an attribute is unrecognized, that attribute is ignored when
 149    processing the control.
 150
 151 4.1.2 PartialApplicationAllowed Semantics
 152
 153    The PartialApplicationAllowed field is used to specify whether the
 154    client will allow the server to apply this control to a subset of
 155    the search result set. If TRUE, the server is free to arbitrarily
 156    apply this control to no, any, or all search results. If FALSE, the
 157    server MUST either apply the control to all search results or fail
 158    to support the control at all.
 159
 160    Client implementations use the DuplicateSearchResult control to
 161    discover which search results have been affected by this control
 162
 163 4.2 Response Controls
 164
 165    Two response controls are defined to provide feedback while the
 166    search results are being processed; DuplicateSearchResult and
 167    DuplicateEntryResponseDone.
 168
 169    The DuplicateSearchResult control is sent with all SearchResultEntry
 170    operations that contain search results which have been modified by
 171    the DuplicateEntryRequest control.
 172
 173
 174
 175
 176 Sermersheim       Internet-Draft - Expires Jan 2001            Page 3
 177 \f
 178 LDAP Control for a Duplicate Entry Representation of Search Results
 179
 180
 181    The DuplicateEntryResponseDone control is sent with the
 182    SearchResultDone operation in order to convey completion
 183    information.
 184
 185 4.2.1 The DuplicateSearchResult control
 186
 187    This control is included in the SearchResultEntry message of any
 188    search result that holds an entry that has been modified by the
 189    DuplicateEntryRequest control as part of the controls field of the
 190    LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. This control
 191    is absent on search results that are unaffected by
 192    DuplicateEntryRequest control.
 193
 194    The controlType is set to "2.16.840.1.113719.1.27.101.2". The
 195    criticality is ignored. The controlValue is not included.
 196
 197 4.2.2 The DuplicateEntryResponseDone control
 198
 199    This control is included in the searchResultDone message as part of
 200    the controls field of the LDAPMessage, as defined in Section 4.1.12
 201    of [RFC2251].
 202
 203    The controlType is set to "2.16.840.1.113719.1.27.101.3". The
 204    criticality is ignored. The controlValue is an OCTET STRING, whose
 205    value is the BER encoding of the following SEQUENCE:
 206
 207       DuplicateEntryResponseDone ::= SEQUENCE {
 208           resultCode,     -- From [RFC2251]
 209           errorMessage    [0] LDAPString OPTIONAL,
 210           attribute       [1] AttributeDescription OPTIONAL }
 211
 212    A result field is provided here to allow the server to convey to the
 213    client that an error resulted due to the control being serviced. For
 214    example, a search that would ordinarily complete successfully may
 215    fail with a sizeLimitExceeded error due to this control being
 216    processed.
 217
 218    Though any result code that is defined in [RFC2251] MAY be returned
 219    the following list assigns special meanings to certain result codes
 220    when returned in this control:
 221
 222    - success:             The control was successful.
 223    - timeLimitExceeded    Time limit reached before attribute values
 224                           could be processed.
 225    - sizeLimitExceeded    Size limit reached as a result of this
 226                           control.
 227    - adminLimitExceeded   result set too large for server to handle.
 228    - unwillingToPerform   Server cannot process control.
 229
 230    errorMessage MAY be populated with a human-readable string in the
 231    event of an erroneous result code.
 232
 233
 234
 235 Sermersheim       Internet-Draft - Expires Jan 2001            Page 4
 236 \f
 237 LDAP Control for a Duplicate Entry Representation of Search Results
 238
 239
 240    attribute MAY be set to the value of the first attribute specified
 241    by the DuplicateEntryRequest that was in error.  The client MUST
 242    ignore the attribute field if the result is success.
 243
 244 5. Protocol Examples
 245
 246 5.1 Simple example
 247
 248    This example will show this control being used to produce a list of
 249    all telephone numbers in the dc=example,dc=net container.  Let's say
 250    the following three entries exist in this container;
 251
 252    dn: cn=User1,dc=example,dc=net
 253    telephoneNumber: 555-0123
 254
 255    dn: cn=User2,dc=example,dc=net
 256    telephoneNumber: 555-8854
 257    telephoneNumber: 555-4588
 258    telephoneNumber: 555-5884
 259
 260    dn: cn=User3,dc=example,dc=net
 261    telephoneNumber: 555-9425
 262    telephoneNumber: 555-7992
 263
 264    First an LDAP search is specified with a baseDN of
 265    "dc=example,dc=net", subtree scope, filter set to
 266    "(telephoneNumber=*)".  A DuplicateEntryRequest control is attached
 267    to the search, specifying "telephoneNumber" as the attribute
 268    description, and the search request is sent to the server.
 269
 270    The set of search results returned by the server would then consist
 271    of the following entries:
 272
 273    dn: cn=User1,dc=example,dc=net
 274    telephoneNumber: 555-0123
 275    <no DuplicateSearchResult control sent with search result>
 276
 277    dn: cn=User2,dc=example,dc=net
 278    telephoneNumber: 555-8854
 279    control: 2.16.840.1.113719.1.27.101.2
 280
 281    dn: cn=User2,dc=example,dc=net
 282    telephoneNumber: 555-4588
 283    control: 2.16.840.1.113719.1.27.101.2
 284
 285    dn: cn=User2,dc=example,dc=net
 286    telephoneNumber: 555-5884
 287    control: 2.16.840.1.113719.1.27.101.2
 288
 289    dn: cn=User3,dc=example,dc=net
 290    telephoneNumber: 555-9425
 291    control: 2.16.840.1.113719.1.27.101.2
 292
 293
 294 Sermersheim       Internet-Draft - Expires Jan 2001            Page 5
 295 \f
 296 LDAP Control for a Duplicate Entry Representation of Search Results
 297
 298
 299    dn: cn=User3,dc=example,dc=net
 300    telephoneNumber: 555-7992
 301    control: 2.16.840.1.113719.1.27.101.2
 302
 303    All but the first entry are accompanied by the DuplicateSearchResult
 304    control when sent from the server.
 305
 306    Note that it is not necessary to use an attribute in this control
 307    that is specified in the search filter.  This example only does so,
 308    because the result was to obtain a list of telephone numbers.
 309
 310 5.2 Specifying multiple attributes
 311
 312    A more complicated example involving multiple attributes will result
 313    in more entries.  If we assume these entries in the directory:
 314
 315    dn: cn=User1,dc=example,dc=net
 316    givenName: User1
 317    mail: user1@example.net
 318
 319    dn: cn=User2,dc=example,dc=net
 320    givenName: User2
 321    givenName: User Two
 322    mail: user2@example.net
 323    mail: usertwo@example.net
 324
 325    And both "mail" and "givenName" are specified as attributes in this
 326    control, the resulting set of entries would be this:
 327
 328    dn: cn=User1,dc=example,dc=net
 329    givenName: User1
 330    mail: user1@example.net
 331
 332    dn: cn=User2,dc=example,dc=net
 333    givenName: User2
 334    mail: user2@example.net
 335    control: 2.16.840.1.113719.1.27.101.2
 336
 337    dn: cn=User2,dc=example,dc=net
 338    givenName: User2
 339    mail: usertwo@example.net
 340    control: 2.16.840.1.113719.1.27.101.2
 341
 342    dn: cn=User2,dc=example,dc=net
 343    givenName: User Two
 344    mail: user2@example.net
 345    control: 2.16.840.1.113719.1.27.101.2
 346
 347    dn: cn=User2,dc=example,dc=net
 348    givenName: User Two
 349    mail: usertwo@example.net
 350    control: 2.16.840.1.113719.1.27.101.2
 351
 352
 353 Sermersheim       Internet-Draft - Expires Jan 2001            Page 6
 354 \f
 355 LDAP Control for a Duplicate Entry Representation of Search Results
 356
 357
 358 5.3 Listing the members of a groupOfNames
 359
 360    This example shows how the controls can be used to turn a single
 361    groupOfNames entry into multiple duplicate entries.  Let's say this
 362    is our groupOfNames entry:
 363
 364    dn: cn=Administrators,dc=example,dc=net
 365    cn: Administrators
 366    member: cn=aBaker,dc=example,dc=net
 367    member: cn=cDavis,dc=example,dc=net
 368    member: cn=bChilds,dc=example,dc=net
 369    member: cn=dEvans,dc=example,dc=net
 370
 371    We could set our search base to "cn=Administrators,dc=example,dc=net
 372    ", filter to "(objectClass=*)", use an object scope (to restrict it
 373    to this entry) and send the duplicateEntryRequest control with
 374    "member" as its attribute value.  The resulting set would look like
 375    this:
 376
 377    dn: cn=Administrators,dc=example,dc=net
 378    member: cn=aBaker,dc=example,dc=net
 379    control: 2.16.840.1.113719.1.27.101.2
 380
 381    dn: cn=Administrators,dc=example,dc=net
 382    member: cn=cDavis,dc=example,dc=net
 383    control: 2.16.840.1.113719.1.27.101.2
 384
 385    dn: cn=Administrators,dc=example,dc=net
 386    member: cn=bChilds,dc=example,dc=net
 387    control: 2.16.840.1.113719.1.27.101.2
 388
 389    dn: cn=Administrators,dc=example,dc=net
 390    member: cn=dEvans,dc=example,dc=net
 391    control: 2.16.840.1.113719.1.27.101.2
 392
 393    This list can then be sorted by member and displayed (also by
 394    member) in a list.
 395
 396 6 Relationship to other controls
 397
 398    This control is intended (but not limited) to be used with the
 399    Server Side Sorting control [RFC2891].  By pairing this control with
 400    the Server Side Sorting control, One can produce a set of entries,
 401    sorted by attribute values, where each attribute value is
 402    represented in the sorted set.  Server implementations MUST ensure
 403    that this control is processed before sorting the result of a
 404    search, as this control alters the result set of search.
 405
 406    This control MAY also be used with the Virtual List View [VLV]
 407    control (which has a dependency on the Server Side Sort control).
 408    The nature of the dependency between the VLV control and the Sort
 409    control is such that the Sorting takes place first. Because the sort
 410    happens first, and because this control is processed before the sort
 411
 412 Sermersheim       Internet-Draft - Expires Jan 2001            Page 7
 413 \f
 414 LDAP Control for a Duplicate Entry Representation of Search Results
 415
 416
 417    control, the impact of this control on the VLV control is minimal.
 418    Some server implementations may need to carefully consider how to
 419    handle the typedown functionality of the VLV control when paired
 420    with this control. The details of this are heavily implementation
 421    dependent and are beyond the scope of this document.
 422
 423 7. Notes for Implementers
 424
 425    Both client and server implementations MUST be aware that using this
 426    control could potentially result in a very large set of search
 427    results. Servers MAY return an adminLimitExceeded result in the
 428    response control due to inordinate consumption of resources. This
 429    may be due to some a priori knowledge such as a server restriction
 430    of the number of attribute in the request control that it's willing
 431    to service, or it may be due to the server attempting to service the
 432    control and running out of resources.
 433
 434    Client implementations MUST be aware that when using this control,
 435    search entries returned will contain a subset of the values of any
 436    specified attribute.
 437
 438    If this control is used in a chained environment, servers SHOULD NOT
 439    pass this control to other servers. Instead they SHOULD gather
 440    results and apply this control themselves.
 441
 442 8. Security Considerations
 443
 444    This control allows finer control of the result set returned by an
 445    LDAP search operation and as such may be used in a denial of service
 446    attack. See Section 7 for more information on how this is detected
 447    and handled.
 448
 449 9. Acknowledgments
 450
 451    The author gratefully thanks the input and support of participants
 452    of the LDAP-EXT working group.
 453
 454 10. References
 455
 456    [RFC2251]
 457    Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
 458    Protocol (v3)", Internet RFC, December, 1997.
 459    Available as RFC 2251.
 460
 461    [RFC2891]
 462    Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
 463    Side Sorting of Search Results", Internet RFC, August, 2000.
 464    Available as RFC 2891.
 465
 466    [VLV]
 467    Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
 468    for Scrolling View Browsing of Search Results", Internet Draft,
 469    April, 2000.
 470
 471 Sermersheim       Internet-Draft - Expires Jan 2001            Page 8
 472 \f
 473 LDAP Control for a Duplicate Entry Representation of Search Results
 474
 475
 476    Available as draft-ietf-ldapext-ldapv3-vlv-04.txt.
 477
 478    [X.511]
 479    ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
 480    1993.
 481
 482    [RFC2119]
 483    Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
 484    Levels", Internet Draft, March, 1997.
 485    Available as RFC 2119.
 486
 487 11. Author's Address
 488
 489    Jim Sermersheim
 490    Novell, Inc.
 491    1800 South Novell Place
 492    Provo, Utah 84606, USA
 493    jimse@novell.com
 494    +1 801 861-3088
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530 Sermersheim       Internet-Draft - Expires Jan 2001            Page 9
 531 \f