git.sur5r.net Git - openldap/blob - doc/drafts/draft-zeilenga-ldap-readentry-xx.txt

   1
   2
   3
   4
   5
   6
   7 INTERNET-DRAFT                                      Kurt D. Zeilenga
   8 Intended Category: Standard Track                OpenLDAP Foundation
   9 Expires in six months                                26 October 2003
  10
  11
  12                          LDAP Read Entry Controls
  13                   <draft-zeilenga-ldap-readentry-01.txt>
  14
  15
  16 1.      Status of this Memo
  17
  18   This document is an Internet-Draft and is in full conformance with all
  19   provisions of Section 10 of RFC2026.
  20
  21   This document is intended to be, after appropriate review and
  22   revision, submitted to the RFC Editor as a Standard Track document.
  23   Distribution of this memo is unlimited.  Technical discussion of this
  24   document will take place on the IETF LDAP Extensions mailing list
  25   <ldapext@ietf.org>.  Please send editorial comments directly to the
  26   author <Kurt@OpenLDAP.org>.
  27
  28   Internet-Drafts are working documents of the Internet Engineering Task
  29   Force (IETF), its areas, and its working groups.  Note that other
  30   groups may also distribute working documents as Internet-Drafts.
  31   Internet-Drafts are draft documents valid for a maximum of six months
  32   and may be updated, replaced, or obsoleted by other documents at any
  33   time.  It is inappropriate to use Internet-Drafts as reference
  34   material or to cite them other than as ``work in progress.''
  35
  36   The list of current Internet-Drafts can be accessed at
  37   <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
  38   Internet-Draft Shadow Directories can be accessed at
  39   <http://www.ietf.org/shadow.html>.
  40
  41   Copyright (C) The Internet Society (2003).  All Rights Reserved.
  42
  43   Please see the Full Copyright section near the end of this document
  44   for more information.
  45
  46
  47 Abstract
  48
  49   This specification describes controls which can be attached to a
  50   Lightweight Directory Access Protocol (LDAP) update request to obtain
  51   copies of the target entry before and/or after the requested update is
  52   applied.
  53
  54
  55
  56
  57
  58 Zeilenga                LDAP Read Entry Controls                [Page 1]
  59 \f
  60 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
  61
  62
  63 1. Background and Intent of Use
  64
  65   This specification describes controls [RFC2251] which can be attached
  66   to Lightweight Directory Access Protocol (LDAP) [RFC3377] update
  67   requests to request and return copies of the target entry.  One
  68   request control, called the Pre-Read request control, indicates that a
  69   copy of the entry before application of update is to be returned.
  70   Another control, called the Post-Read request control, indicates that
  71   a copy of the entry after application of the update is to be returned.
  72   Each request control has a corresponding response control used to
  73   return the entry.
  74
  75   The functionality offered by these controls is based upon similar
  76   functionality in the X.500 Directory Access Protocol (DAP) [X.511].
  77
  78   The Pre-Read controls may be used to obtain replaced or deleted values
  79   of modified attributes or a copy of the entry being deleted.
  80
  81   The Post-Read controls may be used to obtain values of operational
  82   attributes, such as the 'entryUUID' [EntryUUID] and 'modifytimestamp'
  83   [RFC2252] attributes, updated by the server as part of the update
  84   operation.
  85
  86
  87 2. Terminology
  88
  89   Protocol elements are described using ASN.1 [X.680] with implicit
  90   tags.  The term "BER-encoded" means the element is to be encoded using
  91   the Basic Encoding Rules [X.690] under the restrictions detailed in
  92   Section 5.1 of [RFC2251].
  93
  94   DN stands for Distinguished Name.
  95   DSA stands for Directory System Agent (i.e., a directory server).
  96   DSE stands for DSA-specific Entry.
  97
  98   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  99   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 100   document are to be interpreted as described in BCP 14 [RFC2119].
 101
 102
 103 3. Read Entry Controls
 104
 105 3.1. The Pre-Read Controls
 106
 107   The Pre-Read request and response controls are identified by the
 108   IANA-ASSIGNED-OID.1 object identifier.  Servers implementing these
 109   controls SHOULD publish IANA-ASSIGNED-OID.1 as a value of the
 110   'supportedControl' [RFC2252] in their root DSE.
 111
 112
 113
 114 Zeilenga                LDAP Read Entry Controls                [Page 2]
 115 \f
 116 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
 117
 118
 119   The Pre-Read request control is an LDAP Control [RFC2251] whose
 120   controlType is IANA-ASSIGNED-OID.1 and controlValue is a BER-encoded
 121   AttributeDescriptionList [RFC2251].  The criticality may be TRUE or
 122   FALSE.  This control is appropriate for the modifyRequest, delRequest,
 123   and modDNRequest LDAP messages.
 124
 125   The corresponding response control is a LDAP Control whose controlType
 126   is IANA-ASSIGNED-OID.1 and the controlValue, an OCTET STRING, contains
 127   a BER-encoded SearchResultEntry.  The criticality may be TRUE or
 128   FALSE.  This control is appropriate for the modifyResponse,
 129   delResponse, and modDNResponse LDAP messages with a resultCode of
 130   success (0).
 131
 132   When the request control is attached to an appropriate update LDAP
 133   request, the control requests the return of a copy of target entry
 134   prior to the application of the update.  The AttributeDescriptionList
 135   indicates which attributes are requested to appear in the copy.  There
 136   are two special AttributeDescriptions which may be included in the
 137   list, "*" and "+".  "*" requests all user attributes.  "+" requests
 138   all operational attributes.  If the list is empty, all user attributes
 139   are requested.  If the list contains an unrecognized attribute type,
 140   that type is simply ignored.  If all attribute types are unrecognized,
 141   no attributes are to be returned.  The server is to return a
 142   SearchResultEntry containing, subject to access controls and other
 143   constraints, values of the requested attributes.
 144
 145   The normal processing of the update operation and the processing of
 146   this control MUST be performed as one atomic action isolated from
 147   other update operations.
 148
 149   If the update operation fails, no response control is provided.
 150
 151
 152 3.2. The Post-Read Controls
 153
 154   The Post-Read request and response controls are identified by the
 155   IANA-ASSIGNED-OID.2 object identifier.  Servers implementing these
 156   controls SHOULD publish IANA-ASSIGNED-OID.2 as a value of the
 157   'supportedControl' [RFC2252] in their root DSE.
 158
 159   The Post-Read request control is an LDAP Control [RFC2251] whose
 160   controlType is IANA-ASSIGNED-OID.2 and controlValue, an OCTET STRING,
 161   contains a BER-encoded AttributeDescriptionList [RFC2251].  The
 162   criticality may be TRUE or FALSE.  This control is appropriate for the
 163   addRequest, modifyRequest, and modDNRequest LDAP messages.
 164
 165   The corresponding response control is a LDAP Control whose controlType
 166   is IANA-ASSIGNED-OID.2 and controlValue is a BER-encoded
 167
 168
 169
 170 Zeilenga                LDAP Read Entry Controls                [Page 3]
 171 \f
 172 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
 173
 174
 175   SearchResultEntry.  The criticality may be TRUE or FALSE.  This
 176   control is appropriate for the addResponse, modifyResponse, and
 177   modDNResponse LDAP messages with a resultCode of success (0).
 178
 179   When the request control is attached to an appropriate update LDAP
 180   request, the control requests the return of a copy of target entry
 181   after the application of the update.  The AttributeDescriptionList
 182   indicates which attributes are requested to appear in the copy.  There
 183   are two special AttributeDescriptions which may be included in the
 184   list, "*" and "+".  "*" requests all user attributes.  "+" requests
 185   all operational attributes.  If the list is empty, all user attributes
 186   are requested.  If the list contains an unrecognized attribute type,
 187   that type is simply ignored.  If all attribute types are unrecognized,
 188   no attributes are to be returned.  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, no response control is provided.
 197
 198
 199 4. Interaction with other controls
 200
 201   The Pre- and Post-Read controls may be combined with each other and/or
 202   with a variety of other controls.  When combined with the assertion
 203   control [ASSERT], the manageDsaIT control [RFC3296], and/or the proxy
 204   authorization control [PROXYAUTH], the semantics of each control
 205   included in the combination apply.  The Pre- and Post-Read controls
 206   may be combined with other controls as detailed in other technical
 207   specifications.
 208
 209
 210 5. Security Considerations
 211
 212   The controls defined in this document extend update operations to
 213   support read capabilities.  Servers MUST ensure that the client is
 214   authorized both for reading of the information provided in this
 215   control in addition to ensuring the client is authorized to perform
 216   the requested directory update.
 217
 218   Implementors of this (or any) LDAP extension should be familiar with
 219   general LDAP security considerations [RFC3377].
 220
 221
 222 6.  IANA Considerations
 223
 224
 225
 226 Zeilenga                LDAP Read Entry Controls                [Page 4]
 227 \f
 228 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
 229
 230
 231   Registration of the following protocol values [RFC3383] is requested.
 232
 233
 234 6.1.  Object Identifier
 235
 236   It is requested that IANA register an LDAP Object Identifier to
 237   identify LDAP protocol elements defined in this document.
 238
 239       Subject: Request for LDAP Object Identifier Registration
 240       Person & email address to contact for further information:
 241            Kurt Zeilenga <kurt@OpenLDAP.org>
 242       Specification: RFC XXXX
 243       Author/Change Controller: IESG
 244       Comments:
 245            Identifies the LDAP Read Entry Controls
 246
 247
 248 6.2.  LDAP Protocol Mechanisms
 249
 250   It is requested that IANA register the LDAP Protocol Mechanism
 251   described in this document.
 252
 253       Subject: Request for LDAP Protocol Mechanism Registration
 254       Object Identifier: IANA-ASSIGNED-OID.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 XXXX
 260       Author/Change Controller: IESG
 261       Comments: none
 262       in 2
 263
 264       Subject: Request for LDAP Protocol Mechanism Registration
 265       Object Identifier: IANA-ASSIGNED-OID.2
 266       Description: LDAP Post-read Control
 267       Person & email address to contact for further information:
 268            Kurt Zeilenga <kurt@openldap.org>
 269       Usage: Control
 270       Specification: RFC XXXX
 271       Author/Change Controller: IESG
 272       Comments: none
 273       in 2
 274
 275
 276 7. Acknowledgment
 277
 278       The LDAP Pre- and Post-Read controls are modeled after similar
 279
 280
 281
 282 Zeilenga                LDAP Read Entry Controls                [Page 5]
 283 \f
 284 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
 285
 286
 287       capabilities offered in the DAP [X.511].
 288
 289
 290 8. Normative References
 291
 292   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 293                 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
 294
 295   [RFC2251]     Wahl, M., T. Howes and S. Kille, "Lightweight Directory
 296                 Access Protocol (v3)", RFC 2251, December 1997.
 297
 298   [RFC2252]     Wahl, M., A. Coulbeck, T. Howes, and S. Kille,
 299                 "Lightweight Directory Access Protocol (v3):  Attribute
 300                 Syntax Definitions", RFC 2252, December 1997.
 301
 302   [RFC2830]     Hodges, J., R. Morgan, and M. Wahl, "Lightweight
 303                 Directory Access Protocol (v3): Extension for Transport
 304                 Layer Security", RFC 2830, May 2000.
 305
 306   [RFC3296]     Zeilenga, K., "Named Subordinate References in
 307                 Lightweight Directory Access Protocol (LDAP)
 308                 Directories", RFC 3296, July 2002.
 309
 310   [RFC3377]     Hodges, J. and R. Morgan, "Lightweight Directory Access
 311                 Protocol (v3): Technical Specification", RFC 3377,
 312                 September 2002.
 313
 314   [X.680]       International Telecommunication Union -
 315                 Telecommunication Standardization Sector, "Abstract
 316                 Syntax Notation One (ASN.1) - Specification of Basic
 317                 Notation", X.680(1997) (also ISO/IEC 8824-1:1998).
 318
 319   [X.690]       International Telecommunication Union -
 320                 Telecommunication Standardization Sector, "Specification
 321                 of ASN.1 encoding rules: Basic Encoding Rules (BER),
 322                 Canonical Encoding Rules (CER), and Distinguished
 323                 Encoding Rules (DER)", X.690(1997) (also ISO/IEC
 324                 8825-1:1998).
 325
 326   [PROXYAUTH]   Weltman, R., "LDAP Proxy Authentication Control", draft-
 327                 weltman-ldapv3-proxy-xx.txt, a work in progress.
 328
 329   [ASSERT]      Zeilenga, K., "LDAP Assertion Control",
 330                 draft-zeilenga-ldap-assert-xx.txt, a work in progress.
 331
 332
 333 9. Informative References
 334
 335
 336
 337
 338 Zeilenga                LDAP Read Entry Controls                [Page 6]
 339 \f
 340 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
 341
 342
 343   [RFC3383]     Zeilenga, K., "IANA Considerations for LDAP", BCP 64
 344                 (also RFC 3383), September 2002.
 345
 346   [X.511]       International Telecommunication Union -
 347                 Telecommunication Standardization Sector, "The
 348                 Directory: Abstract Service Definition", X.511(1993).
 349
 350   [EntryUUID]   Zeilenga, K., "The LDAP EntryUUID Operational
 351                 Attribute", draft-zeilenga-ldap-uuid-xx.txt, a work in
 352                 progress.
 353
 354
 355 10. Author's Address
 356
 357   Kurt D. Zeilenga
 358   OpenLDAP Foundation
 359   <Kurt@OpenLDAP.org>
 360
 361
 362
 363 Intellectual Property Rights
 364
 365   The IETF takes no position regarding the validity or scope of any
 366   intellectual property or other rights that might be claimed to pertain
 367   to the implementation or use of the technology described in this
 368   document or the extent to which any license under such rights might or
 369   might not be available; neither does it represent that it has made any
 370   effort to identify any such rights.  Information on the IETF's
 371   procedures with respect to rights in standards-track and
 372   standards-related documentation can be found in BCP-11.  Copies of
 373   claims of rights made available for publication and any assurances of
 374   licenses to be made available, or the result of an attempt made to
 375   obtain a general license or permission for the use of such proprietary
 376   rights by implementors or users of this specification can be obtained
 377   from the IETF Secretariat.
 378
 379   The IETF invites any interested party to bring to its attention any
 380   copyrights, patents or patent applications, or other proprietary
 381   rights which may cover technology that may be required to practice
 382   this standard.  Please address the information to the IETF Executive
 383   Director.
 384
 385
 386
 387 Full Copyright
 388
 389   Copyright (C) The Internet Society (2003). All Rights Reserved.
 390
 391
 392
 393
 394 Zeilenga                LDAP Read Entry Controls                [Page 7]
 395 \f
 396 INTERNET-DRAFT      draft-zeilenga-ldap-readentry-01     26 October 2003
 397
 398
 399   This document and translations of it may be copied and furnished to
 400   others, and derivative works that comment on or otherwise explain it
 401   or assist in its implmentation may be prepared, copied, published and
 402   distributed, in whole or in part, without restriction of any kind,
 403   provided that the above copyright notice and this paragraph are
 404   included on all such copies and derivative works.  However, this
 405   document itself may not be modified in any way, such as by removing
 406   the copyright notice or references to the Internet Society or other
 407   Internet organizations, except as needed for the  purpose of
 408   developing Internet standards in which case the procedures for
 409   copyrights defined in the Internet Standards process must be followed,
 410   or as required to translate it into languages other than English.
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450 Zeilenga                LDAP Read Entry Controls                [Page 8]
 451 \f