Network Working Group                                          M. Wahl
Request for Comments: DRAFT                     Sun Microsystems, Inc.  
Expires: January 2001                                        July 2000

                        LDAPv3 Data Model Definitions
                       <draft-wahl-ldapv3-defns-00.txt>

1.  Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all 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.

   Discussion of this document should take place on the LDAP Extensions
   Working Group mailing list <ietf-ldapext@netscape.com>.

Copyright Notice

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

2. Abstract

   The Lightweight Directory Access Protocol (LDAP) is based on an 
   underlying data model which is derived from X.500(1993).  The 
   data model is visible to LDAP clients through protocol interactions.
   This document defines the terms and their relationships which form
   the LDAPv3 data model.
 
3. Data Model

   LDAP was originally defined in terms of X.500 as an X.500 access 
   mechanism, but can be used to access non-X.500 directories also.  An 
   LDAP server MUST act in accordance with the X.500(1993) series of 
   ITU-T recommendations when providing the service, except as modified 
   by the LDAP RFCs themselves.  However, it is not required that an 
   LDAP server make use of any X.500 protocols in providing this 
   service, e.g. LDAP can be mapped onto any other directory system so 
   long as the X.500 data and service model as used in LDAP is not 
   violated in the LDAP interface.



Wahl                        Expires: January 2001               [Page 1]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

3.1. Assumptions

   This document makes significant use of ITU-T Rec. X.501(1993).  

   Implementors are strongly advised to be familiar with X.501(1993) 
   clauses 1-8, as well as X.500(1993) and X.511(1993), before reading 
   the rest of this document.  Due to ITU-T copyright restrictions,
   the text from the ITU-T documents cannot be included here.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  and "MAY" in this document
   are to be interpreted as described in RFC 2119 [1].

3.2. Document Relationship

   This document REPLACES RFC 2251 sections 3.2 through 3.4.

   This document UPDATES RFC 2251 section 4.1.3, 4.1.4, 4.1.5, 4.1.5.1, 
   4.1.6, 4.1.7, 4.1.8, 4.1.9 and 4.1.11.

   This document UPDATES RFC 2252 sections 4.2, 4.3, 4.4, 4.5, 5, 6, 7 
   and 8. 

4. Definitions

   These are listed in alphabetical order.  Section heading numbers and
   full XREF details will be added in a later draft.

* Abstract Object Class

   The term "Abstract Object Class" is defined in X.501(1993) section 
   8.3.1.  Abstract object classes are one kind of object class (XREF). 

   The superclasses of an abstract object class, if any, MUST be other 
   abstract object classes.

   "top" is an example of an abstract object class.  Support for the 
   "top" object class is MANDATORY, as required by RFC 2251.   
   Servers MAY support other abstract classes.

* Alias Entry

   The string name of the alias pointer in LDAP is different from 
   that of X.501(1993), as LDAP bases its definition on RFC 1274.

   An alias entry is a kind of entry (XREF), which has the alias object
   class and the aliasedObjectName attribute both present 
   (aliasedObjectName is a mandatory attribute of the alias object 
   class).  An alias entry MUST be a leaf entry, as required by 
   X.501(1993) section 7.4.


Wahl                        Expires: January 2001               [Page 2]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000
 
   In LDAP, support for aliases is OPTIONAL.  An LDAP server which does 
   not support aliases SHOULD NOT allow entries with aliasedObjectName 
   attribute to be created in the DIT contained by that server.

   See also X.501(1993) section 9.5.

* Approximate Matching 

   X.511(1993) and RFC 2251 defines an approximate match filter item as 
   part of the search filter.  As the attribute type description (XREF) 
   does not include the approximate matching rule, support for 
   approximate matching is implementation-dependent.

   An approximate matching algorithm implemented by an LDAP server 
   SHOULD be based on the following requirements:
    - the assertion value syntax SHOULD be the same as the attribute 
      value syntax,
    - all assertion values which compare TRUE for equality SHOULD 
      compare TRUE for approximate match as well.

   Support for approximate matching of attributes which are subtypes of 
   the name attribute is RECOMMENDED.  Examples of algorithms which 
   have be used for this purpose include SOUNDEX and METAPHONE, 
   however these algorithms do not support non-ASCII letters.

   Support for approximate matching of attributes with Directory String
   syntax (1.3.6.1.4.1.1466.115.121.1.15) is RECOMMENDED.  

   Support for approximate matching of attributes with all other 
   syntaxes is OPTIONAL.

* Attribute

   The basis of the Attribute in LDAP is defined in X.501(1993) section 
   8.1, however it is not exactly the same as the definition in the 
   1993 recommendation, due to the use of the Attribute Description 
   rather than the Attribute Type.

   In LDAP, an attribute consists of an Attribute Description (XREF)
   and a set of one or more associated attribute values (XREF).  An 
   attribute is part of an entry or other kind of DSE.  Attributes
   in a non-entry DSE MAY be implemented differently and behave like
   operational attributes.

         Attribute ::= SEQUENCE {
                 type    AttributeDescription,
                 vals    SET OF AttributeValue }





Wahl                        Expires: January 2001               [Page 3]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   The LDAP server MUST ensure that each attribute contains at least 
   one value.  Note that due to access control or other restrictions an 
   Attribute transferred in protocol may have an empty set.  This is 
   described in RFC 2251 section 4.5.2, concerning the 
   PartialAttributeList ASN.1 type.

   Each attribute value is distinct in the set; there are no duplicates.
   The LDAP server MUST ensure that no two values in a single attribute 
   compare TRUE for equality.

   The order of attribute values within the values set is undefined and
   implementation-dependent, and MUST NOT be relied upon.  An LDAP 
   server could reorder the list of values presented by or to the 
   client.

