source4/ldap_server/devdocs/rfc4528.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                        K. Zeilenga
   8 Request for Comments: 4528                           OpenLDAP Foundation
   9 Category: Standards Track                                      June 2006
  10
  11
  12               Lightweight Directory Access Protocol (LDAP)
  13                            Assertion Control
  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 defines the Lightweight Directory Access Protocol
  31    (LDAP) Assertion Control, which allows a client to specify that a
  32    directory operation should only be processed if an assertion applied
  33    to the target entry of the operation is true.  It can be used to
  34    construct "test and set", "test and clear", and other conditional
  35    operations.
  36
  37 Table of Contents
  38
  39    1. Overview ........................................................2
  40    2. Terminology .....................................................2
  41    3. The Assertion Control ...........................................2
  42    4. Security Considerations .........................................3
  43    5. IANA Considerations .............................................4
  44       5.1. Object Identifier ..........................................4
  45       5.2. LDAP Protocol Mechanism ....................................4
  46       5.3. LDAP Result Code ...........................................4
  47    6. Acknowledgements ................................................5
  48    7. References ......................................................5
  49       7.1. Normative References .......................................5
  50       7.2. Informative References .....................................5
  51
  52
  53
  54
  55
  56
  57
  58 Zeilenga                    Standards Track                     [Page 1]
  59 \f
  60 RFC 4528                 LDAP Assertion Control                June 2006
  61
  62
  63 1.  Overview
  64
  65    This document defines the Lightweight Directory Access Protocol
  66    (LDAP) [RFC4510] assertion control.  The assertion control allows the
  67    client to specify a condition that must be true for the operation to
  68    be processed normally.  Otherwise, the operation is not performed.
  69    For instance, the control can be used with the Modify operation
  70    [RFC4511] to perform atomic "test and set" and "test and clear"
  71    operations.
  72
  73    The control may be attached to any update operation to support
  74    conditional addition, deletion, modification, and renaming of the
  75    target object.  The asserted condition is evaluated as an integral
  76    part the operation.
  77
  78    The control may also be used with the search operation.  Here, the
  79    assertion is applied to the base object of the search before
  80    searching for objects that match the search scope and filter.
  81
  82    The control may also be used with the compare operation.  Here, it
  83    extends the compare operation to allow a more complex assertion.
  84
  85 2. Terminology
  86
  87    Protocol elements are described using ASN.1 [X.680] with implicit
  88    tags.  The term "BER-encoded" means the element is to be encoded
  89    using the Basic Encoding Rules [X.690] under the restrictions
  90    detailed in Section 5.1 of [RFC4511].
  91
  92    DSA stands for Directory System Agent (or server).
  93    DSE stands for DSA-specific Entry.
  94
  95    In this document, the key words "MUST", "MUST NOT", "REQUIRED",
  96    "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
  97    and "OPTIONAL" are to be interpreted as described in BCP 14
  98    [RFC2119].
  99
 100 3.  The Assertion Control
 101
 102    The assertion control is an LDAP Control [RFC4511] whose controlType
 103    is 1.3.6.1.1.12 and whose controlValue is a BER-encoded Filter
 104    [Protocol, Section 4.5.1].  The criticality may be TRUE or FALSE.
 105    There is no corresponding response control.
 106
 107    The control is appropriate for both LDAP interrogation and update
 108    operations [RFC4511], including Add, Compare, Delete, Modify,
 109    ModifyDN (rename), and Search.  It is inappropriate for Abandon,
 110    Bind, Unbind, and StartTLS operations.
 111
 112
 113
 114 Zeilenga                    Standards Track                     [Page 2]
 115 \f
 116 RFC 4528                 LDAP Assertion Control                June 2006
 117
 118
 119    When the control is attached to an LDAP request, the processing of
 120    the request is conditional on the evaluation of the Filter as applied
 121    against the target of the operation.  If the Filter evaluates to
 122    TRUE, then the request is processed normally.  If the Filter
 123    evaluates to FALSE or Undefined, then assertionFailed (122)
 124    resultCode is returned, and no further processing is performed.
 125
 126    For Add, Compare, and ModifyDN operations, the target is indicated by
 127    the entry field in the request.  For Modify operations, the target is
 128    indicated by the object field.  For Delete operations, the target is
 129    indicated by the DelRequest type.  For Compare operations and all
 130    update operations, the evaluation of the assertion MUST be performed
 131    as an integral part of the operation.  That is, the evaluation of the
 132    assertion and the normal processing of the operation SHALL be done as
 133    one atomic action.
 134
 135    For Search operations, the target is indicated by the baseObject
 136    field, and the evaluation is done after "finding" but before
 137    "searching" [RFC4511].  Hence, no entries or continuations references
 138    are returned if the assertion fails.
 139
 140    Servers implementing this technical specification SHOULD publish the
 141    object identifier 1.3.6.1.1.12 as a value of the 'supportedControl'
 142    attribute [RFC4512] in their root DSE.  A server MAY choose to
 143    advertise this extension only when the client is authorized to use
 144    it.
 145
 146    Other documents may specify how this control applies to other LDAP
 147    operations.  In doing so, they must state how the target entry is
 148    determined.
 149
 150 4.  Security Considerations
 151
 152    The filter may, like other components of the request, contain
 153    sensitive information.  When it does, this information should be
 154    appropriately protected.
 155
 156    As with any general assertion mechanism, the mechanism can be used to
 157    determine directory content.  Hence, this mechanism SHOULD be subject
 158    to appropriate access controls.
 159
 160    Some assertions may be very complex, requiring significant time and
 161    resources to evaluate.  Hence, this mechanism SHOULD be subject to
 162    appropriate administrative controls.
 163
 164
 165
 166
 167
 168
 169
 170 Zeilenga                    Standards Track                     [Page 3]
 171 \f
 172 RFC 4528                 LDAP Assertion Control                June 2006
 173
 174
 175    Security considerations for the base operations [RFC4511] extended by
 176    this control, as well as general LDAP security considerations
 177    [RFC4510], generally apply to implementation and use of this
 178    extension.
 179
 180 5.  IANA Considerations
 181
 182 5.1.  Object Identifier
 183
 184    The IANA has assigned an LDAP Object Identifier [RFC4520] to identify
 185    the LDAP Assertion Control defined in this document.
 186
 187        Subject: Request for LDAP Object Identifier Registration
 188        Person & email address to contact for further information:
 189            Kurt Zeilenga <kurt@OpenLDAP.org>
 190        Specification: RFC 4528
 191        Author/Change Controller: IESG
 192        Comments:
 193            Identifies the LDAP Assertion Control
 194
 195 5.2.  LDAP Protocol Mechanism
 196
 197    Registration of this protocol mechanism [RFC4520] is requested.
 198
 199        Subject: Request for LDAP Protocol Mechanism Registration
 200        Object Identifier: 1.3.6.1.1.12
 201        Description: Assertion Control
 202        Person & email address to contact for further information:
 203            Kurt Zeilenga <kurt@openldap.org>
 204        Usage: Control
 205        Specification: RFC 4528
 206        Author/Change Controller: IESG
 207        Comments: none
 208
 209 5.3.  LDAP Result Code
 210
 211    The IANA has assigned an LDAP Result Code [RFC4520] called
 212    'assertionFailed' (122).
 213
 214        Subject: LDAP Result Code Registration
 215        Person & email address to contact for further information:
 216            Kurt Zeilenga <kurt@OpenLDAP.org>
 217        Result Code Name: assertionFailed
 218        Specification: RFC 4528
 219        Author/Change Controller: IESG
 220        Comments:  none
 221
 222
 223
 224
 225
 226 Zeilenga                    Standards Track                     [Page 4]
 227 \f
 228 RFC 4528                 LDAP Assertion Control                June 2006
 229
 230
 231 6.  Acknowledgements
 232
 233    The assertion control concept is attributed to Morteza Ansari.
 234
 235 7.  References
 236
 237 7.1.  Normative References
 238
 239    [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 240                  Requirement Levels", BCP 14, RFC 2119, March 1997.
 241
 242    [RFC4510]     Zeilenga, K., Ed., "Lightweight Directory Access
 243                  Protocol (LDAP): Technical Specification Road Map", RFC
 244                  4510, June 2006.
 245
 246    [RFC4511]     Sermersheim, J., Ed., "Lightweight Directory Access
 247                  Protocol (LDAP): The Protocol", RFC 4511, June 2006.
 248
 249    [RFC4512]     Zeilenga, K., "Lightweight Directory Access Protocol
 250                  (LDAP): Directory Information Models", RFC 4512, June
 251                  2006.
 252
 253    [X.680]       International Telecommunication Union -
 254                  Telecommunication Standardization Sector, "Abstract
 255                  Syntax Notation One (ASN.1) - Specification of Basic
 256                  Notation", X.680(2002) (also ISO/IEC 8824-1:2002).
 257
 258    [X.690]       International Telecommunication Union -
 259                  Telecommunication Standardization Sector,
 260                  "Specification of ASN.1 encoding rules: Basic Encoding
 261                  Rules (BER), Canonical Encoding Rules (CER), and
 262                  Distinguished Encoding Rules (DER)", X.690(2002) (also
 263                  ISO/IEC 8825-1:2002).
 264
 265 7.2.  Informative References
 266
 267    [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
 268                  (IANA) Considerations for the Lightweight Directory
 269                  Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
 270
 271 Author's Address
 272
 273    Kurt D. Zeilenga
 274    OpenLDAP Foundation
 275
 276    EMail: Kurt@OpenLDAP.org
 277
 278
 279
 280
 281
 282 Zeilenga                    Standards Track                     [Page 5]
 283 \f
 284 RFC 4528                 LDAP Assertion Control                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                    Standards Track                     [Page 6]
 339 \f