]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc3672.txt
Fix prev commit
[openldap] / doc / rfc / rfc3672.txt
1
2
3
4
5
6
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
12
13
14      Subentries in the Lightweight Directory Access Protocol (LDAP)
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 (2003).  All Rights Reserved.
27
28 Abstract
29
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).
34
35 1.  Overview
36
37    From [X.501]:
38
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.
44
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.
49
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.
53
54
55
56
57
58 Zeilenga & Legg             Standards Track                     [Page 1]
59 \f
60 RFC 3672                   Subentries in LDAP              December 2003
61
62
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.
67
68 1.1.  Conventions
69
70    Schema definitions are provided using LDAP description formats
71    [RFC2252].  Definitions provided here are formatted (line wrapped)
72    for readability.
73
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].
78
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].
82
83 2.  Subentry Schema
84
85 2.1.  Subtree Specification Syntax
86
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.
99
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.
103
104      SubtreeSpecification ::= SEQUENCE {
105          base                [0] LocalName DEFAULT { },
106                                  COMPONENTS OF ChopSpecification,
107          specificationFilter [4] Refinement OPTIONAL }
108
109      LocalName ::= RDNSequence
110
111
112
113
114 Zeilenga & Legg             Standards Track                     [Page 2]
115 \f
116 RFC 3672                   Subentries in LDAP              December 2003
117
118
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 }
125
126      BaseDistance ::= INTEGER (0 .. MAX)
127
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 }
133
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.
144
145    Any particular use of this mechanism MAY impose limitations or
146    constraints on the components of SubtreeSpecification.
147
148    The LDAP syntax specification is:
149
150        ( 1.3.6.1.4.1.1466.115.121.1.45 DESC 'SubtreeSpecification' )
151
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.
156
157 2.1.1.  Base
158
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.
167
168
169
170 Zeilenga & Legg             Standards Track                     [Page 3]
171 \f
172 RFC 3672                   Subentries in LDAP              December 2003
173
174
175    Entries that are not subordinates of the base entry are excluded from
176    the subtree or subtree refinement.
177
178 2.1.2.  Specific Exclusions
179
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.
189
190 2.1.3.  Minimum and Maximum
191
192    The minimum and maximum components of a ChopSpecification allow the
193    exclusion of entries based on their depth in the DIT.
194
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.
198
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.
204
205 2.1.4.  Specification Filter
206
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.
216
217
218
219
220
221
222
223
224
225
226 Zeilenga & Legg             Standards Track                     [Page 4]
227 \f
228 RFC 3672                   Subentries in LDAP              December 2003
229
230
231 2.2.  Administrative Role Attribute Type
232
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.
237
238    The administrativeRole operational attribute is specified as follows:
239
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 )
244
245    The possible values of this attribute defined in X.501 are:
246
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
255
256    Other values may be defined in other specifications.  Names
257    associated with each administrative role are Object Identifier
258    Descriptors [RFC3383].
259
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.
264
265 2.3.  Subtree Specification Attribute Type
266
267    The subtreeSpecification operational attribute is defined as follows:
268
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 )
273
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.
278
279
280
281
282 Zeilenga & Legg             Standards Track                     [Page 5]
283 \f
284 RFC 3672                   Subentries in LDAP              December 2003
285
286
287 2.4.  Subentry Object Class
288
289    The subentry object class is a structural object class.
290
291        ( 2.5.17.0 NAME 'subentry'
292            SUP top STRUCTURAL
293            MUST ( cn $ subtreeSpecification ) )
294
295 3.  Subentries Control
296
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.
301
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.
309
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 }.
312
313    The controlValue SHALL NOT be absent.
314
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.
318
319    There is no corresponding response control.
320
321    This control is not appropriate for non-Search operations.
322
323 4.  Security Considerations
324
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].
328
329    General LDAP [RFC3377] security considerations also apply.
330
331
332
333
334
335
336
337
338 Zeilenga & Legg             Standards Track                     [Page 6]
339 \f
340 RFC 3672                   Subentries in LDAP              December 2003
341
342
343 5.  IANA Considerations
344
345 5.1.  Descriptors
346
347    The IANA has registered the LDAP descriptors detailed in this
348    technical specification.  The following registration template is
349    suggested:
350
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:
360
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
372
373        where Type A is Attribute, Type O is ObjectClass, and Type R is
374        Administrative Role.
375
376 5.2.  Object Identifiers
377
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.
382
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.
387
388
389
390
391
392
393
394 Zeilenga & Legg             Standards Track                     [Page 7]
395 \f
396 RFC 3672                   Subentries in LDAP              December 2003
397
398
399 5.3.  Protocol Mechanisms
400
401    The IANA has registered the LDAP protocol mechanisms [RFC3383]
402    detailed in this specification.
403
404    Subject: Request for LDAP Protocol Mechanism Registration
405
406    Description: Subentries
407
408    Person & email address to contact for further information:
409         Kurt Zeilenga <kurt@openldap.org>
410
411    Usage: Control
412
413    Specification: RFC3672
414
415    Author/Change Controller: IESG
416
417    Comments: none
418
419 6.  Acknowledgment
420
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.
424
425 7.  Intellectual Property Statement
426
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.
440
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.
446
447
448
449
450 Zeilenga & Legg             Standards Track                     [Page 8]
451 \f
452 RFC 3672                   Subentries in LDAP              December 2003
453
454
455 A.  Subtree Specification ABNF
456
457    This appendix is non-normative.
458
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].
468
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.
472
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 "}"
479
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
486
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"
494
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"
502
503
504
505
506 Zeilenga & Legg             Standards Track                     [Page 9]
507 \f
508 RFC 3672                   Subentries in LDAP              December 2003
509
510
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"
522
523    BaseDistance = INTEGER-0-MAX
524
525    The <sp>, <msp>, <sep>, <INTEGER>, <INTEGER-0-MAX>, <OBJECT-
526    IDENTIFIER> and <LocalName> rules are defined in [RFC3642].
527
528 Normative References
529
530    [X.501]     ITU-T, "The Directory -- Models," X.501, 1993.
531
532    [X.680]     ITU-T, "Abstract Syntax Notation One (ASN.1) -
533                Specification of Basic Notation", X.680, 1994.
534
535    [X.690]     ITU-T, "Specification of ASN.1 encoding rules:  Basic,
536                Canonical, and Distinguished Encoding Rules", X.690,
537                1994.
538
539    [RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate
540                Requirement Levels", BCP 14, RFC 2119, March 1997.
541
542    [RFC2251]   Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
543                Access Protocol (v3)", RFC 2251, December 1997.
544
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.
548
549    [RFC2829]   Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
550                "Authentication Methods for LDAP", RFC 2829, May 2000.
551
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.
555
556    [RFC3377]   Hodges, J. and R. Morgan, "Lightweight Directory Access
557                Protocol (v3): Technical Specification", RFC 3377,
558                September 2002.
559
560
561
562 Zeilenga & Legg             Standards Track                    [Page 10]
563 \f
564 RFC 3672                   Subentries in LDAP              December 2003
565
566
567    [RFC3383]   Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
568                Considerations for the Lightweight Directory Access
569                Protocol (LDAP)", RFC 3383, September 2002.
570
571    [RFC3641]   Legg, S., "Generic String Encoding Rules (GSER) for ASN.1
572                Types", RFC 3641, October 2003.
573
574 Informative References
575
576    [RFC2234]   Crocker, D. and P. Overell, "Augmented BNF for Syntax
577                Specifications: ABNF", RFC 2234, November 1997.
578
579    [RFC3642]   Legg, S., "Common Elements of Generic String Encoding
580                Rules (GSER) Encodings", RFC 3642, October 2003.
581
582    [ASSIGN]    OpenLDAP Foundation, "OpenLDAP OID Delegations",
583                http://www.openldap.org/foundation/oid-delegate.txt
584
585    [PRIVATE]   IANA, "Private Enterprise Numbers",
586                http://www.iana.org/assignments/enterprise-numbers
587
588 Authors' Addresses
589
590    Kurt D. Zeilenga
591    OpenLDAP Foundation
592
593    EMail: Kurt@OpenLDAP.org
594
595
596    Steven Legg
597    Adacel Technologies Ltd.
598    250 Bay Street
599    Brighton, Victoria 3186
600    AUSTRALIA
601
602    Phone: +61 3 8530 7710
603    Fax:   +61 3 8530 7888
604    EMail: steven.legg@adacel.com.au
605
606
607
608
609
610
611
612
613
614
615
616
617
618 Zeilenga & Legg             Standards Track                    [Page 11]
619 \f
620 RFC 3672                   Subentries in LDAP              December 2003
621
622
623 Full Copyright Statement
624
625    Copyright (C) The Internet Society (2003).  All Rights Reserved.
626
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.
640
641    The limited permissions granted above are perpetual and will not be
642    revoked by the Internet Society or its successors or assignees.
643
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.
650
651 Acknowledgement
652
653    Funding for the RFC Editor function is currently provided by the
654    Internet Society.
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674 Zeilenga & Legg             Standards Track                    [Page 12]
675 \f