* Attribute Description

   The term "Attribute Description" is defined by LDAP and is not part 
   of X.501(1993).

   An Attribute Description is a superset of the definition of the 
   Attribute Type (XREF).  

   In the LDAP protocol, an Attribute Description is encoded as a UTF-8 
   string.

         AttributeDescription ::= LDAPString

   Note that its LDAP protocol encoding in ASN.1 is the same as 
   AttributeType, but the AttributeDescription allows additional 
   options to be specified.  

   The content of the AttributeDescription string is generated by the 
   production of <AttributeDescription> in the following BNF:

         <AttributeDescription> ::= <AttributeType> [ ";" <options> ]

         <options>  ::= <option> | <option> ";" <options>

         <option>   ::= <opt-char> <opt-char>*

         <opt-char> ::=  ASCII-equivalent letters, numbers and hyphen

   The BNF production of <AttributeType> is given in the section 
   definition of Attribute Type (XREF).

   Examples of valid AttributeDescription:
         cn
         userCertificate;binary



Wahl                        Expires: January 2001               [Page 4]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   AttributeDescription strings are case insensitive: implementations 
   MUST ignore the case of the ASCII-equivalent letters when comparing 
   two AttributeDescription strings for equality.

   An AttributeDescription with one or more options is treated as a
   subtype of the attribute type without any options.  (See the 
   definition of Attribute Type for the meaning of the term 'subtype'.)
   Options present in an AttributeDescription are never mutually 
   exclusive.  Implementations MUST generate the <options> list sorted
   in ascending order, and servers MUST treat any two 
   AttributeDescription with the same AttributeType and options as 
   equivalent.  A server will treat an AttributeDescription with any 
   options it does not implement as an unrecognized attribute type.

* Attribute Option

   One option, "binary", is defined in this document under "Binary 
   Attribute Description Option" (XREF).  Additional options could be 
   defined in IETF standards-track and experimental RFCs.  Options 
   beginning with "x-" are reserved for private experiments.   Any 
   option could be associated with any AttributeType, although not all 
   combinations need be supported by a server.

   The supported attribute options is not currently published by the 
   directory server, although this may be corrected in future revisions 
   of this document.

* Attribute Type

   The basis of the Attribute Type in LDAP is defined in X.501(1993) 
   clauses 8.1, 8.4 and 12.4, however it is not exactly the same as the 
   definition in X.501, due to a change in the schema representation.

   LDAP refines the schema description representation of 
   Attribute Type of X.501 by requiring that the syntax field in an 
   AttributeTypeDescription be a string representation of an 
   OBJECT IDENTIFIER for the LDAP string syntax definition, and an 
   optional indication of the maximum length of a value of this 
   attribute (defined in RFC 2252 section 4.3.2).

   The attribute type governs the values in the attribute and their use.

   An attribute type is a definition of the following fields:
    - a unique OBJECT IDENTIFIER,
    - optionally, one or more string names, such as "cn",
    - optionally, an indication of a supertype of this attribute type,
    - optionally, an equality matching rule,
    - optionally, an ordering matching rule,
    - optionally, a substring matching rule,
    - a syntax definition (OBJECT IDENTIFIER),


Wahl                        Expires: January 2001               [Page 5]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

    - optionally, a maximum length of a value of this attribute 
      (defined in RFC 2252 section 4.3.2),
    - an indication of whether attributes of this type are 
      single-valued,
    - an indication of whether attributes of this type cannot be 
      modified by normal user applications,
    - an indication of whether attributes of this type are 
      used to form collective attributes, and
    - an indication of the intended usage of the attribute type (XREF).

   These fields are fixed when the attribute type object identifier is 
   assigned.  If one of the fields needs to be changed, then a new 
   object identifier MUST be assigned.





   Each attribute type has a unique OBJECT IDENTIFIER which has been
   assigned to it.  This identifier may be written as decimal digits
   with components separated by periods, e.g. "2.5.4.10".

   Attribute types SHOULD have at least one short descriptive string 
   name.  A specification MAY also assign more than one textual names 
   for an  attribute type.  These names MUST begin with a letter, and 
   only contain ASCII letters, digit characters and hyphens.  They are 
   case insensitive.  (These ASCII characters are identical to ISO 10646
   characters whose UTF-8 encoding is a single byte between 0x00 and
   0x7F.)

   If the server has a textual name for an attribute type, it MUST use a
   textual name for attributes returned in search results.  The dotted-
   decimal OBJECT IDENTIFIER is only used if there is no textual name
   for an attribute type.

   Attribute type textual names are non-unique, as two different
   specifications (neither in standards track RFCs) may choose the same
   name.

         AttributeType ::= LDAPString

   An LDAP server MUST recognize the attribute types objectClass and 
   aliasedObjectName.  See the Alias Entry (XREF) for more information 
   on the aliasedObjectName attribute.

   Servers MUST implement all the attribute types referenced in RFC 
   2252 sections 5.1, 5.2 and 5.3.





Wahl                        Expires: January 2001               [Page 6]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   Servers MAY recognize additional names and attributes, and if they 
   do so, MUST publish the attribute type descriptions (XREF) of these 
   types in the attributeTypes attribute of their subschema entries 
   (XREF).

   Schema developers MUST NOT create attribute definitions whose names
   conflict with attributes defined for use with LDAP in existing
   standards-track RFCs.

   See also Operational Attribute (XREF).

