Internet-Draft D.W.Chadwick LDAP Extensions WG University of Salford Intended Category: Standards Track Expires: 5 December 1999 5 June, 1999 Compound (Families of) Entries STATUS OF THIS MEMO This document is an Internet-Draft and is in full conformance with all the provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft expires on December 5, 1999. Comments and suggestions on this document are encouraged. Comments on this document should be sent to the LDAPEXT working group discussion list: ietf-ldapext@netscape.com or directly to the author. ABSTRACT This document describes protocol support, in the form of LDAP controls, for compound entries. A compound entry logically allows collections of attributes to be grouped together as though they were present in the single compound entry, whereas in fact they are held in a hierarchical set of entries beneath the compound entry. The LDAP controls allow the user to treat a compound entry as either separate entries or as a single compound entry when both searching, retrieving and deleting information from the DIT. Compound entries are briefly described here and a full description of them can be found in the draft version of X.500 (2000)[FPDAM]. 1. Introduction A deficiency in the original X.500(88) information model [X.500(88)] only allows the grouping of related information in an entry if the group of attributes are single valued, but it does not allow the grouping of related information if the group of attributes are multi- valued. This is because there is no way of tagging individual attribute values to indicate in which group they belong. X.500(93) [X.500(93)] solved this problem, but only in a limited way, for administrative information. The X.500(93) standard invented subentries in order to group together the attribute values attached to a subtree specification. Each subtree specification is then held in a different subentry so that the group of attributes applying to it is clearly identified. LDAP has adopted the concept of subentries, albeit in a modified form, and uses them for storing subschema information [LDAP syntax] and replication information [LDUP]. However the LDUP group have extended the original subentry concept to fit their specific needs, e.g. by allowing subentries to have children. This paper describes a general model for grouping together related information, using a concept similar to subentries, but it is more general and richer than subentries. It is believed that this model will be general enough to cater for most, if not all, the current and future needs of the LDAP (including LDUP) and X.500 communities. The concept is termed a Compound Entry, and a compound entry is made up of a hierarchical set of entries. Each child entry holds a group of related attributes that logically belong to or describe the parent entry. A child entry is similar to an existing subentry (both the LDAP and X.500 variants). However, the model is richer than that of the existing subentries, in that any entry can have a child entry (not just an administrative point or naming context entries) and it is recursive i.e. child entries can themselves have child entries. It can be seen that "A hierarchy of entries . that describe a Naming Context, its Replicas, and its Replication Agreements" is one example of a compound entry. The text in quotes is copied from [LDUP]. Protocol support is defined to allow the user (either an administrative user or a regular user) to decide, on a per operation basis, whether some or all of the entries in a compound entry should be treated as one combined entry, or as separate entries. 2. A Brief Introduction to the Model of Compound Entries A compound entry comprises a hierarchical set of entries. Within a compound entry, each superior entry is of object class "parent" and each subordinate entry is of object class "child". The root of a compound entry is termed the ancestor, and this is the only entry of object class parent and not of child. Leaf entries below an ancestor are the only entries of object class child and not of parent. All the remaining entries are of object class parent and child. Parent and child object classes do not define the contents of an entry. They merely indicate that this entry is part of a compound entry. Entry contents are controlled in the usual way using object classes and DIT content rules. Compound entries can be user entries (e.g. to store PGP keys) or administrative entries (e.g. to store replication agreements). The structural object class of each child immediately subordinate to the ancestor is used to indicate the family to which the child and all its subordinates belong. Thus an ancestor could have a family of PGPkey entries and a family of POP3 mail address entries beneath it. The multiple family concept allows the grouping together of fundamentally different types of attributes to be clearly differentiated within a compound entry. Within a compound entry, a path from a leaf entry to the ancestor is termed a strand. Each family member will reside in as many strands as there are leaf family members below it (as immediate or non-immediate subordinates). Strands are used as one way of grouping together entries in a compound entry, prior to operation evaluation. 3. Protocol Support for Compound Entries There are three aspects of adding protocol support to LDAP for compound entries. The first is to indicate whether a compound entry should be treated as separate entries or as one or more groups of entries prior to operation evaluation. This argument, termed FamilyGrouping, forms one LDAP control, and is described in section 4. It applies only to the Search, Compare and RemoveEntry operations. The second defines which members of a compound entry should be returned if one or more family members have been selected by the operation, and, if more than one, whether the entries should be returned separately or not. This argument, termed FamilyReturn, forms a second LDAP control, and is described in section 5. It applies only to the Search operation. A new attribute that allows a compound entry to be bundled together and returned as a single entry is also described. The third task is to define a new result codes that returns an error diagnostic when the user erroneously tries to delete (part of) a family of entries. This is described in section 6. Child entries are created using the AddEntry operation, and modified using the ModifyEntry operation, just like other entries in the DIT. No special protocol support is needed for this. 4 The Family Grouping Control Family grouping allows a single entry, several entries or all entries from a compound entry to be grouped together for joint consideration prior to operation evaluation. Family grouping can be applied to the following operations: Compare - defines the scope within which the compared attribute might lie, Search - defines the groupings on which filtering can take place, RemoveEntry - defines the groupings for removal. The Family Grouping control may be critical or non-critical as determined by the user, except for the RemoveEntry operation when it is always critical. The object identifier for this control is 1.2.826.0.1.3344810.2.0 The value for this control is FamilyGrouping. An absent value implies entryOnly. The following ASN.1 is used to group together members of a compound entry: FamilyGrouping ::= ENUMERATED { entryOnly, (1), compoundEntry (2), strands, (3), multiStrand (4) } entryOnly means that grouping of entries must not take place, and that family member are to considered as separate entries. This is the default value, and ensures backwards compatibility with previous editions of the LDAP standard. compoundEntry means that the complete compound entry is to be considered as a group. For Search and Compare, the base object/entry can refer to any family member in order for the whole compound entry to be grouped together. For Remove-entry operations, it is only applicable when the object name specified is that of an ancestor of a compound entry, and this causes all family members to be removed by the one operation (subject to access control). strands means that all the strands associated with the family member specified by the operation, are to be grouped together in some way. This option is not valid for Remove-entry operations. multiStrand is only applicable to the Search operation. MulitStrand is ignored for other operations. The base object of the Search operation must be the ancestor or higher in the DIT, otherwise this option is ignored. A combination of one strand from each family within a compound entry is grouped together for the purpose of matching. All combinations are to be considered one at a time. 4.1 Use in the Compare Operation For the Compare operation all the attributes in all the family members grouped together by the Family Grouping control are to be compared against the attribute value assertion argument of the Compare operation. 4.2 Use in the RemoveEntry Operation For the RemoveEntry operation all the entries grouped together by the Family Grouping control shall be removed, or none shall be removed and the operation shall fail. The values of FamilySelection shall have the following effect: entryOnly is the default for this operation, and the entry to be removed must be a leaf entry. compoundEntry may be specified for a family member that is an ancestor. All the members of the compound entry will be removed (subject to access control), or none will be. The operation will fail with result code notAncestor if the target object is not an ancestor. strands and multiStrand are not valid for this operation and will be ignored if chosen. 4.3 Use in the Search Operation For the Search operation, each family member within the scope of the Search operation is conceptually merged with other family members, prior to the operation of the filter, to form a group of entries as directed by the Family Grouping control. entryOnly means that each family member forms a separate group. This is the default value, and ensures backwards compatibility with previous editions of the standard. compoundEntry means that all the entries from the compound entry are logically merged together into one big group before applying the filter. strands means that individual strands are considered as separate groups for matching purposes. multiStrand requires that one strand from each family within the compound entry are grouped together for the purpose of matching. Groups must be made from all combinations of family single strands. If a group of entries matches the filter, then each entry in the group is marked as a participating entry. Those entries that directly matched one or more filter items are marked as contributing entries. 5 The FamilyReturn Control This control is only applicable to the Search operation. The family return control is always non-critical. The object identifier for this control is 1.2.826.0.1.3344810.2.1 The value for this control is FamilyReturn. The following ASN.1 defines the family return control: FamilyReturn ::= SEQUENCE { separateFamilyMembers BOOLEAN DEFAULT TRUE, whichEntries ENUMERATED { contributingEntriesOnly (1), participatingEntriesOnly (2), compoundEntry (3) } DEFAULT contributingEntriesOnly } separateFamilyMembers specifies if the family members shall be returned as separate entries in the Search Result (the default) or if they should be packed into the familyInformation derived attribute as described in 5.1. whichEntries specifies which entries should be added to the Search result. If contributingEntriesOnly is specified then only the entries marked as contributing should be added. If participatingEntriesOnly is selected, then only the entries marked contributing should be added to the Search result. If compoundEntry is specified then every family member shall be added to the Search result. If the FamilyReturn control is not present in a Search request then the entries that contributed to the filter match will be returned as separate entries, maintaining backwards compatibility with LDAPv3. 5.1 Family Information derived attribute The family-information attribute is defined in X.500 [FPDAM] and is duplicated here for completeness sake. This attribute is a derived attribute, in that it does not actually exist in any entry. Rather it is a convenient way of packaging together multiple subordinate entries of a parent and returning them in a single attribute of the parent. This can help the client when it is displaying a compound entry. family-information ATTRIBUTE ::= { WITH SYNTAX FamilyEntries USAGE directoryOperation ID id-at-family-information } FamilyEntries ::= SEQUENCE { family-class OBJECT-CLASS.&id, -- structural object class value familyEntries SET OF FamilyEntry } FamilyEntry ::= SEQUENCE { rdn RelativeDistinguishedName, information SET OF CHOICE { attributeType AttributeType, attribute Attribute }, family-info SET OF FamilyEntries OPTIONAL} 6 New Result Codes Add the following new result code to the LDAPv3 protocol [LDAPv3]: notAncestor (72), -- An operation attempted to delete an extended family without specifying the ancestor as the object -- 7 Security Considerations The access controls that govern the processing of LDAP operations on family members will need to be specified by each specific access control scheme that is implemented. The current proposal for the X.500 standard access control scheme [X.500(97)] is as follows. Family members may contain their own EntryACI in the same way as any other entry in the DIT. Family members may be controlled by PrescriptiveACI in the same way as any other entry in the DIT. All the entries in a compound entry may have the same prescriptive access controls applied to them in the following way: family members may inherit the access controls from their ancestor via a new boolean, includeFamilies, in protectedItems, viz: includeFamilies [13] BOOLEAN DEFAULT TRUE } In addition, an ancestor may be given access rights to each family member by updating the semantics of the thisEntry userClass to read: thisEntry means the user with the same distinguished name as the entry being accessed, or if the entry is a member of a family, then additionally the user with the distinguished name of the ancestor. 8 Copyright Copyright (C) The Internet Society (date). 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 assigns. 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. 9 Bibliography [FPDAM] PDAMs to ISO/IEC 9594 Parts 1, 2, 3, 4, 5, 6, 7 and 9 to support the ITU-T Rec. F.510 "Automated Directory Assistance, White Pages Service Definitions", Source: Collaborative ITU-T/SG7/Q15 and JTC1/SC6/WG7 OSI Directory Meeting, April 7-15, Orlando, USA. [LDAPv3] Kille, S., Wahl, M., and Howes, T. "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [LDAP Syntax] Wahl, M., Coulbeck, A., Kille, S., and Howes, T. Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2251, December 1997. [LDUP] Merrells, J.,Reed, E., Srinivasan, U. "LDAP Replication Architecture", , April 1999. [X.500(88)] CCITT Rec. X.501, "The Directory: Models", 1988. [X.500(93)] ITU-T Rec. X.501, "The Directory: Models", 1993. [X.500(97)] ITU-T Rec. X.501, "The Directory: Models", 1997. 10 Authors Address David Chadwick IS Institute University of Salford Salford England M5 4WT Email: d.w.chadwick@iti.salford.ac.uk 11 Expiry Date This document expires: 21 June 1999 Appendix 1. Model of Compound Entries [Editor's Note. All the text in Appendix 1 is copied from the final PDAM [FPDAM] to X.500(97) [X.500(97)], and the final text will form part of the X.500(2000) standard. It is proposed to directly reference the X.500 standard once is it finalised and to remove this text from the final Internet RFC] A.1 Definitions compound entry: a representation of an object in terms of family members that are hierarchically organised into one or more families of entries. family member: a member of a hierarchical collection of entries that comprise a compound entry. ancestor: the entry at the root of the hierarchy of family members that comprise a compound entry. family: a hierarchical subset of family member entries that represents a particular class of information within a compound entry. The root of each family within a compound entry is the ancestor, but apart from the shared root, families do not share common members. A family is distinguished from other families within a compound entry by having a common class (structural object class) for each family member that is immediately subordinate to the ancestor. strand - the set of entries from a compound entry comprising all the entries in a path from a leaf family member up to the ancestor inclusive, in which the selected family member resides. A selected family member will reside in as many strands as there are leaf family members below it (as immediate or non-immediate subordinates). A.2 Information Model A compound entry is a special entry containing subordinate family member entries that contain hierarchically organised information about the object corresponding to the compound entry. The compound entry is represented in the DIT by an ancestor family member, which is at the top of a tree containing other family members. Family members can themselves be organised into one or more families for the purposes of filtering and information retrieval. Each family is a subtree; distinct families have no common family members apart from the shared root that is the ancestor. A family thus comprises an ancestor plus a set of subordinate family members. The class of the family is the common structural object class of each of the component family members that lie immediately subordinate to the ancestor. If two family members that are immediately subordinate to the ancestor have structural object classes A and B, the two family members, together with their subordinate family members, belong to the same family if and only if A and B are the same. A family member that is a child within a family tree is marked with the auxiliary object class child. The presence of the child object class value for an entry causes the immediately superior entry automatically to be marked with the abstract object class value parent. An entry that is both a parent and a child within a family tree is marked with both object class values. The ancestor is the only family member not of object class child. The construction of compound entries is carried out by marking entries with child object class values. Each subordinate of a non-ancestor family member must itself be a family member, and marked with a child object class value. Thus, a user or administrator can only cause a leaf entry to be marked with a child object class value; additionally, subordinates of family members cannot have the child object class value removed. The ASN.1 definition of these object classes can be found in section A.3. All family members of a compound entry must be placed in the same naming context as the ancestor. Family members are not permitted to be alias entries. A.3 Object Class Definitions parent OBJECT-CLASS ::= { KIND abstract ID id-oc-parent } child OBJECT-CLASS ::= { KIND auxiliary ID id-oc-child } NOTES 1 - The object classes parent and child do not specify any appropriate attribute types for the RDNs of family entries. This will be done in the normal way via the appropriate structural object classes and name forms for these entries. 2 - The parent and child object classes may not be combined with the alias object class to form an alias entry. 3 - The parent object class is derived by the presence of an immediately subordinate family member, marked by the presence of a child object class value. It may not be directly administered. The child object class value may only be added or removed when the result is consistent with the architecture of compound entries (e.g. the subordinates of family members must always have a child object class). Internet-Draft Compound ( Families of) Entries 5 June 1999 Chadwick [Page 6]