source4/ldap_server/devdocs/rfc4529.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        K. Zeilenga
   8 Request for Comments: 4529                           OpenLDAP Foundation
   9 Category: Informational                                        June 2006
  10
  11
  12               Requesting Attributes by Object Class in the
  13               Lightweight Directory Access Protocol (LDAP)
  14
  15 Status of This Memo
  16
  17    This memo provides information for the Internet community.  It does
  18    not specify an Internet standard of any kind.  Distribution of this
  19    memo is unlimited.
  20
  21 Copyright Notice
  22
  23    Copyright (C) The Internet Society (2006).
  24
  25 Abstract
  26
  27    The Lightweight Directory Access Protocol (LDAP) search operation
  28    provides mechanisms for clients to request all user application
  29    attributes, all operational attributes, and/or attributes selected by
  30    their description.  This document extends LDAP to support a mechanism
  31    that LDAP clients may use to request the return of all attributes of
  32    an object class.
  33
  34 Table of Contents
  35
  36    1. Background and Intended Use .....................................1
  37    2. Terminology .....................................................2
  38    3. Return of all Attributes of an Object Class .....................2
  39    4. Security Considerations .........................................3
  40    5. IANA Considerations .............................................3
  41    6. References ......................................................4
  42       6.1. Normative References .......................................4
  43       6.2. Informative References .....................................4
  44
  45 1.  Background and Intended Use
  46
  47    In the Lightweight Directory Access Protocol (LDAP) [RFC4510], the
  48    search operation [RFC4511] supports requesting the return of a set of
  49    attributes.  This set is determined by a list of attribute
  50    descriptions.  Two special descriptors are defined to request all
  51    user attributes ("*") [RFC4511] and all operational attributes ("+")
  52    [RFC3673].  However, there is no convenient mechanism for requesting
  53    pre-defined sets of attributes such as the set of attributes used to
  54    represent a particular class of object.
  55
  56
  57
  58 Zeilenga                     Informational                      [Page 1]
  59 \f
  60 RFC 4529         Requesting Attributes by Object Class         June 2006
  61
  62
  63    This document extends LDAP to allow an object class identifier to be
  64    specified in attributes lists, such as in Search requests, to request
  65    the return of all attributes belonging to an object class.  The
  66    COMMERCIAL AT ("@", U+0040) character is used to distinguish an
  67    object class identifier from an attribute descriptions.
  68
  69    For example, the attribute list of "@country" is equivalent to the
  70    attribute list of 'c', 'searchGuide', 'description', and
  71    'objectClass'.  This object class is described in [RFC4519].
  72
  73    This extension is intended primarily to be used where the user is in
  74    direct control of the parameters of the LDAP search operation, for
  75    instance when entering an LDAP URL [RFC4516] into a web browser, such
  76    as <ldap:///dc=example,dc=com?@organization?base>.
  77
  78 2.  Terminology
  79
  80    In this document, the key words "MUST", "MUST NOT", "REQUIRED",
  81    "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
  82    and "OPTIONAL" are to be interpreted as described in BCP 14
  83    [RFC2119].
  84
  85    DSA stands for Directory System Agent (or server).
  86    DSE stands for DSA-specific Entry.
  87
  88 3.  Return of All Attributes of an Object Class
  89
  90    This extension allows object class identifiers to be provided in the
  91    attributes field of the LDAP SearchRequest [RFC4511] or other request
  92    values of the AttributeSelection data type (e.g., attributes field in
  93    pre/post read controls [ReadEntry]) and/or <attributeSelector>
  94    production (e.g., attributes of an LDAP URL [RFC4516]).  For each
  95    object class identified in the attributes field, the request is to be
  96    treated as if each attribute allowed by that class (by "MUST" or
  97    "MAY", directly or by "SUP"erior) [RFC4512] were itself listed.
  98
  99    This extension extends the <attributeSelector> [RFC4511] production
 100    as indicated by the following ABNF [RFC4234]:
 101
 102         attributeSelector =/ objectclassdescription
 103         objectclassdescription = ATSIGN oid options
 104         ATSIGN = %x40 ; COMMERCIAL AT ("@" U+0040)
 105
 106    where <oid> and <options> productions are as defined in [RFC4512].
 107
 108
 109
 110
 111
 112
 113
 114 Zeilenga                     Informational                      [Page 2]
 115 \f
 116 RFC 4529         Requesting Attributes by Object Class         June 2006
 117
 118
 119    The <oid> component of an <objectclassdescription> production
 120    identifies the object class by short name (descr) or object
 121    identifier (numericoid).  If the value of the <oid> component is
 122    unrecognized or does not refer to an object class, the object class
 123    description is to be treated as an unrecognized attribute
 124    description.
 125
 126    The <options> production is included in the grammar for extensibility
 127    purposes.  An object class description with an unrecognized or
 128    inappropriate option is to be treated as unrecognized.
 129
 130    Although object class description options and attribute description
 131    options share the same syntax, they are not semantically related.
 132    This document does not define any object description option.
 133
 134    Servers supporting this feature SHOULD publish the object identifier
 135    (OID) 1.3.6.1.4.1.4203.1.5.2 as a value of the 'supportedFeatures'
 136    [RFC4512] attribute in the root DSE.  Clients supporting this feature
 137    SHOULD NOT use the feature unless they know that the server supports
 138    it.
 139
 140 4.  Security Considerations
 141
 142    This extension provides a shorthand for requesting all attributes of
 143    an object class.  Because these attributes could have been listed
 144    individually, introduction of this shorthand is not believed to raise
 145    additional security considerations.
 146
 147    Implementors of this LDAP extension should be familiar with security
 148    considerations applicable to the LDAP search operation [RFC4511], as
 149    well as with general LDAP security considerations [RFC4510].
 150
 151 5.  IANA Considerations
 152
 153    Registration of the LDAP Protocol Mechanism [RFC4520] defined in this
 154    document has been completed.
 155
 156        Subject: Request for LDAP Protocol Mechanism Registration
 157        Object Identifier: 1.3.6.1.4.1.4203.1.5.2
 158        Description: OC AD Lists
 159        Person & email address to contact for further information:
 160             Kurt Zeilenga <kurt@openldap.org>
 161        Usage: Feature
 162        Specification: RFC 4529
 163        Author/Change Controller: Kurt Zeilenga <kurt@openldap.org>
 164        Comments: none
 165
 166
 167
 168
 169
 170 Zeilenga                     Informational                      [Page 3]
 171 \f
 172 RFC 4529         Requesting Attributes by Object Class         June 2006
 173
 174
 175    This OID was assigned [ASSIGN] by OpenLDAP Foundation, under its
 176    IANA-assigned private enterprise allocation [PRIVATE], for use in
 177    this specification.
 178
 179 6.  References
 180
 181 6.1.  Normative References
 182
 183    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 184                  Requirement Levels", BCP 14, RFC 2119, March 1997.
 185
 186    [RFC4234]     Crocker, D., Ed. and P. Overell, "Augmented BNF for
 187                  Syntax Specifications: ABNF", RFC 4234, October 2005.
 188
 189    [RFC4510]     Zeilenga, K., Ed., "Lightweight Directory Access
 190                  Protocol (LDAP): Technical Specification Road Map", RFC
 191                  4510, June 2006.
 192
 193    [RFC4511]     Sermersheim, J., Ed., "Lightweight Directory Access
 194                  Protocol (LDAP): The Protocol", RFC 4511, June 2006.
 195
 196    [RFC4512]     Zeilenga, K., "Lightweight Directory Access Protocol
 197                  (LDAP): Directory Information Models", RFC 4512, June
 198                  2006.
 199
 200    [RFC4516]     Smith, M., Ed. and T. Howes, "Lightweight Directory
 201                  Access Protocol (LDAP): Uniform Resource Locator", RFC
 202                  4516, June 2006.
 203
 204    [X.680]       International Telecommunication Union -
 205                  Telecommunication Standardization Sector, "Abstract
 206                  Syntax Notation One (ASN.1) - Specification of Basic
 207                  Notation", X.680(2002) (also ISO/IEC 8824-1:2002).
 208
 209 6.2.  Informative References
 210
 211    [RFC3673]     Zeilenga, K., "Lightweight Directory Access Protocol
 212                  version 3 (LDAPv3): All Operational Attributes", RFC
 213                  3673, December 2003.
 214
 215    [RFC4519]     Sciberras, A., Ed., "Lightweight Directory Access
 216                  Protocol (LDAP): Schema for User Applications", RFC
 217                  4519, June 2006.
 218
 219    [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
 220                  (IANA) Considerations for the Lightweight Directory
 221                  Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
 222
 223
 224
 225
 226 Zeilenga                     Informational                      [Page 4]
 227 \f
 228 RFC 4529         Requesting Attributes by Object Class         June 2006
 229
 230
 231    [ReadEntry]   Zeilenga, K., "Lightweight Directory Access Protocol
 232                  (LDAP) Read Entry Controls", RFC 4527, June 2006.
 233
 234    [ASSIGN]      OpenLDAP Foundation, "OpenLDAP OID Delegations",
 235                  http://www.openldap.org/foundation/oid-delegate.txt.
 236
 237    [PRIVATE]     IANA, "Private Enterprise Numbers",
 238                  http://www.iana.org/assignments/enterprise-numbers.
 239
 240 Author's Address
 241
 242    Kurt D. Zeilenga
 243    OpenLDAP Foundation
 244
 245    EMail: Kurt@OpenLDAP.org
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282 Zeilenga                     Informational                      [Page 5]
 283 \f
 284 RFC 4529         Requesting Attributes by Object Class         June 2006
 285
 286
 287 Full Copyright Statement
 288
 289    Copyright (C) The Internet Society (2006).
 290
 291    This document is subject to the rights, licenses and restrictions
 292    contained in BCP 78, and except as set forth therein, the authors
 293    retain all their rights.
 294
 295    This document and the information contained herein are provided on an
 296    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 297    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 298    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 299    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 300    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 301    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 302
 303 Intellectual Property
 304
 305    The IETF takes no position regarding the validity or scope of any
 306    Intellectual Property Rights or other rights that might be claimed to
 307    pertain to the implementation or use of the technology described in
 308    this document or the extent to which any license under such rights
 309    might or might not be available; nor does it represent that it has
 310    made any independent effort to identify any such rights.  Information
 311    on the procedures with respect to rights in RFC documents can be
 312    found in BCP 78 and BCP 79.
 313
 314    Copies of IPR disclosures made to the IETF Secretariat and any
 315    assurances of licenses to be made available, or the result of an
 316    attempt made to obtain a general license or permission for the use of
 317    such proprietary rights by implementers or users of this
 318    specification can be obtained from the IETF on-line IPR repository at
 319    http://www.ietf.org/ipr.
 320
 321    The IETF invites any interested party to bring to its attention any
 322    copyrights, patents or patent applications, or other proprietary
 323    rights that may cover technology that may be required to implement
 324    this standard.  Please address the information to the IETF at
 325    ietf-ipr@ietf.org.
 326
 327 Acknowledgement
 328
 329    Funding for the RFC Editor function is provided by the IETF
 330    Administrative Support Activity (IASA).
 331
 332
 333
 334
 335
 336
 337
 338 Zeilenga                     Informational                      [Page 6]
 339 \f