* Attribute Type Description

   An Attribute Type Description is a representation of all the fields 
   of an attribute type's definition, as well as descriptive 
   information.

   Specifically, the Attribute Type Description adds the following 
   fields:
    - optionally, a human-readable textual description of the 
      attribute, and
    - an indication of whether the attribute type is obsolete.

   RFC 2252 describes the syntax of the Attribute Type Description, a 
   string representation used for the attributeTypes attribute in the 
   subschema entries.

   An AttributeDescription can be used as the value in a NAME part of an
   AttributeTypeDescription.  Note that these are case insensitive.

   Note that the AttributeTypeDescription does not list the matching
   rules which can can be used with that attribute type in an
   extensibleMatch search filter.  This is done using the
   matchingRuleUse attribute described in RFC 2252 section 4.5.

* Attribute Type And Values

   The AttributeTypeAndValues ASN.1 data type consists of an 
   AttributeDescription (XREF) and a unordered set of zero or more 
   AttributeValue (XREF).

   The AttributeTypeAndValues is used only in transfer of modification 
   requests from the LDAP client to the server and search result 
   entries from the server to the client, and need not be stored in 
   this form by the server between operations.

* Attribute Usage

   The field Attribute Usage of an Attribute Type Description (XREF) 
   can be one of the following, as described in X.501(1993):


Wahl                        Expires: January 2001               [Page 7]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   - "userApplications": this is the default for attribute types unless 
     otherwise specified,
   - "directoryOperation": intended for operation of the directory 
     service independent of directory distribution, such as for access 
     control,
   - "distributedOperation": intended for operation of directory 
     service distribution and expected to be synchronized among all 
     replicas of a naming context, 
   - "dSAOperation": intended for operation of the directory service
     distribution and not expected to be synchronized among the 
     replicas of a naming context.

* Attribute Value

   The term "Attribute Value" is defined in X.501(1993) sections 8.1 
   and 8.5.

   A field of type AttributeValue takes on as its value either a string
   encoding of a AttributeValue data type, or an OCTET STRING containing
   an encoded binary value, depending on whether the "binary" option 
   (XREF) is present in the companion AttributeDescription to this 
   AttributeValue.

   The definition of string encodings for different syntaxes and types
   may be found in other documents, and in particular RFC 2252.

         AttributeValue ::= OCTET STRING

   Note that there is no defined limit on the size of this encoding;
   thus protocol values may include multi-megabyte attributes (e.g.
   photographs).

   Attributes may be defined which have arbitrary and non-printable
   syntax.  Implementations MUST NEITHER simply display nor attempt to
   decode as ASN.1 a value if its syntax is not known.  The
   implementation may attempt to discover the subschema of the source
   entry, and retrieve the values of attributeTypes from it.

   Clients MUST NOT send attribute values in a request which are not
   valid according to the syntax defined for the attributes.

* Attribute Value Assertion

   The basis of the Attribute Value Assertion in LDAP is defined in 
   X.501(1993) sections 8.1 and 8.7.2, however it is not exactly the 
   same as the definition in X.501, due to a change from attribute type 
   to attribute description.





Wahl                        Expires: January 2001               [Page 8]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   The AttributeValueAssertion ASN.1 data type definition contains an 
   attribute description and a matching rule assertion value suitable 
   for a matching rule of that attribute description.  If the Attribute
   Value Assertion is part of the Search Filter, the matching rule used 
   is implicit from the context tag; in all other operations, the 
   equality matching rule is used.

         AttributeValueAssertion ::= SEQUENCE {
                 attributeDesc   AttributeDescription,
                 assertionValue  AssertionValue }

         AssertionValue ::= OCTET STRING

   If the "binary" option is present in attributeDesc (XREF), this 
   signals to the server that the assertionValue is a binary encoding 
   of the assertion value.

   For all the string-valued user attributes described in RFC 2252, the
   assertion value syntax is the same as the value syntax.  Clients may
   use attribute values as assertion values in compare requests and
   search filters.

   Note however that the assertion syntax may be different from the
   value syntax for other attributes or for non-equality matching rules.
   These may have an assertion syntax which contains only part of the
   value.  See section 20.2.1.8 of X.501(1993) for examples.

* Auxiliary Object Class

   The term "Auxiliary Object Class" is defined in X.501(1993) section 
   8.1.  Auxiliary object classes are one kind of object class (XREF). 

   There are no mandatory auxiliary object classes for LDAP.

   The superclasses of an auxiliary object class, if any, MUST be 
   either auxiliary or abstract object classes.

* Binary Attribute Description Option

   If the "binary" option is present in an AttributeDescription, it
   overrides any string-based encoding representation defined for that
   attribute.  Instead the attribute is to be transferred as a
   binary value encoded using the Basic Encoding Rules, as defined in 
   ITU-T Rec. X.690(1994).  The syntax of the binary value is an ASN.1 
   data type definition which is referenced by the "SYNTAX" part of the 
   attribute type definition.






Wahl                        Expires: January 2001               [Page 9]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   The presence or absence of the "binary" option only affects the
   transfer of attribute values in protocol; servers store any
   particular attribute in a single format.  If a client requests that a
   server return an attribute in the binary format, but the server
   cannot generate that format, the server MUST treat this attribute
   type as an unrecognized attribute type.  Similarly, clients MUST NOT
   expect servers to return an attribute in binary format if the client
   requested that attribute by name without the binary option.

   This option is intended to be used with attributes whose syntax is a
   complex ASN.1 data type, and the structure of values of that type is
   needed by clients.  Examples of this kind of syntax are "Certificate"
   and "CertificateList".

   A server which supports any of the following attributes MUST 
   support the binary option for them: userCertificate, caCertificate, 
   certificateRevocationList, authorityRevocationList, 
   crossCertificatePair, supportedAlgorithms, deltaRevocationList.

   A server MAY support the binary option for other attributes.

