Internet DRAFT - draft-ietf-chadwick-families

draft-ietf-chadwick-families



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
             <draft-chadwick-families-00.txt>

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", <draft-ietf-ldup-model-00.txt>, 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]