diff options
author | Simo Sorce <idra@samba.org> | 2004-09-30 16:08:09 +0000 |
---|---|---|
committer | Gerald (Jerry) Carter <jerry@samba.org> | 2007-10-10 12:59:31 -0500 |
commit | 338c90404f6ea3a3ccc40c331e018180bbeb32f2 (patch) | |
tree | fc799a94767500c4ff80fb2cf5e8271550fcbb56 /source4 | |
parent | a4a360b7fecaae853bf7d064f982e0bb01e3e4d3 (diff) | |
download | samba-338c90404f6ea3a3ccc40c331e018180bbeb32f2.tar.gz samba-338c90404f6ea3a3ccc40c331e018180bbeb32f2.tar.bz2 samba-338c90404f6ea3a3ccc40c331e018180bbeb32f2.zip |
r2758: keep docos handy while developing it
(This used to be commit 5f9b58c785950e9871ef6411ff2ef34f988959ed)
Diffstat (limited to 'source4')
-rw-r--r-- | source4/ldap_server/devdocs/rfc2252.txt | 1795 | ||||
-rw-r--r-- | source4/ldap_server/devdocs/rfc2253.txt | 563 | ||||
-rw-r--r-- | source4/ldap_server/devdocs/rfc2254.txt | 451 | ||||
-rw-r--r-- | source4/ldap_server/devdocs/rfc2255.txt | 563 | ||||
-rw-r--r-- | source4/ldap_server/devdocs/rfc2256.txt | 1123 | ||||
-rw-r--r-- | source4/ldap_server/devdocs/rfc2307.txt | 1179 |
6 files changed, 5674 insertions, 0 deletions
diff --git a/source4/ldap_server/devdocs/rfc2252.txt b/source4/ldap_server/devdocs/rfc2252.txt new file mode 100644 index 0000000000..5a72b7768a --- /dev/null +++ b/source4/ldap_server/devdocs/rfc2252.txt @@ -0,0 +1,1795 @@ + + + + + + +Network Working Group M. Wahl +Request for Comments: 2252 Critical Angle Inc. +Category: Standards Track A. Coulbeck + Isode Inc. + T. Howes + Netscape Communications Corp. + S. Kille + Isode Limited + December 1997 + + + Lightweight Directory Access Protocol (v3): + Attribute Syntax Definitions + +1. Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +IESG Note + + This document describes a directory access protocol that provides + both read and update access. Update access requires secure + authentication, but this document does not mandate implementation of + any satisfactory authentication mechanisms. + + In accordance with RFC 2026, section 4.4.1, this specification is + being approved by IESG as a Proposed Standard despite this + limitation, for the following reasons: + + a. to encourage implementation and interoperability testing of + these protocols (with or without update access) before they + are deployed, and + + b. to encourage deployment and use of these protocols in read-only + applications. (e.g. applications where LDAPv3 is used as + a query language for directories which are updated by some + secure mechanism other than LDAP), and + + + + + + +Wahl, et. al. Standards Track [Page 1] + +RFC 2252 LADPv3 Attributes December 1997 + + + c. to avoid delaying the advancement and deployment of other Internet + standards-track protocols which require the ability to query, but + not update, LDAPv3 directory servers. + + Readers are hereby warned that until mandatory authentication + mechanisms are standardized, clients and servers written according to + this specification which make use of update functionality are + UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION + IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. + + Implementors are hereby discouraged from deploying LDAPv3 clients or + servers which implement the update functionality, until a Proposed + Standard for mandatory authentication in LDAPv3 has been approved and + published as an RFC. + +2. Abstract + + The Lightweight Directory Access Protocol (LDAP) [1] requires that + the contents of AttributeValue fields in protocol elements be octet + strings. This document defines a set of syntaxes for LDAPv3, and the + rules by which attribute values of these syntaxes are represented as + octet strings for transmission in the LDAP protocol. The syntaxes + defined in this document are referenced by this and other documents + that define attribute types. This document also defines the set of + attribute types which LDAP servers should support. + +3. Overview + + This document defines the framework for developing schemas for + directories accessible via the Lightweight Directory Access Protocol. + + 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. + + Section 4 states the general requirements and notations for attribute + types, object classes, syntax and matching rule definitions. + + Section 5 lists attributes, section 6 syntaxes and section 7 object + classes. + + Additional documents define schemas for representing real-world + objects as directory entries. + + + + + + +Wahl, et. al. Standards Track [Page 2] + +RFC 2252 LADPv3 Attributes December 1997 + + +4. General Issues + + This document describes encodings used in an Internet protocol. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [4]. + + Attribute Type and Object Class definitions are written in a string + representation of the AttributeTypeDescription and + ObjectClassDescription data types defined in X.501(93) [3]. + Implementors are strongly advised to first read the description of + how schema is represented in X.500 before reading the rest of this + document. + +4.1. Common Encoding Aspects + + For the purposes of defining the encoding rules for attribute + syntaxes, the following BNF definitions will be used. They are based + on the BNF styles of RFC 822 [13]. + + a = "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / + "j" / "k" / "l" / "m" / "n" / "o" / "p" / "q" / "r" / + "s" / "t" / "u" / "v" / "w" / "x" / "y" / "z" / "A" / + "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" / + "K" / "L" / "M" / "N" / "O" / "P" / "Q" / "R" / "S" / + "T" / "U" / "V" / "W" / "X" / "Y" / "Z" + + d = "0" / "1" / "2" / "3" / "4" / + "5" / "6" / "7" / "8" / "9" + + hex-digit = d / "a" / "b" / "c" / "d" / "e" / "f" / + "A" / "B" / "C" / "D" / "E" / "F" + + k = a / d / "-" / ";" + + p = a / d / """ / "(" / ")" / "+" / "," / + "-" / "." / "/" / ":" / "?" / " " + + letterstring = 1*a + + numericstring = 1*d + + anhstring = 1*k + + keystring = a [ anhstring ] + + printablestring = 1*p + + + +Wahl, et. al. Standards Track [Page 3] + +RFC 2252 LADPv3 Attributes December 1997 + + + space = 1*" " + + whsp = [ space ] + + utf8 = <any sequence of octets formed from the UTF-8 [9] + transformation of a character from ISO10646 [10]> + + dstring = 1*utf8 + + qdstring = whsp "'" dstring "'" whsp + + qdstringlist = [ qdstring *( qdstring ) ] + + qdstrings = qdstring / ( whsp "(" qdstringlist ")" whsp ) + + In the following BNF for the string representation of OBJECT + IDENTIFIERs, descr is the syntactic representation of an object + descriptor, which consists of letters and digits, starting with a + letter. An OBJECT IDENTIFIER in the numericoid format should not + have leading zeroes (e.g. "0.9.3" is permitted but "0.09.3" should + not be generated). + + When encoding 'oid' elements in a value, the descr encoding option + SHOULD be used in preference to the numericoid. An object descriptor + is a more readable alias for a number OBJECT IDENTIFIER, and these + (where assigned and known by the implementation) SHOULD be used in + preference to numeric oids to the greatest extent possible. Examples + of object descriptors in LDAP are attribute type, object class and + matching rule names. + + oid = descr / numericoid + + descr = keystring + + numericoid = numericstring *( "." numericstring ) + + woid = whsp oid whsp + + ; set of oids of either form + oids = woid / ( "(" oidlist ")" ) + + oidlist = woid *( "$" woid ) + + ; object descriptors used as schema element names + qdescrs = qdescr / ( whsp "(" qdescrlist ")" whsp ) + + qdescrlist = [ qdescr *( qdescr ) ] + + + + +Wahl, et. al. Standards Track [Page 4] + +RFC 2252 LADPv3 Attributes December 1997 + + + qdescr = whsp "'" descr "'" whsp + +4.2. Attribute Types + + The attribute types are described by sample values for the subschema + "attributeTypes" attribute, which is written in the + AttributeTypeDescription syntax. While lines have been folded for + readability, the values transferred in protocol would not contain + newlines. + + The AttributeTypeDescription is encoded according to the following + BNF, and the productions for oid, qdescrs and qdstring are given in + section 4.1. Implementors should note that future versions of this + document may have expanded this BNF to include additional terms. + Terms which begin with the characters "X-" are reserved for private + experiments, and MUST be followed by a <qdstrings>. + + AttributeTypeDescription = "(" whsp + numericoid whsp ; AttributeType identifier + [ "NAME" qdescrs ] ; name used in AttributeType + [ "DESC" qdstring ] ; description + [ "OBSOLETE" whsp ] + [ "SUP" woid ] ; derived from this other + ; AttributeType + [ "EQUALITY" woid ; Matching Rule name + [ "ORDERING" woid ; Matching Rule name + [ "SUBSTR" woid ] ; Matching Rule name + [ "SYNTAX" whsp noidlen whsp ] ; see section 4.3 + [ "SINGLE-VALUE" whsp ] ; default multi-valued + [ "COLLECTIVE" whsp ] ; default not collective + [ "NO-USER-MODIFICATION" whsp ]; default user modifiable + [ "USAGE" whsp AttributeUsage ]; default userApplications + whsp ")" + + AttributeUsage = + "userApplications" / + "directoryOperation" / + "distributedOperation" / ; DSA-shared + "dSAOperation" ; DSA-specific, value depends on server + + Servers are not required to provide the same or any text in the + description part of the subschema values they maintain. Servers + SHOULD provide at least one of the "SUP" and "SYNTAX" fields for each + AttributeTypeDescription. + + Servers MUST implement all the attribute types referenced in sections + 5.1, 5.2 and 5.3. + + + + +Wahl, et. al. Standards Track [Page 5] + +RFC 2252 LADPv3 Attributes December 1997 + + + Servers MAY recognize additional names and attributes not listed in + this document, and if they do so, MUST publish the definitions of the + types in the attributeTypes attribute of their subschema entries. + + Schema developers MUST NOT create attribute definitions whose names + conflict with attributes defined for use with LDAP in existing + standards-track RFCs. + + 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 section 4.5. + + This document refines the schema description 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 section 4.3.2). + +4.3. Syntaxes + + This section defines general requirements for LDAP attribute value + syntax encodings. All documents defining attribute syntax encodings + for use with LDAP are expected to conform to these requirements. + + The encoding rules defined for a given attribute syntax must produce + octet strings. To the greatest extent possible, encoded octet + strings should be usable in their native encoded form for display + purposes. In particular, encoding rules for attribute syntaxes + defining non-binary values should produce strings that can be + displayed with little or no translation by clients implementing LDAP. + There are a few cases (e.g. audio) however, when it is not sensible + to produce a printable representation, and clients MUST NOT assume + that an unrecognized syntax is a string representation. + + In encodings where an arbitrary string, not a Distinguished Name, is + used as part of a larger production, and other than as part of a + Distinguished Name, a backslash quoting mechanism is used to escape + the following separator symbol character (such as "'", "$" or "#") if + it should occur in that string. The backslash is followed by a pair + of hexadecimal digits representing the next character. A backslash + itself in the string which forms part of a larger syntax is always + transmitted as '\5C' or '\5c'. An example is given in section 6.27. + + + + + +Wahl, et. al. Standards Track [Page 6] + +RFC 2252 LADPv3 Attributes December 1997 + + + Syntaxes are also defined for matching rules whose assertion value + syntax is different from the attribute value syntax. + +4.3.1 Binary Transfer of Values + + This encoding format is used if the binary encoding is requested by + the client for an attribute, or if the attribute syntax name is + "1.3.6.1.4.1.1466.115.121.1.5". The contents of the LDAP + AttributeValue or AssertionValue field is a BER-encoded instance of + the attribute value or a matching rule assertion value ASN.1 data + type as defined for use with X.500. (The first byte inside the OCTET + STRING wrapper is a tag octet. However, the OCTET STRING is still + encoded in primitive form.) + + All servers MUST implement this form for both generating attribute + values in search responses, and parsing attribute values in add, + compare and modify requests, if the attribute type is recognized and + the attribute syntax name is that of Binary. Clients which request + that all attributes be returned from entries MUST be prepared to + receive values in binary (e.g. userCertificate;binary), and SHOULD + NOT simply display binary or unrecognized values to users. + +4.3.2. Syntax Object Identifiers + + Syntaxes for use with LDAP are named by OBJECT IDENTIFIERs, which are + dotted-decimal strings. These are not intended to be displayed to + users. + + noidlen = numericoid [ "{" len "}" ] + + len = numericstring + + The following table lists some of the syntaxes that have been defined + for LDAP thus far. The H-R column suggests whether a value in that + syntax would likely be a human readable string. Clients and servers + need not implement all the syntaxes listed here, and MAY implement + other syntaxes. + + Other documents may define additional syntaxes. However, the + definition of additional arbitrary syntaxes is strongly deprecated + since it will hinder interoperability: today's client and server + implementations generally do not have the ability to dynamically + recognize new syntaxes. In most cases attributes will be defined + with the syntax for directory strings. + + + + + + + +Wahl, et. al. Standards Track [Page 7] + +RFC 2252 LADPv3 Attributes December 1997 + + + Value being represented H-R OBJECT IDENTIFIER + ================================================================= + ACI Item N 1.3.6.1.4.1.1466.115.121.1.1 + Access Point Y 1.3.6.1.4.1.1466.115.121.1.2 + Attribute Type Description Y 1.3.6.1.4.1.1466.115.121.1.3 + Audio N 1.3.6.1.4.1.1466.115.121.1.4 + Binary N 1.3.6.1.4.1.1466.115.121.1.5 + Bit String Y 1.3.6.1.4.1.1466.115.121.1.6 + Boolean Y 1.3.6.1.4.1.1466.115.121.1.7 + Certificate N 1.3.6.1.4.1.1466.115.121.1.8 + Certificate List N 1.3.6.1.4.1.1466.115.121.1.9 + Certificate Pair N 1.3.6.1.4.1.1466.115.121.1.10 + Country String Y 1.3.6.1.4.1.1466.115.121.1.11 + DN Y 1.3.6.1.4.1.1466.115.121.1.12 + Data Quality Syntax Y 1.3.6.1.4.1.1466.115.121.1.13 + Delivery Method Y 1.3.6.1.4.1.1466.115.121.1.14 + Directory String Y 1.3.6.1.4.1.1466.115.121.1.15 + DIT Content Rule Description Y 1.3.6.1.4.1.1466.115.121.1.16 + DIT Structure Rule Description Y 1.3.6.1.4.1.1466.115.121.1.17 + DL Submit Permission Y 1.3.6.1.4.1.1466.115.121.1.18 + DSA Quality Syntax Y 1.3.6.1.4.1.1466.115.121.1.19 + DSE Type Y 1.3.6.1.4.1.1466.115.121.1.20 + Enhanced Guide Y 1.3.6.1.4.1.1466.115.121.1.21 + Facsimile Telephone Number Y 1.3.6.1.4.1.1466.115.121.1.22 + Fax N 1.3.6.1.4.1.1466.115.121.1.23 + Generalized Time Y 1.3.6.1.4.1.1466.115.121.1.24 + Guide Y 1.3.6.1.4.1.1466.115.121.1.25 + IA5 String Y 1.3.6.1.4.1.1466.115.121.1.26 + INTEGER Y 1.3.6.1.4.1.1466.115.121.1.27 + JPEG N 1.3.6.1.4.1.1466.115.121.1.28 + LDAP Syntax Description Y 1.3.6.1.4.1.1466.115.121.1.54 + LDAP Schema Definition Y 1.3.6.1.4.1.1466.115.121.1.56 + LDAP Schema Description Y 1.3.6.1.4.1.1466.115.121.1.57 + Master And Shadow Access Points Y 1.3.6.1.4.1.1466.115.121.1.29 + Matching Rule Description Y 1.3.6.1.4.1.1466.115.121.1.30 + Matching Rule Use Description Y 1.3.6.1.4.1.1466.115.121.1.31 + Mail Preference Y 1.3.6.1.4.1.1466.115.121.1.32 + MHS OR Address Y 1.3.6.1.4.1.1466.115.121.1.33 + Modify Rights Y 1.3.6.1.4.1.1466.115.121.1.55 + Name And Optional UID Y 1.3.6.1.4.1.1466.115.121.1.34 + Name Form Description Y 1.3.6.1.4.1.1466.115.121.1.35 + Numeric String Y 1.3.6.1.4.1.1466.115.121.1.36 + Object Class Description Y 1.3.6.1.4.1.1466.115.121.1.37 + Octet String Y 1.3.6.1.4.1.1466.115.121.1.40 + OID Y 1.3.6.1.4.1.1466.115.121.1.38 + Other Mailbox Y 1.3.6.1.4.1.1466.115.121.1.39 + Postal Address Y 1.3.6.1.4.1.1466.115.121.1.41 + Protocol Information Y 1.3.6.1.4.1.1466.115.121.1.42 + + + +Wahl, et. al. Standards Track [Page 8] + +RFC 2252 LADPv3 Attributes December 1997 + + + Presentation Address Y 1.3.6.1.4.1.1466.115.121.1.43 + Printable String Y 1.3.6.1.4.1.1466.115.121.1.44 + Substring Assertion Y 1.3.6.1.4.1.1466.115.121.1.58 + Subtree Specification Y 1.3.6.1.4.1.1466.115.121.1.45 + Supplier Information Y 1.3.6.1.4.1.1466.115.121.1.46 + Supplier Or Consumer Y 1.3.6.1.4.1.1466.115.121.1.47 + Supplier And Consumer Y 1.3.6.1.4.1.1466.115.121.1.48 + Supported Algorithm N 1.3.6.1.4.1.1466.115.121.1.49 + Telephone Number Y 1.3.6.1.4.1.1466.115.121.1.50 + Teletex Terminal Identifier Y 1.3.6.1.4.1.1466.115.121.1.51 + Telex Number Y 1.3.6.1.4.1.1466.115.121.1.52 + UTC Time Y 1.3.6.1.4.1.1466.115.121.1.53 + + A suggested minimum upper bound on the number of characters in value + with a string-based syntax, or the number of bytes in a value for all + other syntaxes, may be indicated by appending this bound count inside + of curly braces following the syntax name's OBJECT IDENTIFIER in an + Attribute Type Description. This bound is not part of the syntax + name itself. For instance, "1.3.6.4.1.1466.0{64}" suggests that + server implementations should allow a string to be 64 characters + long, although they may allow longer strings. Note that a single + character of the Directory String syntax may be encoded in more than + one byte since UTF-8 is a variable-length encoding. + +4.3.3. Syntax Description + + The following BNF may be used to associate a short description with a + syntax OBJECT IDENTIFIER. Implementors should note that future + versions of this document may expand this definition to include + additional terms. Terms whose identifier begins with "X-" are + reserved for private experiments, and MUST be followed by a + <qdstrings>. + + SyntaxDescription = "(" whsp + numericoid whsp + [ "DESC" qdstring ] + whsp ")" + +4.4. Object Classes + + The format for representation of object classes is defined in X.501 + [3]. In general every entry will contain an abstract class ("top" or + "alias"), at least one structural object class, and zero or more + auxiliary object classes. Whether an object class is abstract, + structural or auxiliary is defined when the object class identifier + is assigned. An object class definition should not be changed + without having a new identifier assigned to it. + + + + +Wahl, et. al. Standards Track [Page 9] + +RFC 2252 LADPv3 Attributes December 1997 + + + Object class descriptions are written according to the following BNF. + Implementors should note that future versions of this document may + expand this definition to include additional terms. Terms whose + identifier begins with "X-" are reserved for private experiments, and + MUST be followed by a <qdstrings> encoding. + + ObjectClassDescription = "(" whsp + numericoid whsp ; ObjectClass identifier + [ "NAME" qdescrs ] + [ "DESC" qdstring ] + [ "OBSOLETE" whsp ] + [ "SUP" oids ] ; Superior ObjectClasses + [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ] + ; default structural + [ "MUST" oids ] ; AttributeTypes + [ "MAY" oids ] ; AttributeTypes + whsp ")" + + These are described as sample values for the subschema + "objectClasses" attribute for a server which implements the LDAP + schema. While lines have been folded for readability, the values + transferred in protocol would not contain newlines. + + Servers SHOULD implement all the object classes referenced in section + 7, except for extensibleObject, which is optional. Servers MAY + implement additional object classes not listed in this document, and + if they do so, MUST publish the definitions of the classes in the + objectClasses attribute of their subschema entries. + + Schema developers MUST NOT create object class definitions whose + names conflict with attributes defined for use with LDAP in existing + standards-track RFCs. + +4.5. Matching Rules + + Matching rules are used by servers to compare attribute values + against assertion values when performing Search and Compare + operations. They are also used to identify the value to be added or + deleted when modifying entries, and are used when comparing a + purported distinguished name with the name of an entry. + + Most of the attributes given in this document will have an equality + matching rule defined. + + Matching rule descriptions are written according to the following + BNF. Implementors should note that future versions of this document + may have expanded this BNF to include additional terms. Terms whose + identifier begins with "X-" are reserved for private experiments, and + + + +Wahl, et. al. Standards Track [Page 10] + +RFC 2252 LADPv3 Attributes December 1997 + + + MUST be followed by a <qdstrings> encoding. + + MatchingRuleDescription = "(" whsp + numericoid whsp ; MatchingRule identifier + [ "NAME" qdescrs ] + [ "DESC" qdstring ] + [ "OBSOLETE" whsp ] + "SYNTAX" numericoid + whsp ")" + + Values of the matchingRuleUse list the attributes which are suitable + for use with an extensible matching rule. + + MatchingRuleUseDescription = "(" whsp + numericoid whsp ; MatchingRule identifier + [ "NAME" qdescrs ] + [ "DESC" qdstring ] + [ "OBSOLETE" ] + "APPLIES" oids ; AttributeType identifiers + whsp ")" + + Servers which support matching rules and the extensibleMatch SHOULD + implement all the matching rules in section 8. + + Servers MAY implement additional matching rules not listed in this + document, and if they do so, MUST publish the definitions of the + matching rules in the matchingRules attribute of their subschema + entries. If the server supports the extensibleMatch, then the server + MUST publish the relationship between the matching rules and + attributes in the matchingRuleUse attribute. + + For example, a server which implements a privately-defined matching + rule for performing sound-alike matches on Directory String-valued + attributes would include the following in the subschema entry + (1.2.3.4.5 is an example, the OID of an actual matching rule would be + different): + + matchingRule: ( 1.2.3.4.5 NAME 'soundAlikeMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) + + If this matching rule could be used with the attributes 2.5.4.41 and + 2.5.4.15, the following would also be present: + + matchingRuleUse: ( 1.2.3.4.5 APPLIES (2.5.4.41 $ 2.5.4.15) ) + + + + + + + +Wahl, et. al. Standards Track [Page 11] + +RFC 2252 LADPv3 Attributes December 1997 + + + A client could then make use of this matching rule by sending a + search operation in which the filter is of the extensibleMatch + choice, the matchingRule field is "soundAlikeMatch", and the type + field is "2.5.4.41" or "2.5.4.15". + +5. Attribute Types + + All LDAP server implementations MUST recognize the attribute types + defined in this section. + + Servers SHOULD also recognize all the attributes from section 5 of + [12]. + +5.1. Standard Operational Attributes + + Servers MUST maintain values of these attributes in accordance with + the definitions in X.501(93). + +5.1.1. createTimestamp + + This attribute SHOULD appear in entries which were created using the + Add operation. + + ( 2.5.18.1 NAME 'createTimestamp' EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) + +5.1.2. modifyTimestamp + + This attribute SHOULD appear in entries which have been modified + using the Modify operation. + + ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY generalizedTimeMatch + ORDERING generalizedTimeOrderingMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 + SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) + +5.1.3. creatorsName + + This attribute SHOULD appear in entries which were created using the + Add operation. + + ( 2.5.18.3 NAME 'creatorsName' EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 + SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) + + + + + +Wahl, et. al. Standards Track [Page 12] + +RFC 2252 LADPv3 Attributes December 1997 + + +5.1.4. modifiersName + + This attribute SHOULD appear in entries which have been modified + using the Modify operation. + + ( 2.5.18.4 NAME 'modifiersName' EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 + SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) + +5.1.5. subschemaSubentry + + The value of this attribute is the name of a subschema entry (or + subentry if the server is based on X.500(93)) in which the server + makes available attributes specifying the schema. + + ( 2.5.18.10 NAME 'subschemaSubentry' + EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION + SINGLE-VALUE USAGE directoryOperation ) + +5.1.6. attributeTypes + + This attribute is typically located in the subschema entry. + + ( 2.5.21.5 NAME 'attributeTypes' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) + +5.1.7. objectClasses + + This attribute is typically located in the subschema entry. + + ( 2.5.21.6 NAME 'objectClasses' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) + +5.1.8. matchingRules + + This attribute is typically located in the subschema entry. + + ( 2.5.21.4 NAME 'matchingRules' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.30 USAGE directoryOperation ) + + + + + + + + +Wahl, et. al. Standards Track [Page 13] + +RFC 2252 LADPv3 Attributes December 1997 + + +5.1.9. matchingRuleUse + + This attribute is typically located in the subschema entry. + + ( 2.5.21.8 NAME 'matchingRuleUse' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.31 USAGE directoryOperation ) + +5.2. LDAP Operational Attributes + + These attributes are only present in the root DSE (see [1] and [3]). + + Servers MUST recognize these attribute names, but it is not required + that a server provide values for these attributes, when the attribute + corresponds to a feature which the server does not implement. + +5.2.1. namingContexts + + The values of this attribute correspond to naming contexts which this + server masters or shadows. If the server does not master any + information (e.g. it is an LDAP gateway to a public X.500 directory) + this attribute will be absent. If the server believes it contains + the entire directory, the attribute will have a single value, and + that value will be the empty string (indicating the null DN of the + root). This attribute will allow a client to choose suitable base + objects for searching when it has contacted a server. + + ( 1.3.6.1.4.1.1466.101.120.5 NAME 'namingContexts' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 USAGE dSAOperation ) + +5.2.2. altServer + + The values of this attribute are URLs of other servers which may be + contacted when this server becomes unavailable. If the server does + not know of any other servers which could be used this attribute will + be absent. Clients may cache this information in case their preferred + LDAP server later becomes unavailable. + + ( 1.3.6.1.4.1.1466.101.120.6 NAME 'altServer' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 USAGE dSAOperation ) + +5.2.3. supportedExtension + + The values of this attribute are OBJECT IDENTIFIERs identifying the + supported extended operations which the server supports. + + If the server does not support any extensions this attribute will be + absent. + + + +Wahl, et. al. Standards Track [Page 14] + +RFC 2252 LADPv3 Attributes December 1997 + + + ( 1.3.6.1.4.1.1466.101.120.7 NAME 'supportedExtension' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation ) + +5.2.4. supportedControl + + The values of this attribute are the OBJECT IDENTIFIERs identifying + controls which the server supports. If the server does not support + any controls, this attribute will be absent. + + ( 1.3.6.1.4.1.1466.101.120.13 NAME 'supportedControl' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation ) + +5.2.5. supportedSASLMechanisms + + The values of this attribute are the names of supported SASL + mechanisms which the server supports. If the server does not support + any mechanisms this attribute will be absent. + + ( 1.3.6.1.4.1.1466.101.120.14 NAME 'supportedSASLMechanisms' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE dSAOperation ) + +5.2.6. supportedLDAPVersion + + The values of this attribute are the versions of the LDAP protocol + which the server implements. + + ( 1.3.6.1.4.1.1466.101.120.15 NAME 'supportedLDAPVersion' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 USAGE dSAOperation ) + +5.3. LDAP Subschema Attribute + + This attribute is typically located in the subschema entry. + +5.3.1. ldapSyntaxes + + Servers MAY use this attribute to list the syntaxes which are + implemented. Each value corresponds to one syntax. + + ( 1.3.6.1.4.1.1466.101.120.16 NAME 'ldapSyntaxes' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.54 USAGE directoryOperation ) + +5.4. X.500 Subschema attributes + + These attributes are located in the subschema entry. All servers + SHOULD recognize their name, although typically only X.500 servers + will implement their functionality. + + + + +Wahl, et. al. Standards Track [Page 15] + +RFC 2252 LADPv3 Attributes December 1997 + + +5.4.1. dITStructureRules + + ( 2.5.21.1 NAME 'dITStructureRules' EQUALITY integerFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.17 USAGE directoryOperation ) + +5.4.2. nameForms + + ( 2.5.21.7 NAME 'nameForms' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.35 USAGE directoryOperation ) + +5.4.3. ditContentRules + + ( 2.5.21.2 NAME 'dITContentRules' + EQUALITY objectIdentifierFirstComponentMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.16 USAGE directoryOperation ) + +6. Syntaxes + + Servers SHOULD recognize all the syntaxes described in this section. + +6.1. Attribute Type Description + + ( 1.3.6.1.4.1.1466.115.121.1.3 DESC 'Attribute Type Description' ) + + Values in this syntax are encoded according to the BNF given at the + start of section 4.2. For example, + + ( 2.5.4.0 NAME 'objectClass' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) + +6.2. Binary + + ( 1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary' ) + + Values in this syntax are encoded as described in section 4.3.1. + +6.3. Bit String + + ( 1.3.6.1.4.1.1466.115.121.1.6 DESC 'Bit String' ) + + Values in this syntax are encoded according to the following BNF: + + bitstring = "'" *binary-digit "'B" + + binary-digit = "0" / "1" + + + + + +Wahl, et. al. Standards Track [Page 16] + +RFC 2252 LADPv3 Attributes December 1997 + + + Example: + + '0101111101'B + +6.4. Boolean + + ( 1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean' ) + + Values in this syntax are encoded according to the following BNF: + + boolean = "TRUE" / "FALSE" + + Boolean values have an encoding of "TRUE" if they are logically true, + and have an encoding of "FALSE" otherwise. + +6.5. Certificate + + ( 1.3.6.1.4.1.1466.115.121.1.8 DESC 'Certificate' ) + + Because of the changes from X.509(1988) and X.509(1993) and + additional changes to the ASN.1 definition to support certificate + extensions, no string representation is defined, and values in this + syntax MUST only be transferred using the binary encoding, by + requesting or returning the attributes with descriptions + "userCertificate;binary" or "caCertificate;binary". The BNF notation + in RFC 1778 for "User Certificate" is not recommended to be used. + +6.6. Certificate List + + ( 1.3.6.1.4.1.1466.115.121.1.9 DESC 'Certificate List' ) + + Because of the incompatibility of the X.509(1988) and X.509(1993) + definitions of revocation lists, values in this syntax MUST only be + transferred using a binary encoding, by requesting or returning the + attributes with descriptions "certificateRevocationList;binary" or + "authorityRevocationList;binary". The BNF notation in RFC 1778 for + "Authority Revocation List" is not recommended to be used. + +6.7. Certificate Pair + + ( 1.3.6.1.4.1.1466.115.121.1.10 DESC 'Certificate Pair' ) + + Because the Certificate is being carried in binary, values in this + syntax MUST only be transferred using a binary encoding, by + requesting or returning the attribute description + "crossCertificatePair;binary". The BNF notation in RFC 1778 for + "Certificate Pair" is not recommended to be used. + + + + +Wahl, et. al. Standards Track [Page 17] + +RFC 2252 LADPv3 Attributes December 1997 + + +6.8. Country String + + ( 1.3.6.1.4.1.1466.115.121.1.11 DESC 'Country String' ) + + A value in this syntax is encoded the same as a value of Directory + String syntax. Note that this syntax is limited to values of exactly + two printable string characters, as listed in ISO 3166 [14]. + + CountryString = p p + + Example: + US + +6.9. DN + + ( 1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN' ) + + Values in the Distinguished Name syntax are encoded to have the + representation defined in [5]. Note that this representation is not + reversible to an ASN.1 encoding used in X.500 for Distinguished + Names, as the CHOICE of any DirectoryString element in an RDN is no + longer known. + + Examples (from [5]): + CN=Steve Kille,O=Isode Limited,C=GB + OU=Sales+CN=J. Smith,O=Widget Inc.,C=US + CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB + CN=Before\0DAfter,O=Test,C=GB + 1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB + SN=Lu\C4\8Di\C4\87 + +6.10. Directory String + + ( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' ) + + A string in this syntax is encoded in the UTF-8 form of ISO 10646 (a + superset of Unicode). Servers and clients MUST be prepared to + receive encodings of arbitrary Unicode characters, including + characters not presently assigned to any character set. + + For characters in the PrintableString form, the value is encoded as + the string value itself. + + If it is of the TeletexString form, then the characters are + transliterated to their equivalents in UniversalString, and encoded + in UTF-8 [9]. + + + + + +Wahl, et. al. Standards Track [Page 18] + +RFC 2252 LADPv3 Attributes December 1997 + + + If it is of the UniversalString or BMPString forms [10], UTF-8 is + used to encode them. + + Note: the form of DirectoryString is not indicated in protocol unless + the attribute value is carried in binary. Servers which convert to + DAP MUST choose an appropriate form. Servers MUST NOT reject values + merely because they contain legal Unicode characters outside of the + range of printable ASCII. + + Example: + + This is a string of DirectoryString containing #!%#@ + +6.11. DIT Content Rule Description + + ( 1.3.6.1.4.1.1466.115.121.1.16 DESC 'DIT Content Rule Description' ) + + Values in this syntax are encoded according to the following BNF. + Implementors should note that future versions of this document may + have expanded this BNF to include additional terms. + + + DITContentRuleDescription = "(" + numericoid ; Structural ObjectClass identifier + [ "NAME" qdescrs ] + [ "DESC" qdstring ] + [ "OBSOLETE" ] + [ "AUX" oids ] ; Auxiliary ObjectClasses + [ "MUST" oids ] ; AttributeType identifiers + [ "MAY" oids ] ; AttributeType identifiers + [ "NOT" oids ] ; AttributeType identifiers + ")" + +6.12. Facsimile Telephone Number + + + ( 1.3.6.1.4.1.1466.115.121.1.22 DESC 'Facsimile Telephone Number' ) + + Values in this syntax are encoded according to the following BNF: + + fax-number = printablestring [ "$" faxparameters ] + + faxparameters = faxparm / ( faxparm "$" faxparameters ) + + faxparm = "twoDimensional" / "fineResolution" / + "unlimitedLength" / + "b4Length" / "a3Width" / "b4Width" / "uncompressed" + + + + +Wahl, et. al. Standards Track [Page 19] + +RFC 2252 LADPv3 Attributes December 1997 + + + In the above, the first printablestring is the telephone number, + based on E.123 [15], and the faxparm tokens represent fax parameters. + +6.13. Fax + + ( 1.3.6.1.4.1.1466.115.121.1.23 DESC 'Fax' ) + + Values in this syntax are encoded as if they were octet strings + containing Group 3 Fax images as defined in [7]. + +6.14. Generalized Time + + ( 1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' ) + + Values in this syntax are encoded as printable strings, represented + as specified in X.208. Note that the time zone must be specified. + It is strongly recommended that GMT time be used. For example, + + 199412161032Z + +6.15. IA5 String + + ( 1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String' ) + + The encoding of a value in this syntax is the string value itself. + +6.16. INTEGER + + ( 1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER' ) + + Values in this syntax are encoded as the decimal representation of + their values, with each decimal digit represented by the its + character equivalent. So the number 1321 is represented by the + character string "1321". + +6.17. JPEG + + ( 1.3.6.1.4.1.1466.115.121.1.28 DESC 'JPEG' ) + + Values in this syntax are encoded as strings containing JPEG images + in the JPEG File Interchange Format (JFIF), as described in [8]. + +6.18. Matching Rule Description + + ( 1.3.6.1.4.1.1466.115.121.1.30 DESC 'Matching Rule Description' ) + + Values of type matchingRules are encoded as strings according to the + BNF given in section 4.5. + + + +Wahl, et. al. Standards Track [Page 20] + +RFC 2252 LADPv3 Attributes December 1997 + + +6.19. Matching Rule Use Description + + ( 1.3.6.1.4.1.1466.115.121.1.31 DESC 'Matching Rule Use Description' + ) + + Values of type matchingRuleUse are encoded as strings according to + the BNF given in section 4.5. + +6.20. MHS OR Address + + ( 1.3.6.1.4.1.1466.115.121.1.33 DESC 'MHS OR Address' ) + + Values in this syntax are encoded as strings, according to the format + defined in [11]. + +6.21. Name And Optional UID + + ( 1.3.6.1.4.1.1466.115.121.1.34 DESC 'Name And Optional UID' ) + + Values in this syntax are encoded according to the following BNF: + + NameAndOptionalUID = DistinguishedName [ "#" bitstring ] + + Although the '#' character may occur in a string representation of a + distinguished name, no additional special quoting is done. This + syntax has been added subsequent to RFC 1778. + + Example: + + 1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB#'0101'B + +6.22. Name Form Description + + ( 1.3.6.1.4.1.1466.115.121.1.35 DESC 'Name Form Description' ) + + Values in this syntax are encoded according to the following BNF. + Implementors should note that future versions of this document may + have expanded this BNF to include additional terms. + + NameFormDescription = "(" whsp + numericoid whsp ; NameForm identifier + [ "NAME" qdescrs ] + [ "DESC" qdstring ] + [ "OBSOLETE" whsp ] + "OC" woid ; Structural ObjectClass + "MUST" oids ; AttributeTypes + [ "MAY" oids ] ; AttributeTypes + whsp ")" + + + +Wahl, et. al. Standards Track [Page 21] + +RFC 2252 LADPv3 Attributes December 1997 + + +6.23. Numeric String + + ( 1.3.6.1.4.1.1466.115.121.1.36 DESC 'Numeric String' ) + + The encoding of a string in this syntax is the string value itself. + Example: + + 1997 + +6.24. Object Class Description + + ( 1.3.6.1.4.1.1466.115.121.1.37 DESC 'Object Class Description' ) + + Values in this syntax are encoded according to the BNF in section + 4.4. + +6.25. OID + + ( 1.3.6.1.4.1.1466.115.121.1.38 DESC 'OID' ) + + Values in the Object Identifier syntax are encoded according to + the BNF in section 4.1 for "oid". + + Example: + + 1.2.3.4 + cn + +6.26. Other Mailbox + + ( 1.3.6.1.4.1.1466.115.121.1.39 DESC 'Other Mailbox' ) + + Values in this syntax are encoded according to the following BNF: + + otherMailbox = mailbox-type "$" mailbox + + mailbox-type = printablestring + + mailbox = <an encoded IA5 String> + + In the above, mailbox-type represents the type of mail system in + which the mailbox resides, for example "MCIMail"; and mailbox is the + actual mailbox in the mail system defined by mailbox-type. + +6.27. Postal Address + + ( 1.3.6.1.4.1.1466.115.121.1.41 DESC 'Postal Address' ) + + + + +Wahl, et. al. Standards Track [Page 22] + +RFC 2252 LADPv3 Attributes December 1997 + + + Values in this syntax are encoded according to the following BNF: + + postal-address = dstring *( "$" dstring ) + + In the above, each dstring component of a postal address value is + encoded as a value of type Directory String syntax. Backslashes and + dollar characters, if they occur in the component, are quoted as + described in section 4.3. Many servers limit the postal address to + six lines of up to thirty characters. + + Example: + + 1234 Main St.$Anytown, CA 12345$USA + \241,000,000 Sweepstakes$PO Box 1000000$Anytown, CA 12345$USA + +6.28. Presentation Address + + ( 1.3.6.1.4.1.1466.115.121.1.43 DESC 'Presentation Address' ) + + Values in this syntax are encoded with the representation described + in RFC 1278 [6]. + +6.29. Printable String + + ( 1.3.6.1.4.1.1466.115.121.1.44 DESC 'Printable String' ) + + The encoding of a value in this syntax is the string value itself. + PrintableString is limited to the characters in production p of + section 4.1. + + Example: + + This is a PrintableString + +6.30. Telephone Number + + ( 1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' ) + + Values in this syntax are encoded as if they were Printable String + types. Telephone numbers are recommended in X.520 to be in + international form, as described in E.123 [15]. + + Example: + + +1 512 305 0280 + + + + + + +Wahl, et. al. Standards Track [Page 23] + +RFC 2252 LADPv3 Attributes December 1997 + + +6.31. UTC Time + + ( 1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' ) + + Values in this syntax are encoded as if they were printable strings + with the strings containing a UTCTime value. This is historical; new + attribute definitions SHOULD use GeneralizedTime instead. + +6.32. LDAP Syntax Description + + ( 1.3.6.1.4.1.1466.115.121.1.54 DESC 'LDAP Syntax Description' ) + + Values in this syntax are encoded according to the BNF in section + 4.3.3. + +6.33. DIT Structure Rule Description + + ( 1.3.6.1.4.1.1466.115.121.1.17 DESC 'DIT Structure Rule Description' + ) + + Values with this syntax are encoded according to the following BNF: + + DITStructureRuleDescription = "(" whsp + ruleidentifier whsp ; DITStructureRule identifier + [ "NAME" qdescrs ] + [ "DESC" qdstring ] + [ "OBSOLETE" whsp ] + "FORM" woid whsp ; NameForm + [ "SUP" ruleidentifiers whsp ] ; superior DITStructureRules + ")" + + ruleidentifier = integer + + ruleidentifiers = ruleidentifier | + "(" whsp ruleidentifierlist whsp ")" + + ruleidentifierlist = [ ruleidentifier *( ruleidentifier ) ] + +7. Object Classes + + Servers SHOULD recognize all the names of standard classes from + section 7 of [12]. + +7.1. Extensible Object Class + + The extensibleObject object class, if present in an entry, permits + that entry to optionally hold any attribute. The MAY attribute list + of this class is implicitly the set of all attributes. + + + +Wahl, et. al. Standards Track [Page 24] + +RFC 2252 LADPv3 Attributes December 1997 + + + ( 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. + + Note that 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. + +7.2. subschema + + This object class is used in the subschema entry. + + ( 2.5.20.1 NAME 'subschema' AUXILIARY + MAY ( dITStructureRules $ nameForms $ ditContentRules $ + objectClasses $ attributeTypes $ matchingRules $ + matchingRuleUse ) ) + + The ldapSyntaxes operational attribute may also be present in + subschema entries. + +8. Matching Rules + + Servers which implement the extensibleMatch filter SHOULD allow all + the matching rules listed in this section to be used in the + extensibleMatch. In general these servers SHOULD allow matching + rules to be used with all attribute types known to the server, when + the assertion syntax of the matching rule is the same as the value + syntax of the attribute. + + Servers MAY implement additional matching rules. + +8.1. Matching Rules used in Equality Filters + + Servers SHOULD be capable of performing the following matching rules. + + For all these rules, the assertion syntax is the same as the value + syntax. + + ( 2.5.13.0 NAME 'objectIdentifierMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) + + If the client supplies a filter using an objectIdentifierMatch whose + matchValue oid is in the "descr" form, and the oid is not recognized + by the server, then the filter is Undefined. + + ( 2.5.13.1 NAME 'distinguishedNameMatch' + + + +Wahl, et. al. Standards Track [Page 25] + +RFC 2252 LADPv3 Attributes December 1997 + + + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) + + ( 2.5.13.2 NAME 'caseIgnoreMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) + + ( 2.5.13.8 NAME 'numericStringMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) + + ( 2.5.13.11 NAME 'caseIgnoreListMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) + + ( 2.5.13.14 NAME 'integerMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + + ( 2.5.13.16 NAME 'bitStringMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 ) + + ( 2.5.13.20 NAME 'telephoneNumberMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) + + ( 2.5.13.22 NAME 'presentationAddressMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.43 ) + + ( 2.5.13.23 NAME 'uniqueMemberMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.34 ) + + ( 2.5.13.24 NAME 'protocolInformationMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.42 ) + + ( 2.5.13.27 NAME 'generalizedTimeMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + + ( 1.3.6.1.4.1.1466.109.114.1 NAME 'caseExactIA5Match' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + ( 1.3.6.1.4.1.1466.109.114.2 NAME 'caseIgnoreIA5Match' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) + + When performing the caseIgnoreMatch, caseIgnoreListMatch, + telephoneNumberMatch, caseExactIA5Match and caseIgnoreIA5Match, + multiple adjoining whitespace characters are treated the same as an + individual space, and leading and trailing whitespace is ignored. + + Clients MUST NOT assume that servers are capable of transliteration + of Unicode values. + + + + + + +Wahl, et. al. Standards Track [Page 26] + +RFC 2252 LADPv3 Attributes December 1997 + + +8.2. Matching Rules used in Inequality Filters + + Servers SHOULD be capable of performing the following matching rules, + which are used in greaterOrEqual and lessOrEqual filters. + + ( 2.5.13.28 NAME 'generalizedTimeOrderingMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) + + ( 2.5.13.3 NAME 'caseIgnoreOrderingMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) + + The sort ordering for a caseIgnoreOrderingMatch is implementation- + dependent. + +8.3. Syntax and Matching Rules used in Substring Filters + + The Substring Assertion syntax is used only as the syntax of + assertion values in the extensible match. It is not used as the + syntax of attributes, or in the substring filter. + + ( 1.3.6.1.4.1.1466.115.121.1.58 DESC 'Substring Assertion' ) + + The Substring Assertion is encoded according to the following BNF: + + substring = [initial] any [final] + initial = value + any = "*" *(value "*") + final = value + + The <value> production is UTF-8 encoded string. Should the backslash + or asterix characters be present in a production of <value>, they are + quoted as described in section 4.3. + + Servers SHOULD be capable of performing the following matching rules, + which are used in substring filters. + + ( 2.5.13.4 NAME 'caseIgnoreSubstringsMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) + + ( 2.5.13.21 NAME 'telephoneNumberSubstringsMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) + + ( 2.5.13.10 NAME 'numericStringSubstringsMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) + + + + + + + +Wahl, et. al. Standards Track [Page 27] + +RFC 2252 LADPv3 Attributes December 1997 + + +8.4. Matching Rules for Subschema Attributes + + Servers which allow subschema entries to be modified by clients MUST + support the following matching rules, as they are the equality + matching rules for several of the subschema attributes. + + ( 2.5.13.29 NAME 'integerFirstComponentMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) + + ( 2.5.13.30 NAME 'objectIdentifierFirstComponentMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) + + Implementors should note that the assertion syntax of these matching + rules, an INTEGER or OID, is different from the value syntax of + attributes for which this is the equality matching rule. + + If the client supplies an extensible filter using an + objectIdentifierFirstComponentMatch whose matchValue is in the + "descr" form, and the OID is not recognized by the server, then the + filter is Undefined. + +9. Security Considerations + +9.1. Disclosure + + 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. + +9.2. Use of Attribute Values in Security Applications + + The transformations of an AttributeValue value from its X.501 form to + an LDAP string representation are not always reversible back to the + same BER or DER form. An example of a situation which requires the + DER form of a distinguished name is the verification of an X.509 + certificate. + + For example, a distinguished name consisting of one RDN with one AVA, + in which the type is commonName and the value is of the TeletexString + choice with the letters 'Sam' would be represented in LDAP as the + string CN=Sam. Another distinguished name in which the value is + still 'Sam' but of the PrintableString choice would have the same + representation CN=Sam. + + Applications which require the reconstruction of the DER form of the + value SHOULD NOT use the string representation of attribute syntaxes + when converting a value to LDAP format. Instead it SHOULD use the + + + +Wahl, et. al. Standards Track [Page 28] + +RFC 2252 LADPv3 Attributes December 1997 + + + Binary syntax. + +10. Acknowledgements + + This document is based substantially on RFC 1778, written by Tim + Howes, Steve Kille, Wengyik Yeong and Colin Robbins. + + Many of the attribute syntax encodings defined in this and related + documents are adapted from those used in the QUIPU and the IC R3 + X.500 implementations. The contributions of the authors of both these + implementations in the specification of syntaxes are gratefully + acknowledged. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Wahl, et. al. Standards Track [Page 29] + +RFC 2252 LADPv3 Attributes December 1997 + + +11. Authors' Addresses + + Mark Wahl + Critical Angle Inc. + 4815 West Braker Lane #502-385 + Austin, TX 78759 + USA + + Phone: +1 512 372-3160 + EMail: M.Wahl@critical-angle.com + + Andy Coulbeck + Isode Inc. + 9390 Research Blvd Suite 305 + Austin, TX 78759 + USA + + Phone: +1 512 231-8993 + EMail: A.Coulbeck@isode.com + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd, MS MV068 + Mountain View, CA 94043 + USA + + Phone: +1 650 937-3419 + EMail: howes@netscape.com + + Steve Kille + Isode Limited + The Dome, The Square + Richmond + TW9 1DT + UK + + Phone: +44-181-332-9091 + EMail: S.Kille@isode.com + + + + + + + + + + + + + +Wahl, et. al. Standards Track [Page 30] + +RFC 2252 LADPv3 Attributes December 1997 + + +12. Bibliography + + [1] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + [2] The Directory: Selected Attribute Types. ITU-T Recommendation + X.520, 1993. + + [3] The Directory: Models. ITU-T Recommendation X.501, 1993. + + [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", RFC 2119, March 1997. + + [5] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access + Protocol (v3): UTF-8 String Representation of + Distinguished Names", RFC 2253, December 1997. + + [6] Kille, S., "A String Representation for Presentation Addresses", + RFC 1278, November 1991. + + [7] Terminal Equipment and Protocols for Telematic Services - + Standardization of Group 3 facsimile apparatus for document + transmission. CCITT, Recommendation T.4. + + [8] JPEG File Interchange Format (Version 1.02). Eric Hamilton, + C-Cube Microsystems, Milpitas, CA, September 1, 1992. + + [9] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO + 10646", RFC 2044, October 1996. + + [10] Universal Multiple-Octet Coded Character Set (UCS) - + Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 : + 1993 (With amendments). + + [11] Hardcastle-Kille, S., "Mapping between X.400(1988) / ISO 10021 + and RFC 822", RFC 1327, May 1992. + + [12] Wahl, M., "A Summary of the X.500(96) User Schema for use + with LDAPv3", RFC 2256, December 1997. + + [13] Crocker, D., "Standard of the Format of ARPA-Internet Text + Messages", STD 11, RFC 822, August 1982. + + [14] ISO 3166, "Codes for the representation of names of countries". + + [15] ITU-T Rec. E.123, Notation for national and international + telephone numbers, 1988. + + + + +Wahl, et. al. Standards Track [Page 31] + +RFC 2252 LADPv3 Attributes December 1997 + + +13. Full Copyright Statement + + Copyright (C) The Internet Society (1997). 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, et. al. Standards Track [Page 32] + diff --git a/source4/ldap_server/devdocs/rfc2253.txt b/source4/ldap_server/devdocs/rfc2253.txt new file mode 100644 index 0000000000..a7439eed77 --- /dev/null +++ b/source4/ldap_server/devdocs/rfc2253.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group M. Wahl +Request for Comments: 2253 Critical Angle Inc. +Obsoletes: 1779 S. Kille +Category: Standards Track Isode Ltd. + T. Howes + Netscape Communications Corp. + December 1997 + + + Lightweight Directory Access Protocol (v3): + UTF-8 String Representation of Distinguished Names + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +IESG Note + + This document describes a directory access protocol that provides + both read and update access. Update access requires secure + authentication, but this document does not mandate implementation of + any satisfactory authentication mechanisms. + + In accordance with RFC 2026, section 4.4.1, this specification is + being approved by IESG as a Proposed Standard despite this + limitation, for the following reasons: + + a. to encourage implementation and interoperability testing of + these protocols (with or without update access) before they + are deployed, and + + b. to encourage deployment and use of these protocols in read-only + applications. (e.g. applications where LDAPv3 is used as + a query language for directories which are updated by some + secure mechanism other than LDAP), and + + c. to avoid delaying the advancement and deployment of other Internet + standards-track protocols which require the ability to query, but + not update, LDAPv3 directory servers. + + + + +Wahl, et. al. Proposed Standard [Page 1] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + + Readers are hereby warned that until mandatory authentication + mechanisms are standardized, clients and servers written according to + this specification which make use of update functionality are + UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION + IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. + + Implementors are hereby discouraged from deploying LDAPv3 clients or + servers which implement the update functionality, until a Proposed + Standard for mandatory authentication in LDAPv3 has been approved and + published as an RFC. + +Abstract + + The X.500 Directory uses distinguished names as the primary keys to + entries in the directory. Distinguished Names are encoded in ASN.1 + in the X.500 Directory protocols. In the Lightweight Directory + Access Protocol, a string representation of distinguished names is + transferred. This specification defines the string format for + representing names, which is designed to give a clean representation + of commonly used distinguished names, while being able to represent + any distinguished name. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [6]. + +1. Background + + This specification assumes familiarity with X.500 [1], and the + concept of Distinguished Name. It is important to have a common + format to be able to unambiguously represent a distinguished name. + The primary goal of this specification is ease of encoding and + decoding. A secondary goal is to have names that are human readable. + It is not expected that LDAP clients with a human user interface + would display these strings directly to the user, but would most + likely be performing translations (such as expressing attribute type + names in one of the local national languages). + +2. Converting DistinguishedName from ASN.1 to a String + + In X.501 [2] the ASN.1 structure of distinguished name is defined as: + + DistinguishedName ::= RDNSequence + + RDNSequence ::= SEQUENCE OF RelativeDistinguishedName + + + + + + +Wahl, et. al. Proposed Standard [Page 2] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + + RelativeDistinguishedName ::= SET SIZE (1..MAX) OF + AttributeTypeAndValue + + AttributeTypeAndValue ::= SEQUENCE { + type AttributeType, + value AttributeValue } + + The following sections define the algorithm for converting from an + ASN.1 structured representation to a UTF-8 string representation. + +2.1. Converting the RDNSequence + + If the RDNSequence is an empty sequence, the result is the empty or + zero length string. + + Otherwise, the output consists of the string encodings of each + RelativeDistinguishedName in the RDNSequence (according to 2.2), + starting with the last element of the sequence and moving backwards + toward the first. + + The encodings of adjoining RelativeDistinguishedNames are separated + by a comma character (',' ASCII 44). + +2.2. Converting RelativeDistinguishedName + + When converting from an ASN.1 RelativeDistinguishedName to a string, + the output consists of the string encodings of each + AttributeTypeAndValue (according to 2.3), in any order. + + Where there is a multi-valued RDN, the outputs from adjoining + AttributeTypeAndValues are separated by a plus ('+' ASCII 43) + character. + +2.3. Converting AttributeTypeAndValue + + The AttributeTypeAndValue is encoded as the string representation of + the AttributeType, followed by an equals character ('=' ASCII 61), + followed by the string representation of the AttributeValue. The + encoding of the AttributeValue is given in section 2.4. + + If the AttributeType is in a published table of attribute types + associated with LDAP [4], then the type name string from that table + is used, otherwise it is encoded as the dotted-decimal encoding of + the AttributeType's OBJECT IDENTIFIER. The dotted-decimal notation is + described in [3]. As an example, strings for a few of the attribute + types frequently seen in RDNs include: + + + + + +Wahl, et. al. Proposed Standard [Page 3] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + + String X.500 AttributeType + ------------------------------ + CN commonName + L localityName + ST stateOrProvinceName + O organizationName + OU organizationalUnitName + C countryName + STREET streetAddress + DC domainComponent + UID userid + +2.4. Converting an AttributeValue from ASN.1 to a String + + If the AttributeValue is of a type which does not have a string + representation defined for it, then it is simply encoded as an + octothorpe character ('#' ASCII 35) followed by the hexadecimal + representation of each of the bytes of the BER encoding of the X.500 + AttributeValue. This form SHOULD be used if the AttributeType is of + the dotted-decimal form. + + Otherwise, if the AttributeValue is of a type which has a string + representation, the value is converted first to a UTF-8 string + according to its syntax specification (see for example section 6 of + [4]). + + If the UTF-8 string does not have any of the following characters + which need escaping, then that string can be used as the string + representation of the value. + + o a space or "#" character occurring at the beginning of the + string + + o a space character occurring at the end of the string + + o one of the characters ",", "+", """, "\", "<", ">" or ";" + + Implementations MAY escape other characters. + + If a character to be escaped is one of the list shown above, then it + is prefixed by a backslash ('\' ASCII 92). + + Otherwise the character to be escaped is replaced by a backslash and + two hex digits, which form a single byte in the code of the + character. + + Examples of the escaping mechanism are shown in section 5. + + + + +Wahl, et. al. Proposed Standard [Page 4] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + +3. Parsing a String back to a Distinguished Name + + The structure of the string is specified in a BNF grammar, based on + the grammar defined in RFC 822 [5]. Server implementations parsing a + DN string generated by an LDAPv2 client MUST also accept (and ignore) + the variants given in section 4 of this document. + +distinguishedName = [name] ; may be empty string + +name = name-component *("," name-component) + +name-component = attributeTypeAndValue *("+" attributeTypeAndValue) + +attributeTypeAndValue = attributeType "=" attributeValue + +attributeType = (ALPHA 1*keychar) / oid +keychar = ALPHA / DIGIT / "-" + +oid = 1*DIGIT *("." 1*DIGIT) + +attributeValue = string + +string = *( stringchar / pair ) + / "#" hexstring + / QUOTATION *( quotechar / pair ) QUOTATION ; only from v2 + +quotechar = <any character except "\" or QUOTATION > + +special = "," / "=" / "+" / "<" / ">" / "#" / ";" + +pair = "\" ( special / "\" / QUOTATION / hexpair ) +stringchar = <any character except one of special, "\" or QUOTATION > + +hexstring = 1*hexpair +hexpair = hexchar hexchar + +hexchar = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" + / "a" / "b" / "c" / "d" / "e" / "f" + +ALPHA = <any ASCII alphabetic character> + ; (decimal 65-90 and 97-122) +DIGIT = <any ASCII decimal digit> ; (decimal 48-57) +QUOTATION = <the ASCII double quotation mark character '"' decimal 34> + + + + + + + + +Wahl, et. al. Proposed Standard [Page 5] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + +4. Relationship with RFC 1779 and LDAPv2 + + The syntax given in this document is more restrictive than the syntax + in RFC 1779. Implementations parsing a string generated by an LDAPv2 + client MUST accept the syntax of RFC 1779. Implementations MUST NOT, + however, generate any of the RFC 1779 encodings which are not + described above in section 2. + + Implementations MUST allow a semicolon character to be used instead + of a comma to separate RDNs in a distinguished name, and MUST also + allow whitespace characters to be present on either side of the comma + or semicolon. The whitespace characters are ignored, and the + semicolon replaced with a comma. + + Implementations MUST allow an oid in the attribute type to be + prefixed by one of the character strings "oid." or "OID.". + + Implementations MUST allow for space (' ' ASCII 32) characters to be + present between name-component and ',', between attributeTypeAndValue + and '+', between attributeType and '=', and between '=' and + attributeValue. These space characters are ignored when parsing. + + Implementations MUST allow a value to be surrounded by quote ('"' + ASCII 34) characters, which are not part of the value. Inside the + quoted value, the following characters can occur without any + escaping: + + ",", "=", "+", "<", ">", "#" and ";" + +5. Examples + + This notation is designed to be convenient for common forms of name. + This section gives a few examples of distinguished names written + using this notation. First is a name containing three relative + distinguished names (RDNs): + + CN=Steve Kille,O=Isode Limited,C=GB + + Here is an example name containing three RDNs, in which the first RDN + is multi-valued: + + OU=Sales+CN=J. Smith,O=Widget Inc.,C=US + + This example shows the method of quoting of a comma in an + organization name: + + CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB + + + + +Wahl, et. al. Proposed Standard [Page 6] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + + An example name in which a value contains a carriage return + character: + + CN=Before\0DAfter,O=Test,C=GB + + An example name in which an RDN was of an unrecognized type. The + value is the BER encoding of an OCTET STRING containing two bytes + 0x48 and 0x69. + + 1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB + + Finally, an example of an RDN surname value consisting of 5 letters: + + Unicode Letter Description 10646 code UTF-8 Quoted + =============================== ========== ====== ======= + LATIN CAPITAL LETTER L U0000004C 0x4C L + LATIN SMALL LETTER U U00000075 0x75 u + LATIN SMALL LETTER C WITH CARON U0000010D 0xC48D \C4\8D + LATIN SMALL LETTER I U00000069 0x69 i + LATIN SMALL LETTER C WITH ACUTE U00000107 0xC487 \C4\87 + + Could be written in printable ASCII (useful for debugging purposes): + + SN=Lu\C4\8Di\C4\87 + +6. References + + [1] The Directory -- overview of concepts, models and services. + ITU-T Rec. X.500(1993). + + [2] The Directory -- Models. ITU-T Rec. X.501(1993). + + [3] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory + Access Protocol (v3)", RFC 2251, December 1997. + + [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", + RFC 2252, December 1997. + + [5] Crocker, D., "Standard of the Format of ARPA-Internet Text + Messages", STD 11, RFC 822, August 1982. + + [6] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", RFC 2119. + + + + + + + +Wahl, et. al. Proposed Standard [Page 7] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + +7. Security Considerations + +7.1. Disclosure + + Distinguished Names typically consist of descriptive information + about the entries they name, which can be people, organizations, + devices or other real-world objects. This frequently includes some + of the following kinds of information: + + - the common name of the object (i.e. a person's full name) + - an email or TCP/IP address + - its physical location (country, locality, city, street address) + - organizational attributes (such as department name or affiliation) + + Most countries have privacy laws regarding the publication of + information about people. + +7.2. Use of Distinguished Names in Security Applications + + The transformations of an AttributeValue value from its X.501 form to + an LDAP string representation are not always reversible back to the + same BER or DER form. An example of a situation which requires the + DER form of a distinguished name is the verification of an X.509 + certificate. + + For example, a distinguished name consisting of one RDN with one AVA, + in which the type is commonName and the value is of the TeletexString + choice with the letters 'Sam' would be represented in LDAP as the + string CN=Sam. Another distinguished name in which the value is + still 'Sam' but of the PrintableString choice would have the same + representation CN=Sam. + + Applications which require the reconstruction of the DER form of the + value SHOULD NOT use the string representation of attribute syntaxes + when converting a distinguished name to the LDAP format. Instead, + they SHOULD use the hexadecimal form prefixed by the octothorpe ('#') + as described in the first paragraph of section 2.4. + +8. Authors' Addresses + + Mark Wahl + Critical Angle Inc. + 4815 W. Braker Lane #502-385 + Austin, TX 78759 + USA + + EMail: M.Wahl@critical-angle.com + + + + +Wahl, et. al. Proposed Standard [Page 8] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + + Steve Kille + Isode Ltd. + The Dome + The Square + Richmond, Surrey + TW9 1DT + England + + Phone: +44-181-332-9091 + EMail: S.Kille@ISODE.COM + + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd, MS MV068 + Mountain View, CA 94043 + USA + + Phone: +1 650 937-3419 + EMail: howes@netscape.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Wahl, et. al. Proposed Standard [Page 9] + +RFC 2253 LADPv3 Distinguished Names December 1997 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (1997). 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, et. al. Proposed Standard [Page 10] + diff --git a/source4/ldap_server/devdocs/rfc2254.txt b/source4/ldap_server/devdocs/rfc2254.txt new file mode 100644 index 0000000000..323fdb00b7 --- /dev/null +++ b/source4/ldap_server/devdocs/rfc2254.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group T. Howes +Request for Comments: 2254 Netscape Communications Corp. +Category: Standards Track December 1997 + + + The String Representation of LDAP Search Filters + +1. Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +IESG Note + + This document describes a directory access protocol that provides + both read and update access. Update access requires secure + authentication, but this document does not mandate implementation of + any satisfactory authentication mechanisms. + + In accordance with RFC 2026, section 4.4.1, this specification is + being approved by IESG as a Proposed Standard despite this + limitation, for the following reasons: + + a. to encourage implementation and interoperability testing of + these protocols (with or without update access) before they + are deployed, and + + b. to encourage deployment and use of these protocols in read-only + applications. (e.g. applications where LDAPv3 is used as + a query language for directories which are updated by some + secure mechanism other than LDAP), and + + c. to avoid delaying the advancement and deployment of other Internet + standards-track protocols which require the ability to query, but + not update, LDAPv3 directory servers. + + + + + + + + + +Howes Standards Track [Page 1] + +RFC 2254 String Representation of LDAP December 1997 + + + Readers are hereby warned that until mandatory authentication + mechanisms are standardized, clients and servers written according to + this specification which make use of update functionality are + UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION + IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. + + Implementors are hereby discouraged from deploying LDAPv3 clients or + servers which implement the update functionality, until a Proposed + Standard for mandatory authentication in LDAPv3 has been approved and + published as an RFC. + +2. Abstract + + The Lightweight Directory Access Protocol (LDAP) [1] defines a + network representation of a search filter transmitted to an LDAP + server. Some applications may find it useful to have a common way of + representing these search filters in a human-readable form. This + document defines a human-readable string format for representing LDAP + search filters. + + This document replaces RFC 1960, extending the string LDAP filter + definition to include support for LDAP version 3 extended match + filters, and including support for representing the full range of + possible LDAP search filters. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Howes Standards Track [Page 2] + +RFC 2254 String Representation of LDAP December 1997 + + +3. LDAP Search Filter Definition + + An LDAPv3 search filter is defined in Section 4.5.1 of [1] as + follows: + + Filter ::= CHOICE { + and [0] SET OF Filter, + or [1] SET OF Filter, + not [2] Filter, + equalityMatch [3] AttributeValueAssertion, + substrings [4] SubstringFilter, + greaterOrEqual [5] AttributeValueAssertion, + lessOrEqual [6] AttributeValueAssertion, + present [7] AttributeDescription, + approxMatch [8] AttributeValueAssertion, + extensibleMatch [9] MatchingRuleAssertion + } + + SubstringFilter ::= SEQUENCE { + type AttributeDescription, + SEQUENCE OF CHOICE { + initial [0] LDAPString, + any [1] LDAPString, + final [2] LDAPString + } + } + + AttributeValueAssertion ::= SEQUENCE { + attributeDesc AttributeDescription, + attributeValue AttributeValue + } + + MatchingRuleAssertion ::= SEQUENCE { + matchingRule [1] MatchingRuleID OPTIONAL, + type [2] AttributeDescription OPTIONAL, + matchValue [3] AssertionValue, + dnAttributes [4] BOOLEAN DEFAULT FALSE + } + + AttributeDescription ::= LDAPString + + AttributeValue ::= OCTET STRING + + MatchingRuleID ::= LDAPString + + AssertionValue ::= OCTET STRING + + LDAPString ::= OCTET STRING + + + +Howes Standards Track [Page 3] + +RFC 2254 String Representation of LDAP December 1997 + + + where the LDAPString above is limited to the UTF-8 encoding of the + ISO 10646 character set [4]. The AttributeDescription is a string + representation of the attribute description and is defined in [1]. + The AttributeValue and AssertionValue OCTET STRING have the form + defined in [2]. The Filter is encoded for transmission over a + network using the Basic Encoding Rules defined in [3], with + simplifications described in [1]. + +4. String Search Filter Definition + + The string representation of an LDAP search filter is defined by the + following grammar, following the ABNF notation defined in [5]. The + filter format uses a prefix notation. + + filter = "(" filtercomp ")" + filtercomp = and / or / not / item + and = "&" filterlist + or = "|" filterlist + not = "!" filter + filterlist = 1*filter + item = simple / present / substring / extensible + simple = attr filtertype value + filtertype = equal / approx / greater / less + equal = "=" + approx = "~=" + greater = ">=" + less = "<=" + extensible = attr [":dn"] [":" matchingrule] ":=" value + / [":dn"] ":" matchingrule ":=" value + present = attr "=*" + substring = attr "=" [initial] any [final] + initial = value + any = "*" *(value "*") + final = value + attr = AttributeDescription from Section 4.1.5 of [1] + matchingrule = MatchingRuleId from Section 4.1.9 of [1] + value = AttributeValue from Section 4.1.6 of [1] + + The attr, matchingrule, and value constructs are as described in the + corresponding section of [1] given above. + + + + + + + + + + + +Howes Standards Track [Page 4] + +RFC 2254 String Representation of LDAP December 1997 + + + If a value should contain any of the following characters + + Character ASCII value + --------------------------- + * 0x2a + ( 0x28 + ) 0x29 + \ 0x5c + NUL 0x00 + + the character must be encoded as the backslash '\' character (ASCII + 0x5c) followed by the two hexadecimal digits representing the ASCII + value of the encoded character. The case of the two hexadecimal + digits is not significant. + + This simple escaping mechanism eliminates filter-parsing ambiguities + and allows any filter that can be represented in LDAP to be + represented as a NUL-terminated string. Other characters besides the + ones listed above may be escaped using this mechanism, for example, + non-printing characters. + + For example, the filter checking whether the "cn" attribute contained + a value with the character "*" anywhere in it would be represented as + "(cn=*\2a*)". + + Note that although both the substring and present productions in the + grammar above can produce the "attr=*" construct, this construct is + used only to denote a presence filter. + +5. Examples + + This section gives a few examples of search filters written using + this notation. + + (cn=Babs Jensen) + (!(cn=Tim Howes)) + (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) + (o=univ*of*mich*) + + The following examples illustrate the use of extensible matching. + + (cn:1.2.3.4.5:=Fred Flintstone) + (sn:dn:2.4.6.8.10:=Barney Rubble) + (o:dn:=Ace Industry) + (:dn:2.4.6.8.10:=Dino) + + + + + + +Howes Standards Track [Page 5] + +RFC 2254 String Representation of LDAP December 1997 + + + The second example illustrates the use of the ":dn" notation to + indicate that matching rule "2.4.6.8.10" should be used when making + comparisons, and that the attributes of an entry's distinguished name + should be considered part of the entry when evaluating the match. + + The third example denotes an equality match, except that DN + components should be considered part of the entry when doing the + match. + + The fourth example is a filter that should be applied to any + attribute supporting the matching rule given (since the attr has been + left off). Attributes supporting the matching rule contained in the + DN should also be considered. + + The following examples illustrate the use of the escaping mechanism. + + (o=Parens R Us \28for all your parenthetical needs\29) + (cn=*\2A*) + (filename=C:\5cMyFile) + (bin=\00\00\00\04) + (sn=Lu\c4\8di\c4\87) + + The first example shows the use of the escaping mechanism to + represent parenthesis characters. The second shows how to represent a + "*" in a value, preventing it from being interpreted as a substring + indicator. The third illustrates the escaping of the backslash + character. + + The fourth example shows a filter searching for the four-byte value + 0x00000004, illustrating the use of the escaping mechanism to + represent arbitrary data, including NUL characters. + + The final example illustrates the use of the escaping mechanism to + represent various non-ASCII UTF-8 characters. + +6. Security Considerations + + This memo describes a string representation of LDAP search filters. + While the representation itself has no known security implications, + LDAP search filters do. They are interpreted by LDAP servers to + select entries from which data is retrieved. LDAP servers should + take care to protect the data they maintain from unauthorized access. + + + + + + + + + +Howes Standards Track [Page 6] + +RFC 2254 String Representation of LDAP December 1997 + + +7. References + + [1] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + [2] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", RFC + 2252, December 1997. + + [3] Specification of ASN.1 encoding rules: Basic, Canonical, and + Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994. + + [4] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO + 10646", RFC 2044, October 1996. + + [5] Crocker, D., "Standard for the Format of ARPA Internet Text + Messages", STD 11, RFC 822, August 1982. + +8. Author's Address + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Road + Mountain View, CA 94043 + USA + + Phone: +1 415 937-3419 + EMail: howes@netscape.com + + + + + + + + + + + + + + + + + + + + + + + +Howes Standards Track [Page 7] + +RFC 2254 String Representation of LDAP December 1997 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (1997). 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. + + + + + + + + + + + + + + + + + + + + + + + + +Howes Standards Track [Page 8] + diff --git a/source4/ldap_server/devdocs/rfc2255.txt b/source4/ldap_server/devdocs/rfc2255.txt new file mode 100644 index 0000000000..a03567154e --- /dev/null +++ b/source4/ldap_server/devdocs/rfc2255.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group T. Howes +Request for Comments: 2255 M. Smith +Category: Standards Track Netscape Communications Corp. + December 1997 + + + The LDAP URL Format + +1. Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +IESG NOTE + + This document describes a directory access protocol that provides + both read and update access. Update access requires secure + authentication, but this document does not mandate implementation of + any satisfactory authentication mechanisms. + + In accordance with RFC 2026, section 4.4.1, this specification is + being approved by IESG as a Proposed Standard despite this + limitation, for the following reasons: + + a. to encourage implementation and interoperability testing of + these protocols (with or without update access) before they + are deployed, and + + b. to encourage deployment and use of these protocols in read-only + applications. (e.g. applications where LDAPv3 is used as + a query language for directories which are updated by some + secure mechanism other than LDAP), and + + c. to avoid delaying the advancement and deployment of other Internet + standards-track protocols which require the ability to query, but + not update, LDAPv3 directory servers. + + + + + + + + +Howes & Smith Standards Track [Page 1] + +RFC 2255 LDAP URL Format December 1997 + + + Readers are hereby warned that until mandatory authentication + mechanisms are standardized, clients and servers written according to + this specification which make use of update functionality are + UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION + IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. + + Implementors are hereby discouraged from deploying LDAPv3 clients or + servers which implement the update functionality, until a Proposed + Standard for mandatory authentication in LDAPv3 has been approved and + published as an RFC. + +2. Abstract + + LDAP is the Lightweight Directory Access Protocol, defined in [1], + [2] and [3]. This document describes a format for an LDAP Uniform + Resource Locator. The format describes an LDAP search operation to + perform to retrieve information from an LDAP directory. This document + replaces RFC 1959. It updates the LDAP URL format for version 3 of + LDAP and clarifies how LDAP URLs are resolved. This document also + defines an extension mechanism for LDAP URLs, so that future + documents can extend their functionality, for example, to provide + access to new LDAPv3 extensions as they are defined. + + The key words "MUST", "MAY", and "SHOULD" used in this document are + to be interpreted as described in [6]. + + + + + + + + + + + + + + + + + + + + + + + + + + +Howes & Smith Standards Track [Page 2] + +RFC 2255 LDAP URL Format December 1997 + + +3. URL Definition + + An LDAP URL begins with the protocol prefix "ldap" and is defined by + the following grammar. + + ldapurl = scheme "://" [hostport] ["/" + [dn ["?" [attributes] ["?" [scope] + ["?" [filter] ["?" extensions]]]]]] + scheme = "ldap" + attributes = attrdesc *("," attrdesc) + scope = "base" / "one" / "sub" + dn = distinguishedName from Section 3 of [1] + hostport = hostport from Section 5 of RFC 1738 [5] + attrdesc = AttributeDescription from Section 4.1.5 of [2] + filter = filter from Section 4 of [4] + extensions = extension *("," extension) + extension = ["!"] extype ["=" exvalue] + extype = token / xtoken + exvalue = LDAPString from section 4.1.2 of [2] + token = oid from section 4.1 of [3] + xtoken = ("X-" / "x-") token + + The "ldap" prefix indicates an entry or entries residing in the LDAP + server running on the given hostname at the given portnumber. The + default LDAP port is TCP port 389. If no hostport is given, the + client must have some apriori knowledge of an appropriate LDAP server + to contact. + + The dn is an LDAP Distinguished Name using the string format + described in [1]. It identifies the base object of the LDAP search. + + ldapurl = scheme "://" [hostport] ["/" + [dn ["?" [attributes] ["?" [scope] + ["?" [filter] ["?" extensions]]]]]] + scheme = "ldap" + attributes = attrdesc *("," attrdesc) + scope = "base" / "one" / "sub" + dn = distinguishedName from Section 3 of [1] + hostport = hostport from Section 5 of RFC 1738 [5] + attrdesc = AttributeDescription from Section 4.1.5 of [2] + filter = filter from Section 4 of [4] + extensions = extension *("," extension) + extension = ["!"] extype ["=" exvalue] + extype = token / xtoken + exvalue = LDAPString from section 4.1.2 of [2] + token = oid from section 4.1 of [3] + xtoken = ("X-" / "x-") token + + + + +Howes & Smith Standards Track [Page 3] + +RFC 2255 LDAP URL Format December 1997 + + + The "ldap" prefix indicates an entry or entries residing in the LDAP + server running on the given hostname at the given portnumber. The + default LDAP port is TCP port 389. If no hostport is given, the + client must have some apriori knowledge of an appropriate LDAP server + to contact. + + The dn is an LDAP Distinguished Name using the string format + described in [1]. It identifies the base object of the LDAP search. + + The attributes construct is used to indicate which attributes should + be returned from the entry or entries. Individual attrdesc names are + as defined for AttributeDescription in [2]. If the attributes part + is omitted, all user attributes of the entry or entries should be + requested (e.g., by setting the attributes field + AttributeDescriptionList in the LDAP search request to a NULL list, + or (in LDAPv3) by requesting the special attribute name "*"). + + The scope construct is used to specify the scope of the search to + perform in the given LDAP server. The allowable scopes are "base" + for a base object search, "one" for a one-level search, or "sub" for + a subtree search. If scope is omitted, a scope of "base" is assumed. + + The filter is used to specify the search filter to apply to entries + within the specified scope during the search. It has the format + specified in [4]. If filter is omitted, a filter of + "(objectClass=*)" is assumed. + + The extensions construct provides the LDAP URL with an extensibility + mechanism, allowing the capabilities of the URL to be extended in the + future. Extensions are a simple comma-separated list of type=value + pairs, where the =value portion MAY be omitted for options not + requiring it. Each type=value pair is a separate extension. These + LDAP URL extensions are not necessarily related to any of the LDAPv3 + extension mechanisms. Extensions may be supported or unsupported by + the client resolving the URL. An extension prefixed with a '!' + character (ASCII 33) is critical. An extension not prefixed with a ' + !' character is non-critical. + + If an extension is supported by the client, the client MUST obey the + extension if the extension is critical. The client SHOULD obey + supported extensions that are non-critical. + + If an extension is unsupported by the client, the client MUST NOT + process the URL if the extension is critical. If an unsupported + extension is non-critical, the client MUST ignore the extension. + + + + + + +Howes & Smith Standards Track [Page 4] + +RFC 2255 LDAP URL Format December 1997 + + + If a critical extension cannot be processed successfully by the + client, the client MUST NOT process the URL. If a non-critical + extension cannot be processed successfully by the client, the client + SHOULD ignore the extension. + + Extension types prefixed by "X-" or "x-" are reserved for use in + bilateral agreements between communicating parties. Other extension + types MUST be defined in this document, or in other standards-track + documents. + + One LDAP URL extension is defined in this document in the next + section. Other documents or a future version of this document MAY + define other extensions. + + Note that any URL-illegal characters (e.g., spaces), URL special + characters (as defined in section 2.2 of RFC 1738) and the reserved + character '?' (ASCII 63) occurring inside a dn, filter, or other + element of an LDAP URL MUST be escaped using the % method described + in RFC 1738 [5]. If a comma character ',' occurs inside an extension + value, the character MUST also be escaped using the % method. + +4. The Bindname Extension + + This section defines an LDAP URL extension for representing the + distinguished name for a client to use when authenticating to an LDAP + directory during resolution of an LDAP URL. Clients MAY implement + this extension. + + The extension type is "bindname". The extension value is the + distinguished name of the directory entry to authenticate as, in the + same form as described for dn in the grammar above. The dn may be the + NULL string to specify unauthenticated access. The extension may be + either critical (prefixed with a '!' character) or non-critical (not + prefixed with a '!' character). + + If the bindname extension is critical, the client resolving the URL + MUST authenticate to the directory using the given distinguished name + and an appropriate authentication method. Note that for a NULL + distinguished name, no bind MAY be required to obtain anonymous + access to the directory. If the extension is non-critical, the client + MAY bind to the directory using the given distinguished name. + +5. URL Processing + + This section describes how an LDAP URL SHOULD be resolved by a + client. + + + + + +Howes & Smith Standards Track [Page 5] + +RFC 2255 LDAP URL Format December 1997 + + + First, the client obtains a connection to the LDAP server referenced + in the URL, or an LDAP server of the client's choice if no LDAP + server is explicitly referenced. This connection MAY be opened + specifically for the purpose of resolving the URL or the client MAY + reuse an already open connection. The connection MAY provide + confidentiality, integrity, or other services, e.g., using TLS. Use + of security services is at the client's discretion if not specified + in the URL. + + Next, the client authenticates itself to the LDAP server. This step + is optional, unless the URL contains a critical bindname extension + with a non-NULL value. If a bindname extension is given, the client + proceeds according to the section above. + + If a bindname extension is not specified, the client MAY bind to the + directory using a appropriate dn and authentication method of its own + choosing (including NULL authentication). + + Next, the client performs the LDAP search operation specified in the + URL. Additional fields in the LDAP protocol search request, such as + sizelimit, timelimit, deref, and anything else not specified or + defaulted in the URL specification, MAY be set at the client's + discretion. + + Once the search has completed, the client MAY close the connection to + the LDAP server, or the client MAY keep the connection open for + future use. + +6. Examples + + The following are some example LDAP URLs using the format defined + above. The first example is an LDAP URL referring to the University + of Michigan entry, available from an LDAP server of the client's + choosing: + + ldap:///o=University%20of%20Michigan,c=US + + The next example is an LDAP URL referring to the University of + Michigan entry in a particular ldap server: + + ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US + + Both of these URLs correspond to a base object search of the + "o=University of Michigan, c=US" entry using a filter of + "(objectclass=*)", requesting all attributes. + + The next example is an LDAP URL referring to only the postalAddress + attribute of the University of Michigan entry: + + + +Howes & Smith Standards Track [Page 6] + +RFC 2255 LDAP URL Format December 1997 + + + ldap://ldap.itd.umich.edu/o=University%20of%20Michigan, + c=US?postalAddress + + The corresponding LDAP search operation is the same as in the + previous example, except that only the postalAddress attribute is + requested. + + The next example is an LDAP URL referring to the set of entries found + by querying the given LDAP server on port 6666 and doing a subtree + search of the University of Michigan for any entry with a common name + of "Babs Jensen", retrieving all attributes: + + ldap://host.com:6666/o=University%20of%20Michigan, + c=US??sub?(cn=Babs%20Jensen) + + The next example is an LDAP URL referring to all children of the c=GB + entry: + + ldap://ldap.itd.umich.edu/c=GB?objectClass?one + + The objectClass attribute is requested to be returned along with the + entries, and the default filter of "(objectclass=*)" is used. + + The next example is an LDAP URL to retrieve the mail attribute for + the LDAP entry named "o=Question?,c=US" is given below, illustrating + the use of the escaping mechanism on the reserved character '?'. + + ldap://ldap.question.com/o=Question%3f,c=US?mail + + The next example illustrates the interaction between LDAP and URL + quoting mechanisms. + + ldap://ldap.netscape.com/o=Babsco,c=US??(int=%5c00%5c00%5c00%5c04) + + The filter in this example uses the LDAP escaping mechanism of \ to + encode three zero or null bytes in the value. In LDAP, the filter + would be written as (int=\00\00\00\04). Because the \ character must + be escaped in a URL, the \'s are escaped as %5c in the URL encoding. + + The final example shows the use of the bindname extension to specify + the dn a client should use for authentication when resolving the URL. + + ldap:///??sub??bindname=cn=Manager%2co=Foo + ldap:///??sub??!bindname=cn=Manager%2co=Foo + + The two URLs are the same, except that the second one marks the + bindname extension as critical. Notice the use of the % encoding + method to encode the comma in the distinguished name value in the + + + +Howes & Smith Standards Track [Page 7] + +RFC 2255 LDAP URL Format December 1997 + + + bindname extension. + +7. Security Considerations + + General URL security considerations discussed in [5] are relevant for + LDAP URLs. + + The use of security mechanisms when processing LDAP URLs requires + particular care, since clients may encounter many different servers + via URLs, and since URLs are likely to be processed automatically, + without user intervention. A client SHOULD have a user-configurable + policy about which servers to connect to using which security + mechanisms, and SHOULD NOT make connections that are inconsistent + with this policy. + + Sending authentication information, no matter the mechanism, may + violate a user's privacy requirements. In the absence of specific + policy permitting authentication information to be sent to a server, + a client should use an anonymous connection. (Note that clients + conforming to previous LDAP URL specifications, where all connections + are anonymous and unprotected, are consistent with this + specification; they simply have the default security policy.) + + Some authentication methods, in particular reusable passwords sent to + the server, may reveal easily-abused information to the remote server + or to eavesdroppers in transit, and should not be used in URL + processing unless explicitly permitted by policy. Confirmation by + the human user of the use of authentication information is + appropriate in many circumstances. Use of strong authentication + methods that do not reveal sensitive information is much preferred. + + The LDAP URL format allows the specification of an arbitrary LDAP + search operation to be performed when evaluating the LDAP URL. + Following an LDAP URL may cause unexpected results, for example, the + retrieval of large amounts of data, the initiation of a long-lived + search, etc. The security implications of resolving an LDAP URL are + the same as those of resolving an LDAP search query. + +8. Acknowledgements + + The LDAP URL format was originally defined at the University of + Michigan. This material is based upon work supported by the National + Science Foundation under Grant No. NCR-9416667. The support of both + the University of Michigan and the National Science Foundation is + gratefully acknowledged. + + + + + + +Howes & Smith Standards Track [Page 8] + +RFC 2255 LDAP URL Format December 1997 + + + Several people have made valuable comments on this document. In + particular RL "Bob" Morgan and Mark Wahl deserve special thanks for + their contributions. + +9. References + + [1] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access + Protocol (v3): UTF-8 String Representation of Distinguished Names", + RFC 2253, December 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. + + [4] Howes, T., "A String Representation of LDAP Search Filters", RFC + 2254, December 1997. + + [5] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource + Locators (URL)," RFC 1738, December 1994. + + [6] Bradner, S., "Key Words for use in RFCs to Indicate Requirement + Levels," RFC 2119, March 1997. + +Authors' Addresses + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd. + Mountain View, CA 94043 + USA + + Phone: +1 415 937-3419 + EMail: howes@netscape.com + + + Mark Smith + Netscape Communications Corp. + 501 E. Middlefield Rd. + Mountain View, CA 94043 + USA + + Phone: +1 415 937-3477 + EMail: mcs@netscape.com + + + + + +Howes & Smith Standards Track [Page 9] + +RFC 2255 LDAP URL Format December 1997 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1997). 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. + + + + + + + + + + + + + + + + + + + + + + + + +Howes & Smith Standards Track [Page 10] + diff --git a/source4/ldap_server/devdocs/rfc2256.txt b/source4/ldap_server/devdocs/rfc2256.txt new file mode 100644 index 0000000000..69706f65a6 --- /dev/null +++ b/source4/ldap_server/devdocs/rfc2256.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group M. Wahl +Request for Comments: 2256 Critical Angle Inc. +Category: Standards Track December 1997 + + + A Summary of the X.500(96) User Schema for use with LDAPv3 + +1. Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +IESG Note + + This document describes a directory access protocol that provides + both read and update access. Update access requires secure + authentication, but this document does not mandate implementation of + any satisfactory authentication mechanisms. + + In accordance with RFC 2026, section 4.4.1, this specification is + being approved by IESG as a Proposed Standard despite this + limitation, for the following reasons: + + a. to encourage implementation and interoperability testing of + these protocols (with or without update access) before they + are deployed, and + + b. to encourage deployment and use of these protocols in read-only + applications. (e.g. applications where LDAPv3 is used as + a query language for directories which are updated by some + secure mechanism other than LDAP), and + + c. to avoid delaying the advancement and deployment of other Internet + standards-track protocols which require the ability to query, but + not update, LDAPv3 directory servers. + + Readers are hereby warned that until mandatory authentication + mechanisms are standardized, clients and servers written according to + this specification which make use of update functionality are + UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION + IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. + + + +Wahl Standards Track [Page 1] + +RFC 2256 LDAPv3 Schema December 1997 + + + Implementors are hereby discouraged from deploying LDAPv3 clients or + servers which implement the update functionality, until a Proposed + Standard for mandatory authentication in LDAPv3 has been approved and + published as an RFC. + +2. Abstract + + This document provides an overview of the attribute types and object + classes defined by the ISO and ITU-T committees in the X.500 + documents, in particular those intended for use by directory clients. + This is the most widely used schema for LDAP/X.500 directories, and + many other schema definitions for white pages objects use it as a + basis. This document does not cover attributes used for the + administration of X.500 directory servers, nor does it include + attributes defined by other ISO/ITU-T documents. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [6]. + +3. General Issues + + This document references syntaxes given in section 6 of this document + and section 6 of [1]. Matching rules are listed in section 8 of this + document and section 8 of [1]. + + The attribute type and object class definitions are written using the + BNF form of AttributeTypeDescription and ObjectClassDescription given + in [1]. Lines have been folded for readability. + +4. Source + + The schema definitions in this document are based on those found in + X.500 [2],[3],[4],[5], and updates to these documents, specifically: + + Sections Source + ============ ============ + 5.1 - 5.2 X.501(93) + 5.3 - 5.36 X.520(88) + 5.37 - 5.41 X.509(93) + 5.42 - 5.52 X.520(93) + 5.53 - 5.54 X.509(96) + 5.55 X.520(96) + 6.1 RFC 1274 + 6.2 (new syntax) + 6.3 - 6.6 RFC 1274 + 7.1 - 7.2 X.501(93) + 7.3 - 7.18 X.521(93) + + + +Wahl Standards Track [Page 2] + +RFC 2256 LDAPv3 Schema December 1997 + + + 7.19 - 7.21 X.509(96) + 7.22 X.521(96) + + Some attribute names are different from those found in X.520(93). + + Three new attributes supportedAlgorithms, deltaRevocationList and + dmdName, and the objectClass dmd, are defined in the X.500(96) + documents. + +5. Attribute Types + + An LDAP server implementation SHOULD recognize the attribute types + described in this section. + +5.1. objectClass + + The values of the objectClass attribute describe the kind of object + which an entry represents. The objectClass attribute is present in + every entry, with at least two values. One of the values is either + "top" or "alias". + + ( 2.5.4.0 NAME 'objectClass' EQUALITY objectIdentifierMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) + +5.2. aliasedObjectName + + The aliasedObjectName attribute is used by the directory service if + the entry containing this attribute is an alias. + + ( 2.5.4.1 NAME 'aliasedObjectName' EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE ) + +5.3. knowledgeInformation + + This attribute is no longer used. + + ( 2.5.4.2 NAME 'knowledgeInformation' EQUALITY caseIgnoreMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} ) + +5.4. cn + + This is the X.500 commonName attribute, which contains a name of an + object. If the object corresponds to a person, it is typically the + person's full name. + + ( 2.5.4.3 NAME 'cn' SUP name ) + + + + + +Wahl Standards Track [Page 3] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.5. sn + + This is the X.500 surname attribute, which contains the family name + of a person. + + ( 2.5.4.4 NAME 'sn' SUP name ) + +5.6. serialNumber + + This attribute contains the serial number of a device. + + ( 2.5.4.5 NAME 'serialNumber' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.44{64} ) + +5.7. c + + This attribute contains a two-letter ISO 3166 country code + (countryName). + + ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) + +5.8. l + + This attribute contains the name of a locality, such as a city, + county or other geographic region (localityName). + + ( 2.5.4.7 NAME 'l' SUP name ) + +5.9. st + + This attribute contains the full name of a state or province + (stateOrProvinceName). + + ( 2.5.4.8 NAME 'st' SUP name ) + +5.10. street + + This attribute contains the physical address of the object to which + the entry corresponds, such as an address for package delivery + (streetAddress). + + ( 2.5.4.9 NAME 'street' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} ) + + + + + + +Wahl Standards Track [Page 4] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.11. o + + This attribute contains the name of an organization + (organizationName). + + ( 2.5.4.10 NAME 'o' SUP name ) + +5.12. ou + + This attribute contains the name of an organizational unit + (organizationalUnitName). + + ( 2.5.4.11 NAME 'ou' SUP name ) + +5.13. title + + This attribute contains the title, such as "Vice President", of a + person in their organizational context. The "personalTitle" + attribute would be used for a person's title independent of their job + function. + + ( 2.5.4.12 NAME 'title' SUP name ) + +5.14. description + + This attribute contains a human-readable description of the object. + + ( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) + +5.15. searchGuide + + This attribute is for use by X.500 clients in constructing search + filters. It is obsoleted by enhancedSearchGuide, described below in + 5.48. + + ( 2.5.4.14 NAME 'searchGuide' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.25 ) + +5.16. businessCategory + + This attribute describes the kind of business performed by an + organization. + + ( 2.5.4.15 NAME 'businessCategory' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} ) + + + +Wahl Standards Track [Page 5] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.17. postalAddress + + ( 2.5.4.16 NAME 'postalAddress' EQUALITY caseIgnoreListMatch + SUBSTR caseIgnoreListSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) + +5.18. postalCode + + ( 2.5.4.17 NAME 'postalCode' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{40} ) + +5.19. postOfficeBox + + ( 2.5.4.18 NAME 'postOfficeBox' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{40} ) + +5.20. physicalDeliveryOfficeName + + ( 2.5.4.19 NAME 'physicalDeliveryOfficeName' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} ) + +5.21. telephoneNumber + + ( 2.5.4.20 NAME 'telephoneNumber' EQUALITY telephoneNumberMatch + SUBSTR telephoneNumberSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.50{32} ) + +5.22. telexNumber + + ( 2.5.4.21 NAME 'telexNumber' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.52 ) + +5.23. teletexTerminalIdentifier + + ( 2.5.4.22 NAME 'teletexTerminalIdentifier' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.51 ) + +5.24. facsimileTelephoneNumber + + ( 2.5.4.23 NAME 'facsimileTelephoneNumber' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.22 ) + + + + + + + +Wahl Standards Track [Page 6] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.25. x121Address + + ( 2.5.4.24 NAME 'x121Address' EQUALITY numericStringMatch + SUBSTR numericStringSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.36{15} ) + +5.26. internationaliSDNNumber + + ( 2.5.4.25 NAME 'internationaliSDNNumber' EQUALITY numericStringMatch + SUBSTR numericStringSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.36{16} ) + +5.27. registeredAddress + + This attribute holds a postal address suitable for reception of + telegrams or expedited documents, where it is necessary to have the + recipient accept delivery. + + ( 2.5.4.26 NAME 'registeredAddress' SUP postalAddress + SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) + +5.28. destinationIndicator + + This attribute is used for the telegram service. + + ( 2.5.4.27 NAME 'destinationIndicator' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.44{128} ) + +5.29. preferredDeliveryMethod + + ( 2.5.4.28 NAME 'preferredDeliveryMethod' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.14 + SINGLE-VALUE ) + +5.30. presentationAddress + + This attribute contains an OSI presentation address. + + ( 2.5.4.29 NAME 'presentationAddress' + EQUALITY presentationAddressMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.43 + SINGLE-VALUE ) + + + + + + + + +Wahl Standards Track [Page 7] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.31. supportedApplicationContext + + This attribute contains the identifiers of OSI application contexts. + + ( 2.5.4.30 NAME 'supportedApplicationContext' + EQUALITY objectIdentifierMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) + +5.32. member + + ( 2.5.4.31 NAME 'member' SUP distinguishedName ) + +5.33. owner + + ( 2.5.4.32 NAME 'owner' SUP distinguishedName ) + +5.34. roleOccupant + + ( 2.5.4.33 NAME 'roleOccupant' SUP distinguishedName ) + +5.35. seeAlso + + ( 2.5.4.34 NAME 'seeAlso' SUP distinguishedName ) + +5.36. userPassword + + ( 2.5.4.35 NAME 'userPassword' EQUALITY octetStringMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40{128} ) + + Passwords are stored using an Octet String syntax and are not + encrypted. Transfer of cleartext passwords are strongly discouraged + where the underlying transport service cannot guarantee + confidentiality and may result in disclosure of the password to + unauthorized parties. + +5.37. userCertificate + + This attribute is to be stored and requested in the binary form, as + 'userCertificate;binary'. + + ( 2.5.4.36 NAME 'userCertificate' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 ) + +5.38. cACertificate + + This attribute is to be stored and requested in the binary form, as + 'cACertificate;binary'. + + + + +Wahl Standards Track [Page 8] + +RFC 2256 LDAPv3 Schema December 1997 + + + ( 2.5.4.37 NAME 'cACertificate' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 ) + +5.39. authorityRevocationList + + This attribute is to be stored and requested in the binary form, as + 'authorityRevocationList;binary'. + + ( 2.5.4.38 NAME 'authorityRevocationList' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 ) + +5.40. certificateRevocationList + + This attribute is to be stored and requested in the binary form, as + 'certificateRevocationList;binary'. + + ( 2.5.4.39 NAME 'certificateRevocationList' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 ) + +5.41. crossCertificatePair + + This attribute is to be stored and requested in the binary form, as + 'crossCertificatePair;binary'. + + ( 2.5.4.40 NAME 'crossCertificatePair' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.10 ) + +5.42. name + + The name attribute type is the attribute supertype from which string + attribute types typically used for naming may be formed. It is + unlikely that values of this type itself will occur in an entry. LDAP + server implementations which do not support attribute subtyping need + not recognize this attribute in requests. Client implementations + MUST NOT assume that LDAP servers are capable of performing attribute + subtyping. + + ( 2.5.4.41 NAME 'name' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} ) + +5.43. givenName + + The givenName attribute is used to hold the part of a person's name + which is not their surname nor middle name. + + ( 2.5.4.42 NAME 'givenName' SUP name ) + + + + +Wahl Standards Track [Page 9] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.44. initials + + The initials attribute contains the initials of some or all of an + individuals names, but not the surname(s). + + ( 2.5.4.43 NAME 'initials' SUP name ) + +5.45. generationQualifier + + The generationQualifier attribute contains the part of the name which + typically is the suffix, as in "IIIrd". + + ( 2.5.4.44 NAME 'generationQualifier' SUP name ) + +5.46. x500UniqueIdentifier + + The x500UniqueIdentifier attribute is used to distinguish between + objects when a distinguished name has been reused. This is a + different attribute type from both the "uid" and "uniqueIdentifier" + types. + + ( 2.5.4.45 NAME 'x500UniqueIdentifier' EQUALITY bitStringMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 ) + +5.47. dnQualifier + + The dnQualifier attribute type specifies disambiguating information + to add to the relative distinguished name of an entry. It is + intended for use when merging data from multiple sources in order to + prevent conflicts between entries which would otherwise have the same + name. It is recommended that the value of the dnQualifier attribute + be the same for all entries from a particular source. + + ( 2.5.4.46 NAME 'dnQualifier' EQUALITY caseIgnoreMatch + ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 ) + +5.48. enhancedSearchGuide + + This attribute is for use by X.500 clients in constructing search + filters. + + ( 2.5.4.47 NAME 'enhancedSearchGuide' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.21 ) + + + + + + + +Wahl Standards Track [Page 10] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.49. protocolInformation + + This attribute is used in conjunction with the presentationAddress + attribute, to provide additional information to the OSI network + service. + + ( 2.5.4.48 NAME 'protocolInformation' + EQUALITY protocolInformationMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.42 ) + +5.50. distinguishedName + + This attribute type is not used as the name of the object itself, but + it is instead a base type from which attributes with DN syntax + inherit. + + It is unlikely that values of this type itself will occur in an + entry. LDAP server implementations which do not support attribute + subtyping need not recognize this attribute in requests. Client + implementations MUST NOT assume that LDAP servers are capable of + performing attribute subtyping. + + ( 2.5.4.49 NAME 'distinguishedName' EQUALITY distinguishedNameMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) + +5.51. uniqueMember + + ( 2.5.4.50 NAME 'uniqueMember' EQUALITY uniqueMemberMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.34 ) + +5.52. houseIdentifier + + This attribute is used to identify a building within a location. + + ( 2.5.4.51 NAME 'houseIdentifier' EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} ) + +5.53. supportedAlgorithms + + This attribute is to be stored and requested in the binary form, as + 'supportedAlgorithms;binary'. + + ( 2.5.4.52 NAME 'supportedAlgorithms' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.49 ) + + + + + + +Wahl Standards Track [Page 11] + +RFC 2256 LDAPv3 Schema December 1997 + + +5.54. deltaRevocationList + + This attribute is to be stored and requested in the binary form, as + 'deltaRevocationList;binary'. + + ( 2.5.4.53 NAME 'deltaRevocationList' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 ) + +5.55. dmdName + + The value of this attribute specifies a directory management domain + (DMD), the administrative authority which operates the directory + server. + + ( 2.5.4.54 NAME 'dmdName' SUP name ) + +6. Syntaxes + + Servers SHOULD recognize the syntaxes defined in this section. Each + syntax begins with a sample value of the ldapSyntaxes attribute which + defines the OBJECT IDENTIFIER of the syntax. The descriptions of + syntax names are not carried in protocol, and are not guaranteed to + be unique. + +6.1. Delivery Method + + ( 1.3.6.1.4.1.1466.115.121.1.14 DESC 'Delivery Method' ) + + Values in this syntax are encoded according to the following BNF: + + delivery-value = pdm / ( pdm whsp "$" whsp delivery-value ) + + pdm = "any" / "mhs" / "physical" / "telex" / "teletex" / + "g3fax" / "g4fax" / "ia5" / "videotex" / "telephone" + + Example: + + telephone + +6.2. Enhanced Guide + + ( 1.3.6.1.4.1.1466.115.121.1.21 DESC 'Enhanced Guide' ) + + Values in this syntax are encoded according to the following BNF: + + EnhancedGuide = woid whsp "#" whsp criteria whsp "#" whsp subset + + subset = "baseobject" / "oneLevel" / "wholeSubtree" + + + +Wahl Standards Track [Page 12] + +RFC 2256 LDAPv3 Schema December 1997 + + + The criteria production is defined in the Guide syntax below. This + syntax has been added subsequent to RFC 1778. + + Example: + + person#(sn)#oneLevel + +6.3. Guide + + ( 1.3.6.1.4.1.1466.115.121.1.25 DESC 'Guide' ) + + Values in this syntax are encoded according to the following BNF: + + guide-value = [ object-class "#" ] criteria + + object-class = woid + + criteria = criteria-item / criteria-set / ( "!" criteria ) + + criteria-set = ( [ "(" ] criteria "&" criteria-set [ ")" ] ) / + ( [ "(" ] criteria "|" criteria-set [ ")" ] ) + + criteria-item = [ "(" ] attributetype "$" match-type [ ")" ] + + match-type = "EQ" / "SUBSTR" / "GE" / "LE" / "APPROX" + + This syntax should not be used for defining new attributes. + +6.4. Octet String + + ( 1.3.6.1.4.1.1466.115.121.1.40 DESC 'Octet String' ) + + Values in this syntax are encoded as octet strings. + + + Example: + + secret + +6.5. Teletex Terminal Identifier + + ( 1.3.6.1.4.1.1466.115.121.1.51 DESC 'Teletex Terminal Identifier' ) + + Values in this syntax are encoded according to the following BNF: + + teletex-id = ttx-term 0*("$" ttx-param) + + ttx-term = printablestring + + + +Wahl Standards Track [Page 13] + +RFC 2256 LDAPv3 Schema December 1997 + + + ttx-param = ttx-key ":" ttx-value + + ttx-key = "graphic" / "control" / "misc" / "page" / "private" + + ttx-value = octetstring + + In the above, the first printablestring is the encoding of the first + portion of the teletex terminal identifier to be encoded, and the + subsequent 0 or more octetstrings are subsequent portions of the + teletex terminal identifier. + +6.6. Telex Number + + ( 1.3.6.1.4.1.1466.115.121.1.52 DESC 'Telex Number' ) + + Values in this syntax are encoded according to the following BNF: + + telex-number = actual-number "$" country "$" answerback + + actual-number = printablestring + + country = printablestring + + answerback = printablestring + + In the above, actual-number is the syntactic representation of the + number portion of the TELEX number being encoded, country is the + TELEX country code, and answerback is the answerback code of a TELEX + terminal. + +6.7. Supported Algorithm + + ( 1.3.6.1.4.1.1466.115.121.1.49 DESC 'Supported Algorithm' ) + + No printable representation of values of the supportedAlgorithms + attribute is defined in this document. Clients which wish to store + and retrieve this attribute MUST use "supportedAlgorithms;binary", in + which the value is transferred as a binary encoding. + +7. Object Classes + + LDAP servers MUST recognize the object classes "top" and "subschema". + LDAP servers SHOULD recognize all the other object classes listed + here as values of the objectClass attribute. + +7.1. top + + ( 2.5.6.0 NAME 'top' ABSTRACT MUST objectClass ) + + + +Wahl Standards Track [Page 14] + +RFC 2256 LDAPv3 Schema December 1997 + + +7.2. alias + + ( 2.5.6.1 NAME 'alias' SUP top STRUCTURAL MUST aliasedObjectName ) + +7.3. country + + ( 2.5.6.2 NAME 'country' SUP top STRUCTURAL MUST c + MAY ( searchGuide $ description ) ) + +7.4. locality + + ( 2.5.6.3 NAME 'locality' SUP top STRUCTURAL + MAY ( street $ seeAlso $ searchGuide $ st $ l $ description ) ) + +7.5. organization + + ( 2.5.6.4 NAME 'organization' SUP top STRUCTURAL MUST o + MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $ + x121Address $ registeredAddress $ destinationIndicator $ + preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ + telephoneNumber $ internationaliSDNNumber $ + facsimileTelephoneNumber $ + street $ postOfficeBox $ postalCode $ postalAddress $ + physicalDeliveryOfficeName $ st $ l $ description ) ) + +7.6. organizationalUnit + + ( 2.5.6.5 NAME 'organizationalUnit' SUP top STRUCTURAL MUST ou + MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $ + x121Address $ registeredAddress $ destinationIndicator $ + preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ + telephoneNumber $ internationaliSDNNumber $ + facsimileTelephoneNumber $ + street $ postOfficeBox $ postalCode $ postalAddress $ + physicalDeliveryOfficeName $ st $ l $ description ) ) + +7.7. person + + ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn ) + MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) ) + +7.8. organizationalPerson + + ( 2.5.6.7 NAME 'organizationalPerson' SUP person STRUCTURAL + MAY ( title $ x121Address $ registeredAddress $ + destinationIndicator $ + preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ + telephoneNumber $ internationaliSDNNumber $ + + + +Wahl Standards Track [Page 15] + +RFC 2256 LDAPv3 Schema December 1997 + + + facsimileTelephoneNumber $ + street $ postOfficeBox $ postalCode $ postalAddress $ + physicalDeliveryOfficeName $ ou $ st $ l ) ) + +7.9. organizationalRole + + ( 2.5.6.8 NAME 'organizationalRole' SUP top STRUCTURAL MUST cn + MAY ( x121Address $ registeredAddress $ destinationIndicator $ + preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ + telephoneNumber $ internationaliSDNNumber $ + facsimileTelephoneNumber $ + seeAlso $ roleOccupant $ preferredDeliveryMethod $ street $ + postOfficeBox $ postalCode $ postalAddress $ + physicalDeliveryOfficeName $ ou $ st $ l $ description ) ) + +7.10. groupOfNames + + ( 2.5.6.9 NAME 'groupOfNames' SUP top STRUCTURAL MUST ( member $ cn ) + MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) ) + +7.11. residentialPerson + + ( 2.5.6.10 NAME 'residentialPerson' SUP person STRUCTURAL MUST l + MAY ( businessCategory $ x121Address $ registeredAddress $ + destinationIndicator $ preferredDeliveryMethod $ telexNumber $ + teletexTerminalIdentifier $ telephoneNumber $ + internationaliSDNNumber $ + facsimileTelephoneNumber $ preferredDeliveryMethod $ street $ + postOfficeBox $ postalCode $ postalAddress $ + physicalDeliveryOfficeName $ st $ l ) ) + +7.12. applicationProcess + + ( 2.5.6.11 NAME 'applicationProcess' SUP top STRUCTURAL MUST cn + MAY ( seeAlso $ ou $ l $ description ) ) + +7.13. applicationEntity + + ( 2.5.6.12 NAME 'applicationEntity' SUP top STRUCTURAL + MUST ( presentationAddress $ cn ) + MAY ( supportedApplicationContext $ seeAlso $ ou $ o $ l $ + description ) ) + +7.14. dSA + + ( 2.5.6.13 NAME 'dSA' SUP applicationEntity STRUCTURAL + MAY knowledgeInformation ) + + + + +Wahl Standards Track [Page 16] + +RFC 2256 LDAPv3 Schema December 1997 + + +7.15. device + + ( 2.5.6.14 NAME 'device' SUP top STRUCTURAL MUST cn + MAY ( serialNumber $ seeAlso $ owner $ ou $ o $ l $ description ) ) + +7.16. strongAuthenticationUser + + ( 2.5.6.15 NAME 'strongAuthenticationUser' SUP top AUXILIARY + MUST userCertificate ) + +7.17. certificationAuthority + + ( 2.5.6.16 NAME 'certificationAuthority' SUP top AUXILIARY + MUST ( authorityRevocationList $ certificateRevocationList $ + cACertificate ) MAY crossCertificatePair ) + +7.18. groupOfUniqueNames + + ( 2.5.6.17 NAME 'groupOfUniqueNames' SUP top STRUCTURAL + MUST ( uniqueMember $ cn ) + MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) ) + +7.19. userSecurityInformation + + ( 2.5.6.18 NAME 'userSecurityInformation' SUP top AUXILIARY + MAY ( supportedAlgorithms ) ) + +7.20. certificationAuthority-V2 + + ( 2.5.6.16.2 NAME 'certificationAuthority-V2' SUP + certificationAuthority + AUXILIARY MAY ( deltaRevocationList ) ) + +7.21. cRLDistributionPoint + + ( 2.5.6.19 NAME 'cRLDistributionPoint' SUP top STRUCTURAL + MUST ( cn ) MAY ( certificateRevocationList $ + authorityRevocationList $ + deltaRevocationList ) ) + +7.22. dmd + + ( 2.5.6.20 NAME 'dmd' SUP top STRUCTURAL MUST ( dmdName ) + MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $ + x121Address $ registeredAddress $ destinationIndicator $ + preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ + telephoneNumber $ internationaliSDNNumber $ + facsimileTelephoneNumber $ + + + +Wahl Standards Track [Page 17] + +RFC 2256 LDAPv3 Schema December 1997 + + + street $ postOfficeBox $ postalCode $ postalAddress $ + physicalDeliveryOfficeName $ st $ l $ description ) ) + +8. Matching Rules + + Servers MAY implement additional matching rules. + +8.1. octetStringMatch + + Servers which implement the extensibleMatch filter SHOULD allow the + matching rule listed in this section to be used in the + extensibleMatch. In general these servers SHOULD allow matching + rules to be used with all attribute types known to the server, when + the assertion syntax of the matching rule is the same as the value + syntax of the attribute. + + ( 2.5.13.17 NAME 'octetStringMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) + +9. 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. + + Transfer of cleartext passwords are strongly discouraged where the + underlying transport service cannot guarantee confidentiality and may + result in disclosure of the password to unauthorized parties. + +10. Acknowledgements + + The definitions on which this document have been developed by + committees for telecommunications and international standards. No + new attribute definitions have been added. The syntax definitions + are based on the ISODE "QUIPU" implementation of X.500. + +11. Bibliography + + [1] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, + "Lightweight X.500 Directory Access Protocol (v3): Attribute + Syntax Definitions", RFC 2252, December 1997. + + [2] The Directory: Models. ITU-T Recommendation X.501, 1996. + + [3] The Directory: Authentication Framework. ITU-T Recommendation + X.509, 1996. + + + + +Wahl Standards Track [Page 18] + +RFC 2256 LDAPv3 Schema December 1997 + + + [4] The Directory: Selected Attribute Types. ITU-T Recommendation + X.520, 1996. + + [5] The Directory: Selected Object Classes. ITU-T Recommendation + X.521, 1996. + + [6] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", RFC 2119, March 1997. + +12. Author's Address + + Mark Wahl + Critical Angle Inc. + 4815 West Braker Lane #502-385 + Austin, TX 78759 + USA + + Phone: +1 512 372 3160 + EMail: M.Wahl@critical-angle.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Wahl Standards Track [Page 19] + +RFC 2256 LDAPv3 Schema December 1997 + + +13. Full Copyright Statement + + Copyright (C) The Internet Society (1997). 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 Standards Track [Page 20] + diff --git a/source4/ldap_server/devdocs/rfc2307.txt b/source4/ldap_server/devdocs/rfc2307.txt new file mode 100644 index 0000000000..f46519f127 --- /dev/null +++ b/source4/ldap_server/devdocs/rfc2307.txt @@ -0,0 +1,1179 @@ + + + + + + +Network Working Group L. Howard +Request for Comments: 2307 Independent Consultant +Category: Experimental March 1998 + + + An Approach for Using LDAP as a Network Information Service + +Status of this Memo + + This memo defines an Experimental Protocol for the Internet + community. It does not specify an Internet standard of any kind. + Discussion and suggestions for improvement are requested. + Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + This document describes an experimental mechanism for mapping + entities related to TCP/IP and the UNIX system into X.500 [X500] + entries so that they may be resolved with the Lightweight Directory + Access Protocol [RFC2251]. A set of attribute types and object + classes are proposed, along with specific guidelines for interpreting + them. + + The intention is to assist the deployment of LDAP as an + organizational nameservice. No proposed solutions are intended as + standards for the Internet. Rather, it is hoped that a general + consensus will emerge as to the appropriate solution to such + problems, leading eventually to the adoption of standards. The + proposed mechanism has already been implemented with some success. + +1. Background and Motivation + + The UNIX (R) operating system, and its derivatives (specifically, + those which support TCP/IP and conform to the X/Open Single UNIX + specification [XOPEN]) require a means of looking up entities, by + matching them against search criteria or by enumeration. (Other + operating systems that support TCP/IP may provide some means of + resolving some of these entities. This schema is applicable to those + environments also.) + + These entities include users, groups, IP services (which map names to + IP ports and protocols, and vice versa), IP protocols (which map + names to IP protocol numbers and vice versa), RPCs (which map names + to ONC Remote Procedure Call [RFC1057] numbers and vice versa), NIS + + + +Howard Experimental [Page 1] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + netgroups, booting information (boot parameters and MAC address + mappings), filesystem mounts, IP hosts and networks, and RFC822 mail + aliases. + + Resolution requests are made through a set of C functions, provided + in the UNIX system's C library. For example, the UNIX system utility + "ls", which enumerates the contents of a filesystem directory, uses + the C library function getpwuid() in order to map user IDs to login + names. Once the request is made, it is resolved using a "nameservice" + which is supported by the client library. The nameservice may be, at + its simplest, a collection of files in the local filesystem which are + opened and searched by the C library. Other common nameservices + include the Network Information Service (NIS) and the Domain Name + System (DNS). (The latter is typically used for resolving hosts, + services and networks.) Both these nameservices have the advantage of + being distributed and thus permitting a common set of entities to be + shared amongst many clients. + + LDAP is a distributed, hierarchical directory service access protocol + which is used to access repositories of users and other network- + related entities. Because LDAP is often not tightly integrated with + the host operating system, information such as users may need to be + kept both in LDAP and in an operating system supported nameservice + such as NIS. By using LDAP as the the primary means of resolving + these entities, these redundancy issues are minimized and the + scalability of LDAP can be exploited. (By comparison, NIS services + based on flat files do not have the scalability or extensibility of + LDAP or X.500.) + + The object classes and attributes defined below are suitable for + representing the aforementioned entities in a form compatible with + LDAP and X.500 directory services. + +2. General Issues + +2.1. Terminology + + The key words "MUST", "SHOULD", and "MAY" used in this document are + to be interpreted as described in [RFC2119]. + + For the purposes of this document, the term "nameservice" refers to a + service, such as NIS or flat files, that is used by the operating + system to resolve entities within a single, local naming context. + Contrast this with a "directory service" such as LDAP, which supports + extensible schema and multiple naming contexts. + + + + + + +Howard Experimental [Page 2] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + The term "NIS-related entities" broadly refers to entities which are + typically resolved using the Network Information Service. (NIS was + previously known as YP.) Deploying LDAP for resolving these entities + does not imply that NIS be used, as a gateway or otherwise. In + particular, the host and network classes are generically applicable, + and may be implemented on any system that wishes to use LDAP or X.500 + for host and network resolution. + + The "DUA" (directory user agent) refers to the LDAP client querying + these entities, such as an LDAP to NIS gateway or the C library. The + "client" refers to the application which ultimately makes use of the + information returned by the resolution. It is irrelevant whether the + DUA and the client reside within the same address space. The act of + the DUA making this information to the client is termed + "republishing". + + To avoid confusion, the term "login name" refers to the user's login + name (being the value of the uid attribute) and the term "user ID" + refers to he user's integer identification number (being the value of + the uidNumber attribute). + + The phrases "resolving an entity" and "resolution of entities" refer + respectively to enumerating NIS-related entities of a given type, and + matching them against a given search criterion. One or more entities + are returned as a result of successful "resolutions" (a "match" + operation will only return one entity). + + The use of the term UNIX does not confer upon this schema the + endorsement of owners of the UNIX trademark. Where necessary, the + term "TCP/IP entity" is used to refer to protocols, services, hosts, + and networks, and the term "UNIX entity" to its complement. (The + former category does not mandate the host operating system supporting + the interfaces required for resolving UNIX entities.) + + The OIDs defined below are derived from iso(1) org(3) dod(6) + internet(1) directory(1) nisSchema(1). + +2.2. Attributes + + The attributes and classes defined in this document are summarized + below. + + The following attributes are defined in this document: + + uidNumber + gidNumber + gecos + homeDirectory + + + +Howard Experimental [Page 3] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + loginShell + shadowLastChange + shadowMin + shadowMax + shadowWarning + shadowInactive + shadowExpire + shadowFlag + memberUid + memberNisNetgroup + nisNetgroupTriple + ipServicePort + ipServiceProtocol + ipProtocolNumber + oncRpcNumber + ipHostNumber + ipNetworkNumber + ipNetmaskNumber + macAddress + bootParameter + bootFile + nisMapName + nisMapEntry + + Additionally, some of the attributes defined in [RFC2256] are + required. + +2.3. Object classes + + The following object classes are defined in this document: + + posixAccount + shadowAccount + posixGroup + ipService + ipProtocol + oncRpc + ipHost + ipNetwork + nisNetgroup + nisMap + nisObject + ieee802Device + bootableDevice + + Additionally, some of the classes defined in [RFC2256] are required. + + + + + +Howard Experimental [Page 4] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +2.4. Syntax definitions + + The following syntax definitions [RFC2252] are used by this schema. + The nisNetgroupTripleSyntax represents NIS netgroup triples: + + ( nisSchema.0.0 NAME 'nisNetgroupTripleSyntax' + DESC 'NIS netgroup triple' ) + + Values in this syntax are represented by the following: + + nisnetgrouptriple = "(" hostname "," username "," domainname ")" + hostname = "" / "-" / keystring + username = "" / "-" / keystring + domainname = "" / "-" / keystring + + X.500 servers may use the following representation of the above + syntax: + + nisNetgroupTripleSyntax ::= SEQUENCE { + hostname [0] IA5String OPTIONAL, + username [1] IA5String OPTIONAL, + domainname [2] IA5String OPTIONAL + } + + The bootParameterSyntax syntax represents boot parameters: + + ( nisSchema.0.1 NAME 'bootParameterSyntax' + DESC 'Boot parameter' ) + + where: + + bootparameter = key "=" server ":" path + key = keystring + server = keystring + path = keystring + + X.500 servers may use the following representation of the above + syntax: + + bootParameterSyntax ::= SEQUENCE { + key IA5String, + server IA5String, + path IA5String + } + + Values adhering to these syntaxes are encoded as strings by LDAP + servers. + + + + +Howard Experimental [Page 5] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +3. Attribute definitions + + This section contains attribute definitions to be implemented by DUAs + supporting this schema. + + ( nisSchema.1.0 NAME 'uidNumber' + DESC 'An integer uniquely identifying a user in an + administrative domain' + EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.1 NAME 'gidNumber' + DESC 'An integer uniquely identifying a group in an + administrative domain' + EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.2 NAME 'gecos' + DESC 'The GECOS field; the common name' + EQUALITY caseIgnoreIA5Match + SUBSTRINGS caseIgnoreIA5SubstringsMatch + SYNTAX 'IA5String' SINGLE-VALUE ) + + ( nisSchema.1.3 NAME 'homeDirectory' + DESC 'The absolute path to the home directory' + EQUALITY caseExactIA5Match + SYNTAX 'IA5String' SINGLE-VALUE ) + + ( nisSchema.1.4 NAME 'loginShell' + DESC 'The path to the login shell' + EQUALITY caseExactIA5Match + SYNTAX 'IA5String' SINGLE-VALUE ) + + ( nisSchema.1.5 NAME 'shadowLastChange' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.6 NAME 'shadowMin' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.7 NAME 'shadowMax' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.8 NAME 'shadowWarning' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.9 NAME 'shadowInactive' + + + +Howard Experimental [Page 6] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.10 NAME 'shadowExpire' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.11 NAME 'shadowFlag' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.12 NAME 'memberUid' + EQUALITY caseExactIA5Match + SUBSTRINGS caseExactIA5SubstringsMatch + SYNTAX 'IA5String' ) + + ( nisSchema.1.13 NAME 'memberNisNetgroup' + EQUALITY caseExactIA5Match + SUBSTRINGS caseExactIA5SubstringsMatch + SYNTAX 'IA5String' ) + + ( nisSchema.1.14 NAME 'nisNetgroupTriple' + DESC 'Netgroup triple' + SYNTAX 'nisNetgroupTripleSyntax' ) + + ( nisSchema.1.15 NAME 'ipServicePort' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.16 NAME 'ipServiceProtocol' + SUP name ) + + ( nisSchema.1.17 NAME 'ipProtocolNumber' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.18 NAME 'oncRpcNumber' + EQUALITY integerMatch + SYNTAX 'INTEGER' SINGLE-VALUE ) + + ( nisSchema.1.19 NAME 'ipHostNumber' + DESC 'IP address as a dotted decimal, eg. 192.168.1.1, + omitting leading zeros' + EQUALITY caseIgnoreIA5Match + SYNTAX 'IA5String{128}' ) + + ( nisSchema.1.20 NAME 'ipNetworkNumber' + DESC 'IP network as a dotted decimal, eg. 192.168, + + + +Howard Experimental [Page 7] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + omitting leading zeros' + EQUALITY caseIgnoreIA5Match + SYNTAX 'IA5String{128}' SINGLE-VALUE ) + + ( nisSchema.1.21 NAME 'ipNetmaskNumber' + DESC 'IP netmask as a dotted decimal, eg. 255.255.255.0, + omitting leading zeros' + EQUALITY caseIgnoreIA5Match + SYNTAX 'IA5String{128}' SINGLE-VALUE ) + + ( nisSchema.1.22 NAME 'macAddress' + DESC 'MAC address in maximal, colon separated hex + notation, eg. 00:00:92:90:ee:e2' + EQUALITY caseIgnoreIA5Match + SYNTAX 'IA5String{128}' ) + + ( nisSchema.1.23 NAME 'bootParameter' + DESC 'rpc.bootparamd parameter' + SYNTAX 'bootParameterSyntax' ) + + ( nisSchema.1.24 NAME 'bootFile' + DESC 'Boot image name' + EQUALITY caseExactIA5Match + SYNTAX 'IA5String' ) + + ( nisSchema.1.26 NAME 'nisMapName' + SUP name ) + + ( nisSchema.1.27 NAME 'nisMapEntry' + EQUALITY caseExactIA5Match + SUBSTRINGS caseExactIA5SubstringsMatch + SYNTAX 'IA5String{1024}' SINGLE-VALUE ) + +4. Class definitions + + This section contains class definitions to be implemented by DUAs + supporting the schema. + + The rfc822MailGroup object class MAY be used to represent a mail + group for the purpose of alias expansion. Several alternative schemes + for mail routing and delivery using LDAP directories, which are + outside the scope of this document. + + ( nisSchema.2.0 NAME 'posixAccount' SUP top AUXILIARY + DESC 'Abstraction of an account with POSIX attributes' + MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory ) + MAY ( userPassword $ loginShell $ gecos $ description ) ) + + + + +Howard Experimental [Page 8] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + ( nisSchema.2.1 NAME 'shadowAccount' SUP top AUXILIARY + DESC 'Additional attributes for shadow passwords' + MUST uid + MAY ( userPassword $ shadowLastChange $ shadowMin + shadowMax $ shadowWarning $ shadowInactive $ + shadowExpire $ shadowFlag $ description ) ) + + ( nisSchema.2.2 NAME 'posixGroup' SUP top STRUCTURAL + DESC 'Abstraction of a group of accounts' + MUST ( cn $ gidNumber ) + MAY ( userPassword $ memberUid $ description ) ) + + ( nisSchema.2.3 NAME 'ipService' SUP top STRUCTURAL + DESC 'Abstraction an Internet Protocol service. + Maps an IP port and protocol (such as tcp or udp) + to one or more names; the distinguished value of + the cn attribute denotes the service's canonical + name' + MUST ( cn $ ipServicePort $ ipServiceProtocol ) + MAY ( description ) ) + + ( nisSchema.2.4 NAME 'ipProtocol' SUP top STRUCTURAL + DESC 'Abstraction of an IP protocol. Maps a protocol number + to one or more names. The distinguished value of the cn + attribute denotes the protocol's canonical name' + MUST ( cn $ ipProtocolNumber $ description ) + MAY description ) + + ( nisSchema.2.5 NAME 'oncRpc' SUP top STRUCTURAL + DESC 'Abstraction of an Open Network Computing (ONC) + [RFC1057] Remote Procedure Call (RPC) binding. + This class maps an ONC RPC number to a name. + The distinguished value of the cn attribute denotes + the RPC service's canonical name' + MUST ( cn $ oncRpcNumber $ description ) + MAY description ) + + ( nisSchema.2.6 NAME 'ipHost' SUP top AUXILIARY + + DESC 'Abstraction of a host, an IP device. The distinguished + value of the cn attribute denotes the host's canonical + name. Device SHOULD be used as a structural class' + MUST ( cn $ ipHostNumber ) + MAY ( l $ description $ manager ) ) + + ( nisSchema.2.7 NAME 'ipNetwork' SUP top STRUCTURAL + DESC 'Abstraction of a network. The distinguished value of + the cn attribute denotes the network's canonical name' + + + +Howard Experimental [Page 9] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + MUST ( cn $ ipNetworkNumber ) + MAY ( ipNetmaskNumber $ l $ description $ manager ) ) + + ( nisSchema.2.8 NAME 'nisNetgroup' SUP top STRUCTURAL + DESC 'Abstraction of a netgroup. May refer to other netgroups' + MUST cn + MAY ( nisNetgroupTriple $ memberNisNetgroup $ description ) ) + + ( nisSchema.2.09 NAME 'nisMap' SUP top STRUCTURAL + DESC 'A generic abstraction of a NIS map' + MUST nisMapName + MAY description ) + + ( nisSchema.2.10 NAME 'nisObject' SUP top STRUCTURAL + DESC 'An entry in a NIS map' + MUST ( cn $ nisMapEntry $ nisMapName ) + MAY description ) + + ( nisSchema.2.11 NAME 'ieee802Device' SUP top AUXILIARY + DESC 'A device with a MAC address; device SHOULD be + used as a structural class' + MAY macAddress ) + + ( nisSchema.2.12 NAME 'bootableDevice' SUP top AUXILIARY + DESC 'A device with boot parameters; device SHOULD be + used as a structural class' + MAY ( bootFile $ bootParameter ) ) + +5. Implementation details + +5.1. Suggested resolution methods + + The preferred means of directing a client application (one using the + shared services of the C library) to use LDAP as its information + source for the functions listed in 5.2 is to modify the source code + to directly query LDAP. As the source to commercial C libraries and + applications is rarely available to the end-user, one could emulate a + supported nameservice (such as NIS). (This is also an appropriate + opportunity to perform caching of entries across process address + spaces.) In the case of NIS, reference implementations are widely + available and the RPC interface is well known. + + The means by which the operating system is directed to use LDAP is + implementation dependent. For example, some operating systems and C + libraries support end-user extensible resolvers using dynamically + loadable libraries and a nameservice "switch". The means in which the + DUA locates LDAP servers is also implementation dependent. + + + + +Howard Experimental [Page 10] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +5.2. Affected library functions + + The following functions are typically found in the C libraries of + most UNIX and POSIX compliant systems. An LDAP search filter + [RFC2254] which may be used to satisfy the function call is included + alongside each function name. Parameters are denoted by %s and %d for + string and integer arguments, respectively. Long lines are broken. + + getpwnam() (&(objectClass=posixAccount)(uid=%s)) + getpwuid() (&(objectClass=posixAccount) + (uidNumber=%d)) + getpwent() (objectClass=posixAccount) + + getspnam() (&(objectClass=shadowAccount)(uid=%s)) + getspent() (objectClass=shadowAccount) + + getgrnam() (&(objectClass=posixGroup)(cn=%s)) + getgrgid() (&(objectClass=posixGroup) + (gidNumber=%d)) + getgrent() (objectClass=posixGroup) + + getservbyname() (&(objectClass=ipService) + (cn=%s)(ipServiceProtocol=%s)) + getservbyport() (&(objectClass=ipService) + (ipServicePort=%d) + (ipServiceProtocol=%s)) + getservent() (objectClass=ipService) + + getrpcbyname() (&(objectClass=oncRpc)(cn=%s)) + getrpcbynumber() (&(objectClass=oncRpc)(oncRpcNumber=%d)) + getrpcent() (objectClass=oncRpc) + + getprotobyname() (&(objectClass=ipProtocol)(cn=%s)) + getprotobynumber() (&(objectClass=ipProtocol) + (ipProtocolNumber=%d)) + getprotoent() (objectClass=ipProtocol) + + gethostbyname() (&(objectClass=ipHost)(cn=%s)) + gethostbyaddr() (&(objectClass=ipHost)(ipHostNumber=%s)) + gethostent() (objectClass=ipHost) + + getnetbyname() (&(objectClass=ipNetwork)(cn=%s)) + getnetbyaddr() (&(objectClass=ipNetwork) + (ipNetworkNumber=%s)) + getnetent() (objectClass=ipNetwork) + + setnetgrent() (&(objectClass=nisNetgroup)(cn=%s)) + + + + +Howard Experimental [Page 11] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +5.3. Interpreting user and group entries + + User and group resolution is initiated by the functions prefixed by + getpw and getgr respectively. The uid attribute contains the user's + login name. The cn attribute, in posixGroup entries, contains the + group's name. + + The account object class provides a convenient structural class for + posixAccount, and SHOULD be used where additional attributes are not + required. + + It is suggested that uid and cn are used as the RDN attribute type + for posixAccount and posixGroup entries, respectively. + + An account's GECOS field is preferably determined by a value of the + gecos attribute. If no gecos attribute exists, the value of the cn + attribute MUST be used. (The existence of the gecos attribute allows + information embedded in the GECOS field, such as a user's telephone + number, to be returned to the client without overloading the cn + attribute. It also accommodates directories where the common name + does not contain the user's full name.) + + An entry of class posixAccount, posixGroup, or shadowAccount without + a userPassword attribute MUST NOT be used for authentication. The + client should be returned a non-matchable password such as "x". + + userPassword values MUST be represented by following syntax: + + passwordvalue = schemeprefix encryptedpassword + schemeprefix = "{" scheme "}" + scheme = "crypt" / "md5" / "sha" / altscheme + altscheme = "x-" keystring + encryptedpassword = encrypted password + + The encrypted password contains of a plaintext key hashed using the + algorithm scheme. + + userPassword values which do not adhere to this syntax MUST NOT be + used for authentication. The DUA MUST iterate through the values of + the attribute until a value matching the above syntax is found. Only + if encryptedpassword is an empty string does the user have no + password. DUAs are not required to consider encryption schemes which + the client will not recognize; in most cases, it may be sufficient to + consider only "crypt". + + Below is an example of a userPassword attribute: + + userPassword: {crypt}X5/DBrWPOQQaI + + + +Howard Experimental [Page 12] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + A future standard may specify LDAP v3 attribute descriptions to + represent hashed userPasswords, as noted below. This schema MUST NOT + be used with LDAP v2 DUAs and DSAs. + + attributetype = attributename sep attributeoption + attributename = "userPassword" + sep = ";" + attributeoption = schemeclass "-" scheme + schemeclass = "hash" / altschemeclass + scheme = "crypt" / "md5" / "sha" / altscheme + altschemeclass = "x-" keystring + altscheme = keystring + + + Below is an example of a userPassword attribute, represented with an + LDAP v3 attribute description: + + userPassword;hash-crypt: X5/DBrWPOQQaI + + + A DUA MAY utilise the attributes in the shadowAccount class to + provide shadow password service (getspnam() and getspent()). In such + cases, the DUA MUST NOT make use of the userPassword attribute for + getpwnam() et al, and MUST return a non-matchable password (such as + "x") to the client instead. + +5.4. Interpreting hosts and networks + + The ipHostNumber and ipNetworkNumber attributes are defined in + preference to dNSRecord (defined in [RFC1279]), in order to simplify + the DUA's role in interpreting entries in the directory. A dNSRecord + expresses a complete resource record, including time to live and + class data, which is extraneous to this schema. + + Additionally, the ipHost and ipNetwork classes permit a host or + network (respectively) and all its aliases to be represented by a + single entry in the directory. This is not necessarily possible if a + DNS resource record is mapped directly to an LDAP entry. + Implementations that wish to use LDAP to master DNS zone information + are not precluded from doing so, and may simply avoid the ipHost and + ipNetwork classes. + + This document redefines, although not exclusively, the ipNetwork + class defined in [RFC1279], in order to achieve consistent naming + with ipHost. The ipNetworkNumber attribute is also used in the + siteContact object class [ROSE]. + + + + + +Howard Experimental [Page 13] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + The trailing zeros in a network address MUST be omitted. CIDR-style + network addresses (eg. 192.168.1/24) MAY be used. + + Hosts with IPv6 addresses MUST be written in their "preferred" form + as defined in section 2.2.1 of [RFC1884], such that all components of + the address are indicated and leading zeros are omitted. This + provides a consistent means of resolving ipHosts by address. + +5.5. Interpreting other entities + + In general, a one-to-one mapping between entities and LDAP entries is + proposed, in that each entity has exactly one representation in the + DIT. In some cases this is not feasible; for example, a service which + is represented in more than one protocol domain. Consider the + following entry: + + dn: cn=domain, dc=aja, dc=com + cn: domain + cn: nameserver + objectClass: top + objectClass: ipService + ipServicePort: 53 + ipServiceProtocol: tcp + ipServiceProtocol: udp + + This entry MUST map to the following two (2) services entities: + + domain 53/tcp nameserver + domain 53/udp nameserver + + While the above two entities may be represented as separate LDAP + entities, with different distinguished names (such as + cn=domain+ipServiceProtocol=tcp, ... and + cn=domain+ipServiceProtocol=udp, ...) it is convenient to represent + them as a single entry. (If a service is represented in multiple + protocol domains with different ports, then multiple entries are + required; multivalued RDNs may be used to distinguish them.) + + With the exception of userPassword values, which are parsed according + to the syntax considered in section 5.2, any empty values (consisting + of a zero length string) are returned by the DUA to the client. The + DUA MUST reject any entries which do not conform to the schema + (missing mandatory attributes). Non-conforming entries SHOULD be + ignored while enumerating entries. + + The nisObject object class MAY be used as a generic means of + representing NIS entities. Its use is not encouraged; where support + for entities not described in this schema is desired, an appropriate + + + +Howard Experimental [Page 14] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + schema should be devised. Implementors are strongly advised to + support end-user extensible mappings between NIS entities and object + classes. (Where the nisObject class is used, the nisMapName attribute + may be used as a RDN.) + +5.6. Canonicalizing entries with multi-valued naming attributes + + For entities such as hosts, services, networks, protocols, and RPCs, + where there may be one or more aliases, the respective entry's + relative distinguished name SHOULD be used to determine the canonical + name. Any other values for the same attribute are used as aliases. + For example, the service described in section 5.5 has the canonical + name "domain" and exactly one alias, "nameserver". + + The schema in this document generally only defines one attribute per + class which is suitable for distinguishing an entity (excluding any + attributes with integer syntax; it is assumed that entries will be + distinguished on name). Usually, this is the common name (cn) + attribute. This aids the DUA in determining the canonical name of an + entity, as it can examine the value of the relative distinguished + name. Aliases are thus any values of the distinguishing attribute + (such as cn) which do not match the canonical name of the entity. + + In the event that a different attribute is used to distinguish the + entry, as may be the case where these object classes are used as + auxiliary classes, the entry's canonical name may not be present in + the RDN. In this case, the DUA MUST choose one of the non- + distinguished values to represent the entity's canonical name. As the + directory server guarantees no ordering of attribute values, it may + not be possible to distinguish an entry deterministically. This + ambiguity SHOULD NOT be resolved by mapping one directory entry into + multiple entities. + +6. Implementation focus + + A NIS server which uses LDAP instead of local files has been + developed which supports the schema defined in this document. + + A reference implementation of the C library resolution code has been + written for the Free Software Foundation. It may support other C + libraries which support the Name Service Switch (NSS) or the + Information Retrieval Service (IRS). + + The author has made available a freely distributable set of scripts + which parses local databases such as /etc/passwd and /etc/hosts into + a form suitable for loading into an LDAP server. + + + + + +Howard Experimental [Page 15] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +7. Security Considerations + + The entirety of related security considerations are outside the scope + of this document. It is noted that making passwords encrypted with a + widely understood hash function (such as crypt()) available to non- + privileged users is dangerous because it exposes them to dictionary + and brute-force attacks. This is proposed only for compatibility + with existing UNIX system implementations. Sites where security is + critical SHOULD consider using a strong authentication service for + user authentication. + + Alternatively, the encrypted password could be made available only to + a subset of privileged DUAs, which would provide "shadow" password + service to client applications. This may be difficult to enforce. + + Because the schema represents operating system-level entities, access + to these entities SHOULD be granted on a discretionary basis. (There + is little point in restricting access to data which will be + republished without restriction, however.) It is particularly + important that only administrators can modify entries defined in this + schema, with the exception of allowing a principal to change their + password (which may be done on behalf of the user by a client bound + as a superior principal, such that password restrictions may be + enforced). For example, if a user were allowed to change the value of + their uidNumber attribute, they could subvert security by + equivalencing their account with the superuser account. + + A subtree of the DIT which is to be republished by a DUA (such as a + NIS gateway) SHOULD be within the same administrative domain that the + republishing DUA represents. (For example, principals outside an + organization, while conceivably part of the DIT, should not be + considered with the same degree of authority as those within the + organization.) + + Finally, care should be exercised with integer attributes of a + sensitive nature (particularly the uidNumber and gidNumber + attributes) which contain zero-length values. DUAs MAY treat such + values as corresponding to the "nobody" or "nogroup" user and group, + respectively. + +8. Acknowledgements + + Thanks to Leif Hedstrom of Netscape Communications Corporation, + Michael Grant and Rosanna Lee of Sun Microsystems Inc., Ed Reed of + Novell Inc., and Mark Wahl of Critical Angle Inc. for their valuable + contributions to the development of this schema. Thanks to Andrew + Josey of The Open Group for clarifying the use of the UNIX trademark, + and to Tim Howes and Peter J. Cherny for their support. + + + +Howard Experimental [Page 16] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + UNIX is a registered trademark of The Open Group. + +9. References + + [RFC1057] + Sun Microsystems, Inc., "RPC: Remote Procedure Call: Protocol + Specification Version 2", RFC 1057, June 1988. + + [RFC1279] + Kille, S., "X.500 and Domains", RFC 1279, November 1991. + + [RFC1884] + Hinden, R., and S. Deering, "IP Version 6 Addressing + Architecture", RFC 1884, December 1995. + + [RFC2119] + Bradner, S., "Key Words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [RFC2251] + Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + [RFC2252] + Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", + RFC 2252, December 1997. + + [RFC2254] + Howes, T., "The String Representation of LDAP Search Filters", + RFC 2254, December 1997. + + [RFC2256] + Wahl, M., "A Summary of the X.500(96) User Schema for use with + LDAPv3", RFC 2256, December 1997. + + [ROSE] + M. T. Rose, "The Little Black Book: Mail Bonding with OSI + Directory Services", ISBN 0-13-683210-5, Prentice-Hall, Inc., + 1992. + + [X500] + "Information Processing Systems - Open Systems Interconnection - + The Directory: Overview of Concepts, Models and Service", + ISO/IEC JTC 1/SC21, International Standard 9594-1, 1988. + + + + + + +Howard Experimental [Page 17] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + [XOPEN] + ISO/IEC 9945-1:1990, Information Technology - Portable Operating + Systems Interface (POSIX) - Part 1: Systems Application + Programming Interface (API) [C Language] + +10. Author's Address + + Luke Howard + PO Box 59 + Central Park Vic 3145 + Australia + + EMail: lukeh@xedoc.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Howard Experimental [Page 18] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +A. Example entries + + The examples described in this section are provided to illustrate the + schema described in this memo. They are not meant to be exhaustive. + + The following entry is an example of the posixAccount class: + + dn: uid=lester, dc=aja, dc=com + objectClass: top + objectClass: account + objectClass: posixAccount + uid: lester + cn: Lester the Nightfly + userPassword: {crypt}X5/DBrWPOQQaI + gecos: Lester + loginShell: /bin/csh + uidNumber: 10 + gidNumber: 10 + homeDirectory: /home/lester + + + This corresponds the UNIX system password file entry: + + lester:X5/DBrWPOQQaI:10:10:Lester:/home/lester:/bin/sh + + The following entry is an example of the ipHost class: + + dn: cn=peg.aja.com, dc=aja, dc=com + objectClass: top + objectClass: device + objectClass: ipHost + objectClass: bootableDevice + objectClass: ieee802Device + cn: peg.aja.com + cn: www.aja.com + ipHostNumber: 10.0.0.1 + macAddress: 00:00:92:90:ee:e2 + bootFile: mach + bootParameter: root=fs:/nfsroot/peg + bootParameter: swap=fs:/nfsswap/peg + bootParameter: dump=fs:/nfsdump/peg + + This entry represents the host canonically peg.aja.com, also known as + www.aja.com. The Ethernet address and four boot parameters are also + specified. + + + + + + +Howard Experimental [Page 19] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + + An example of the nisNetgroup class: + + dn: cn=nightfly, dc=aja, dc=com + objectClass: top + objectClass: nisNetgroup + cn: nightfly + nisNetgroupTriple: (charlemagne,peg,dunes.aja.com) + nisNetgroupTriple: (lester,-,) + memberNisNetgroup: kamakiriad + + This entry represents the netgroup nightfly, which contains two + triples (the user charlemagne, the host peg, and the domain + dunes.aja.com; and, the user lester, no host, and any domain) and one + netgroup (kamakiriad). + + Finally, an example of the nisObject class: + + dn: nisMapName=tracks, dc=dunes, dc=aja, dc=com + objectClass: top + objectClass: nisMap + nisMapName: tracks + + dn: cn=Maxine, nisMapName=tracks, dc=dunes, dc=aja, dc=com + objectClass: top + objectClass: nisObject + cn: Maxine + nisMapName: tracks + nisMapEntry: Nightfly$4 + + This entry represents the NIS map tracks, and a single map entry. + + + + + + + + + + + + + + + + + + + + + +Howard Experimental [Page 20] + +RFC 2307 Using LDAP as a Network Information Service March 1998 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1998). 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. + + + + + + + + + + + + + + + + + + + + + + + + +Howard Experimental [Page 21] + |