* Client

   An LDAP client establishes a connection to one or more LDAP servers, 
   and invokes operations. 

* Continuation Reference

   A continuation reference is returned by an LDAP server in response 
   to a search if it was able to locate the base object of the search, 
   but one or more entries in the scope of the search are in naming 
   contexts not held by that server.

* Context Prefix

   The entry (XREF) at the top of a naming context (XREF).

* Directory Information Tree

   The LDAP protocol assumes there are one or more servers which jointly
   provide access to a Directory Information Tree (DIT).  The tree is 
   primarily made up of entries (XREF), held in naming contexts (XREF). 
   The root of the DIT is the root DSE (XREF), which is not part of any 
   naming context.

   An LDAP client MUST be able to handle a DIT with at least ten layers 
   of naming contexts between the root and a leaf entry, and SHOULD
   handle an arbitrary number of layers.




Wahl                        Expires: January 2001              [Page 10]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   Each entry in a Directory Information Tree has a distinguished name 
   which is unique in the tree.  This name is not globally unique, 
   however: on the Internet, there are multiple, unconnected, directory 
   information trees.

* Directory Service

   A set of one or more cooperating servers (XREF) which provide a 
   integrated Directory Information Tree (XREF).  Any server in this
   set will be able to route an operation for any entry in the Directory
   Information Tree.

   On the Internet, there are multiple distinct directory services.

* Distinguished Name

   The term "Distinguished Name" is defined in X.501(1993) section 9.4.

   An LDAPDN is defined to be the representation of a Distinguished Name
   after encoding according to the specification in RFC 2253, such that

         <distinguished-name> ::= <name>

   where <name> are as defined in RFC 2253.

   Only Attribute Types can be present in a relative distinguished name
   component; the options of Attribute Descriptions (next section) MUST
   NOT be used in specifying distinguished names.

* DIT: See Directory Information Tree

* DN: See Distinguished Name

* DSA: See Server

* DSA-Specific Entry: See DSE

* DSA Information Tree: See DSAIT

* DSAIT 

   The DSAIT is based on the definition of the "DSA Information Tree" in
   X.501(1993) section 19.1.1, however LDAP servers are not required to 
   support the full distribution and DSAIT operational models of X.501.
   (DSA is an X.500 term for the directory server).

   The DSAIT contains all the DSEs held by a particular LDAP server.





Wahl                        Expires: January 2001              [Page 11]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   In general, the DSAIT of an LDAP server will consist of at least the 
   following:
    - all the naming contexts held by the server,
    - the root DSE,
    - the subschema entries, if any, which are not part of a naming 
      context,
    - referral DSEs, if any, which are not part of a naming context 
      (XREF). 

   An LDAP server MAY support other kinds of DSEs, for example a change 
   log.

* DSE

   The DSE is based on the definition of the "DSA-Specific Entry" in 
   X.501(1993) section 19.3, however LDAP servers are not required to 
   support the full distribution and DSAIT operational models of X.501.

   In an LDAP server, each DSE MUST have a unique distinguished name 
   (XREF) in its Directory Information Tree (XREF) and MUST have one or 
   more attributes.

   The following are the kinds of DSEs in an LDAP server:
    - entries (XREF), both object and alias, 
    - the root DSE (XREF),
    - the subschema entries (XREF), and
    - referral DSEs (XREF).

   LDAP servers are NOT required to provide or support the dseType 
   attribute.

* Entry

   The term "Entry" is defined in X.501(1993) section 7.3.  There are 
   at least two kinds of entries: object entries (XREF) and alias 
   entries (XREF).   

   To support the subschema publication requirement, an LDAP server 
   MUST either support subschema as subentries (XREF), or as entries.  

   Each entry MUST contain one or more attributes (XREF), and MUST have 
   a unique distinguished name (XREF) in its Directory Information Tree 
   (XREF).  In particular, one or more attribute values from the entry 
   form its relative distinguished name (XREF), which MUST be unique 
   among all its siblings.  The concatenation of the relative 
   distinguished names of the sequence of entries from a particular 
   entry to an immediate subordinate of the root of the tree forms that 
   entry's Distinguished Name (DN), which is unique in the tree.  An 
   example of a Distinguished Name is

   CN=Steve Kille, O=Isode Limited, C=GB

Wahl                        Expires: January 2001              [Page 12]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   X.501(1993) sections 8.3 and 12.3.2 require that each entry MUST 
   contain an objectClass attribute, which indicates the structural,
   auxiliary and abstract classes which define the attributes permitted 
   and required in that entry.  Each entry is implicitly of object class
   "top", and that value MAY be omitted from the entry.  

   Each entry MUST have at least one structural object class (XREF).
   An LDAP client SHOULD NOT attempt to change the structural object 
   class (XREF) of an entry once it has been created, as forbidden by 
   X.501(1993) 8.3.2.

   Servers MUST NOT permit clients to add attributes to an entry unless
   those attributes are permitted by the object class definitions, the
   schema controlling that entry (specified in the subschema), or are 
   operational attributes (XREF) known to that server and used for 
   administrative purposes.  Note that there is a particular 
   objectClass  'extensibleObject' defined below which permits all 
   user attributes to be present in an entry.

   Entries MAY contain, among others, the following operational
   attributes (XREF), defined in X.501(1993) and RFC 2252. These 
   attributes are maintained automatically by the server and are not 
   modifiable by clients (they are marked NO-USER-MODIFICATION in 
   their schema definitions.)  

   - creatorsName: the Distinguished Name of the user who added this
     entry to the directory.

   - createTimestamp: the time this entry was added to the directory.

   - modifiersName: the Distinguished Name of the user who last modified
     this entry.

   - modifyTimestamp: the time this entry was last modified.

   - subschemaSubentry:  the Distinguished Name of the subschema entry
     (or subentry) which controls the schema for this entry.

