RFC 3672
Subentries in the Lightweight Directory Access Protocol (LDAP)
Subentries in the Lightweight Directory Access Protocol (LDAP) 🎀
RFC 3672 (part 1 of 2) 💖
okay bestie, so this one's a Standards Track doc from December 2003, written by K. Zeilenga (OpenLDAP Foundation) and S. Legg (Adacel Technologies). its header doesn't list anything it obsoletes or updates, so it's standing on its own 💅
Status of this Memo ✨
this is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🫶 for the current standardization state and status, check the "Internet Official Protocol Standards" (STD 1). distribution of this memo is unlimited.
Copyright Notice 🌸
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract 💜
okay so in X.500 directories, subentries are special entries that hold info for a subtree or subtree refinement. this doc takes those X.500 subentry mechanisms and adapts them for LDAP 🦋
1. Overview ✨
so X.501 describes it like this:
A subentry is a special kind of entry immediately subordinate to an administrative point. It contains attributes that pertain to a subtree (or subtree refinement) associated with its administrative point. The subentries and their administrative point are part of the same naming context. A single subentry may serve all or several aspects of administrative authority. Alternatively, a specific aspect of administrative authority may be handled through one or more of its own subentries.
subentries in LDAP [RFC3377] SHALL behave in accordance with X.501 unless this spec says otherwise 🔥
now the main rule: without the subentries control (more on that in Section 3), subentries SHALL NOT be considered in one-level and subtree scope search operations. for every other operation, including base scope search operations, subentries SHALL be considered. so they're basically hidden from most searches unless you ask for them 👀
1.1. Conventions 🍓
schema definitions use LDAP description formats [RFC2252], and they're line wrapped here so they're easier to read 💅
protocol elements are described with ASN.1 [X.680]. "BER-encoded" means the element gets encoded with the Basic Encoding Rules [X.690], under the restrictions in Section 5.1 of [RFC2251] 🧚
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document get read as described in BCP 14 [RFC2119]. the capital ones are the rules bestie, don't sleep on them 😭
2. Subentry Schema 💖
2.1. Subtree Specification Syntax 🦋
the Subtree Specification syntax is a general purpose way to pick out a subset of entries in a subtree of the Directory Information Tree (DIT) 🌈 a subtree starts at some base entry and includes its subordinates down to some lower boundary, which could go all the way to the leaf entries. a subtree specification is always used inside a context or scope that implicitly sets the subtree's bounds. for example, the scope of a subtree specification for a subschema administrative area doesn't include the subtrees of any subordinate administrative point entries for subschema administration. when a subtree specification doesn't pick out a contiguous subset of entries inside one subtree, the collection gets called a subtree refinement. it's giving precision 💅
this syntax matches the SubtreeSpecification ASN.1 type from [X.501], Section 11.3. it's copied here so you have it all in one place 🫶
SubtreeSpecification ::= SEQUENCE {
base [0] LocalName DEFAULT { },
COMPONENTS OF ChopSpecification,
specificationFilter [4] Refinement OPTIONAL }
LocalName ::= RDNSequence
ChopSpecification ::= SEQUENCE {
specificExclusions [1] SET OF CHOICE {
chopBefore [0] LocalName,
chopAfter [1] LocalName } OPTIONAL,
minimum [2] BaseDistance DEFAULT 0,
maximum [3] BaseDistance OPTIONAL }
BaseDistance ::= INTEGER (0 .. MAX)
Refinement ::= CHOICE {
item [0] OBJECT-CLASS.&id,
and [1] SET OF Refinement,
or [2] SET OF Refinement,
not [3] Refinement }so the components are: base (which names the base entry of the subtree or refinement) and specificExclusions, minimum, maximum, and specificationFilter, which all shrink the set of subordinate entries under the base. the subtree or refinement holds every entry in scope that none of the components exclude. when every component is absent (aka the value is the empty sequence, {}), the subtree implicitly includes every entry in scope. big brain stuff 🧠✨
any particular use of this mechanism MAY impose limitations or constraints on the components of SubtreeSpecification 🎀
the LDAP syntax spec is:
( 1.3.6.1.4.1.1466.115.121.1.45 DESC 'SubtreeSpecification' )LDAP-specific encoding for values of this syntax is defined by the Generic String Encoding Rules [RFC3641]. Appendix A gives an equivalent Augmented Backus-Naur Form (ABNF) [RFC2234] for this syntax 🌸
2.1.1. Base 🍓
the base component of SubtreeSpecification names the base entry of the subtree or refinement. the base entry can be an entry subordinate to the root entry of the scope where the subtree specification is used. in that case, the base component holds a sequence of Relative Distinguished Names (RDNs) relative to the root entry of the scope. or the base can be the root entry of the scope itself (the default). then the base component is absent or holds an empty sequence of RDNs 💅
entries that aren't subordinates of the base entry get excluded from the subtree or refinement. bye bye 👋
2.1.2. Specific Exclusions 🦋
the specificExclusions component of a ChopSpecification is a list of exclusions. each one names entries and their subordinates to leave out of the subtree or refinement 🧚 an entry is named by a sequence of RDNs relative to the base entry (that's a LocalName). every exclusion takes either the chopBefore form or the chopAfter form.
- with chopBefore, the named entry and all its subordinates are excluded.
- with chopAfter, only the subordinates of the named entry are excluded. the named entry itself stays.
the difference is lowkey so important 😭
2.1.3. Minimum and Maximum 🌈
the minimum and maximum components of a ChopSpecification let you exclude entries based on how deep they are in the DIT 🫶
entries with fewer than the minimum number of RDN arcs below the base entry are excluded from the subtree or refinement. a minimum of zero (the default) corresponds to the base entry itself.
entries with more than the maximum number of RDN arcs below the base entry are excluded. if the maximum component is absent, there's no upper limit on the number of RDN arcs below the base entry, so nothing gets cut for being too deep 🍓
2.1.4. Specification Filter 💜
the specificationFilter component is a boolean expression made of assertions about the values of the objectClass attribute of the base entry and its subordinates. a Refinement assertion item evaluates to true for an entry if that entry's objectClass attribute contains the OID named in the assertion. entries where the whole filter evaluates to false get excluded from the subtree refinement. and if the specificationFilter is absent, then no entries get excluded from the subtree or refinement because of their objectClass attribute values ✨
2.2. Administrative Role Attribute Type 💖
the Administrative Model in [X.501], clause 10 says administrative entries MUST... wait, no, it says they require an administrativeRole attribute. that attribute shows the associated administrative area is about one or more administrative roles 🎀
the administrativeRole operational attribute looks like this:
( 2.5.18.5 NAME 'administrativeRole'
EQUALITY objectIdentifierMatch
USAGE directoryOperation
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )the possible values X.501 defines are:
OID NAME
-------- -------------------------------
2.5.23.1 autonomousArea
2.5.23.2 accessControlSpecificArea
2.5.23.3 accessControlInnerArea
2.5.23.4 subschemaAdminSpecificArea
2.5.23.5 collectiveAttributeSpecificArea
2.5.23.6 collectiveAttributeInnerAreaother specs can define other values too. names for each administrative role are Object Identifier Descriptors [RFC3383] 🧚
administrativeRole also controls which subentries are allowed to sit under an administrative entry. a subentry that isn't one of the classes the administrativeRole attribute permits cannot be subordinate to that administrative entry. the gatekeeping is real 🔥
2.3. Subtree Specification Attribute Type 🌸
the subtreeSpecification operational attribute is defined like this:
( 2.5.18.6 NAME 'subtreeSpecification'
SINGLE-VALUE
USAGE directoryOperation
SYNTAX 1.3.6.1.4.1.1466.115.121.1.45 )this attribute is in every subentry. see [X.501], clause 10. its values name collections of entries in the DIT for one or more aspects of administrative authority 🦋
2.4. Subentry Object Class 🌈
the subentry object class is a structural object class 💅
( 2.5.17.0 NAME 'subentry'
SUP top STRUCTURAL
MUST ( cn $ subtreeSpecification ) )(part 1 of 2, more to come 💜)
5.1. Descriptors 💅
okay so IANA already registered all the LDAP descriptors in this spec, and this is the template they suggest for it 🎀
Subject: Request for LDAP Descriptor Registration
Descriptor (short name): see comment
Object Identifier: see comment
Person & email address to contact for further information:
Kurt Zeilenga <kurt@OpenLDAP.org>
Usage: see comment
Specification: RFC3672
Author/Change Controller: IESG
Comments:
NAME Type OID
------------------------ ---- --------
accessControlInnerArea R 2.5.23.3
accessControlSpecificArea R 2.5.23.2
administrativeRole A 2.5.18.5
autonomousArea R 2.5.23.1
collectiveAttributeInnerArea R 2.5.23.6
collectiveAttributeSpecificArea R 2.5.23.5
subentry O 2.5.17.0
subschemaAdminSpecificArea R 2.5.23.4
subtreeSpecification A 2.5.18.6
where Type A is Attribute, Type O is ObjectClass, and Type R is
Administrative Role.Quick decoder for that table: A is Attribute, O is ObjectClass, and R is Administrative Role 🦋
5.2. Object Identifiers 🆔
This doc uses the OID 1.3.6.1.4.1.4203.1.10.1 to identify an LDAP protocol element defined in it ✨ That OID was assigned [ASSIGN] by the OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], just for this spec.
Other OIDs that show up here were either assigned by the ISO/IEC Joint Technical Committee 1 - Subcommittee 6 to identify elements of X.500 schema, or assigned in RFC 2252 for the way they're used here 🌸
5.3. Protocol Mechanisms 🧚
IANA has also registered the LDAP protocol mechanisms [RFC3383] detailed in this spec. Here's the template for that one:
Subject: Request for LDAP Protocol Mechanism Registration
Description: Subentries
Person & email address to contact for further information:
Kurt Zeilenga <kurt@openldap.org>
Usage: Control
Specification: RFC3672
Author/Change Controller: IESG
Comments: none6. Acknowledgment ✨
This doc is based on engineering done by the IETF LDUP and LDAPext Working Groups, including "LDAP Subentry Schema" by Ed Reed. It also borrows from a bunch of ITU documents, including X.501. Thank you, legends 🫶
7. Intellectual Property Statement 🔒
Okay, the IETF is not picking a side here. It takes no position on whether any intellectual property or other rights someone claims about the tech in this doc are valid or in scope, or whether a license for those rights is available (or not). It also doesn't claim to have tried to find any of those rights 🙈
If you want the IETF's rules on rights for standards-track and standards-related docs, check out BCP-11. Claims of rights that were filed for publication, any promised licenses, and the results of anyone trying to get a general license for implementers or users of this spec can all be requested from the IETF Secretariat 💼
The IETF also invites anyone to flag any copyrights, patents, patent applications, or other proprietary rights that might cover tech needed to practice this standard. Send that info to the IETF Executive Director 📮
A. Subtree Specification ABNF 📜
This appendix is non-normative. Don't worry, it's just here as a handy cheat sheet 💖
The LDAP-specific string encoding for the Subtree Specification syntax is specified by the Generic String Encoding Rules [RFC3641]. The ABNF [RFC2234] in this appendix is only a convenience, and it's equivalent to the encoding you get from applying [RFC3641]. The SubtreeSpecification ASN.1 type might get extended in future editions of [X.501], so treat this ABNF as a snapshot in time. If you need the LDAP-specific encoding for any extension, [RFC3641] is where to look ✨
If this ABNF and the encoding from [RFC3641] ever disagree, [RFC3641] wins. It's the final word 👑
SubtreeSpecification = "{" [ sp ss-base ]
[ sep sp ss-specificExclusions ]
[ sep sp ss-minimum ]
[ sep sp ss-maximum ]
[ sep sp ss-specificationFilter ]
sp "}"
ss-base = id-base msp LocalName
ss-specificExclusions = id-specificExclusions msp
SpecificExclusions
ss-minimum = id-minimum msp BaseDistance
ss-maximum = id-maximum msp BaseDistance
ss-specificationFilter = id-specificationFilter msp Refinement
id-base = %x62.61.73.65 ; "base"
id-specificExclusions = %x73.70.65.63.69.66.69.63.45.78.63.6C.75.73
%x69.6F.6E.73 ; "specificExclusions"
id-minimum = %x6D.69.6E.69.6D.75.6D ; "minimum"
id-maximum = %x6D.61.78.69.6D.75.6D ; "maximum"
id-specificationFilter = %x73.70.65.63.69.66.69.63.61.74.69.6F.6E.46
%x69.6C.74.65.72 ; "specificationFilter"
SpecificExclusions = "{" [ sp SpecificExclusion
*( "," sp SpecificExclusion ) ] sp "}"
SpecificExclusion = chopBefore / chopAfter
chopBefore = id-chopBefore ":" LocalName
chopAfter = id-chopAfter ":" LocalName
id-chopBefore = %x63.68.6F.70.42.65.66.6F.72.65 ; "chopBefore"
id-chopAfter = %x63.68.6F.70.41.66.74.65.72 ; "chopAfter"
Refinement = item / and / or / not
item = id-item ":" OBJECT-IDENTIFIER
and = id-and ":" Refinements
or = id-or ":" Refinements
not = id-not ":" Refinement
Refinements = "{" [ sp Refinement
*( "," sp Refinement ) ] sp "}"
id-item = %x69.74.65.6D ; "item"
id-and = %x61.6E.64 ; "and"
id-or = %x6F.72 ; "or"
id-not = %x6E.6F.74 ; "not"
BaseDistance = INTEGER-0-MAXThe <sp>, <msp>, <sep>, <INTEGER>, <INTEGER-0-MAX>, <OBJECT-IDENTIFIER> and <LocalName> rules are defined in [RFC3642]. Bookmark that one 🧁
Normative References 📚
[X.501] ITU-T, "The Directory -- Models," X.501, 1993.
[X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) -
Specification of Basic Notation", X.680, 1994.
[X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic,
Canonical, and Distinguished Encoding Rules", X.690,
1994.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
Access Protocol (v3)", RFC 2251, December 1997.
[RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille,
"Lightweight Directory Access Protocol (v3): Attribute
Syntax Definitions", RFC 2252, December 1997.
[RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
"Authentication Methods for LDAP", RFC 2829, May 2000.
[RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight
Directory Access Protocol (v3): Extension for Transport
Layer Security", RFC 2830, May 2000.
[RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
Protocol (v3): Technical Specification", RFC 3377,
September 2002.
[RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
Considerations for the Lightweight Directory Access
Protocol (LDAP)", RFC 3383, September 2002.
[RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1
Types", RFC 3641, October 2003.Informative References 🌈
[RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[RFC3642] Legg, S., "Common Elements of Generic String Encoding
Rules (GSER) Encodings", RFC 3642, October 2003.
[ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
http://www.openldap.org/foundation/oid-delegate.txt
[PRIVATE] IANA, "Private Enterprise Numbers",
http://www.iana.org/assignments/enterprise-numbersAuthors' Addresses 💌
Kurt D. Zeilenga
OpenLDAP Foundation
EMail: Kurt@OpenLDAP.org
Steven Legg
Adacel Technologies Ltd.
250 Bay Street
Brighton, Victoria 3186
AUSTRALIA
Phone: +61 3 8530 7710
Fax: +61 3 8530 7888
EMail: steven.legg@adacel.com.auFull Copyright Statement ⚖️
The legal text below is kept word for word on purpose, so nothing about the permissions or disclaimers changes 🔐
Copyright (C) The Internet Society (2003). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.Acknowledgement 💖
Funding for the RFC Editor function is currently provided by the Internet Society. And that's the whole thing, bestie 🎀✨
📦 where this page comes from
- ietf: rfc3672 2003-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms