1
2
3
4
5
6
7Network Working Group                                        K. Zeilenga
8Request for Comments: 4528                           OpenLDAP Foundation
9Category: Standards Track                                      June 2006
10
11
12              Lightweight Directory Access Protocol (LDAP)
13                           Assertion Control
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 defines the Lightweight Directory Access Protocol
31   (LDAP) Assertion Control, which allows a client to specify that a
32   directory operation should only be processed if an assertion applied
33   to the target entry of the operation is true.  It can be used to
34   construct "test and set", "test and clear", and other conditional
35   operations.
36
37Table of Contents
38
39   1. Overview ........................................................2
40   2. Terminology .....................................................2
41   3. The Assertion Control ...........................................2
42   4. Security Considerations .........................................3
43   5. IANA Considerations .............................................4
44      5.1. Object Identifier ..........................................4
45      5.2. LDAP Protocol Mechanism ....................................4
46      5.3. LDAP Result Code ...........................................4
47   6. Acknowledgements ................................................5
48   7. References ......................................................5
49      7.1. Normative References .......................................5
50      7.2. Informative References .....................................5
51
52
53
54
55
56
57
58Zeilenga                    Standards Track                     [Page 1]
59
60RFC 4528                 LDAP Assertion Control                June 2006
61
62
631.  Overview
64
65   This document defines the Lightweight Directory Access Protocol
66   (LDAP) [RFC4510] assertion control.  The assertion control allows the
67   client to specify a condition that must be true for the operation to
68   be processed normally.  Otherwise, the operation is not performed.
69   For instance, the control can be used with the Modify operation
70   [RFC4511] to perform atomic "test and set" and "test and clear"
71   operations.
72
73   The control may be attached to any update operation to support
74   conditional addition, deletion, modification, and renaming of the
75   target object.  The asserted condition is evaluated as an integral
76   part the operation.
77
78   The control may also be used with the search operation.  Here, the
79   assertion is applied to the base object of the search before
80   searching for objects that match the search scope and filter.
81
82   The control may also be used with the compare operation.  Here, it
83   extends the compare operation to allow a more complex assertion.
84
852. Terminology
86
87   Protocol elements are described using ASN.1 [X.680] with implicit
88   tags.  The term "BER-encoded" means the element is to be encoded
89   using the Basic Encoding Rules [X.690] under the restrictions
90   detailed in Section 5.1 of [RFC4511].
91
92   DSA stands for Directory System Agent (or server).
93   DSE stands for DSA-specific Entry.
94
95   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
96   "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
97   and "OPTIONAL" are to be interpreted as described in BCP 14
98   [RFC2119].
99
1003.  The Assertion Control
101
102   The assertion control is an LDAP Control [RFC4511] whose controlType
103   is 1.3.6.1.1.12 and whose controlValue is a BER-encoded Filter
104   [Protocol, Section 4.5.1].  The criticality may be TRUE or FALSE.
105   There is no corresponding response control.
106
107   The control is appropriate for both LDAP interrogation and update
108   operations [RFC4511], including Add, Compare, Delete, Modify,
109   ModifyDN (rename), and Search.  It is inappropriate for Abandon,
110   Bind, Unbind, and StartTLS operations.
111
112
113
114Zeilenga                    Standards Track                     [Page 2]
115
116RFC 4528                 LDAP Assertion Control                June 2006
117
118
119   When the control is attached to an LDAP request, the processing of
120   the request is conditional on the evaluation of the Filter as applied
121   against the target of the operation.  If the Filter evaluates to
122   TRUE, then the request is processed normally.  If the Filter
123   evaluates to FALSE or Undefined, then assertionFailed (122)
124   resultCode is returned, and no further processing is performed.
125
126   For Add, Compare, and ModifyDN operations, the target is indicated by
127   the entry field in the request.  For Modify operations, the target is
128   indicated by the object field.  For Delete operations, the target is
129   indicated by the DelRequest type.  For Compare operations and all
130   update operations, the evaluation of the assertion MUST be performed
131   as an integral part of the operation.  That is, the evaluation of the
132   assertion and the normal processing of the operation SHALL be done as
133   one atomic action.
134
135   For Search operations, the target is indicated by the baseObject
136   field, and the evaluation is done after "finding" but before
137   "searching" [RFC4511].  Hence, no entries or continuations references
138   are returned if the assertion fails.
139
140   Servers implementing this technical specification SHOULD publish the
141   object identifier 1.3.6.1.1.12 as a value of the 'supportedControl'
142   attribute [RFC4512] in their root DSE.  A server MAY choose to
143   advertise this extension only when the client is authorized to use
144   it.
145
146   Other documents may specify how this control applies to other LDAP
147   operations.  In doing so, they must state how the target entry is
148   determined.
149
1504.  Security Considerations
151
152   The filter may, like other components of the request, contain
153   sensitive information.  When it does, this information should be
154   appropriately protected.
155
156   As with any general assertion mechanism, the mechanism can be used to
157   determine directory content.  Hence, this mechanism SHOULD be subject
158   to appropriate access controls.
159
160   Some assertions may be very complex, requiring significant time and
161   resources to evaluate.  Hence, this mechanism SHOULD be subject to
162   appropriate administrative controls.
163
164
165
166
167
168
169
170Zeilenga                    Standards Track                     [Page 3]
171
172RFC 4528                 LDAP Assertion Control                June 2006
173
174
175   Security considerations for the base operations [RFC4511] extended by
176   this control, as well as general LDAP security considerations
177   [RFC4510], generally apply to implementation and use of this
178   extension.
179
1805.  IANA Considerations
181
1825.1.  Object Identifier
183
184   The IANA has assigned an LDAP Object Identifier [RFC4520] to identify
185   the LDAP Assertion Control defined in this document.
186
187       Subject: Request for LDAP Object Identifier Registration
188       Person & email address to contact for further information:
189           Kurt Zeilenga <kurt@OpenLDAP.org>
190       Specification: RFC 4528
191       Author/Change Controller: IESG
192       Comments:
193           Identifies the LDAP Assertion Control
194
1955.2.  LDAP Protocol Mechanism
196
197   Registration of this protocol mechanism [RFC4520] is requested.
198
199       Subject: Request for LDAP Protocol Mechanism Registration
200       Object Identifier: 1.3.6.1.1.12
201       Description: Assertion Control
202       Person & email address to contact for further information:
203           Kurt Zeilenga <kurt@openldap.org>
204       Usage: Control
205       Specification: RFC 4528
206       Author/Change Controller: IESG
207       Comments: none
208
2095.3.  LDAP Result Code
210
211   The IANA has assigned an LDAP Result Code [RFC4520] called
212   'assertionFailed' (122).
213
214       Subject: LDAP Result Code Registration
215       Person & email address to contact for further information:
216           Kurt Zeilenga <kurt@OpenLDAP.org>
217       Result Code Name: assertionFailed
218       Specification: RFC 4528
219       Author/Change Controller: IESG
220       Comments:  none
221
222
223
224
225
226Zeilenga                    Standards Track                     [Page 4]
227
228RFC 4528                 LDAP Assertion Control                June 2006
229
230
2316.  Acknowledgements
232
233   The assertion control concept is attributed to Morteza Ansari.
234
2357.  References
236
2377.1.  Normative References
238
239   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
240                 Requirement Levels", BCP 14, RFC 2119, March 1997.
241
242   [RFC4510]     Zeilenga, K., Ed., "Lightweight Directory Access
243                 Protocol (LDAP): Technical Specification Road Map", RFC
244                 4510, June 2006.
245
246   [RFC4511]     Sermersheim, J., Ed., "Lightweight Directory Access
247                 Protocol (LDAP): The Protocol", RFC 4511, June 2006.
248
249   [RFC4512]     Zeilenga, K., "Lightweight Directory Access Protocol
250                 (LDAP): Directory Information Models", RFC 4512, June
251                 2006.
252
253   [X.680]       International Telecommunication Union -
254                 Telecommunication Standardization Sector, "Abstract
255                 Syntax Notation One (ASN.1) - Specification of Basic
256                 Notation", X.680(2002) (also ISO/IEC 8824-1:2002).
257
258   [X.690]       International Telecommunication Union -
259                 Telecommunication Standardization Sector,
260                 "Specification of ASN.1 encoding rules: Basic Encoding
261                 Rules (BER), Canonical Encoding Rules (CER), and
262                 Distinguished Encoding Rules (DER)", X.690(2002) (also
263                 ISO/IEC 8825-1:2002).
264
2657.2.  Informative References
266
267   [RFC4520]     Zeilenga, K., "Internet Assigned Numbers Authority
268                 (IANA) Considerations for the Lightweight Directory
269                 Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
270
271Author's Address
272
273   Kurt D. Zeilenga
274   OpenLDAP Foundation
275
276   EMail: Kurt@OpenLDAP.org
277
278
279
280
281
282Zeilenga                    Standards Track                     [Page 5]
283
284RFC 4528                 LDAP Assertion Control                June 2006
285
286
287Full Copyright Statement
288
289   Copyright (C) The Internet Society (2006).
290
291   This document is subject to the rights, licenses and restrictions
292   contained in BCP 78, and except as set forth therein, the authors
293   retain all their rights.
294
295   This document and the information contained herein are provided on an
296   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
297   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
298   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
299   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
300   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
301   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
302
303Intellectual Property
304
305   The IETF takes no position regarding the validity or scope of any
306   Intellectual Property Rights or other rights that might be claimed to
307   pertain to the implementation or use of the technology described in
308   this document or the extent to which any license under such rights
309   might or might not be available; nor does it represent that it has
310   made any independent effort to identify any such rights.  Information
311   on the procedures with respect to rights in RFC documents can be
312   found in BCP 78 and BCP 79.
313
314   Copies of IPR disclosures made to the IETF Secretariat and any
315   assurances of licenses to be made available, or the result of an
316   attempt made to obtain a general license or permission for the use of
317   such proprietary rights by implementers or users of this
318   specification can be obtained from the IETF on-line IPR repository at
319   http://www.ietf.org/ipr.
320
321   The IETF invites any interested party to bring to its attention any
322   copyrights, patents or patent applications, or other proprietary
323   rights that may cover technology that may be required to implement
324   this standard.  Please address the information to the IETF at
325   ietf-ipr@ietf.org.
326
327Acknowledgement
328
329   Funding for the RFC Editor function is provided by the IETF
330   Administrative Support Activity (IASA).
331
332
333
334
335
336
337
338Zeilenga                    Standards Track                     [Page 6]
339
340