* Extensible Object Class

   The Extensible Object Class was defined in RFC 2252.   It is not 
   part of X.501(1993).

   The extensibleObject object class, if present in an entry, permits
   that entry to optionally hold any user attribute.  The MAY attribute 
   list of this class is implicitly the set of all attributes.

   Support for this object class by LDAP servers is OPTIONAL. Not all 
   servers will implement this object class, and those which do not 
   will reject requests to add entries which contain this object class, 
   or modify an entry to add this object class.

Wahl                        Expires: January 2001              [Page 13]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   The follow Attribute Type Description (XREF) is RECOMMENDED for use 
   in publishing support for this attribute.

   attributeTypes: ( 1.3.6.1.4.1.1466.101.120.111 NAME 
   'extensibleObject' SUP top AUXILIARY )

   The mandatory attributes of the other object classes of this entry
   are still required to be present.

* Filter

   A filter defines the conditions that must be fulfilled in order for a
   search to match a given entry.

   The 'and', 'or' and 'not' filter choices can be used to form 
   combinations of filters. At least one filter element MUST be present 
   in an 'and' or 'or' choice.  
   
   The other filter choices match against individual attribute values of
   entries in the scope of the search.  

   A server MUST evaluate filters according to the three-valued logic
   of X.511(1993) section 7.8.1.  In summary, a filter is evaluated to
   either "TRUE", "FALSE" or "Undefined".  If the filter evaluates
   to TRUE for a particular entry, then the attributes of that entry
   are returned as part of the search result (subject to any applicable
   access control restrictions). If the filter evaluates to FALSE or
   Undefined, then the entry is ignored for the search.

   A filter of the "and" choice is TRUE if all the filters in the SET
   OF evaluate to TRUE, FALSE if at least one filter is FALSE, and
   otherwise Undefined.  A filter of the "or" choice is FALSE if all
   of the filters in the SET OF evaluate to FALSE, TRUE if at least
   one filter is TRUE, and Undefined otherwise.  A filter of the "not"
   choice is TRUE if the filter being negated is FALSE, FALSE if it is
   TRUE, and Undefined if it is Undefined.

   See also Filter Item (XREF).

* Filter Item

   In LDAP, the following filter items are defined:
    - equalityMatch: uses the equality matching rule,
    - substrings:  See also Substrings Filter (XREF),
    - greaterOrEqual: uses the ordering matching rule,
    - lessOrEqual: uses the ordering matching rule,
    - present,
    - approxMatch: uses an implementation-defined matching rule,  
    - extensibleMatch: uses a user-specified matching rule.



Wahl                        Expires: January 2001              [Page 14]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000


   The present match evaluates to TRUE where there is an attribute or
   subtype of the specified attribute description present in an entry,
   and FALSE otherwise (including a presence test with an unrecognized
   attribute description.)

   A filter item evaluates to Undefined when the server would not
   be able to determine whether the assertion value matches an
   entry.  If an attribute description in an equalityMatch, substrings,
   greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch
   filter is not recognized by the server, a matching rule id in the
   extensibleMatch is not recognized by the server, the assertion
   value cannot be parsed, or the type of filtering requested is not
   implemented, then the filter is Undefined.  Thus for example if a
   server did not recognize the attribute type shoeSize, a filter of
   (shoeSize=*) would evaluate to FALSE, and the filters (shoeSize=12),
   (shoeSize>=12) and (shoeSize<=12) would evaluate to Undefined.

   Servers MUST NOT return errors if attribute descriptions or matching
   rule ids are not recognized, or assertion values cannot be parsed.
   More details of filter processing are given in section 7.8 of 
   X.511(1993).

   See also Substring Filter (XREF) and Matching Rule Assertion (XREF).

* Matching Rule

   The term "Matching Rule" is defined in X.501(1993) sections 8.1, 
   8.7 and 12.5.

   A matching rule is a means of expressing how a server should compare
   an AssertionValue received in a search filter with an abstract data
   value.  The matching rule defines the syntax of the assertion value
   and the process to be performed in the server.

   There are five kinds of matching rules:
    - equality,
    - ordering,
    - substring,
    - approximate, and
    - extensible. 

   Equality, ordering and substring matching rules MUST meet the 
   requirements of X.501(1993) 8.7.4.

   An X.501(1993) Matching Rule is identified in the LDAP protocol by
   the printable representation of its OBJECT IDENTIFIER, either as one
   of the strings given in RFC 2252, or as decimal digits with 
   components separated by periods, e.g. "caseIgnoreIA5Match" or
   "1.3.6.1.4.1.453.33.33".


Wahl                        Expires: January 2001              [Page 15]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

         MatchingRuleId ::= LDAPString

   Servers which support matching rules for use in the extensibleMatch
   search filter MUST list the matching rules they implement in
   subschema entries, using the matchingRules attributes.  The server
   SHOULD also list there, using the matchingRuleUse attribute, the
   attribute types with which each matching rule can be used.  More
   information is given in section 4.4 of RFC 2252.

