source: branches/samba-3.5.x/source4/ldap_server/devdocs/rfc4527.txt

Last change on this file was 414, checked in by Herwig Bauernfeind, 15 years ago

Samba 3.5.0: Initial import

File size: 15.6 KB
Line 
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
60
61RFC 4527 LDAP Read Entry Controls June 2006
62
63
641. 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
922. 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
115Zeilenga Standards Track [Page 2]
116
117
118RFC 4527 LDAP Read Entry Controls June 2006
119
120
1213. Read Entry Controls
122
1233.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
1583.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
172Zeilenga Standards Track [Page 3]
173
174
175RFC 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
2024. 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
2115. 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
229Zeilenga Standards Track [Page 4]
230
231
232RFC 4527 LDAP Read Entry Controls June 2006
233
234
2356. IANA Considerations
236
237 Registration of the following protocol values [RFC4520] have been
238 completed by the IANA.
239
2406.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@OpenLDAP.org>
248 Specification: RFC 4527
249 Author/Change Controller: IESG
250 Comments: Identifies the LDAP Read Entry Controls
251
2526.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@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@openldap.org>
272 Usage: Control
273 Specification: RFC 4527
274 Author/Change Controller: IESG
275 Comments: none
276
2777. 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
286Zeilenga Standards Track [Page 5]
287
288
289RFC 4527 LDAP Read Entry Controls June 2006
290
291
2928. References
293
2948.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
343Zeilenga Standards Track [Page 6]
344
345
346RFC 4527 LDAP Read Entry Controls June 2006
347
348
3498.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
364Author's Address
365
366 Kurt D. Zeilenga
367 OpenLDAP Foundation
368
369 EMail: Kurt@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
400Zeilenga Standards Track [Page 7]
401
402
403RFC 4527 LDAP Read Entry Controls June 2006
404
405
406Full 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
422Intellectual 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@ietf.org.
445
446Acknowledgement
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
457Zeilenga Standards Track [Page 8]
458
459
Note: See TracBrowser for help on using the repository browser.