| blob | 62097db7fadeb68e8e6ff43f7761dc4cfd5e1023 |
7 Network Working Group K. Zeilenga
8 Request for Comments: 3672 OpenLDAP Foundation
9 Category: Standards Track S. Legg
10 Adacel Technologies
11 December 2003
14 Subentries in the Lightweight Directory Access Protocol (LDAP)
16 Status of this Memo
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.
24 Copyright Notice
26 Copyright (C) The Internet Society (2003). All Rights Reserved.
28 Abstract
30 In X.500 directories, subentries are special entries used to hold
31 information associated with a subtree or subtree refinement. This
32 document adapts X.500 subentries mechanisms for use with the
33 Lightweight Directory Access Protocol (LDAP).
35 1. Overview
37 From [X.501]:
39 A subentry is a special kind of entry immediately subordinate to
40 an administrative point. It contains attributes that pertain to
41 a subtree (or subtree refinement) associated with its
42 administrative point. The subentries and their administrative
43 point are part of the same naming context.
45 A single subentry may serve all or several aspects of
46 administrative authority. Alternatively, a specific aspect of
47 administrative authority may be handled through one or more of
48 its own subentries.
50 Subentries in the Lightweight Directory Access Protocol (LDAP)
51 [RFC3377] SHALL behave in accordance with X.501 unless noted
52 otherwise in this specification.
58 Zeilenga & Legg Standards Track [Page 1]
59 \f
60 RFC 3672 Subentries in LDAP December 2003
63 In absence of the subentries control (detailed in Section 3),
64 subentries SHALL NOT be considered in one-level and subtree scope
65 search operations. For all other operations, including base scope
66 search operations, subentries SHALL be considered.
68 1.1. Conventions
70 Schema definitions are provided using LDAP description formats
71 [RFC2252]. Definitions provided here are formatted (line wrapped)
72 for readability.
74 Protocol elements are described using ASN.1 [X.680]. The term "BER-
75 encoded" means the element is to be encoded using the Basic Encoding
76 Rules [X.690] under the restrictions detailed in Section 5.1 of
77 [RFC2251].
79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
81 document are to be interpreted as described in BCP 14 [RFC2119].
83 2. Subentry Schema
85 2.1. Subtree Specification Syntax
87 The Subtree Specification syntax provides a general purpose mechanism
88 for the specification of a subset of entries in a subtree of the
89 Directory Information Tree (DIT). A subtree begins at some base
90 entry and includes the subordinates of that entry down to some
91 identified lower boundary, possibly extending to the leaf entries. A
92 subtree specification is always used within a context or scope which
93 implicitly determines the bounds of the subtree. For example, the
94 scope of a subtree specification for a subschema administrative area
95 does not include the subtrees of any subordinate administrative point
96 entries for subschema administration. Where a subtree specification
97 does not identify a contiguous subset of the entries within a single
98 subtree the collection is termed a subtree refinement.
100 This syntax corresponds to the SubtreeSpecification ASN.1 type
101 described in [X.501], Section 11.3. This ASN.1 data type definition
102 is reproduced here for completeness.
104 SubtreeSpecification ::= SEQUENCE {
105 base [0] LocalName DEFAULT { },
106 COMPONENTS OF ChopSpecification,
107 specificationFilter [4] Refinement OPTIONAL }
109 LocalName ::= RDNSequence
114 Zeilenga & Legg Standards Track [Page 2]
115 \f
116 RFC 3672 Subentries in LDAP December 2003
119 ChopSpecification ::= SEQUENCE {
120 specificExclusions [1] SET OF CHOICE {
121 chopBefore [0] LocalName,
122 chopAfter [1] LocalName } OPTIONAL,
123 minimum [2] BaseDistance DEFAULT 0,
124 maximum [3] BaseDistance OPTIONAL }
126 BaseDistance ::= INTEGER (0 .. MAX)
128 Refinement ::= CHOICE {
129 item [0] OBJECT-CLASS.&id,
130 and [1] SET OF Refinement,
131 or [2] SET OF Refinement,
132 not [3] Refinement }
134 The components of SubtreeSpecification are: base, which identifies
135 the base entry of the subtree or subtree refinement, and
136 specificExclusions, minimum, maximum and specificationFilter, which
137 then reduce the set of subordinate entries of the base entry. The
138 subtree or subtree refinement contains all the entries within scope
139 that are not excluded by any of the components of the subtree
140 specification. When all of the components of SubtreeSpecification
141 are absent (i.e., when a value of the Subtree Specification syntax is
142 the empty sequence, {}), the specified subtree implicitly includes
143 all the entries within scope.
145 Any particular use of this mechanism MAY impose limitations or
146 constraints on the components of SubtreeSpecification.
148 The LDAP syntax specification is:
150 ( 1.3.6.1.4.1.1466.115.121.1.45 DESC 'SubtreeSpecification' )
152 The LDAP-specific encoding of values of this syntax is defined by the
153 Generic String Encoding Rules [RFC3641]. Appendix A provides an
154 equivalent Augmented Backus-Naur Form (ABNF) [RFC2234] for this
155 syntax.
157 2.1.1. Base
159 The base component of SubtreeSpecification nominates the base entry
160 of the subtree or subtree refinement. The base entry may be an entry
161 which is subordinate to the root entry of the scope in which the
162 subtree specification is used, in which case the base component
163 contains a sequence of Relative Distinguished Names (RDNs) relative
164 to the root entry of the scope, or may be the root entry of the scope
165 itself (the default), in which case the base component is absent or
166 contains an empty sequence of RDNs.
170 Zeilenga & Legg Standards Track [Page 3]
171 \f
172 RFC 3672 Subentries in LDAP December 2003
175 Entries that are not subordinates of the base entry are excluded from
176 the subtree or subtree refinement.
178 2.1.2. Specific Exclusions
180 The specificExclusions component of a ChopSpecification is a list of
181 exclusions that specify entries and their subordinates to be excluded
182 from the subtree or subtree refinement. The entry is specified by a
183 sequence of RDNs relative to the base entry (i.e., a LocalName).
184 Each exclusion is of either the chopBefore or chopAfter form. If the
185 chopBefore form is used then the specified entry and its subordinates
186 are excluded from the subtree or subtree refinement. If the
187 chopAfter form is used then only the subordinates of the specified
188 entry are excluded from the subtree or subtree refinement.
190 2.1.3. Minimum and Maximum
192 The minimum and maximum components of a ChopSpecification allow the
193 exclusion of entries based on their depth in the DIT.
195 Entries that are less than the minimum number of RDN arcs below the
196 base entry are excluded from the subtree or subtree refinement. A
197 minimum value of zero (the default) corresponds to the base entry.
199 Entries that are more than the maximum number of RDN arcs below the
200 base entry are excluded from the subtree or subtree refinement. An
201 absent maximum component indicates that there is no upper limit on
202 the number of RDN arcs below the base entry for entries in the
203 subtree or subtree refinement.
205 2.1.4. Specification Filter
207 The specificationFilter component is a boolean expression of
208 assertions about the values of the objectClass attribute of the base
209 entry and its subordinates. A Refinement assertion item evaluates to
210 true for an entry if that entry's objectClass attribute contains the
211 OID nominated in the assertion. Entries for which the overall filter
212 evaluates to false are excluded from the subtree refinement. If the
213 specificationFilter is absent then no entries are excluded from the
214 subtree or subtree refinement because of their objectClass attribute
215 values.
226 Zeilenga & Legg Standards Track [Page 4]
227 \f
228 RFC 3672 Subentries in LDAP December 2003
231 2.2. Administrative Role Attribute Type
233 The Administrative Model defined in [X.501], clause 10 requires that
234 administrative entries contain an administrativeRole attribute to
235 indicate that the associated administrative area is concerned with
236 one or more administrative roles.
238 The administrativeRole operational attribute is specified as follows:
240 ( 2.5.18.5 NAME 'administrativeRole'
241 EQUALITY objectIdentifierMatch
242 USAGE directoryOperation
243 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
245 The possible values of this attribute defined in X.501 are:
247 OID NAME
248 -------- -------------------------------
249 2.5.23.1 autonomousArea
250 2.5.23.2 accessControlSpecificArea
251 2.5.23.3 accessControlInnerArea
252 2.5.23.4 subschemaAdminSpecificArea
253 2.5.23.5 collectiveAttributeSpecificArea
254 2.5.23.6 collectiveAttributeInnerArea
256 Other values may be defined in other specifications. Names
257 associated with each administrative role are Object Identifier
258 Descriptors [RFC3383].
260 The administrativeRole operational attribute is also used to regulate
261 the subentries permitted to be subordinate to an administrative
262 entry. A subentry not of a class permitted by the administrativeRole
263 attribute cannot be subordinate to the administrative entry.
265 2.3. Subtree Specification Attribute Type
267 The subtreeSpecification operational attribute is defined as follows:
269 ( 2.5.18.6 NAME 'subtreeSpecification'
270 SINGLE-VALUE
271 USAGE directoryOperation
272 SYNTAX 1.3.6.1.4.1.1466.115.121.1.45 )
274 This attribute is present in all subentries. See [X.501], clause 10.
275 Values of the subtreeSpecification attribute nominate collections of
276 entries within the DIT for one or more aspects of administrative
277 authority.
282 Zeilenga & Legg Standards Track [Page 5]
283 \f
284 RFC 3672 Subentries in LDAP December 2003
287 2.4. Subentry Object Class
289 The subentry object class is a structural object class.
291 ( 2.5.17.0 NAME 'subentry'
292 SUP top STRUCTURAL
293 MUST ( cn $ subtreeSpecification ) )
295 3. Subentries Control
297 The subentries control MAY be sent with a searchRequest to control
298 the visibility of entries and subentries which are within scope.
299 Non-visible entries or subentries are not returned in response to the
300 request.
302 The subentries control is an LDAP Control whose controlType is
303 1.3.6.1.4.1.4203.1.10.1, criticality is TRUE or FALSE (hence absent),
304 and controlValue contains a BER-encoded BOOLEAN indicating
305 visibility. A controlValue containing the value TRUE indicates that
306 subentries are visible and normal entries are not. A controlValue
307 containing the value FALSE indicates that normal entries are visible
308 and subentries are not.
310 Note that TRUE visibility has the three octet encoding { 01 01 FF }
311 and FALSE visibility has the three octet encoding { 01 01 00 }.
313 The controlValue SHALL NOT be absent.
315 In absence of this control, subentries are not visible to singleLevel
316 and wholeSubtree scope Search requests but are visible to baseObject
317 scope Search requests.
319 There is no corresponding response control.
321 This control is not appropriate for non-Search operations.
323 4. Security Considerations
325 Subentries often hold administrative information or other sensitive
326 information and should be protected from unauthorized access and
327 disclosure as described in [RFC2829][RFC2830].
329 General LDAP [RFC3377] security considerations also apply.
338 Zeilenga & Legg Standards Track [Page 6]
339 \f
340 RFC 3672 Subentries in LDAP December 2003
343 5. IANA Considerations
345 5.1. Descriptors
347 The IANA has registered the LDAP descriptors detailed in this
348 technical specification. The following registration template is
349 suggested:
351 Subject: Request for LDAP Descriptor Registration
352 Descriptor (short name): see comment
353 Object Identifier: see comment
354 Person & email address to contact for further information:
355 Kurt Zeilenga <kurt@OpenLDAP.org>
356 Usage: see comment
357 Specification: RFC3672
358 Author/Change Controller: IESG
359 Comments:
361 NAME Type OID
362 ------------------------ ---- --------
363 accessControlInnerArea R 2.5.23.3
364 accessControlSpecificArea R 2.5.23.2
365 administrativeRole A 2.5.18.5
366 autonomousArea R 2.5.23.1
367 collectiveAttributeInnerArea R 2.5.23.6
368 collectiveAttributeSpecificArea R 2.5.23.5
369 subentry O 2.5.17.0
370 subschemaAdminSpecificArea R 2.5.23.4
371 subtreeSpecification A 2.5.18.6
373 where Type A is Attribute, Type O is ObjectClass, and Type R is
374 Administrative Role.
376 5.2. Object Identifiers
378 This document uses the OID 1.3.6.1.4.1.4203.1.10.1 to identify an
379 LDAP protocol element defined herein. This OID was assigned [ASSIGN]
380 by OpenLDAP Foundation, under its IANA-assigned private enterprise
381 allocation [PRIVATE], for use in this specification.
383 Other OIDs which appear in this document were either assigned by the
384 ISO/IEC Joint Technical Committee 1 - Subcommittee 6 to identify
385 elements of X.500 schema or assigned in RFC 2252 for the use
386 described here.
394 Zeilenga & Legg Standards Track [Page 7]
395 \f
396 RFC 3672 Subentries in LDAP December 2003
399 5.3. Protocol Mechanisms
401 The IANA has registered the LDAP protocol mechanisms [RFC3383]
402 detailed in this specification.
404 Subject: Request for LDAP Protocol Mechanism Registration
406 Description: Subentries
408 Person & email address to contact for further information:
409 Kurt Zeilenga <kurt@openldap.org>
411 Usage: Control
413 Specification: RFC3672
415 Author/Change Controller: IESG
417 Comments: none
419 6. Acknowledgment
421 This document is based on engineering done by IETF LDUP and LDAPext
422 Working Groups including "LDAP Subentry Schema" by Ed Reed. This
423 document also borrows from a number of ITU documents including X.501.
425 7. Intellectual Property Statement
427 The IETF takes no position regarding the validity or scope of any
428 intellectual property or other rights that might be claimed to
429 pertain to the implementation or use of the technology described in
430 this document or the extent to which any license under such rights
431 might or might not be available; neither does it represent that it
432 has made any effort to identify any such rights. Information on the
433 IETF's procedures with respect to rights in standards-track and
434 standards-related documentation can be found in BCP-11. Copies of
435 claims of rights made available for publication and any assurances of
436 licenses to be made available, or the result of an attempt made to
437 obtain a general license or permission for the use of such
438 proprietary rights by implementors or users of this specification can
439 be obtained from the IETF Secretariat.
441 The IETF invites any interested party to bring to its attention any
442 copyrights, patents or patent applications, or other proprietary
443 rights which may cover technology that may be required to practice
444 this standard. Please address the information to the IETF Executive
445 Director.
450 Zeilenga & Legg Standards Track [Page 8]
451 \f
452 RFC 3672 Subentries in LDAP December 2003
455 A. Subtree Specification ABNF
457 This appendix is non-normative.
459 The LDAP-specific string encoding for the Subtree Specification
460 syntax is specified by the Generic String Encoding Rules [RFC3641].
461 The ABNF [RFC2234] in this appendix for this syntax is provided only
462 as a convenience and is equivalent to the encoding specified by the
463 application of [RFC3641]. Since the SubtreeSpecification ASN.1 type
464 may be extended in future editions of [X.501], the provided ABNF
465 should be regarded as a snapshot in time. The LDAP-specific encoding
466 for any extension to the SubtreeSpecification ASN.1 type can be
467 determined from [RFC3641].
469 In the event that there is a discrepancy between this ABNF and the
470 encoding determined by [RFC3641], [RFC3641] is to be taken as
471 definitive.
473 SubtreeSpecification = "{" [ sp ss-base ]
474 [ sep sp ss-specificExclusions ]
475 [ sep sp ss-minimum ]
476 [ sep sp ss-maximum ]
477 [ sep sp ss-specificationFilter ]
478 sp "}"
480 ss-base = id-base msp LocalName
481 ss-specificExclusions = id-specificExclusions msp
482 SpecificExclusions
483 ss-minimum = id-minimum msp BaseDistance
484 ss-maximum = id-maximum msp BaseDistance
485 ss-specificationFilter = id-specificationFilter msp Refinement
487 id-base = %x62.61.73.65 ; "base"
488 id-specificExclusions = %x73.70.65.63.69.66.69.63.45.78.63.6C.75.73
489 %x69.6F.6E.73 ; "specificExclusions"
490 id-minimum = %x6D.69.6E.69.6D.75.6D ; "minimum"
491 id-maximum = %x6D.61.78.69.6D.75.6D ; "maximum"
492 id-specificationFilter = %x73.70.65.63.69.66.69.63.61.74.69.6F.6E.46
493 %x69.6C.74.65.72 ; "specificationFilter"
495 SpecificExclusions = "{" [ sp SpecificExclusion
496 *( "," sp SpecificExclusion ) ] sp "}"
497 SpecificExclusion = chopBefore / chopAfter
498 chopBefore = id-chopBefore ":" LocalName
499 chopAfter = id-chopAfter ":" LocalName
500 id-chopBefore = %x63.68.6F.70.42.65.66.6F.72.65 ; "chopBefore"
501 id-chopAfter = %x63.68.6F.70.41.66.74.65.72 ; "chopAfter"
506 Zeilenga & Legg Standards Track [Page 9]
507 \f
508 RFC 3672 Subentries in LDAP December 2003
511 Refinement = item / and / or / not
512 item = id-item ":" OBJECT-IDENTIFIER
513 and = id-and ":" Refinements
514 or = id-or ":" Refinements
515 not = id-not ":" Refinement
516 Refinements = "{" [ sp Refinement
517 *( "," sp Refinement ) ] sp "}"
518 id-item = %x69.74.65.6D ; "item"
519 id-and = %x61.6E.64 ; "and"
520 id-or = %x6F.72 ; "or"
521 id-not = %x6E.6F.74 ; "not"
523 BaseDistance = INTEGER-0-MAX
525 The <sp>, <msp>, <sep>, <INTEGER>, <INTEGER-0-MAX>, <OBJECT-
526 IDENTIFIER> and <LocalName> rules are defined in [RFC3642].
528 Normative References
530 [X.501] ITU-T, "The Directory -- Models," X.501, 1993.
532 [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) -
533 Specification of Basic Notation", X.680, 1994.
535 [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic,
536 Canonical, and Distinguished Encoding Rules", X.690,
537 1994.
539 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
540 Requirement Levels", BCP 14, RFC 2119, March 1997.
542 [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
543 Access Protocol (v3)", RFC 2251, December 1997.
545 [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille,
546 "Lightweight Directory Access Protocol (v3): Attribute
547 Syntax Definitions", RFC 2252, December 1997.
549 [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
550 "Authentication Methods for LDAP", RFC 2829, May 2000.
552 [RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight
553 Directory Access Protocol (v3): Extension for Transport
554 Layer Security", RFC 2830, May 2000.
556 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
557 Protocol (v3): Technical Specification", RFC 3377,
558 September 2002.
562 Zeilenga & Legg Standards Track [Page 10]
563 \f
564 RFC 3672 Subentries in LDAP December 2003
567 [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
568 Considerations for the Lightweight Directory Access
569 Protocol (LDAP)", RFC 3383, September 2002.
571 [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1
572 Types", RFC 3641, October 2003.
574 Informative References
576 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
577 Specifications: ABNF", RFC 2234, November 1997.
579 [RFC3642] Legg, S., "Common Elements of Generic String Encoding
580 Rules (GSER) Encodings", RFC 3642, October 2003.
582 [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
583 http://www.openldap.org/foundation/oid-delegate.txt
585 [PRIVATE] IANA, "Private Enterprise Numbers",
586 http://www.iana.org/assignments/enterprise-numbers
588 Authors' Addresses
590 Kurt D. Zeilenga
591 OpenLDAP Foundation
593 EMail: Kurt@OpenLDAP.org
596 Steven Legg
597 Adacel Technologies Ltd.
598 250 Bay Street
599 Brighton, Victoria 3186
600 AUSTRALIA
602 Phone: +61 3 8530 7710
603 Fax: +61 3 8530 7888
604 EMail: steven.legg@adacel.com.au
618 Zeilenga & Legg Standards Track [Page 11]
619 \f
620 RFC 3672 Subentries in LDAP December 2003
623 Full Copyright Statement
625 Copyright (C) The Internet Society (2003). All Rights Reserved.
627 This document and translations of it may be copied and furnished to
628 others, and derivative works that comment on or otherwise explain it
629 or assist in its implementation may be prepared, copied, published
630 and distributed, in whole or in part, without restriction of any
631 kind, provided that the above copyright notice and this paragraph are
632 included on all such copies and derivative works. However, this
633 document itself may not be modified in any way, such as by removing
634 the copyright notice or references to the Internet Society or other
635 Internet organizations, except as needed for the purpose of
636 developing Internet standards in which case the procedures for
637 copyrights defined in the Internet Standards process must be
638 followed, or as required to translate it into languages other than
639 English.
641 The limited permissions granted above are perpetual and will not be
642 revoked by the Internet Society or its successors or assignees.
644 This document and the information contained herein is provided on an
645 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
646 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
647 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
648 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
649 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
651 Acknowledgement
653 Funding for the RFC Editor function is currently provided by the
654 Internet Society.
674 Zeilenga & Legg Standards Track [Page 12]
675 \f