source4/ldap_server/devdocs/rfc4527.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        K. Zeilenga
   8 Request for Comments: 4527                           OpenLDAP Foundation
   9 Category: Standards Track                                      June 2006
  10
  11
  12               Lightweight Directory Access Protocol (LDAP)
  13                           Read Entry Controls
  14
  15
  16 Status of This Memo
  17
  18    This document specifies an Internet standards track protocol for the
  19    Internet community, and requests discussion and suggestions for
  20    improvements.  Please refer to the current edition of the "Internet
  21    Official Protocol Standards" (STD 1) for the standardization state
  22    and status of this protocol.  Distribution of this memo is unlimited.
  23
  24 Copyright Notice
  25
  26    Copyright (C) The Internet Society (2006).
  27
  28 Abstract
  29
  30    This document specifies an extension to the Lightweight Directory
  31    Access Protocol (LDAP) to allow the client to read the target entry
  32    of an update operation.  The client may request to read the entry
  33    before and/or after the modifications are applied.  These reads are
  34    done as an atomic part of the update operation.
  35
  36 Table of Contents
  37
  38    1. Background and Intent of Use ....................................2
  39    2. Terminology .....................................................2
  40    3. Read Entry Controls .............................................3
  41       3.1. The Pre-Read Controls ......................................3
  42       3.2. The Post-Read Controls .....................................3
  43    4. Interaction with Other Controls .................................4
  44    5. Security Considerations .........................................4
  45    6. IANA Considerations .............................................5
  46       6.1. Object Identifier ..........................................5
  47       6.2. LDAP Protocol Mechanisms ...................................5
  48    7. Acknowledgement .................................................5
  49    8. References ......................................................6
  50       8.1. Normative References .......................................6
  51       8.2. Informative References .....................................7
  52
  53
  54
  55
  56
  57
  58 Zeilenga                    Standards Track                     [Page 1]
  59 \f
  60 RFC 4527                LDAP Read Entry Controls               June 2006
  61
  62
  63 1.  Background and Intent of Use
  64
  65    This document specifies an extension to the Lightweight Directory
  66    Access Protocol (LDAP) [RFC4510] to allow the client to read the
  67    target entry of an update operation (e.g., Add, Delete, Modify,
  68    ModifyDN).  The extension utilizes controls [RFC4511] attached to
  69    update requests to request and return copies of the target entry.
  70    One request control, called the Pre-Read request control, indicates
  71    that a copy of the entry before application of update is to be
  72    returned.  Another control, called the Post-Read request control,
  73    indicates that a copy of the entry after application of the update is
  74    to be returned.  Each request control has a corresponding response
  75    control used to return the entry.
  76
  77    To ensure proper isolation, the controls are processed as an atomic
  78    part of the update operation.
  79
  80    The functionality offered by these controls is based upon similar
  81    functionality in the X.500 Directory Access Protocol (DAP) [X.511].
  82
  83    The Pre-Read controls may be used to obtain replaced or deleted
  84    values of modified attributes or a copy of the entry being deleted.
  85
  86    The Post-Read controls may be used to obtain values of operational
  87    attributes, such as the 'entryUUID' [RFC4530] and 'modifyTimestamp'
  88    [RFC4512] attributes, updated by the server as part of the update
  89    operation.
  90
  91 2. Terminology
  92
  93    Protocol elements are described using ASN.1 [X.680] with implicit
  94    tags.  The term "BER-encoded" means the element is to be encoded
  95    using the Basic Encoding Rules [X.690] under the restrictions
  96    detailed in Section 5.1 of [RFC4511].
  97
  98    DN stands for Distinguished Name.
  99    DSA stands for Directory System Agent (i.e., a directory server).
 100    DSE stands for DSA-specific Entry.
 101
 102    In this document, the key words "MUST", "MUST NOT", "REQUIRED",
 103    "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
 104    and "OPTIONAL" are to be interpreted as described in BCP 14
 105    [RFC2119].
 106
 107
 108
 109
 110
 111
 112
 113
 114 Zeilenga                    Standards Track                     [Page 2]
 115 \f
 116 RFC 4527                LDAP Read Entry Controls               June 2006
 117
 118
 119 3.  Read Entry Controls
 120
 121 3.1.  The Pre-Read Controls
 122
 123    The Pre-Read request and response controls are identified by the
 124    1.3.6.1.1.13.1 object identifier.  Servers implementing these
 125    controls SHOULD publish 1.3.6.1.1.13.1 as a value of the
 126    'supportedControl' [RFC4512] in their root DSE.
 127
 128    The Pre-Read request control is a LDAP Control [RFC4511] whose
 129    controlType is 1.3.6.1.1.13.1 and whose controlValue is a BER-encoded
 130    AttributeSelection [RFC4511], as extended by [RFC3673].  The
 131    criticality may be TRUE or FALSE.  This control is appropriate for
 132    the modifyRequest, delRequest, and modDNRequest LDAP messages.
 133
 134    The corresponding response control is a LDAP Control whose
 135    controlType is 1.3.6.1.1.13.1 and whose the controlValue, an OCTET
 136    STRING, contains a BER-encoded SearchResultEntry.  The criticality
 137    may be TRUE or FALSE.  This control is appropriate for the
 138    modifyResponse, delResponse, and modDNResponse LDAP messages with a
 139    resultCode of success (0).
 140
 141    When the request control is attached to an appropriate update LDAP
 142    request, the control requests the return of a copy of the target
 143    entry prior to the application of the update.  The AttributeSelection
 144    indicates, as discussed in [RFC4511][RFC3673], which attributes are
 145    requested to appear in the copy.  The server is to return a
 146    SearchResultEntry containing, subject to access controls and other
 147    constraints, values of the requested attributes.
 148
 149    The normal processing of the update operation and the processing of
 150    this control MUST be performed as one atomic action isolated from
 151    other update operations.
 152
 153    If the update operation fails (in either normal or control
 154    processing), no Pre-Read response control is provided.
 155
 156 3.2.  The Post-Read Controls
 157
 158    The Post-Read request and response controls are identified by the
 159    1.3.6.1.1.13.2 object identifier.  Servers implementing these
 160    controls SHOULD publish 1.3.6.1.1.13.2 as a value of the
 161    'supportedControl' [RFC4512] in their root DSE.
 162
 163    The Post-Read request control is a LDAP Control [RFC4511] whose
 164    controlType is 1.3.6.1.1.13.2 and whose controlValue, an OCTET
 165    STRING, contains a BER-encoded AttributeSelection [RFC4511], as
 166    extended by [RFC3673].  The criticality may be TRUE or FALSE.  This
 167
 168
 169
 170 Zeilenga                    Standards Track                     [Page 3]
 171 \f
 172 RFC 4527                LDAP Read Entry Controls               June 2006
 173
 174
 175    control is appropriate for the addRequest, modifyRequest, and
 176    modDNRequest LDAP messages.
 177
 178    The corresponding response control is a LDAP Control whose
 179    controlType is 1.3.6.1.1.13.2 and whose controlValue is a BER-encoded
 180    SearchResultEntry.  The criticality may be TRUE or FALSE.  This
 181    control is appropriate for the addResponse, modifyResponse, and
 182    modDNResponse LDAP messages with a resultCode of success (0).
 183
 184    When the request control is attached to an appropriate update LDAP
 185    request, the control requests the return of a copy of the target
 186    entry after the application of the update.  The AttributeSelection
 187    indicates, as discussed in [RFC4511][RFC3673], which attributes are
 188    requested to appear in the copy.  The server is to return a
 189    SearchResultEntry containing, subject to access controls and other
 190    constraints, values of the requested attributes.
 191
 192    The normal processing of the update operation and the processing of
 193    this control MUST be performed as one atomic action isolated from
 194    other update operations.
 195
 196    If the update operation fails (in either normal or control
 197    processing), no Post-Read response control is provided.
 198
 199 4.  Interaction with Other Controls
 200
 201    The Pre-Read and Post-Read controls may be combined with each other
 202    and/or with a variety of other controls.  When combined with the
 203    assertion control [RFC4528] and/or the manageDsaIT control [RFC3296],
 204    the semantics of each control included in the combination applies.
 205    The Pre-Read and Post-Read controls may be combined with other
 206    controls as detailed in other technical specifications.
 207
 208 5.  Security Considerations
 209
 210    The controls defined in this document extend update operations to
 211    support read capabilities.  Servers MUST ensure that the client is
 212    authorized for reading of the information provided in this control
 213    and that the client is authorized to perform the requested directory
 214    update.
 215
 216    Security considerations for the update operations [RFC4511] extended
 217    by this control, as well as general LDAP security considerations
 218    [RFC4510], generally apply to implementation and use of this
 219    extension
 220
 221
 222
 223
 224
 225
 226 Zeilenga                    Standards Track                     [Page 4]
 227 \f
 228 RFC 4527                LDAP Read Entry Controls               June 2006
 229
 230
 231 6.  IANA Considerations
 232
 233    Registration of the following protocol values [RFC4520] have been
 234    completed by the IANA.
 235
 236 6.1.  Object Identifier
 237
 238    The IANA has registered an LDAP Object Identifier to identify LDAP
 239    protocol elements defined in this document.
 240
 241        Subject: Request for LDAP Object Identifier Registration
 242        Person & email address to contact for further information:
 243             Kurt Zeilenga <kurt@OpenLDAP.org>
 244        Specification: RFC 4527
 245        Author/Change Controller: IESG
 246        Comments: Identifies the LDAP Read Entry Controls
 247
 248 6.2.  LDAP Protocol Mechanisms
 249
 250    The IANA has registered the LDAP Protocol Mechanism described in this
 251    document.
 252
 253        Subject: Request for LDAP Protocol Mechanism Registration
 254        Object Identifier: 1.3.6.1.1.13.1
 255        Description: LDAP Pre-read Control
 256        Person & email address to contact for further information:
 257             Kurt Zeilenga <kurt@openldap.org>
 258        Usage: Control
 259        Specification: RFC 4527
 260        Author/Change Controller: IESG
 261        Comments: none
 262
 263        Subject: Request for LDAP Protocol Mechanism Registration
 264        Object Identifier: 1.3.6.1.1.13.2
 265        Description: LDAP Post-read Control
 266        Person & email address to contact for further information:
 267             Kurt Zeilenga <kurt@openldap.org>
 268        Usage: Control
 269        Specification: RFC 4527
 270        Author/Change Controller: IESG
 271        Comments: none
 272
 273 7.  Acknowledgement
 274
 275    The LDAP Pre-Read and Post-Read controls are modeled after similar
 276    capabilities offered in the DAP [X.511].
 277
 278
 279
 280
 281
 282 Zeilenga                    Standards Track                     [Page 5]
 283 \f
 284 RFC 4527                LDAP Read Entry Controls               June 2006
 285
 286
 287 8.  References
 288
 289 8.1.  Normative References
 290
 291    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 292                  Requirement Levels", BCP 14, RFC 2119, March 1997.
 293
 294    [RFC3296]     Zeilenga, K., "Named Subordinate References in
 295                  Lightweight Directory Access Protocol (LDAP)
 296                  Directories", RFC 3296, July 2002.
 297
 298    [RFC3673]     Zeilenga, K., "Lightweight Directory Access Protocol
 299                  version 3 (LDAPv3): All Operational Attributes", RFC
 300                  3673, December 2003.
 301
 302    [RFC4510]     Zeilenga, K., Ed, "Lightweight Directory Access
 303                  Protocol (LDAP): Technical Specification Road Map", RFC
 304                  4510, June 2006.
 305
 306    [RFC4511]     Sermersheim, J., Ed., "Lightweight Directory Access
 307                  Protocol (LDAP): The Protocol", RFC 4511, June 2006.
 308
 309    [RFC4512]     Zeilenga, K., "Lightweight Directory Access Protocol
 310                  (LDAP): Directory Information Models", RFC 4512, June
 311                  2006.
 312
 313    [RFC4528]     Zeilenga, K., "Lightweight Directory Access Protocol
 314                  (LDAP) Assertion Control", RFC 4528, June 2006.
 315
 316    [X.680]       International Telecommunication Union -
 317                  Telecommunication Standardization Sector, "Abstract
 318                  Syntax Notation One (ASN.1) - Specification of Basic
 319                  Notation", X.680(1997) (also ISO/IEC 8824-1:1998).
 320
 321    [X.690]       International Telecommunication Union -
 322                  Telecommunication Standardization Sector,
 323                  "Specification of ASN.1 encoding rules: Basic Encoding
 324                  Rules (BER), Canonical Encoding Rules (CER), and
 325                  Distinguished Encoding Rules (DER)", X.690(1997) (also
 326                  ISO/IEC 8825-1:1998).
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338 Zeilenga                    Standards Track                     [Page 6]
 339 \f
 340 RFC 4527                LDAP Read Entry Controls               June 2006
 341
 342
 343 8.2.  Informative References
 344
 345    [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
 346                  (IANA) Considerations for the Lightweight Directory
 347                  Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
 348
 349    [RFC4530]     Zeilenga, K., "Lightweight Directory Access Protocol
 350                  (LDAP) EntryUUID Operational Attribute", RFC 4530, June
 351                  2006.
 352
 353    [X.511]       International Telecommunication Union -
 354                  Telecommunication Standardization Sector, "The
 355                  Directory: Abstract Service Definition", X.511(1993)
 356                  (also ISO/IEC 9594-3:1993).
 357
 358 Author's Address
 359
 360    Kurt D. Zeilenga
 361    OpenLDAP Foundation
 362
 363    EMail: Kurt@OpenLDAP.org
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394 Zeilenga                    Standards Track                     [Page 7]
 395 \f
 396 RFC 4527                LDAP Read Entry Controls               June 2006
 397
 398
 399 Full Copyright Statement
 400
 401    Copyright (C) The Internet Society (2006).
 402
 403    This document is subject to the rights, licenses and restrictions
 404    contained in BCP 78, and except as set forth therein, the authors
 405    retain all their rights.
 406
 407    This document and the information contained herein are provided on an
 408    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 409    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 410    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 411    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 412    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 413    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 414
 415 Intellectual Property
 416
 417    The IETF takes no position regarding the validity or scope of any
 418    Intellectual Property Rights or other rights that might be claimed to
 419    pertain to the implementation or use of the technology described in
 420    this document or the extent to which any license under such rights
 421    might or might not be available; nor does it represent that it has
 422    made any independent effort to identify any such rights.  Information
 423    on the procedures with respect to rights in RFC documents can be
 424    found in BCP 78 and BCP 79.
 425
 426    Copies of IPR disclosures made to the IETF Secretariat and any
 427    assurances of licenses to be made available, or the result of an
 428    attempt made to obtain a general license or permission for the use of
 429    such proprietary rights by implementers or users of this
 430    specification can be obtained from the IETF on-line IPR repository at
 431    http://www.ietf.org/ipr.
 432
 433    The IETF invites any interested party to bring to its attention any
 434    copyrights, patents or patent applications, or other proprietary
 435    rights that may cover technology that may be required to implement
 436    this standard.  Please address the information to the IETF at
 437    ietf-ipr@ietf.org.
 438
 439 Acknowledgement
 440
 441    Funding for the RFC Editor function is provided by the IETF
 442    Administrative Support Activity (IASA).
 443
 444
 445
 446
 447
 448
 449
 450 Zeilenga                    Standards Track                     [Page 8]
 451 \f