← Back to branch summary

~zulcss/samba/server-dailies-3.4

« back to all changes in this revision

Viewing changes to source4/ldap_server/devdocs/rfc4527.txt

  • Committer: Chuck Short
  • Date: 2010-09-28 20:38:39 UTC
  • Revision ID: zulcss@ubuntu.com-20100928203839-pgjulytsi9ue63x1
Initial version

Show diffs side-by-side

added added

removed removed

Lines of Context:
source4/ldap_server/devdocs/rfc4527.txt
 
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
 
 
60
RFC 4527                LDAP Read Entry Controls               June 2006
 
61
 
 
62
 
 
63
1.  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
 
 
91
2. 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
 
 
114
Zeilenga                    Standards Track                     [Page 2]
 
115
 
 
116
RFC 4527                LDAP Read Entry Controls               June 2006
 
117
 
 
118
 
 
119
3.  Read Entry Controls
 
120
 
 
121
3.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
 
 
156
3.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
 
 
170
Zeilenga                    Standards Track                     [Page 3]
 
171
 
 
172
RFC 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
 
 
199
4.  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
 
 
208
5.  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
 
 
226
Zeilenga                    Standards Track                     [Page 4]
 
227
 
 
228
RFC 4527                LDAP Read Entry Controls               June 2006
 
229
 
 
230
 
 
231
6.  IANA Considerations
 
232
 
 
233
   Registration of the following protocol values [RFC4520] have been
 
234
   completed by the IANA.
 
235
 
 
236
6.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
 
 
248
6.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
 
 
273
7.  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
 
 
282
Zeilenga                    Standards Track                     [Page 5]
 
283
 
 
284
RFC 4527                LDAP Read Entry Controls               June 2006
 
285
 
 
286
 
 
287
8.  References
 
288
 
 
289
8.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
 
 
338
Zeilenga                    Standards Track                     [Page 6]
 
339
 
 
340
RFC 4527                LDAP Read Entry Controls               June 2006
 
341
 
 
342
 
 
343
8.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
 
 
358
Author'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
 
 
394
Zeilenga                    Standards Track                     [Page 7]
 
395
 
 
396
RFC 4527                LDAP Read Entry Controls               June 2006
 
397
 
 
398
 
 
399
Full 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
 
 
415
Intellectual 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
 
 
439
Acknowledgement
 
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
 
 
450
Zeilenga                    Standards Track                     [Page 8]
 
451