* Matching Rule Assertion

   The term "Matching Rule Assertion" is defined in X.501(1993) section 
   8.1.

   The extensibleMatch is derived from the X.511 MatchingRuleAssertion 
   ASN.1 data type.  It has been simplified for LDAP use:

         MatchingRuleAssertion ::= SEQUENCE {
                 matchingRule    [1] MatchingRuleId OPTIONAL,
                 type            [2] AttributeDescription OPTIONAL,
                 matchValue      [3] AssertionValue,
                 dnAttributes    [4] BOOLEAN DEFAULT FALSE }

   If the matchingRule field is absent, the type field MUST be present,
   and the equality match is performed for that type.  If the type 
   field is absent and matchingRule is present, the matchValue is 
   compared against all attributes in an entry which support that 
   matchingRule, and the matchingRule determines the syntax for the 
   assertion value (the filter item evaluates to TRUE if it matches 
   with at least one attribute in the entry, FALSE if it does not match 
   any attribute in the entry, and Undefined if the matchingRule is not 
   recognized or the assertionValue cannot be parsed.)  If the type 
   field is present and matchingRule is present, the matchingRule MUST 
   be one permitted for use with that type, otherwise the filter item is
   undefined.  If the dnAttributes field is set to TRUE, the match is
   applied against all the attributes in an entry's distinguished name
   as well, and also evaluates to TRUE if there is at least one
   attribute in the distinguished name for which the filter item
   evaluates to TRUE.  (Editors note: The dnAttributes field is present
   so that there does not need to be multiple versions of generic
   matching rules such as for word matching, one to apply to entries
   and another to apply to entries and dn attributes as well).

* Matching Rule Use

   The Attribute Type Description does not list the matching rules 
   which can be used with that attribute type in an extensibleMatch 
   search filter.  This is done instead using the matchingRuleUse 
   attribute in the subschema entry, described in RFC 2252 section 4.5.



Wahl                        Expires: January 2001              [Page 16]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

* Naming Context

   The largest collection of entries, starting at an entry that is
   mastered by a particular server, and including all its subordinates
   and their subordinates, down to the entries which are mastered by
   different servers, is termed a naming context.  The root of the DIT
   is a DSA-specific Entry (DSE) and not part of any naming context:
   each server has different attribute values in the root DSE.  

   Some servers MAY hold cache or shadow copies of entries, which can be
   used to answer search and comparison queries, but will return
   referrals or contact other servers if modification operations are
   requested.

* Object Class

   The term "Object Class" is defined in X.501(1993) section 8.3.  In 
   LDAP, there are four kinds of object class: abstract (XREF), 
   structural (XREF), auxiliary (XREF) and the extensible object class 
   (XREF).  The extensible object class is not defined in X.500.

   The object class governs the attributes in an entry.

   An object class is a definition of the following fields: 
    - a unique OBJECT IDENTIFIER,
    - optionally, one or more string names, such as "top",
    - optionally, an indication of the superclasses of this object 
      class, 
    - an indication of whether the class of abstract, structural or 
      auxiliary (the extensible object class is defined as auxiliary),
    - a list of the types of attributes which must be present in the 
      entry, and
    - a list of the types of attributes which may be present in the 
      entry.

   These fields are fixed when the object class object identifier is 
   assigned.  If one of the fields needs to be changed, then a new 
   object identifier MUST be assigned.

   If superclasses are specified, then the mandatory and optional 
   attribute lists of the superclasses are also accepted 

   Indication that an attribute of a particular type is allowed in an 
   entry also allows a subtypes of that attribute to be included.








Wahl                        Expires: January 2001              [Page 17]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   An LDAP server MUST recognize the object class "top", which is an 
   abstract object class.  Servers SHOULD implement all the object 
   classes referenced in section 7 of RFC 2252, except for 
   extensibleObject, which is OPTIONAL. Servers MAY implement 
   additional object classes.  Servers MUST publish the definitions of 
   the classes which they implement in the objectClasses 
   attribute of their subschema entries.

   Schema developers MUST NOT create object class definitions whose
   names conflict with object classes defined for use with LDAP in 
   existing standards-track RFCs.

   Servers MUST NOT permit clients to add attributes to an entry unless
   those attributes are permitted by the object class definitions, the
   schema controlling that entry (specified in the subschema), or are 
   operational attributes known to that server and used for 
   administrative purposes.  

* Object Class Description

   An Object Class Description is a representation of all the fields of 
   an object classes' definition, as well as descriptive information.

   Specifically, the Object Class Description adds the following fields:
    - optionally, a human-readable textual description of the object 
      class, and
    - an indication of whether the object class is obsolete.

   RFC 2252 describes the syntax of the Object Class Description, a 
   string representation used for the objectClasses attribute in the 
   subschema entries.

* Object Entry

   An Object Entry is an entry (XREF) which is not an alias entry.  

* Operational Attribute

   Operational attributes are defined in X.501(1993), and in RFC 2251 
   section 3.2.1.

   Operational attributes are used by servers for administering the 
   directory system itself.  They are not returned in search results 
   unless explicitly requested by name.  Their presence in an entry is 
   not governed by the object class of the entry, but by rules inside 
   the server itself.

   LDAP servers MUST recognize the attribute types of RFC 2252 sections
   5.1, 5.2 and 5.3, and SHOULD recognize the attribute types of RFC 
   2252 section 5.4.


