1 2 3 4 5 6 7Network Working Group K. Zeilenga 8Request for Comments: 4527 OpenLDAP Foundation 9Category: Standards Track June 2006 10 11 12 Lightweight Directory Access Protocol (LDAP) 13 Read Entry Controls 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 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 36Table 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 58Zeilenga Standards Track [Page 1] 59 60RFC 4527 LDAP Read Entry Controls June 2006 61 62 631. 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 912. 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 114Zeilenga Standards Track [Page 2] 115 116RFC 4527 LDAP Read Entry Controls June 2006 117 118 1193. Read Entry Controls 120 1213.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 1563.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 170Zeilenga Standards Track [Page 3] 171 172RFC 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 1994. 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 2085. 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 226Zeilenga Standards Track [Page 4] 227 228RFC 4527 LDAP Read Entry Controls June 2006 229 230 2316. IANA Considerations 232 233 Registration of the following protocol values [RFC4520] have been 234 completed by the IANA. 235 2366.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 2486.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 2737. 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 282Zeilenga Standards Track [Page 5] 283 284RFC 4527 LDAP Read Entry Controls June 2006 285 286 2878. References 288 2898.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 338Zeilenga Standards Track [Page 6] 339 340RFC 4527 LDAP Read Entry Controls June 2006 341 342 3438.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 358Author'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 394Zeilenga Standards Track [Page 7] 395 396RFC 4527 LDAP Read Entry Controls June 2006 397 398 399Full 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 415Intellectual 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 439Acknowledgement 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 450Zeilenga Standards Track [Page 8] 451 452