7 INTERNET-DRAFT Kurt D. Zeilenga
8 Intended Category: Standard Track OpenLDAP Foundation
9 Date: 17 May 2002 Steven Legg
10 Expires in six months Adacel Technologies
14 <draft-zeilenga-ldap-subentry-05.txt>
19 This document is an Internet-Draft and is in full conformance with all
20 provisions of Section 10 of RFC2026.
22 This document is intended to be, after appropriate review and
23 revision, submitted to the RFC Editor as a Standard Track document.
24 Distribution of this memo is unlimited. Technical discussion of this
25 document will take place on the IETF LDAP Extension Working Group
26 mailing list <ietf-ldapext@netscape.com>. Please send editorial
27 comments directly to the author <Kurt@OpenLDAP.org>.
29 Internet-Drafts are working documents of the Internet Engineering Task
30 Force (IETF), its areas, and its working groups. Note that other
31 groups may also distribute working documents as Internet-Drafts.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as ``work in progress.''
37 The list of current Internet-Drafts can be accessed at
38 <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
39 Internet-Draft Shadow Directories can be accessed at
40 <http://www.ietf.org/shadow.html>.
42 Copyright 2002, The Internet Society. All Rights Reserved.
44 Please see the Copyright section near the end of this document for
50 In X.500 directories, subentries are special entries used to hold
51 information associated with a subtree or subtree refinement. This
52 document adapts X.500 subentries mechanisms for use with Lightweight
53 Directory Access Protocol (LDAP).
58 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 1]
60 INTERNET-DRAFT Subentries in LDAP 17 May 2002
65 Schema definitions are provided using LDAP description formats
66 [RFC2252]. Definitions provided here are formatted (line wrapped) for
69 Protocol elements are described using ASN.1 [X.680]. The term
70 "BER-encoded" means the element is to be encoded using the Basic
71 Encoding Rules [X.690] under the restrictions detailed in Section 5.1
74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
76 document are to be interpreted as described in BCP 14 [RFC2119].
82 A subentry is a special kind of entry immediately subordinate to
83 an administrative point. It contains attributes that pertain to a
84 subtree (or subtree refinement) associated with its administrative
85 point. The subentries and their administrative point are part of
86 the same naming context.
88 A single subentry may serve all or several aspects of
89 administrative authority. Alternatively, a specific aspect of
90 administrative authority may be handled through one or more of its
93 Subentries in Lightweight Directory Access Protocol (LDAP) [LDAPTS]
94 SHALL behave in accordance with X.501 unless noted otherwise in this
97 In absence of the subentries control (detailed in Section 3),
98 subentries SHALL NOT be considered in one-level and subtree scope
99 search operations. For all other operations, including base scope
100 search operations, subentries SHALL be considered.
105 2.1. Subtree Specification Syntax
107 The Subtree Specification syntax provides a general purpose mechanism
108 for the specification of a subset of entries in a subtree of the
109 Directory Information Tree (DIT). A subtree begins at some base entry
110 and includes the subordinates of that entry down to some identified
114 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 2]
116 INTERNET-DRAFT Subentries in LDAP 17 May 2002
119 lower boundary, possibly extending to the leaf entries. A subtree
120 specification is always used within a context or scope which
121 implicitly determines the bounds of the subtree. For example, the
122 scope of a subtree specification for a subschema administrative area
123 does not include the subtrees of any subordinate administrative point
124 entries for subschema administration. Where a subtree specification
125 does not identify a contiguous subset of the entries within a single
126 subtree the collection is termed a subtree refinement.
128 This syntax corresponds to the SubtreeSpecification ASN.1 type
129 described in [X.501], Section 11.3. This ASN.1 data type definition
130 is reproduced here for completeness.
132 SubtreeSpecification ::= SEQUENCE {
133 base [0] LocalName DEFAULT { },
134 COMPONENTS OF ChopSpecification,
135 specificationFilter [4] Refinement OPTIONAL }
138 LocalName ::= RDNSequence
140 ChopSpecification ::= SEQUENCE {
141 specificExclusions [1] SET OF CHOICE {
142 chopBefore [0] LocalName,
143 chopAfter [1] LocalName } OPTIONAL,
144 minimum [2] BaseDistance DEFAULT 0,
145 maximum [3] BaseDistance OPTIONAL}
147 BaseDistance ::= INTEGER (0 .. MAX)
149 Refinement ::= CHOICE {
150 item [0] OBJECT-CLASS.&id,
151 and [1] SET OF Refinement,
152 or [2] SET OF Refinement,
155 The components of SubtreeSpecification are: base, which identifies the
156 base entry of the subtree or subtree refinement, and
157 specificExclusions, minimum, maximum and specificationFilter, which
158 then reduce the set of subordinate entries of the base entry. The
159 subtree or subtree refinement contains all the entries within scope
160 that are not excluded by any of the components of the subtree
161 specification. When all of the components of SubtreeSpecification are
162 absent (i.e. when a value of the Subtree Specification syntax is the
163 empty sequence, {}), the subtree so specified implicitly includes all
164 the entries within scope.
166 Any particular use of this mechanism MAY impose limitations or
170 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 3]
172 INTERNET-DRAFT Subentries in LDAP 17 May 2002
175 constraints on the components of SubtreeSpecification.
177 The LDAP syntax specification is:
179 ( 1.3.6.1.4.1.1466.115.121.1.45 DESC 'SubtreeSpecification' )
181 The native LDAP encoding of values of this syntax is defined by the
182 Generic String Encoding Rules [GSER]. Appendix A provides an
183 equivalent ABNF for this syntax.
188 The base component of SubtreeSpecification nominates the base entry of
189 the subtree or subtree refinement. The base entry may be an entry
190 which is subordinate to the root entry of the scope in which the
191 subtree specification is used, in which case the base component
192 contains a sequence of RDNs relative to the root entry of the scope,
193 or may be the root entry of the scope itself (the default), in which
194 case the base component is absent or contains an empty sequence of
197 Entries that are not subordinates of the base entry are excluded from
198 the subtree or subtree refinement.
201 2.1.2. Specific Exclusions
203 The specificExclusions component of a ChopSpecification is a list of
204 exclusions that specify entries and their subordinates to be excluded
205 from the the subtree or subtree refinement. The entry is specified by
206 a sequence of RDNs relative to the base entry (i.e. a LocalName).
207 Each exclusion is of either the chopBefore or chopAfter form. If the
208 chopBefore form is used then the specified entry and its subordinates
209 are excluded from the subtree or subtree refinement. If the chopAfter
210 form is used then only the subordinates of the specified entry are
211 excluded from the subtree or subtree refinement.
214 2.1.3. Minimum and Maximum
216 The minimum and maximum components of a ChopSpecification allow the
217 exclusion of entries based on their depth in the DIT.
219 Entries that are less than the minimum number of RDN arcs below the
220 base entry are excluded from the subtree or subtree refinement. A
221 minimum value of zero (the default) corresponds to the base entry.
226 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 4]
228 INTERNET-DRAFT Subentries in LDAP 17 May 2002
231 Entries that are more than the maximum number of RDN arcs below the
232 base entry are excluded from the subtree or subtree refinement. An
233 absent maximum component indicates that there is no upper limit on the
234 number of RDN arcs below the base entry for entries in the subtree or
237 2.1.4. Specification Filter
239 The specificationFilter component is a boolean expression of
240 assertions about the values of the objectClass attribute of the base
241 entry and its subordinates. A Refinement assertion item evaluates to
242 true for an entry if that entry's objectClass attribute contains the
243 OID nominated in the assertion. Entries for which the overall filter
244 evaluates to false are excluded from the subtree refinement. If the
245 specificationFilter is absent then no entries are excluded from the
246 subtree or subtree refinement because of their objectClass attribute
250 2.2. Administrative Role Attribute Type
252 The Administrative Model defined in [X.501], clause 10 requires that
253 administrative entries contain an administrativeRole attribute to
254 indicate that the associated administrative area is concerned with one
255 or more administrative roles.
257 The administrativeRole operational attribute is specified as follows:
259 ( 2.5.18.5 NAME 'administrativeRole'
260 EQUALITY objectIdentifierMatch
261 USAGE directoryOperation
262 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
264 The possible values of this attribute defined in X.501 are:
267 -------- -------------------------------
268 2.5.23.1 autonomousArea
269 2.5.23.2 accessControlSpecificArea
270 2.5.23.3 accessControlInnerArea
271 2.5.23.4 subschemaAdminSpecificArea
272 2.5.23.5 collectiveAttributeSpecificArea
273 2.5.23.6 collectiveAttributeInnerArea
275 Other values may be defined in other specifications. Names associated
276 with each administrative role are Object Identifier Descriptors
282 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 5]
284 INTERNET-DRAFT Subentries in LDAP 17 May 2002
287 The administrativeRole operational attribute is also used to regulate
288 the subentries permitted to be subordinate to an administrative entry.
289 A subentry not of a class permitted by the administrativeRole
290 attribute cannot be subordinate to the administrative entry.
293 2.3. Subtree Specification Attribute Type
295 The subtreeSpecification operational attribute is defined as follows:
297 ( 2.5.18.6 NAME 'subtreeSpecification'
299 USAGE directoryOperation
300 SYNTAX 1.3.6.1.4.1.1466.115.121.1.45 )
302 This attribute is present in all subentries. See [X.501], clause 10.
303 Values of the subtreeSpecification attribute nominate collections of
304 entries within the DIT for one or more aspects of administrative
308 2.4. Subentry Object Class
310 The subentry object class is a structural object class.
312 ( 2.5.20.0 NAME 'subentry'
314 MUST ( cn $ subtreeSpecification ) )
317 3. Subentries Control
319 The subentries control MAY be sent with a searchRequest to control the
320 visibility of entries and subentries which are within scope.
321 Non-visible entries or subentries are not returned in response to the
324 The subentries control is an LDAP Control whose controlType is
325 1.3.6.1.4.1.4203.1.10.1, criticality is TRUE or FALSE (hence absent),
326 and controlValue contains a BER-encoded BOOLEAN indicating visibility.
327 A controlValue containing the value TRUE indicates that subentries are
328 visible and normal entries are not. A controlValue containing the
329 value FALSE indicates that normal entries are visible and subentries
332 Note that TRUE visibility has the three octet encoding { 01 01 FF }
333 and FALSE visibility has the three octet encoding { 01 01 00 }.
338 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 6]
340 INTERNET-DRAFT Subentries in LDAP 17 May 2002
343 The controlValue SHALL NOT be absent.
345 In absence of this control, subentries are not visible to singleLevel
346 and wholeSubtree scope Search requests but are visible to baseObject
347 scope Search requests.
349 There is no corresponding response control.
351 This control is not appropriate for non-Search operations.
354 4. Security Considerations
356 Subentries often hold administrative information or other sensitive
357 information and should be protected from unauthorized access and
358 disclosure as described in [RFC2829][RFC2830].
360 General LDAP [LDAPTS] security considerations also apply.
363 5. IANA Considerations
367 It is requested that IANA register the LDAP descriptors used in this
368 document per the following registration template:
370 Subject: Request for LDAP Descriptor Registration
371 Descriptor (short name): see comment
372 Object Identifier: see comment
373 Person & email address to contact for further information:
374 Kurt Zeilenga <kurt@OpenLDAP.org>
376 Specification: RFCXXXX
377 Author/Change Controller: IESG
381 ------------------------ ---- --------
382 accessControlInnerArea R 2.5.23.3
383 accessControlSpecificArea R 2.5.23.2
384 administrativeRole A 2.5.18.5
385 autonomousArea R 2.5.23.1
386 collectiveAttributeInnerArea R 2.5.23.6
387 collectiveAttributeSpecificArea R 2.5.23.5
389 subschemaAdminSpecificArea R 2.5.23.4
390 subtreeSpecification A 2.5.18.6
394 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 7]
396 INTERNET-DRAFT Subentries in LDAP 17 May 2002
399 where Type A is Attribute, Type O is ObjectClass, and Type R is
403 5.2 Object Identifiers
405 No IANA assignment of object identifiers is requested.
407 This document uses the OID 1.3.6.1.4.1.4203.1.10.1 to identify an LDAP
408 protocol element defined herein. This OID was assigned [ASSIGN] by
409 OpenLDAP Foundation under its IANA assigned private enterprise
410 allocation [PRIVATE] for use in this specification.
412 Other OIDs which appear in this document were either assigned by the
413 ISO/IEC Joint Technical Committee 1 - Subcommitte 6 to identify
414 elements of X.500 schema or assigned in RFC 2252 for the use described
420 This document is based on engineering done by IETF LDUP and LDAPext
421 Working Groups including "LDAP Subentry Schema" by Ed Reed. This
422 document also borrows from a number of ITU documents including X.501.
425 7. Authors' Addresses
430 Email: Kurt@OpenLDAP.org
433 Adacel Technologies Ltd.
434 405-409 Ferntree Gully Road
435 Mount Waverley, Victoria 3149
438 Phone: +61 3 9451 2107
440 EMail: steven.legg@adacel.com.au
443 8. Normative References
445 [X.501] ITU-T, "The Directory -- Models," X.501, 1993.
450 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 8]
452 INTERNET-DRAFT Subentries in LDAP 17 May 2002
455 [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) -
456 Specification of Basic Notation", X.680, 1994.
458 [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic,
459 Canonical, and Distinguished Encoding Rules", X.690, 1994.
461 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
462 Requirement Levels", BCP 14 (was RFC 2119), March 1997.
464 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
465 Protocol (v3)", RFC 2251, December 1997.
467 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
468 Directory Access Protocol (v3): Attribute Syntax
469 Definitions", RFC 2252, December 1997.
471 [RFC2829] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan,
472 "Authentication Methods for LDAP", RFC 2829, May 2000
474 [RFC2830] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory
475 Access Protocol (v3): Extension for Transport Layer
476 Security", RFC 2830, May 2000.
478 [LDAPTS] J. Hodges, R.L. Morgan, "Lightweight Directory Access
479 Protocol (v3): Technical Specification",
480 draft-ietf-ldapbis-ldapv3-ts-xx.txt, a work in progress.
482 [GSER] S. Legg, "Generic String Encoding Rules for ASN.1 Types",
483 draft-legg-ldapext-gser--xx.txt, a work in progress.
485 [LDAPIANA] K. Zeilenga, "IANA Considerations for LDAP", draft-ietf-
486 ldapbis-iana-xx.txt, a work in progress.
489 9. Informative References
491 [RFC2234] D. Crocker, P. Overell, "Augmented BNF for Syntax
492 Specifications: ABNF", RFC 2234, November 1997.
494 [GCE] S. Legg, "Common Elements of GSER Encodings",
495 draft-legg-ldap-gser-abnf-xx.txt, a work in progress.
497 [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
498 http://www.openldap.org/foundation/oid-delegate.txt.
500 [PRIVATE] IANA, "Private Enterprise Numbers",
501 http://www.iana.org/assignments/enterprise-numbers.
506 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 9]
508 INTERNET-DRAFT Subentries in LDAP 17 May 2002
511 A. Subtree Specification ABNF
513 This appendix is non-normative.
515 The LDAP-specific native string encoding for the Subtree Specification
516 syntax is specified by the Generic String Encoding Rules [GSER]. The
517 ABNF [RFC2234] in this appendix for this syntax is provided only as a
518 convenience and is equivalent to the encoding specified by the
519 application of [GSER]. Since the SubtreeSpecification ASN.1 type may
520 be extended in future editions of [X.501], the provided ABNF should be
521 regarded as a snapshot in time. The native LDAP encoding for any
522 extension to the SubtreeSpecification ASN.1 type can be determined
525 In the event that there is a discrepancy between this ABNF and the
526 encoding determined by [GSER], [GSER] is to be taken as definitive.
528 SubtreeSpecification = "{" [ sp base ]
529 [ sep sp specificExclusions ]
532 [ sep sp specificationFilter ]
535 base = id-base msp LocalName
536 specificExclusions = id-specificExclusions msp SpecificExclusions
537 minimum = id-minimum msp BaseDistance
538 maximum = id-maximum msp BaseDistance
539 specificationFilter = id-specificationFilter msp Refinement
541 id-base = %x62.61.73.65 ; "base"
542 id-specificExclusions = %x73.70.65.63.69.66.69.63.45.78.63.6C.75.73
543 %x69.6F.6E.73 ; "specificExclusions"
544 id-minimum = %x6D.69.6E.69.6D.75.6D ; "minimum"
545 id-maximum = %x6D.61.78.69.6D.75.6D ; "maximum"
546 id-specificationFilter = %x73.70.65.63.69.66.69.63.61.74.69.6F.6E.46
547 %x69.6C.74.65.72 ; "specificationFilter"
549 SpecificExclusions = "{" sp SpecificExclusion
550 *( "," sp SpecificExclusion ) sp "}"
551 SpecificExclusion = chopBefore / chopAfter
552 chopBefore = id-chopBefore ":" LocalName
553 chopAfter = id-chopAfter ":" LocalName
554 id-chopBefore = %x63.68.6F.70.42.65.66.6F.72.65 ; "chopBefore"
555 id-chopAfter = %x63.68.6F.70.41.66.74.65.72 ; "chopAfter"
557 Refinement = item / and / or / not
558 item = id-item ":" OBJECT-IDENTIFIER
562 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 10]
564 INTERNET-DRAFT Subentries in LDAP 17 May 2002
567 and = id-and ":" Refinements
568 or = id-or ":" Refinements
569 not = id-not ":" Refinement
570 Refinements = "{" [ sp Refinement
571 *( "," sp Refinement ) ] sp "}"
572 id-item = %x69.74.65.6D ; "item"
573 id-and = %x61.6E.64 ; "and"
574 id-or = %x6F.72 ; "or"
575 id-not = %x6E.6F.74 ; "not"
577 BaseDistance = INTEGER
579 The <sp>, <msp>, <sep>, <INTEGER>, <OBJECT-IDENTIFIER> and <LocalName>
580 rules are defined in [GCE].
583 Copyright 2002, The Internet Society. All Rights Reserved.
585 This document and translations of it may be copied and furnished to
586 others, and derivative works that comment on or otherwise explain it
587 or assist in its implementation may be prepared, copied, published and
588 distributed, in whole or in part, without restriction of any kind,
589 provided that the above copyright notice and this paragraph are
590 included on all such copies and derivative works. However, this
591 document itself may not be modified in any way, such as by removing
592 the copyright notice or references to the Internet Society or other
593 Internet organizations, except as needed for the purpose of
594 developing Internet standards in which case the procedures for
595 copyrights defined in the Internet Standards process must be followed,
596 or as required to translate it into languages other than English.
598 The limited permissions granted above are perpetual and will not be
599 revoked by the Internet Society or its successors or assigns.
601 This document and the information contained herein is provided on an
602 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
603 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
604 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
605 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
606 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
618 Zeilenga draft-zeilenga-ldap-subentry-05 [Page 11]