]> git.sur5r.net Git - openldap/blob - doc/drafts/draft-zeilenga-ldap-subentry-xx.txt
no functional change
[openldap] / doc / drafts / draft-zeilenga-ldap-subentry-xx.txt
1
2
3
4
5
6
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
11
12
13                             Subentries in LDAP
14                   <draft-zeilenga-ldap-subentry-05.txt>
15
16
17 Status of this Memo
18
19   This document is an Internet-Draft and is in full conformance with all
20   provisions of Section 10 of RFC2026.
21
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>.
28
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.''
36
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>.
41
42   Copyright 2002, The Internet Society.  All Rights Reserved.
43
44   Please see the Copyright section near the end of this document for
45   more information.
46
47
48 Abstract
49
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).
54
55
56
57
58 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 1]
59 \f
60 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
61
62
63 Conventions
64
65   Schema definitions are provided using LDAP description formats
66   [RFC2252].  Definitions provided here are formatted (line wrapped) for
67   readability.
68
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
72   of [RFC2251].
73
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].
77
78
79 1. Overview
80
81   From [X.501]:
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.
87
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
91       own subentries.
92
93   Subentries in Lightweight Directory Access Protocol (LDAP) [LDAPTS]
94   SHALL behave in accordance with X.501 unless noted otherwise in this
95   specification.
96
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.
101
102
103 2. Subentry Schema
104
105 2.1. Subtree Specification Syntax
106
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
111
112
113
114 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 2]
115 \f
116 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
117
118
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.
127
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.
131
132     SubtreeSpecification ::= SEQUENCE {
133         base                [0] LocalName DEFAULT { },
134                                 COMPONENTS OF ChopSpecification,
135         specificationFilter [4] Refinement OPTIONAL }
136
137
138     LocalName ::= RDNSequence
139
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}
146
147     BaseDistance ::= INTEGER (0 .. MAX)
148
149     Refinement ::= CHOICE {
150         item                [0] OBJECT-CLASS.&id,
151         and                 [1] SET OF Refinement,
152         or                  [2] SET OF Refinement,
153         not                 [3] Refinement }
154
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.
165
166   Any particular use of this mechanism MAY impose limitations or
167
168
169
170 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 3]
171 \f
172 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
173
174
175   constraints on the components of SubtreeSpecification.
176
177   The LDAP syntax specification is:
178
179       ( 1.3.6.1.4.1.1466.115.121.1.45 DESC 'SubtreeSpecification' )
180
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.
184
185
186 2.1.1. Base
187
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
195   RDNs.
196
197   Entries that are not subordinates of the base entry are excluded from
198   the subtree or subtree refinement.
199
200
201 2.1.2. Specific Exclusions
202
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.
212
213
214 2.1.3. Minimum and Maximum
215
216   The minimum and maximum components of a ChopSpecification allow the
217   exclusion of entries based on their depth in the DIT.
218
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.
222
223
224
225
226 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 4]
227 \f
228 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
229
230
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
235   subtree refinement.
236
237 2.1.4. Specification Filter
238
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
247   values.
248
249
250 2.2. Administrative Role Attribute Type
251
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.
256
257   The administrativeRole operational attribute is specified as follows:
258
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 )
263
264   The possible values of this attribute defined in X.501 are:
265
266        OID            NAME
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
274
275   Other values may be defined in other specifications.  Names associated
276   with each administrative role are Object Identifier Descriptors
277   [LDAPIANA].
278
279
280
281
282 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 5]
283 \f
284 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
285
286
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.
291
292
293 2.3. Subtree Specification Attribute Type
294
295   The subtreeSpecification operational attribute is defined as follows:
296
297       ( 2.5.18.6 NAME 'subtreeSpecification'
298           SINGLE-VALUE
299           USAGE directoryOperation
300           SYNTAX 1.3.6.1.4.1.1466.115.121.1.45 )
301
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
305   authority.
306
307
308 2.4. Subentry Object Class
309
310   The subentry object class is a structural object class.
311
312       ( 2.5.20.0 NAME 'subentry'
313           SUP top STRUCTURAL
314           MUST ( cn $ subtreeSpecification ) )
315
316
317 3. Subentries Control
318
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
322   request.
323
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
330   are not.
331
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 }.
334
335
336
337
338 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 6]
339 \f
340 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
341
342
343   The controlValue SHALL NOT be absent.
344
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.
348
349   There is no corresponding response control.
350
351   This control is not appropriate for non-Search operations.
352
353
354 4. Security Considerations
355
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].
359
360   General LDAP [LDAPTS] security considerations also apply.
361
362
363 5. IANA Considerations
364
365 5.1 Descriptors
366
367   It is requested that IANA register the LDAP descriptors used in this
368   document per the following registration template:
369
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>
375       Usage: see comment
376       Specification: RFCXXXX
377       Author/Change Controller: IESG
378       Comments:
379
380         NAME                            Type OID
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
388         subentry                        O    2.5.20.0
389         subschemaAdminSpecificArea      R    2.5.23.4
390         subtreeSpecification            A    2.5.18.6
391
392
393
394 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 7]
395 \f
396 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
397
398
399       where Type A is Attribute, Type O is ObjectClass, and Type R is
400       Administrative Role.
401
402
403 5.2 Object Identifiers
404
405   No IANA assignment of object identifiers is requested.
406
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.
411
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
415   here.
416
417
418 6. Acknowledgment
419
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.
423
424
425 7. Authors' Addresses
426
427   Kurt D. Zeilenga
428   OpenLDAP Foundation
429
430   Email: Kurt@OpenLDAP.org
431
432   Steven Legg
433   Adacel Technologies Ltd.
434   405-409 Ferntree Gully Road
435   Mount Waverley, Victoria 3149
436   AUSTRALIA
437
438   Phone: +61 3 9451 2107
439     Fax: +61 3 9541 2121
440   EMail: steven.legg@adacel.com.au
441
442
443 8. Normative References
444
445   [X.501]     ITU-T, "The Directory -- Models," X.501, 1993.
446
447
448
449
450 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 8]
451 \f
452 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
453
454
455   [X.680]     ITU-T, "Abstract Syntax Notation One (ASN.1) -
456               Specification of Basic Notation", X.680, 1994.
457
458   [X.690]     ITU-T, "Specification of ASN.1 encoding rules:  Basic,
459               Canonical, and Distinguished Encoding Rules", X.690, 1994.
460
461   [RFC2119]   S. Bradner, "Key words for use in RFCs to Indicate
462               Requirement Levels", BCP 14 (was RFC 2119), March 1997.
463
464   [RFC2251]   M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
465               Protocol (v3)", RFC 2251, December 1997.
466
467   [RFC2252]   M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
468               Directory Access Protocol (v3):  Attribute Syntax
469               Definitions", RFC 2252, December 1997.
470
471   [RFC2829]   M. Wahl, H. Alvestrand, J. Hodges, R. Morgan,
472               "Authentication Methods for LDAP", RFC 2829, May 2000
473
474   [RFC2830]   J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory
475               Access Protocol (v3): Extension for Transport Layer
476               Security", RFC 2830, May 2000.
477
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.
481
482   [GSER] S. Legg, "Generic String Encoding Rules for ASN.1 Types",
483               draft-legg-ldapext-gser--xx.txt, a work in progress.
484
485   [LDAPIANA]  K. Zeilenga, "IANA Considerations for LDAP", draft-ietf-
486               ldapbis-iana-xx.txt, a work in progress.
487
488
489 9. Informative References
490
491   [RFC2234]   D. Crocker, P. Overell, "Augmented BNF for Syntax
492               Specifications: ABNF", RFC 2234, November 1997.
493
494   [GCE]       S. Legg, "Common Elements of GSER Encodings",
495               draft-legg-ldap-gser-abnf-xx.txt, a work in progress.
496
497   [ASSIGN]   OpenLDAP Foundation, "OpenLDAP OID Delegations",
498               http://www.openldap.org/foundation/oid-delegate.txt.
499
500   [PRIVATE]  IANA, "Private Enterprise Numbers",
501               http://www.iana.org/assignments/enterprise-numbers.
502
503
504
505
506 Zeilenga             draft-zeilenga-ldap-subentry-05            [Page 9]
507 \f
508 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
509
510
511 A. Subtree Specification ABNF
512
513   This appendix is non-normative.
514
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
523   from [GSER].
524
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.
527
528     SubtreeSpecification = "{"    [ sp base ]
529                               [ sep sp specificExclusions ]
530                               [ sep sp minimum ]
531                               [ sep sp maximum ]
532                               [ sep sp specificationFilter ]
533                                     sp "}"
534
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
540
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"
548
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"
556
557     Refinement  = item / and / or / not
558     item        = id-item ":" OBJECT-IDENTIFIER
559
560
561
562 Zeilenga             draft-zeilenga-ldap-subentry-05           [Page 10]
563 \f
564 INTERNET-DRAFT             Subentries in LDAP                17 May 2002
565
566
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"
576
577     BaseDistance = INTEGER
578
579   The <sp>, <msp>, <sep>, <INTEGER>, <OBJECT-IDENTIFIER> and <LocalName>
580   rules are defined in [GCE].
581
582
583 Copyright 2002, The Internet Society.  All Rights Reserved.
584
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.
597
598   The limited permissions granted above are perpetual and will not be
599   revoked by the Internet Society or its successors or assigns.
600
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.
607
608
609
610
611
612
613
614
615
616
617
618 Zeilenga             draft-zeilenga-ldap-subentry-05           [Page 11]
619 \f