1 2 3 4 5 6 7Network Working Group K. Zeilenga 8Request for Comments: 4528 OpenLDAP Foundation 9Category: Standards Track June 2006 10 11 12 Lightweight Directory Access Protocol (LDAP) 13 Assertion Control 14 15 16Status 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 24Copyright Notice 25 26 Copyright (C) The Internet Society (2006). 27 28Abstract 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 37Table 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 58Zeilenga Standards Track [Page 1] 59 60RFC 4528 LDAP Assertion Control June 2006 61 62 631. 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 852. 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 1003. 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 114Zeilenga Standards Track [Page 2] 115 116RFC 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 1504. 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 170Zeilenga Standards Track [Page 3] 171 172RFC 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 1805. IANA Considerations 181 1825.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 1955.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 2095.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 226Zeilenga Standards Track [Page 4] 227 228RFC 4528 LDAP Assertion Control June 2006 229 230 2316. Acknowledgements 232 233 The assertion control concept is attributed to Morteza Ansari. 234 2357. References 236 2377.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 2657.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 271Author's Address 272 273 Kurt D. Zeilenga 274 OpenLDAP Foundation 275 276 EMail: Kurt@OpenLDAP.org 277 278 279 280 281 282Zeilenga Standards Track [Page 5] 283 284RFC 4528 LDAP Assertion Control June 2006 285 286 287Full 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 303Intellectual 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 327Acknowledgement 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 338Zeilenga Standards Track [Page 6] 339 340