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