Wahl                        Expires: January 2001              [Page 18]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

* Partial Attribute List 

   The Partial Attributes List is an unordered sequence of Attribute 
   Type and Values (XREF) data items used in search results.

* Purported Name

   The term "Purported Name" is defined in X.501(1993) section 9.2.  It 
   is structurally similar to a distinguished name (XREF).  All 
   Distinguished Names sent by the client to the server are actually 
   purported names, since the client does not know for sure whether the
   entry exists or not.
   
* Referral

   An LDAP server can return a referral, a set of URLs of other LDAP 
   servers, any of which should be contacted by the client to progress 
   the operation.

   Referrals can be returned in the following situations, among others:
    - superior reference (XREF): the client's request is for a base 
      entry which is not below the context prefix of any naming context 
      held by the server,
    - subordinate reference (XREF): the client's request is for a base 
      entry below a naming context held by the server,
    - continuation reference (XREF): the client's search request spans 
      naming context boundaries, and
    - modification of a read-only copy of a naming context.

* Relative Distinguished Name

   The term "Relative Distinguished Name" is defined in X.501(1993) 
   section 9.3.

   In LDAP, the representation of a Relative Distinguished Name after 
   encoding according to the specification in RFC 2253, such that

         <relative-distinguished-name> ::= <name-component>

   where <name-component> is defined in RFC 2253.

   Only Attribute Types can be present in a relative distinguished name
   component; the options of Attribute Descriptions (next section) MUST
   NOT be used in specifying distinguished names.

* Root DSE

   The basis of the root DSE in LDAP is defined in X.501(1993), however
   it is not exactly the same, as the root DSE in X.500 does not support
   filtering based on the objectClass attribute.


Wahl                        Expires: January 2001              [Page 19]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   An LDAP server MUST provide information about itself and other 
   information that is specific to each server.  This is represented as 
   a group of attributes located in the root DSE (DSA-Specific Entry), 
   which is named with the zero-length LDAPDN.  These attributes are 
   retrievable if a client performs a base object search of the root 
   with filter "(objectClass=*)", however they are subject to access 
   control restrictions.  

   The server MUST support filtering for presence on the attribute 
   objectClass when processing a base object search (XREF) of the root 
   DSE.  Note that recognition of this search filter for the root DSE 
   is a special case.

   The root DSE MUST NOT be included if the client performs a subtree 
   search starting from the root.

   Servers MAY allow clients to modify the attributes of the root DSE.

   The following attributes of the root DSE are defined in section 5.2 
   of RFC 2252.  Additional attributes may be defined in other 
   documents.

   - namingContexts: naming contexts (XREF) held in the server.

   - subschemaSubentry: subschema entries (or subentries) [XREF] known 
     by this server.

   - altServer: alternative servers in case this one is later
     unavailable.

   - supportedExtension: list of supported extended operations.

   - supportedControl: list of supported controls.

   - supportedSASLMechanisms: list of supported SASL security features.

   - supportedLDAPVersion: LDAP versions implemented by the server.

   If the server does not master entries and does not know the locations
   of schema information, the subschemaSubentry attribute is not present
   in the root DSE.  If the server masters directory entries under one
   or more schema rules, there can be any number of values of the
   subschemaSubentry attribute in the root DSE.

   LDAP servers are NOT required to provide or support the dseType 
   attribute.






Wahl                        Expires: January 2001              [Page 20]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

* Schema

   Schema is the collection of attribute type definitions, object class
   definitions and other information which a server uses to determine
   how to match a filter or attribute value assertion (in a compare
   operation) against the attributes of an entry, and whether to permit
   add and modify operations.  The definition of schema for use with
   LDAP is given in RFC 2251 and X.501(1993).  Additional schema 
   elements may be defined in other documents.

* Scope

   The scope field of an LDAP search request is an indicator of the 
   scope of the search to be performed.
   
   The semantics of the possible values of this field are identical to 
   the semantics of the scope field in the X.511 Search Operation.

* Server

   An LDAP server passively accepts connection from LDAP clients, and 
   responds to operations.  An LDAP server can also return unsolicited 
   notifications on a connection.

   Each LDAP server has a DSAIT (XREF), which contains the portion of 
   the Directory Information Tree (XREF) held by that server.

   An LDAP server MUST provide information about itself and other
   information that is specific to each server.  This is represented as
   the root DSE (XREF).

   Servers which perform caching or shadowing MUST ensure that they do
   not violate any access control constraints placed on the data by the
   originating server.

* Structural Object Class

   The term "Structural Object Class" is defined in X.501(1993) section 
   8.1. Structural object classes are one kind of object class (XREF).

   The superclasses of a structural object class, if any, MUST be either
   structural or abstract object classes.

* Structural Object Class of the Entry

   Each entry MUST have at least one structural object class (XREF).  In
   addition, an LDAP server MUST NOT allow more than one structural 
   object class value be present in the entry unless there is exactly 
   one most subordinate structural object class.  In particular, there 
   are no subclasses of this class also included in the entry.


Wahl                        Expires: January 2001              [Page 21]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   An LDAP client SHOULD NOT attempt to change the structural object 
   class (XREF) of an entry once it has been created, as forbidden by 
   X.501(1993) 8.3.2.

* Subschema

   The term "subschema" is defined in X.501(1993) section 14.

   The subschema of an LDAP server is the set of attribute types, object
   classes and other schema elements which can be applied to entries in
   a subschema administrative area (XREF). 

