1 2 3 4 5 6 7Network Working Group K. Zeilenga 8Request for Comments: 3672 OpenLDAP Foundation 9Category: Standards Track S. Legg 10 Adacel Technologies 11 December 2003 12 13 14 Subentries in the Lightweight Directory Access Protocol (LDAP) 15 16Status of this Memo 17 18 This document specifies an Internet standards track protocol for the 19 Internet community, and requests discussion and suggestions for 20 improvements. Please refer to the current edition of the "Internet 21 Official Protocol Standards" (STD 1) for the standardization state 22 and status of this protocol. Distribution of this memo is unlimited. 23 24Copyright Notice 25 26 Copyright (C) The Internet Society (2003). All Rights Reserved. 27 28Abstract 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 351. 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 58Zeilenga & Legg Standards Track [Page 1] 59 60RFC 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 681.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 832. Subentry Schema 84 852.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 114Zeilenga & Legg Standards Track [Page 2] 115 116RFC 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 1572.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 170Zeilenga & Legg Standards Track [Page 3] 171 172RFC 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 1782.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 1902.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 2052.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 226Zeilenga & Legg Standards Track [Page 4] 227 228RFC 3672 Subentries in LDAP December 2003 229 230 2312.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 2652.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 282Zeilenga & Legg Standards Track [Page 5] 283 284RFC 3672 Subentries in LDAP December 2003 285 286 2872.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 2953. 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 3234. 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 338Zeilenga & Legg Standards Track [Page 6] 339 340RFC 3672 Subentries in LDAP December 2003 341 342 3435. IANA Considerations 344 3455.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 3765.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 394Zeilenga & Legg Standards Track [Page 7] 395 396RFC 3672 Subentries in LDAP December 2003 397 398 3995.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 4196. 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 4257. 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 450Zeilenga & Legg Standards Track [Page 8] 451 452RFC 3672 Subentries in LDAP December 2003 453 454 455A. 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 506Zeilenga & Legg Standards Track [Page 9] 507 508RFC 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 528Normative 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 562Zeilenga & Legg Standards Track [Page 10] 563 564RFC 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 574Informative 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 588Authors' 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 618Zeilenga & Legg Standards Track [Page 11] 619 620RFC 3672 Subentries in LDAP December 2003 621 622 623Full 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 651Acknowledgement 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 674Zeilenga & Legg Standards Track [Page 12] 675 676