Internet-Draft D.W.Chadwick LDAP Extensions WG University of Salford Intended Category: Standards Track Expires: 21 June 1999 21 December 1998 Families of Entries STATUS OF THIS MEMO This document is an Internet Draft. 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. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a "working draft" or "work in progress." To learn the current status of any Internet-Draft, please check the 1id-abstracts.txt listing contained in the Internet-Drafts Shadow Directories on ftp.ietf.org, nic.nordu.net, ftp.isi.edu, or munnari.oz.au. 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 ABSTRACT This document describes a model for grouping together collections of attributes into families of entries, for directory servers that follow the X.500 and LDAP information models. This document also describes protocol support, in the form of LDAP controls, that allows the user to treat a family of entries as either separate entries or as a combined entry when both searching, retrieving and deleting information from the DIT. 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. 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. The concept is a Family of Entries, where each child entry holds related information pertaining to that of its parent. A child entry is similar to an existing subentry. But the model is richer than that of subentries, in that any entry can have a child entry (not just an administrative point) and it is recursive i.e. child entries can themselves have child entries. Protocol support is defined to allow the user to decide, on a per operation basis, whether some or all of the entries in a family should be treated as one compound entry, or as separate entries. 2. Model of Families of Entries [Editor's Note. All the text in Section 2 is copied from the PDAM [PDAM] 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] 2.1 Definitions family (of entries): a subtree of entries in the DIT that holds information that is in some way related to the ancestor. ancestor (of a family): the entry at the root of a family of entries 2.2 Information Model A family of entries is a subtree of entries in the DIT. The members of the family collectively comprise a family tree within the DIT. The entry at the root of the family tree is termed the ancestor of the family. A family is characterised by all the members holding information relating either directly or indirectly to the ancestor. Families may be specially treated by the user when performing operations on the Directory. For example, the user may decide which family members should be logically merged together during the filtering stage of a search operation, and/or which family members should be returned if one of them has been selected. The standard object class and DIT content rules regulate the contents of each entry within a family tree. The standard name forms and DIT structure rules regulate the naming of each entry within a family tree. A family member that is a parent within the family tree is marked with the abstract object class parent. A family member that is a child within a family tree is marked with the abstract object class child. An entry that is both a parent and a child within a family tree is marked with both object classes. The Directory knows about the object classes child and parent and uses this information to determine family membership. The ASN.1 definitions of these object classes can be found in section 2.3. The ancestor is the only family member not of object class child. Each child entry must have a parent entry. Each parent entry must have at least one child entry. [Editor's note. This means that when the first child is created the server needs to mark the superior entry as object class parent, and when the last child is deleted, remove this object class. Is this the best way to implement this, or should we allow parents to have no children?] Every entry of object class child shall only have subordinates of object class child (at least). NOTE. This prevents entries that are not part of a family from appearing in the family tree. The ancestor is the only entry in a family tree that may have subordinates that are not of object class child. This allows family trees to be added below existing entries anywhere in the DIT. In the simplest case a family will consist of a parent and one or more children. In a more complex family, there will be grandparents, uncles, nieces, etc. although not all of these family members may be identified. 2.3 Object Class Definitions parent OBJECT-CLASS ::= { KIND abstract ID id-oc-parent } Child OBJECT-CLASS ::= { KIND abstract ID id-oc-child } NOTE - 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. 3. Protocol Support for Families There are three aspects of adding protocol support to LDAP for families of entries. The first is to indicate whether family members should be treated as separate entries or should be grouped together into one or more compound entries prior to operation evaluation. This argument, termed FamilyGrouping, forms one LDAP control, and is described in section 4. The second, which is only applicable to the Search operation, defines which members of a family should be returned if one or more family members have been selected by the act of filtering. This argument, termed FamilyReturn, forms a second LDAP control, and is described in section 5. The third task is to define two new result codes that return an error diagnostic when the user erroneously tries to delete (part of) a family of entries. These are described in section 6. 3.1 Family Selection The following ASN.1 construct forms the basic data structure used by both the FamilyGrouping and FamilyReturn LDAP controls. FamilySelection ::= ENUMERATED { entryOnly (1) , entry&parent (2), upToAncestor (3), nuclearFamily (4), entry&subtree (5), extendedFamily (6) } entryOnly means that only the family member itself is to be selected. This is the default value, and ensures backwards compatibility with previous editions of the standard. entry&parent means that the family member and its immediate parent are to be selected. upToAncestor means that the family member and all its parents up to the ancestor are to be selected. nuclearFamily means that the family member and all its immediate children are to be selected. entry&subtree means that the family member and all its children, grandchildren, and great-grandchildren etc. down to the leaves are to be selected. extendedFamily means that the entire family of the family member selected is to be selected. An example of family selection is depicted pictorially below: / A / \ B C / \ \ D E F / | \ / \ G H I J K / \ K L Suppose A is the ancestor of a large extended family comprising entries A,B,...L. Suppose that entry D is the target entry of a particular operation. The following are the family members that are selected by the various enumerated options of FamilySelection: entryOnly - D entry&parent - D and B upToAncestor - D, B and A nuclearFamily - D, G, H and I entry&subtree - D, G, H, I, K and L extendedFamily - A, B, C, D, E, F, G, H, I, J, K, L 4 The Family Grouping Control The Family Grouping control is only applicable to the following operations: Compare, Search and RemoveEntry. 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 FamilySelection. An absent value implies entryOnly. 4.1 Use in the Compare Operation For the Compare operation all the attributes in all the family members selected 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 selected 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. entry&parent and upToAncestor shall not be set for this operation. nuclearFamily may be specified for a leaf entry or a non-leaf entry of object class parent. In the latter case the parent and all its children will be removed. The operation will fail with result code grandparent if any of the children are also of object class parent. entry&subtree may be specified for a leaf entry or a non-leaf entry of object class parent. In the latter case, the parent and all its subordinates, down to the leaves, will be removed. extendedFamily may be specified for a leaf entry or a non-leaf entry that is an ancestor. All the members of the extended family will be removed. The operation will fail with result code notAncestor if the target object is not an ancestor. 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, as directed by the Family Grouping control: entryOnly means that the filter is applied to each family member in isolation. This is the default value, and ensures backwards compatibility with previous editions of the standard. entry&parent means that the entry and its immediate parent are to be logically merged before applying the filter. upToAncestor means that the entry and all its parents up to the ancestor are to be logically merged before applying the filter. nuclearFamily means that the entry and all its immediate children are to be logically merged before applying the filter. entry&subtree means that the entry and all its children down to the leaves are to be logically merged before applying the filter. extendedFamily means that the entire family of the entry is to be logically merged before applying the filter. If a collection of merged family entries passes the filter, then each family member in the collection is added to the set of entries comprising the Search result. In addition, for each family member so selected, members of the same family as indicated by the FamilyReturn control (see section 5) should be added to the set of entries comprising the Search result. 5 The FamilyReturn Control This control is only applicable to the Search operation. The Family Grouping 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 FamilySelection. For each family member present in the Search result after evaluation of the filter, members of the same family, as directed by the Family Return control, are added to the Search result. Duplicate family members shall be removed before the Search result is returned to the requestor. 6 New Result Codes Add the following two new result codes to the LDAPv3 protocol [LDAPv3]: notAncestor (72), -- An operation attempted to delete an extended family without specifying the ancestor as the object -- grandparent (73), -- An operation attempted to delete a nuclear family that has grandchildren -- 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 family may have the same prescriptive access controls applied to them in the following way: they are all included in the scope of the subtree specification of the access control subentry and additionally they may all be members of the same object class that is used to refine the subtree specification. The following change to the semantics of the thisEntry userClass in the access control model is proposed: 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 [PDAM] 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 16-23 September 1998, Beijing, China. [LDAPv3] Kille, S., Wahl, M., and T. Howes, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [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