* Subschema Administrative Area

   The term "Subschema Administrative Area" is defined in X.501(1993).  
   It contains one or more entries which are controlled by a particular 
   subschema entry (XREF).

* Subschema Entry

   Subschema entries are used for administering information about the
   directory schema, in particular the object classes and attribute
   types supported by directory servers.  A single subschema entry
   contains all schema definitions used by entries in a particular part
   of the directory tree.

   Servers which follow X.500(1993) models SHOULD implement subschema
   using the X.500 subentry mechanisms (XREF), and so these subschemas 
   are not ordinary entries.  LDAP clients SHOULD NOT assume that 
   servers implement any of the other aspects of X.500 subschema.  A 
   server which masters entries and permits clients to modify these 
   entries MUST implement and provide access to these subschema entries,
   so that its clients may discover the attributes and object classes 
   which are permitted to be present. It is strongly RECOMMENDED that
   all other servers implement this as well.

   The following four attributes MUST be present in all subschema
   entries:

   - cn: this attribute MUST be used to form the RDN of the subschema
     entry.

   - objectClass: the attribute MUST have at least the values "top" and
     "subschema".  (Note that the "top" value is mandatory here, 
     although it may be omitted in user entries). 

   - objectClasses: each value of this attribute specifies an Object
     Class Description (XREF) of each class known to the server.  

   - attributeTypes: each value of this attribute specifies an Attribute
     Type Description (XREF) of each attribute known to the server.

Wahl                        Expires: January 2001              [Page 22]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   These are defined in RFC 2252. Other attributes MAY be present in
   subschema entries, to reflect additional supported capabilities.
   These include matchingRules, matchingRuleUse, dITStructureRules,
   dITContentRules, nameForms and ldapSyntaxes.

   Servers SHOULD provide the attributes createTimestamp and
   modifyTimestamp in subschema entries, in order to allow clients to
   maintain their caches of schema information.

   Clients MUST only retrieve attributes from a subschema entry by
   requesting a base object search of the entry, where the search filter
   is "(objectClass=subschema)". (This will allow LDAP servers which
   gateway to X.500(1993) to detect that subentry information is being
   requested.)

* Subentry

   The term "subentry" is defined in X.501(1993) section 11.6.

   Support for subentries by LDAP servers is OPTIONAL.  Those which do 
   not implement subentries implement subschema as object entries.

* Subordinate Reference

   The subordinate reference is the kind of referral (XREF) that is 
   returned to clients in response to a request whose base is below the 
   context prefix of a naming context held by the server, but not in 
   the naming context itself. It would typically contain a reference 
   to a server which holds a naming context that contains the client's 
   target entry.

* Substring Filter

   The substring filter item consists of an attribute description, and 
   at least one of the following:

    - an initial string,
    - a final string,
    - one or more strings which may occur anywhere in the value.

   Support for substring matching of attributes with Directory String
   syntax (1.3.6.1.4.1.1466.115.121.1.15) is RECOMMENDED.  

   Support for substring matching of attributes with all other syntaxes
   is OPTIONAL.

   Substring matching rules MUST meet the requirements of X.501(1993) 
   8.7.4.

   See RFC 2252 section 8.3 for more information on how substring 
   assertion values are represented for a matching rule assertion value.

Wahl                        Expires: January 2001              [Page 23]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

* Superior Reference

   The superior reference is the kind of referral (XREF) that is 
   returned to clients in response to a request whose base is not 
   below the context prefix of any naming contexts by a server which 
   does not hold any naming contexts immediately subordinate to the 
   root DSE.  It would typically contain a reference to a server 
   which holds a naming context that is closer to the root DSE. 

* Syntax

   A syntax defines how values of a particular attribute are encoded for
   transmission.

   Each syntax used in LDAP has a unique object identifier.  

   See section 4.3 of RFC 2252 for more information.

* Value: See Attribute Value

5. Security Considerations

   Attributes of directory entries are used to provide descriptive
   information about the real-world objects they represent, which can be
   people, organizations or devices.  Most countries have privacy laws
   regarding the publication of information about people.  See also
   the Security Considerations section of RFC 2251.

6. Acknowledgements

   The contents of this document are based on earlier documents written
   by Tim Howes, Steve Kille, Colin Robbins, Wengyik Yeong and Mark 
   Wahl.

   Design ideas included in this document are based on those discussed 
   in the ASID, LDAPEXT and other IETF Working Groups.  The 
   contributions of individuals in these working groups is gratefully 
   acknowledged.

7. Bibliography

   [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
       Levels", RFC 2119, March 1997.

   [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
       Protocol (v3)", RFC 2251, December 1997.

   [3] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
       Directory Access Protocol (v3): Attribute Syntax Definitions",
       RFC 2252, December 1997.


Wahl                        Expires: January 2001              [Page 24]

INTERNET-DRAFT           LDAPv3 Data Model Definitions         July 2000

   [4] Kille, S., Wahl, M., and T. Howes, "Lightweight Directory Access
       Protocol (v3): UTF-8 String Representation of Distinguished
       Names", RFC 2253, December 1997.

   [5] Barker, P., Kille, S., "The COSINE and Internet X.500 Schema",
       RFC 1274, November 1991.

   [6] ITU-T Rec. X.501, "The Directory: Models", 1993.

   [7] ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
       1993.


8. Author's Addresses

   Mark Wahl
   Sun Microsystems, Inc.
   8911 Capital of Texas Hwy
   Suite 4140
   Austin TX 78759  USA

9. Copyright Statement

   Copyright (C) The Internet Society (2000).  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.




Wahl                        Expires: January 2001              [Page 25]