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