From: Kurt Zeilenga Date: Fri, 13 Aug 1999 23:47:39 +0000 (+0000) Subject: Include more LDAP RFCs X-Git-Tag: TWEB_OL_BASE~220 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=fdaab5763f09d7c5fb14135babcc29e5e8d1c329;p=openldap Include more LDAP RFCs --- diff --git a/doc/rfc/rfc1488.txt b/doc/rfc/rfc1488.txt new file mode 100644 index 0000000000..ecafe75bfd --- /dev/null +++ b/doc/rfc/rfc1488.txt @@ -0,0 +1,619 @@ + + + + + + +Network Working Group T. Howes +Request for Comments: 1488 University of Michigan + S. Kille + ISODE Consortium + W. Yeong + Performance Systems International + C. Robbins + NeXor Ltd. + July 1993 + + + The X.500 String Representation of Standard Attribute Syntaxes + +Status of this Memo + + This RFC specifies an IAB standards track protocol for the Internet + community, and requests discussion and suggestions for improvements. + Please refer to the current edition of the "IAB Official Protocol + Standards" for the standardization state and status of this protocol. + Distribution of this memo is unlimited. + +Abstract + + The Lightweight Directory Access Protocol (LDAP) [9] requires that + the contents of AttributeValue fields in protocol elements be octet + strings. This document defines the requirements that must be + satisfied by encoding rules used to render Directory attribute + syntaxes into a form suitable for use in the LDAP, then goes on to + define the encoding rules for the standard set of attribute syntaxes + defined in [1,2] and [3]. + +1. Attribute Syntax Encoding Requirements + + This section defines general requirements for lightweight directory + protocol attribute syntax encodings. All documents defining attribute + syntax encodings for use by the lightweight directory protocols 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 the + lightweight directory protocols. + + + + + + +Howes, Kille, Yeong & Robbins [Page 1] + +RFC 1488 X.500 Syntax Encoding July 1993 + + +2. Standard Attribute Syntax Encodings + + For the purposes of defining the encoding rules for the standard + attribute syntaxes, the following auxiliary BNF definitions will be + used: + + ::= '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' + + ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + + ::= | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | + 'A' | 'B' | 'C' | 'D' | 'E' | 'F' + + ::= | | '-' + +

::= | | ''' | '(' | ')' | '+' | ',' | '-' | '.' | + '/' | ':' | '?' | ' ' + + ::= The ASCII newline character with hexadecimal value 0x0A + + ::= | + + ::= | + + ::= | + + ::= | + + ::=

|

+ + ::= ' ' | ' ' + +2.1. Undefined + + Values of type Undefined are encoded as if they were values of type + Octet String. + +2.2. Case Ignore String + + A string of type caseIgnoreStringSyntax is encoded as the string + value itself. + + + + + +Howes, Kille, Yeong & Robbins [Page 2] + +RFC 1488 X.500 Syntax Encoding July 1993 + + +2.3. Case Exact String + + The encoding of a string of type caseExactStringSyntax is the string + value itself. + +2.4. Printable String + + The encoding of a string of type printableStringSyntax is the string + value itself. + +2.5. Numeric String + + The encoding of a string of type numericStringSyntax is the string + value itself. + +2.6. Octet String + + The encoding of a string of type octetStringSyntax is the string + value itself. + +2.7. Case Ignore IA5 String + + The encoding of a string of type caseIgnoreIA5String is the string + value itself. + +2.8. IA5 String + + The encoding of a string of type iA5StringSyntax is the string value + itself. + +2.9. T61 String + + The encoding of a string of type t61StringSyntax is the string value + itself. + +2.10. Case Ignore List + + Values of type caseIgnoreListSyntax are encoded according to the + following BNF: + + ::= | + '$' + + ::= a string encoded according to the rules + for Case Ignore String as above. + + + + + + +Howes, Kille, Yeong & Robbins [Page 3] + +RFC 1488 X.500 Syntax Encoding July 1993 + + +2.11. Case Exact List + + Values of type caseExactListSyntax are encoded according to the + following BNF: + + ::= | + '$' + + ::= a string encoded according to the rules for + Case Exact String as above. + +2.12. Distinguished Name + + Values of type distinguishedNameSyntax are encoded to have the + representation defined in [5]. + +2.13. Boolean + + Values of type booleanSyntax are encoded according to the following + BNF: + + ::= "TRUE" | "FALSE" + + Boolean values have an encoding of "TRUE" if they are logically true, + and have an encoding of "FALSE" otherwise. + +2.14. Integer + + Values of type integerSyntax are encoded as the decimal + representation of their values, with each decimal digit represented + by the its character equivalent. So the digit 1 is represented by the + character + +2.15. Object Identifier + + Values of type objectIdentifierSyntax are encoded according to the + following BNF: + + ::= | '.' | + + ::= + + ::= | '.' + + In the above BNF, is the syntactic representation of an + object descriptor. When encoding values of type + objectIdentifierSyntax, the first encoding option should be used in + preference to the second, which should be used in preference to the + + + +Howes, Kille, Yeong & Robbins [Page 4] + +RFC 1488 X.500 Syntax Encoding July 1993 + + + third wherever possible. That is, in encoding object identifiers, + object descriptors (where assigned and known by the implementation) + should be used in preference to numeric oids to the greatest extent + possible. For example, in encoding the object identifier representing + an organizationName, the descriptor "organizationName" is preferable + to "ds.4.10", which is in turn preferable to the string "2.5.4.10". + +2.16. Telephone Number + + Values of type telephoneNumberSyntax are encoded as if they were + Printable String types. + +2.17. Telex Number + + Values of type telexNumberSyntax are encoded according to the + following BNF: + + ::= '$' '$' + + ::= + + ::= + + ::= + + In the above, is the syntactic representation of the + number portion of the TELEX number being encoded, is the + TELEX country code, and is the answerback code of a + TELEX terminal. + +2.18. Teletex Terminal Identifier + + Values of type teletexTerminalIdentifier are encoded according to the + following BNF: + + ::= 0*( '$' ) + + In the above, the first is the encoding of the + first portion of the teletex terminal identifier to be encoded, and + the subsequent 0 or more are subsequent portions + of the teletex terminal identifier. + +2.19. Facsimile Telephone Number + + Values of type FacsimileTelephoneNumber are encoded according to the + following BNF: + + ::= [ '$' ] + + + +Howes, Kille, Yeong & Robbins [Page 5] + +RFC 1488 X.500 Syntax Encoding July 1993 + + + ::= | '$' + + ::= 'twoDimensional' | 'fineResolution' | 'unlimitedLength' | + 'b4Length' | 'a3Width' | 'b4Width' | 'uncompressed' + + In the above, the first is the actual fax number, + and the tokens represent fax parameters. + +2.20. Presentation Address + + Values of type PresentationAddress are encoded to have the + representation described in [6]. + +2.21. UTC Time + + Values of type uTCTimeSyntax are encoded as if they were Printable + Strings with the strings containing a UTCTime value. + +2.22. Guide (search guide) + + Values of type Guide, such as values of the searchGuide attribute, + are encoded according to the following BNF: + + ::= [ '#' ] + + ::= an encoded value of type objectIdentifierSyntax + + ::= | | '!' + + ::= [ '(' ] '&' [ ')' ] | + [ '(' ] '|' [ ')' ] + + ::= [ '(' ] '$' [ ')' ] + + ::= "EQ" | "SUBSTR" | "GE" | "LE" | "APPROX" + +2.23. Postal Address + +Values of type PostalAddress are encoded according to the following BNF: + + ::= | '$' + + In the above, each component of a postal address value is + encoded as a value of type t61StringSyntax. + + + + + + + +Howes, Kille, Yeong & Robbins [Page 6] + +RFC 1488 X.500 Syntax Encoding July 1993 + + +2.24. User Password + + Values of type userPasswordSyntax are encoded as if they were of type + octetStringSyntax. + +2.25. User Certificate + + Values of type userCertificate are encoded according to the following + BNF: + + ::= '#' '#' '#' + '#' + + ::= + + ::= an encoded Distinguished Name + + ::= '#' + + ::= + + ::= + + ::= | | + '{ASN}' + + ::= an encoded Distinguished Name + + ::= '#' + + ::= | '-' + + ::= '#' + + ::= an encoded UTCTime value + + ::= | + +2.26. CA Certificate + + Values of type cACertificate are encoded as if the values were of + type userCertificate. + +2.27. Authority Revocation List + + Values of type authorityRevocationList are encoded according to the + following BNF: + + + + +Howes, Kille, Yeong & Robbins [Page 7] + +RFC 1488 X.500 Syntax Encoding July 1993 + + + ::= '#' '#' + [ '#' ] + + ::= '#' + [ '#' 0*() '#'] + + ::= '#' '#' + '#' + + The syntactic components , , , + , and have the same definitions as in + the BNF for the userCertificate attribute syntax. + +2.28. Certificate Revocation List + + Values of type certificateRevocationList are encoded as if the values + were of type authorityRevocationList. + +2.29. Cross Certificate Pair + + Values of type crossCertificatePair are encoded according to the + following BNF: + + ::= '|' + + The syntactic component has the same definition as in + the BNF for the userCertificate attribute syntax. + +2.30. Delivery Method + + Values of type deliveryMethod are encoded according to the following + BNF: + + ::= | '$' + + ::= 'any' | 'mhs' | 'physical' | 'telex' | 'teletex' | + 'g3fax' | 'g4fax' | 'ia5' | 'videotex' | 'telephone' + +2.31. Other Mailbox + + Values of the type otherMailboxSyntax are encoded according to the + following BNF: + + ::= '$' + + ::= an encoded Printable String + + ::= an encoded IA5 String + + + +Howes, Kille, Yeong & Robbins [Page 8] + +RFC 1488 X.500 Syntax Encoding July 1993 + + + In the above, represents the type of mail system in + which the mailbox resides, for example "Internet" or "MCIMail"; and + is the actual mailbox in the mail system defined by + . + +2.32. Mail Preference + + Values of type mailPreferenceOption are encoded according to the + following BNF: + + ::= "NO-LISTS" | "ANY-LIST" | "PROFESSIONAL-LISTS" + +2.33. MHS OR Address + + Values of type MHS OR Address are encoded as strings, according to + the format defined in [10]. + +2.34. Photo + + Values of type Photo are encoded as if they were octet strings + containing JPEG images in the JPEG File Interchange Format (JFIF), as + described in [8]. + +2.35. Fax + + Values of type Fax are encoded as if they were octet strings + containing Group 3 Fax images as defined in [7]. + +3. Acknowledgements + + Many of the attribute syntax encodings defined in this document are + adapted from those used in the QUIPU X.500 implementation. The + contribu- tions of the authors of the QUIPU implementation in the + specification of the QUIPU syntaxes [4] are gratefully acknowledged. + +4. Bibliography + + [1] The Directory: Selected Attribute Syntaxes. CCITT, + Recommendation X.520. + + [2] Information Processing Systems -- Open Systems Interconnection -- + The Directory: Selected Attribute Syntaxes. + + [3] Barker, P., and S. Kille, "The COSINE and Internet X.500 Schema", + RFC 1274, University College London, November 1991. + + [4] The ISO Development Environment: User's Manual -- Volume 5: + QUIPU. Colin Robbins, Stephen E. Kille. + + + +Howes, Kille, Yeong & Robbins [Page 9] + +RFC 1488 X.500 Syntax Encoding July 1993 + + + [5] Kille, S., "A String Representation of Distinguished Names", RFC + 1485, July 1993. + + [6] Kille, S., "A String Representation for Presentation Addresses", + RFC 1278, University College London, 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] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access + Protocol", RFC 1487, Performance Systems International, + University of Michigan, ISODE Consortium, July 1993. + + [10] Kille, S., "Mapping between X.400(1988)/ISO 10021 and RFC 822", + RFC 1327, University College London, May 1992. + +5. Security Considerations + + Security issues are not discussed in this memo. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Howes, Kille, Yeong & Robbins [Page 10] + +RFC 1488 X.500 Syntax Encoding July 1993 + + +6. Authors' Addresses + + Tim Howes + University of Michigan + ITD Research Systems + 535 W William St. + Ann Arbor, MI 48103-4943 + USA + + Phone: +1 313 747-4454 + EMail: tim@umich.edu + + + Steve Kille + ISODE Consortium + PO Box 505 + London + SW11 1DX + UK + + Phone: +44-71-223-4062 + EMail: S.Kille@isode.com + + + Wengyik Yeong + PSI, Inc. + 510 Huntmar Park Drive + Herndon, VA 22070 + USA + + Phone: +1 703-450-8001 + EMail: yeongw@psilink.com + + + Colin Robbins + NeXor Ltd + University Park + Nottingham + NG7 2RD + UK + + + + + + + + + + + +Howes, Kille, Yeong & Robbins [Page 11] + \ No newline at end of file diff --git a/doc/rfc/rfc2079.txt b/doc/rfc/rfc2079.txt new file mode 100644 index 0000000000..f761d36f2a --- /dev/null +++ b/doc/rfc/rfc2079.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group M. Smith +Request for Comments: 2079 Netscape Communications +Category: Standards Track January 1997 + + + Definition of an X.500 Attribute Type and an Object Class to Hold + Uniform Resource Identifiers (URIs) + +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. + +Abstract + + Uniform Resource Locators (URLs) are being widely used to specify the + location of Internet resources. There is an urgent need to be able + to include URLs in directories that conform to the LDAP and X.500 + information models, and a desire to include other types of Uniform + Resource Identifiers (URIs) as they are defined. A number of + independent groups are already experimenting with the inclusion of + URLs in LDAP and X.500 directories. This document builds on the + experimentation to date and defines a new attribute type and an + auxiliary object class to allow URIs, including URLs, to be stored in + directory entries in a standard way. + +Background and Intended Usage + + Uniform Resource Locators (URLs) as defined by [1] are the first of + several types of Uniform Resource Identifiers (URIs) being defined by + the IETF. URIs are widely used on the Internet, most notably within + Hypertext Markup Language [2] documents. This document defines an + X.500 [3,4] attribute type called labeledURI and an auxiliary object + class called labeledURIObject to hold all types of URIs, including + URLs. These definitions are designed for use in LDAP and X.500 + directories, and may be used in other contexts as well. + + + + + + + + + + + + +Smith Standards Track [Page 1] + +RFC 2079 URI Attribute Type and Object Class January 1997 + + +Schema Definition of the labeledURI Attribute Type + + Name: labeledURI + ShortName: None + Description: Uniform Resource Identifier with optional label + OID: umichAttributeType.57 (1.3.6.1.4.1.250.1.57) + Syntax: caseExactString + SizeRestriction: None + SingleValued: False + +Discussion of the labeledURI Attribute Type + + The labeledURI attribute type has the caseExactString syntax (since + URIs are case-sensitive) and it is multivalued. Values placed in the + attribute should consist of a URI (at the present time, a URL) + optionally followed by one or more space characters and a label. + Since space characters are not allowed to appear un-encoded in URIs, + there is no ambiguity about where the label begins. At the present + time, the URI portion must comply with the URL specification [1]. + Multiple labeledURI values will generally indicate different + resources that are all related to the X.500 object, but may indicate + different locations for the same resource. + + The label is used to describe the resource to which the URI points, + and is intended as a friendly name fit for human consumption. This + document does not propose any specific syntax for the label part. In + some cases it may be helpful to include in the label some indication + of the kind and/or size of the resource referenced by the URI. + + Note that the label may include any characters allowed by the + caseExactString syntax, but that the use of non-IA5 (non-ASCII) + characters is discouraged as not all directory clients may handle + them in the same manner. If non-IA5 characters are included, they + should be represented using the X.500 conventions, not the HTML + conventions (e.g., the character that is an "a" with a ring above it + should be encoded using the T.61 sequence 0xCA followed by an "a" + character; do not use the HTML escape sequence "å"). + +Examples of labeledURI Attribute Values + + An example of a labeledURI attribute value that does not include a + label: + + ftp://ds.internic.net/rfc/rfc822.txt + + + + + + + +Smith Standards Track [Page 2] + +RFC 2079 URI Attribute Type and Object Class January 1997 + + + An example of a labeledURI attribute value that contains a tilde + character in the URL (special characters in a URL must be encoded as + specified by the URL document [1]). The label is "LDAP Home Page": + + http://www.umich.edu/%7Ersug/ldap/ LDAP Home Page + + Another example. This one includes a hint in the label to help the + user realize that the URL points to a photo image. + + http://champagne.inria.fr/Unites/rennes.gif Rennes [photo] + +Schema Definition of the labeledURIObject Object Class + + Name: labeledURIObject + Description: object that contains the URI attribute type + OID: umichObjectClass.15 (1.3.6.1.4.1.250.3.15) + SubclassOf: top + MustContain: + MayContain: labeledURI + +Discussion of the labeledURIObject Object Class + + The labeledURIObject class is a subclass of top and may contain the + labeledURI attribute. The intent is that this object class can be + added to existing directory objects to allow for inclusion of URI + values. This approach does not preclude including the labeledURI + attribute type directly in other object classes as appropriate. + +Security Considerations + + Security considerations are not discussed in this memo, except to + note that blindly inserting the label portion of a labeledURI + attribute value into an HTML document is not recommended, as this may + allow a malicious individual to include HTML tags in the label that + mislead viewers of the entire document in which the labeledURI value + was inserted. + +Acknowledgments + + Paul-Andre Pays, Martijn Koster, Tim Howes, Rakesh Patel, Russ + Wright, and Hallvard Furuseth provided invaluable assistance in the + creation of this document. + + This material is based in part upon work supported by the National + Science Foundation under Grant No. NCR-9416667. + + + + + + +Smith Standards Track [Page 3] + +RFC 2079 URI Attribute Type and Object Class January 1997 + + +Appendix: The labeledURL Attribute Type (Deprecated) + + An earlier draft of this document defined an additional attribute + type called labeledURL. This attribute type is deprecated, and + should not be used when adding new values to directory entries. The + original motivation for including a separate attribute type to hold + URLs was that this would better enable efficient progammatic access + to specific types of URIs. After some deliberation, the IETF-ASID + working group concluded that it was better to simply have one + attribute than two. + + The schema definition for labeledURL is included here for historical + reference only. Directory client software may want to support this + schema definition (in addition to labeledURI) to ease the transition + away from labeledURL for those sites that are using it. + + Name: labeledURL + ShortName: None + Description: Uniform Resource Locator with optional label + OID: umichAttributeType.41 (1.3.6.1.4.1.250.1.41) + Syntax: caseExactString + SizeRestriction: None + SingleValued: False + OID: umichAttributeType.41 (1.3.6.1.4.1.250.1.41) + +References + + [1] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, + University of Minnesota, December 1994. + + + [2] Berners-Lee, T., and D. Connolly, "Hypertext Markup Language - + 2.0", RFC 1866, + + [3] The Directory: Overview of Concepts, Models and Service. CCITT + Recommendation X.500, 1988. + + [4] Information Processing Systems -- Open Systems Interconnection -- + The Directory: Overview of Concepts, Models and Service. ISO/IEC JTC + 1/SC21; International Standard 9594-1, 1988. + + + + + + + + + + +Smith Standards Track [Page 4] + +RFC 2079 URI Attribute Type and Object Class January 1997 + + +Author's Address + + Mark Smith + Netscape Communications Corp. + 501 E. Middlefield Rd. + Mountain View, CA 94043, USA + + Phone: +1 415 937-3477 + EMail: mcs@netscape.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Smith Standards Track [Page 5] + diff --git a/doc/rfc/rfc2559.txt b/doc/rfc/rfc2559.txt new file mode 100644 index 0000000000..3768a2a822 --- /dev/null +++ b/doc/rfc/rfc2559.txt @@ -0,0 +1,731 @@ + + + + + + +Network Working Group S. Boeyen +Request for Comments: 2559 Entrust +Updates: 1778 T. Howes +Category: Standards Track Netscape + P. Richard + Xcert + April 1999 + + + Internet X.509 Public Key Infrastructure + Operational Protocols - LDAPv2 + +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 (1999). All Rights Reserved. + +1. Abstract + + The protocol described in this document is designed to satisfy some + of the operational requirements within the Internet X.509 Public Key + Infrastructure (IPKI). Specifically, this document addresses + requirements to provide access to Public Key Infrastructure (PKI) + repositories for the purposes of retrieving PKI information and + managing that same information. The mechanism described in this + document is based on the Lightweight Directory Access Protocol (LDAP) + v2, defined in RFC 1777, defining a profile of that protocol for use + within the IPKI and updates encodings for certificates and revocation + lists from RFC 1778. Additional mechanisms addressing PKIX + operational requirements are specified in separate documents. + + The key words 'MUST', 'REQUIRED', 'SHOULD', 'RECOMMENDED', and 'MAY' + in this document are to be interpreted as described in RFC 2119. + +2. Introduction + + This specification is part of a multi-part standard for development + of a Public Key Infrastructure (PKI) for the Internet. This + specification addresses requirements to provide retrieval of X.509 + PKI information, including certificates and CRLs from a repository. + This specification also addresses requirements to add, delete and + + + +Boeyen, et al. Standards Track [Page 1] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + + modify PKI information in a repository. A profile based on the LDAP + version 2 protocol is provided to satisfy these requirements. + +3. Model + + The PKI components, as defined in PKIX Part 1, which are involved in + PKIX operational protocol interactions include: + + - End Entities + - Certification Authorities (CA) + - Repository + + End entities and CAs using LDAPv2, retrieve PKI information from the + repository using a subset of the LDAPv2 protocol. + + CAs populate the repository with PKI information using a subset of + the LDAPv2 protocol. + +4. Lightweight Directory Access Protocol (LDAP) + + The following sections examine the retrieval of PKI information from + a repository and management of PKI information in a repository. A + profile of the LDAPv2 protocol is defined for providing these + services. + + Section 5 satisfies the requirement to retrieve PKI information (a + certificate, CRL, or other information of interest) from an entry in + the repository, where the retrieving entity (either an end entity or + a CA) has knowledge of the name of the entry. This is termed + "repository read". + + Section 6 satisfies the same requirement as 5 for the situation where + the name of the entry is not known, but some other related + information which may optionally be used as a filter against + candidate entries in the repository, is known. This is termed + "repository search". + + Section 7 satisfies the requirement of CAs to add, delete and modify + PKI information information (a certificate, CRL, or other information + of interest)in the repository. This is termed "repository modify". + + The subset of LDAPv2 needed to support each of these functions is + described below. Note that the repository search service is a + superset of the repository read service in terms of the LDAPv2 + functionality needed. + + Note that all tags are implicit by default in the ASN.1 definitions + that follow. + + + +Boeyen, et al. Standards Track [Page 2] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + +5. LDAP Repository Read + + To retrieve information from an entry corresponding to the subject or + issuer name of a certificate, requires a subset of the following + three LDAP operations: + + BindRequest (and BindResponse) + SearchRequest (and SearchResponse) + UnbindRequest + + The subset of each REQUIRED operation is given below. + +5.1. Bind + +5.1.1. Bind Request + + The full LDAP v2 Bind Request is defined in RFC 1777. + + An application providing a LDAP repository read service MUST + implement the following subset of this operation: + + BindRequest ::= + [APPLICATION 0] SEQUENCE { + version INTEGER (2), + name LDAPDN, -- MUST accept NULL LDAPDN + simpleauth [0] OCTET STRING -- MUST accept NULL simple + } + + An application providing a LDAP repository read service MAY implement + other aspects of the BindRequest as well. + + Different services may have different security requirements. Some + services may allow anonymous search, others may require + authentication. Those services allowing anonymous search may choose + only to allow search based on certain criteria and not others. + + A LDAP repository read service SHOULD implement some level of + anonymous search access. A LDAP repository read service MAY implement + authenticated search access. + +5.1.2. Bind Response + + The full LDAPv2 BindResponse is described in RFC 1777. + + An application providing a LDAP repository read service MUST + implement this entire protocol element, though only the following + error codes may be returned from a Bind operation: + + + + +Boeyen, et al. Standards Track [Page 3] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + + success (0), + operationsError (1), + protocolError (2), + authMethodNotSupported (7), + noSuchObject (32), + invalidDNSyntax (34), + inappropriateAuthentication (48), + invalidCredentials (49), + busy (51), + unavailable (52), + unwillingToPerform (53), + other (80) + +5.2. Search + +5.2.1. Search Request + + The full LDAPv2 SearchRequest is defined in RFC 1777. + + An application providing a LDAP repository read service MUST + implement the following subset of the SearchRequest. + + SearchRequest ::= + [APPLICATION 3] SEQUENCE { + baseObject LDAPDN, + scope ENUMERATED { + baseObject (0), + }, + derefAliases ENUMERATED { + neverDerefAliases (0), + }, + sizeLimit INTEGER (0), + timeLimit INTEGER (0), + attrsOnly BOOLEAN, -- FALSE only + filter Filter, + attributes SEQUENCE OF AttributeType + } + + Filter ::= + CHOICE { + present [7] AttributeType, -- "objectclass" only + } + + This subset of the LDAPv2 SearchRequest allows the LDAPv2 "read" + operation: a base object search with a filter testing for the + existence of the objectClass attribute. + + + + + +Boeyen, et al. Standards Track [Page 4] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + + An application providing a LDAP repository read service MAY implement + other aspects of the SearchRequest as well. + +5.2.2. + + The full LDAPv2 SearchResponse is defined in RFC 1777. + + An application providing a LDAP repository read service over LDAPv2 + MUST implement the full SearchResponse. + + Note that in the case of multivalued attributes such as + userCertificate a SearchResponse containing this attribute will + include all values, assuming the requester has sufficient access + permissions. The application/relying party may need to select an + appropriate value to be used. Also note that retrieval of a + certificate from a named entry does not guarantee that the + certificate will include that same Distinguished Name (DN) and in + some cases the subject DN in the certificate may be NULL. + +5.3. Unbind + + The full LDAPv2 UnbindRequest is defined in RFC 1777. + + An application providing a LDAP repository read service MUST + implement the full UnbindRequest. + +6. LDAP Repository Search + + To search, using arbitrary criteria, for an entry in a repository + containing a certificate, CRL, or other information of interest, + requires a subset of the following three LDAP operations: + + BindRequest (and BindResponse) + SearchRequest (and SearchResponse) + UnbindRequest + + The subset of each operation REQUIRED is given below. + +6.1. Bind + + The BindRequest and BindResponse subsets needed are the same as those + described in Section 5.1. + + The full LDAP v2 Bind Request is defined in RFC 1777. + + + + + + + +Boeyen, et al. Standards Track [Page 5] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + +6.2. Search + +6.2.1. Search Request + + The full LDAPv2 SearchRequest is defined in RFC 1777. + + An application providing a LDAP repository search service MUST + implement the following subset of the SearchRequest protocol unit. + + SearchRequest ::= + [APPLICATION 3] SEQUENCE { + baseObject LDAPDN, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefAliases (0), + }, + sizeLimit INTEGER (0 .. maxInt), + timeLimit INTEGER (0 .. maxInt), + attrsOnly BOOLEAN, -- FALSE only + filter Filter, + attributes SEQUENCE OF AttributeType + } + + All aspects of the SearchRequest MUST be supported, except for the + following: + + - Only the neverDerefAliases value of derefAliases needs to be + supported + + - Only the FALSE value for attrsOnly needs to be supported + + This subset provides a more general search capability. It is a + superset of the SearchRequest subset defined in Section 5.2.1. The + elements added to this service are: + + - singleLevel and wholeSubtree scope needs to be supported + + - sizeLimit is included + + - timeLimit is included + + - Enhanced filter capability + + + + + +Boeyen, et al. Standards Track [Page 6] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + + An application providing a LDAP repository search service MAY + implement other aspects of the SearchRequest as well. + +6.2.2. Search Response + + The full LDAPv2 SearchResponse is defined in RFC 1777. + + An application providing a LDAP repository search service over LDAPv2 + MUST implement the full SearchResponse. + +6.3. Unbind + + An application providing a LDAP repository search service MUST + implement the full UnbindRequest. + +7. LDAP Repository Modify + + To add, delete and modify PKI information in a repository requires a + subset of the following LDAP operations: + + BindRequest (and BindResponse) + ModifyRequest (and ModifyResponse) + AddRequest (and AddResponse) + DelRequest (and DelResponse + UnbindRequest + + The subset of each operation REQUIRED is given below. + +7.1. Bind + + The full LDAP v2 Bind Request is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the following subset of this operation: + + BindRequest ::= + [APPLICATION 0] SEQUENCE { + version INTEGER (2), + name LDAPDN, + simpleauth [0] OCTET STRING + } + + A LDAP repository modify service MUST implement authenticated access. + + The BindResponse subsets needed are the same as those described in + Section 5.1.2. + + + + + +Boeyen, et al. Standards Track [Page 7] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + +7.2. Modify + +7.2.1. Modify Request + + The full LDAPv2 ModifyRequest is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the following subset of the ModifyRequest protocol unit. + + ModifyRequest ::= + [APPLICATION 6] SEQUENCE { + object LDAPDN, + modification SEQUENCE OF SEQUENCE { + operation ENUMERATED { + add (0), + delete (1) + }, + modification SEQUENCE { + type AttributeType, + values SET OF + AttributeValue + } + } + } + + All aspects of the ModifyRequest MUST be supported, except for the + following: + + - Only the add and delete values of operation need to be supported + +7.2.2. Modify Response + + The full LDAPv2 ModifyResponse is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the full ModifyResponse. + +7.3. Add + +7.3.1. Add Request + + The full LDAPv2 AddRequest is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the full AddRequest. + + + + + + +Boeyen, et al. Standards Track [Page 8] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + +7.3.2. Add Response + + The full LDAPv2 AddResponse is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the full AddResponse. + +7.4. Delete + +7.4.1. Delete Request + + The full LDAPv2 DelRequest is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the full DelRequest. + +7.4.2. Delete Response + + The full LDAPv2 DelResponse is defined in RFC 1777. + + An application providing a LDAP repository modify service MUST + implement the full DelResponse. + +7.5. Unbind + + An application providing a LDAP repository modify service MUST + implement the full UnbindRequest. + +8. Non-standard attribute value encodings + + When conveyed in LDAP requests and results, attributes defined in + X.500 are to be encoded using string representations defined in RFC + 1778, The String Representation of Standard Attribute Syntaxes. + These string encodings were based on the attribute definitions from + X.500(1988). Thus, the string representations of the PKI information + elements are for version 1 certificates and version 1 revocation + lists. Since this specification uses version 3 certificates and + version 2 revocation lists, as defined in X.509(1997), the RFC 1778 + string encoding of these attributes is inappropriate. + + For this reason, these attributes MUST be encoded using a syntax + similar to the syntax "Undefined" from section 2.1 of RFC 1778: + values of these attributes are encoded as if they were values of type + "OCTET STRING", with the string value of the encoding being the DER- + encoding of the value itself. For example, when writing a + userCertificate to the repository, the CA generates a DER-encoding of + the certificate and uses that encoding as the value of the + userCertificate attribute in the LDAP Modify request.This encoding + + + +Boeyen, et al. Standards Track [Page 9] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + + style is consistent with the encoding scheme proposed for LDAPv3, + which is now being defined within the IETF. + + Note that certificates and revocation lists will be transferred using + this mechanism rather than the string encodings in RFC 1778 and + client systems which do not understand this encoding may experience + problems with these attributes. + +9. Transport + + An application providing a LDAP repository read service, LDAP + repository search service, or LDAP repository modify service MUST + support LDAPv2 transport over TCP, as defined in Section 3.1 of RFC + 1777. + + An application providing a LDAP repository read service, LDAP + repository search service, or LDAP repository modify service MAY + support LDAPv2 transport over other reliable transports as well. + +10. Security Considerations + + Since the elements of information which are key to the PKI service + (certificates and CRLs) are both digitally signed pieces of + information, additional integrity service is NOT REQUIRED. As + neither information element need be kept secret and anonymous access + to such information, for retrieval purposes is generally acceptable, + privacy service is NOT REQUIRED for information retrieval requests. + + CAs have additional requirements, including modification of PKI + information. Simple authentication alone is not sufficient for these + purposes. It is RECOMMENDED that some stronger means of + authentication and/or (if simple authentication is used) some means + of protecting the privacy of the password is used, (e.g. accept + modifications only via physically secure networks, use IPsec, use SSH + or TLS or SSL tunnel). Without such authentication, it is possible + that a denial-of-service attack could occur where the attacker + replaces valid certificates with bogus ones. + + For the LDAP repository modify service, profiled in section 7, there + are some specific security considerations with respect to access + control. These controls apply to a repository which is under the same + management control as the CA. Organizations operating directories are + NOT REQUIRED to provide external CAs access permission to their + directories. + + + + + + + +Boeyen, et al. Standards Track [Page 10] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + + The CA MUST have access control permissions allowing it to: + + For CA entries: + - add, modify and delete all PKI attributes for its own + directory entry; + - add, modify and delete all values of these attributes. + + For CRL distribution point entries (if used): + - create, modify and delete entries of object class + cRLDistributionPoint immediately subordinate to its own + entry; + - add, modify and delete all attributes, and all values of + these attributes for these entries. + + For subscriber (end-entity) entries: + - add, modify and delete the attribute userCertificate and all + values of that attribute, issued by this CA to/from these + entries. + + The CA is the ONLY entity with these permissions. + + An application providing LDAP repository read, LDAP repository + search, or LDAP repository modify service as defined in this + specification is NOT REQUIRED to implement any additional security + features other than those described herein, however an implementation + SHOULD do so. + +11. References + + [1] Yeong, Y., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol", RFC 1777, March 1995. + + [2] Howes, T., Kille, S., Yeong, W. and C. Robbins, "The String + Representation of Standard Attribute Syntaxes", RFC 1778, March + 1995. + + [3] Bradner, S., "Key Words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + + + + + + + + + + + + +Boeyen, et al. Standards Track [Page 11] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + +12. Authors' Addresses + + Sharon Boeyen + Entrust Technologies Limited + 750 Heron Road + Ottawa, Ontario + Canada K1V 1A7 + + EMail: sharon.boeyen@entrust.com + + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd. + Mountain View, CA 94043 + USA + + EMail: howes@netscape.com + + + Patrick Richard + Xcert Software Inc. + Suite 1001, 701 W. Georgia Street + P.O. Box 10145 + Pacific Centre + Vancouver, B.C. + Canada V7Y 1C6 + + EMail: patr@xcert.com + + + + + + + + + + + + + + + + + + + + + + +Boeyen, et al. Standards Track [Page 12] + +RFC 2559 PKIX Operational Protocols - LDAPv2 April 1999 + + +13. Full Copyright Statement + + Copyright (C) The Internet Society (1999). 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. + + + + + + + + + + + + + + + + + + + + + + + + +Boeyen, et al. Standards Track [Page 13] + diff --git a/doc/rfc/rfc2587.txt b/doc/rfc/rfc2587.txt new file mode 100644 index 0000000000..a5c18a68cd --- /dev/null +++ b/doc/rfc/rfc2587.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group S. Boeyen +Request for Comments: 2587 Entrust +Category: Standards Track T. Howes + Netscape + P. Richard + Xcert + June 1999 + + + + Internet X.509 Public Key Infrastructure + LDAPv2 Schema + +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 (1999). All Rights Reserved. + +1. Abstract + + The schema defined in this document is a minimal schema to support + PKIX in an LDAPv2 environment, as defined in RFC 2559. Only PKIX- + specific components are specified here. LDAP servers, acting as PKIX + repositories should support the auxiliary object classes defined in + this specification and integrate this schema specification with the + generic and other application-specific schemas as appropriate, + depending on the services to be supplied by that server. + + The key words 'MUST', 'SHALL', 'REQUIRED', 'SHOULD', 'RECOMMENDED', + and 'MAY' in this document are to be interpreted as described in RFC + 2119. + +2. Introduction + + This specification is part of a multi-part standard for development + of a Public Key Infrastructure (PKI) for the Internet. LDAPv2 is one + mechanism defined for access to a PKI repository. Other mechanisms, + such as http, are also defined. If an LDAP server, accessed by LDAPv2 + is used to provide a repository, the minimum requirement is that the + repository support the addition of X.509 certificates to directory + + + + +Boeyen, et al. Standards Track [Page 1] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + + entries. Certificate Revocation List (CRL)is one mechanism for + publishing revocation information in a repository. Other mechanisms, + such as http, are also defined. + + This specification defines the attributes and object classes to be + used by LDAP servers acting as PKIX repositories and to be understood + by LDAP clients communicating with such repositories to query, add, + modify and delete PKI information. Some object classes and attributes + defined in X.509 are duplicated here for completeness. For end + entities and Certification Authorities (CA), the earlier X.509 + defined object classes mandated inclusion of attributes which are + optional for PKIX. Also, because of the mandatory attribute + specification, this would have required dynamic modification of the + object class attribute should the attributes not always be present in + entries. For these reasons, alternative object classes are defined in + this document for use by LDAP servers acting as PKIX repositories. + +3. PKIX Repository Objects + + The primary PKIX objects to be represented in a repository are: + + - End Entities + - Certification Authorities (CA) + + These objects are defined in RFC 2459. + +3.1. End Entities + + For purposes of PKIX schema definition, the role of end entities as + subjects of certificates is the major aspect relevant to this + specification. End entities may be human users, or other types of + entities to which certificates may be issued. In some cases, the + entry for the end entity may already exist and the PKI-specific + information is added to the existing entry. In other cases the entry + may not exist prior to the issuance of a certificate, in which case + the entity adding the certificate may also need to create the entry. + Schema elements used to represent the non PKIX aspects of an entry, + such as the structural object class used to represent organizational + persons, may vary, depending on the particular environment and set of + applications served and are outside the scope of this specification. + + The following auxiliary object class MAY be used to represent + certificate subjects: + + + + + + + + +Boeyen, et al. Standards Track [Page 2] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + +pkiUser OBJECT-CLASS ::= { + SUBCLASS OF { top} + KIND auxiliary + MAY CONTAIN {userCertificate} + ID joint-iso-ccitt(2) ds(5) objectClass(6) pkiUser(21)} + +userCertificate ATTRIBUTE ::= { + WITH SYNTAX Certificate + EQUALITY MATCHING RULE certificateExactMatch + ID joint-iso-ccitt(2) ds(5) attributeType(4) userCertificate(36) } + + An end entity may obtain one or more certificates from one or more + Certification Authorities. The userCertificate attribute MUST be + used to represent these certificates in the directory entry + representing that user. + +3.2. Certification Authorities + + As with end entities, Certification Authorities are typically + represented in directories as auxiliary components of entries + representing a more generic object, such as organizations, + organizational units etc. The non PKIX-specific schema elements for + these entries, such as the structural object class of the object, are + outside the scope of this specification. + + The following auxiliary object class MAY be used to represent + Certification Authorities: + +pkiCA OBJECT-CLASS ::= { + SUBCLASS OF { top} + KIND auxiliary + MAY CONTAIN {cACertificate | + certificateRevocationList | + authorityRevocationList | + crossCertificatePair } + ID joint-iso-ccitt(2) ds(5) objectClass(6) pkiCA(22)} + +cACertificate ATTRIBUTE ::= { + WITH SYNTAX Certificate + EQUALITY MATCHING RULE certificateExactMatch + ID joint-iso-ccitt(2) ds(5) attributeType(4) cACertificate(37) } + +crossCertificatePairATTRIBUTE::={ + WITH SYNTAX CertificatePair + EQUALITY MATCHING RULE certificatePairExactMatch + ID joint-iso-ccitt(2) ds(5) attributeType(4) crossCertificatePair(40)} + + + + + +Boeyen, et al. Standards Track [Page 3] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + + The cACertificate attribute of a CA's directory entry shall be used + to store self-issued certificates (if any) and certificates issued to + this CA by CAs in the same realm as this CA. + + The forward elements of the crossCertificatePair attribute of a CA's + directory entry shall be used to store all, except self-issued + certificates issued to this CA. Optionally, the reverse elements of + the crossCertificatePair attribute, of a CA's directory entry may + contain a subset of certificates issued by this CA to other CAs. + When both the forward and the reverse elements are present in a + single attribute value, issuer name in one certificate shall match + the subject name in the other and vice versa, and the subject public + key in one certificate shall be capable of verifying the digital + signature on the other certificate and vice versa. + + When a reverse element is present, the forward element value and the + reverse element value need not be stored in the same attribute value; + in other words, they can be stored in either a single attribute value + or two attribute values. + + In the case of V3 certificates, none of the above CA certificates + shall include a basicConstraints extension with the cA value set to + FALSE. + + The definition of realm is purely a matter of local policy. + + certificateRevocationListATTRIBUTE::={ + WITH SYNTAX CertificateList + EQUALITY MATCHING RULE certificateListExactMatch + ID joint-iso-ccitt(2) ds(5) attributeType(4) + certificateRevocationList(39)} + + The certificateRevocationList attribute, if present in a particular + CA's entry, contains CRL(s) as defined in RFC 2459. + + authorityRevocationListATTRIBUTE::={ + WITH SYNTAX CertificateList + EQUALITY MATCHING RULE certificateListExactMatch + ID joint-iso-ccitt(2) ds(5) attributeType(4) + authorityRevocationList(38)} + + The authorityRevocationList attribute, if present in a particular + CA's entry, includes revocation information regarding certificates + issued to other CAs. + + + + + + + +Boeyen, et al. Standards Track [Page 4] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + +3.2.1. CRL distribution points + + CRL distribution points are an optional mechanism, specified in RFC + 2459, which MAY be used to distribute revocation information. + + A patent statement regarding CRL distribution points can be found at + the end of this document. + + If a CA elects to use CRL distribution points, the following object + class is used to represent these. + + cRLDistributionPoint OBJECT-CLASS::= { + SUBCLASS OF { top } + KIND structural + MUST CONTAIN { commonName } + MAY CONTAIN { certificateRevocationList | + authorityRevocationList | + deltaRevocationList } + ID joint-iso-ccitt(2) ds(5) objectClass(6) cRLDistributionPoint(19) } + + The certificateRevocationList and authorityRevocationList attributes + are as defined above. + + The commonName attribute and deltaRevocationList attributes, defined + in X.509, are duplicated below. + + commonName ATTRIBUTE::={ + SUBTYPE OF name + WITH SYNTAX DirectoryString + ID joint-iso-ccitt(2) ds(5) attributeType(4) commonName(3) } + + deltaRevocationList ATTRIBUTE ::= { + WITH SYNTAX CertificateList + EQUALITY MATCHING RULE certificateListExactMatch + ID joint-iso-ccitt(2) ds(5) attributeType(4) + deltaRevocationList(53) } + +3.2.2. Delta CRLs + + Delta CRLs are an optional mechanism, specified in RFC 2459, which + MAY be used to enhance the distribution of revocation information. + + If a CA elects to use delta CRLs, the following object class is used + to represent these. + + + + + + + +Boeyen, et al. Standards Track [Page 5] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + + deltaCRL OBJECT-CLASS::= { + SUBCLASS OF { top } + KIND auxiliary + MAY CONTAIN { deltaRevocationList } + ID joint-iso-ccitt(2) ds(5) objectClass(6) deltaCRL(23) } + +4. Security Considerations + + Since the elements of information which are key to the PKI service + (certificates and CRLs) are both digitally signed pieces of + information, no additional integrity service is REQUIRED. + + Security considerations with respect to retrieval, addition, + deletion, and modification of the information supported by this + schema definition are addressed in RFC 2559. + +5. References + + [1] Yeong, Y., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol", RFC 1777, March 1995. + + [2] Bradner, S., "Key Words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + +6 Intellectual Property Rights + + The IETF has been notified of intellectual property rights claimed in + regard to some or all of the specification contained in this + document. For more information consult the online list of claimed + rights. + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + + + + + + +Boeyen, et al. Standards Track [Page 6] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + +7. Authors' Addresses + + Sharon Boeyen + Entrust Technologies Limited + 750 Heron Road + Ottawa, Ontario + Canada K1V 1A7 + + EMail: sharon.boeyen@entrust.com + + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd. + Mountain View, CA 94043 + USA + + EMail: howes@netscape.com + + + Patrick Richard + Xcert Software Inc. + Suite 1001, 701 W. Georgia Street + P.O. Box 10145 + Pacific Centre + Vancouver, B.C. + Canada V7Y 1C6 + + EMail: patr@xcert.com + + + + + + + + + + + + + + + + + + + + + + +Boeyen, et al. Standards Track [Page 7] + +RFC 2587 PKIX LDAPv2 Schema June 1999 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1999). 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. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Boeyen, et al. Standards Track [Page 8] + diff --git a/doc/rfc/rfc2589.txt b/doc/rfc/rfc2589.txt new file mode 100644 index 0000000000..002385162c --- /dev/null +++ b/doc/rfc/rfc2589.txt @@ -0,0 +1,675 @@ + + + + + + +Network Working Group Y. Yaacovi +Request for Comments: 2589 Microsoft +Category: Standards Track M. Wahl + Innosoft International, Inc. + T. Genovese + Microsoft + May 1999 + + + Lightweight Directory Access Protocol (v3): + Extensions for Dynamic Directory Services + +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 (1999). All Rights Reserved. + +1. Abstract + + This document defines the requirements for dynamic directory services + and specifies the format of request and response extended operations + for supporting client-server interoperation in a dynamic directories + environment. + + The Lightweight Directory Access Protocol (LDAP) [1] supports + lightweight access to static directory services, allowing relatively + fast search and update access. Static directory services store + information about people that persists in its accuracy and value over + a long period of time. + + Dynamic directory services are different in that they store + information that only persists in its accuracy and value when it is + being periodically refreshed. This information is stored as dynamic + entries in the directory. A typical use will be a client or a person + that is either online - in which case it has an entry in the + directory, or is offline - in which case its entry disappears from + the directory. Though the protocol operations and attributes used by + dynamic directory services are similar to the ones used for static + directory services, clients that store dynamic information in the + directory need to periodically refresh this information, in order to + prevent it from disappearing. If dynamic entries are not refreshed + + + +Yaacovi, et al. Standards Track [Page 1] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + within a given timeout, they will be removed from the directory. For + example, this will happen if the client that set them goes offline. + + A flow control mechanism from the server is also described that + allows a server to inform clients how often they should refresh their + presence. + +2. Requirements + + The protocol extensions must allow accessing dynamic information in a + directory in a standard LDAP manner, to allow clients to access + static and dynamic information in the same way. + + By definition, dynamic entries are not persistent and clients may go + away gracefully or not. The proposed extensions must offer a way for + a server to tell if entries are still valid, and to do this in a way + that is scalable. There also must be a mechanism for clients to + reestablish their entry with the server. + + There must be a way for clients to find out, in a standard LDAP + manner, if servers support the dynamic extensions. + + Finally, to allow clients to broadly use the dynamic extensions, the + extensions need to be registered as standard LDAP extended + operations. + +3. Description of Approach + + The Lightweight Directory Access Protocol (LDAP) [1] permits + additional operation requests and responses to be added to the + protocol. This proposal takes advantage of these to support + directories which contain dynamic information in a manner which is + fully integrated with LDAP. + + The approach described in this proposal defines dynamic entries in + order to allow implementing directories with dynamic information. An + implementation of dynamic directories, must be able to support + dynamic directory entries. + +3.1. Dynamic Entries and the dynamicObject object class + + A dynamic entry is an object in the directory tree which has a time- + to-live associated with it. This time-to-live is set when the entry + is created. The time-to-live is automatically decremented, and when + it expires the dynamic entry disappears. By invoking the refresh + extended operation (defined below) to re-set the time-to-live, a + client can cause the entry to remain present a while longer. + + + + +Yaacovi, et al. Standards Track [Page 2] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + A dynamic entry is created by including the objectClass value given + in section 5 in the list of attributes when adding an entry. This + method is subject to standard access control restrictions. + + The extended operation covered here, allows a client to refresh a + dynamic entry by invoking, at intervals, refresh operations + containing that entry's name. Dynamic entries will be treated the + same as non-dynamic entries when processing search, compare, add, + delete, modify and modifyDN operations. However if clients stop + sending refresh operations for an entry, then the server will + automatically and without notification remove that entry from the + directory. This removal will be treated the same as if the entry had + been deleted by an LDAP protocol operation. + + There is no way to change a static entry into a dynamic one and + vice-versa. If the client is using Modify with an objectClass of + dynamicObject on a static entry, the server must return a service + error either "objectClassModsProhibited" (if the server does not + allow objectClass modifications at all) or "objectClassViolation" (if + the server does allow objectClass modifications in general). + + A dynamic entry may be removed by the client using the delete + operation. This operation will be subject to access control + restrictions. + + A non-dynamic entry cannot be added subordinate to a dynamic entry: + the server must return an appropriate update or service error if this + is attempted. + + The support of dynamic attributes of an otherwise static object, are + outside the scope of this document. + +3.2 Dynamic meetings (conferences) + + The way dynamicObject is defined, it has a time-to-live associated + with it, and that's about it. Though the most common dynamic object + is a person object, there is no specific type associated with the + dynamicObject as defined here. By the use of the dynamic object's + attributes, one can make this object represent practically anything. + + Specifically, Meetings (conferences) can be represented by dynamic + objects. While full-featured meeting support requires special + semantics and handling by the server (and is not in the scope of this + document), the extensions described here, provide basic meetings + support. A meeting object can be refreshed by the meeting + participants, and when it is not, the meeting entry disappears. The + one meeting type that is naturally supported by the dynamic + extensions is creator-owned meeting. + + + +Yaacovi, et al. Standards Track [Page 3] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + +3.2.1 Creator-owned meetings + + Creator-owned meetings are created by a client that sets the time- + to-live attribute for the entry, and it is this client's + responsibility to refresh the meeting entry, so that it will not + disappear. Others might join the meeting, by modifying the + appropriate attribute, but they are not allowed to refresh the entry. + When the client that created the entry goes away, it can delete the + meeting entry, or it might disappear when its time-to-live expires. + This is consistent with the common model for dynamicObject as + described above. + +4. Protocol Additions + +4.1 Refresh Request + + Refresh is a protocol operation sent by a client to tell the server + that the client is still alive and the dynamic directory entry is + still accurate and valuable. The client sends a Refresh request + periodically based on the value of the client refresh period (CRP). + The server can request that the client change this value. As long as + the server receives a Refresh request within the timeout period, the + directory entry is guaranteed to persist on the server. Client + implementers should be aware that since the intervening network + between the client and server is unreliable, a Refresh request packet + may be delayed or lost while in transit. If this occurs, the entry + may disappear, and the client will need to detect this and re-add the + entry. + + A client may request this operation by transmitting an LDAP PDU + containing an ExtendedRequest. An LDAP ExtendedRequest is defined as + follows: + + ExtendedRequest ::= [APPLICATION 23] SEQUENCE { + requestName [0] LDAPOID, + requestValue [1] OCTET STRING OPTIONAL } + + The requestName field must be set to the string + "1.3.6.1.4.1.1466.101.119.1". + + The requestValue field will contain as a value the DER-encoding of + the following ASN.1 data type: + + SEQUENCE { + entryName [0] LDAPDN, + requestTtl [1] INTEGER + } + + + + +Yaacovi, et al. Standards Track [Page 4] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + The entryName field is the UTF-8 string representation of the name of + the dynamic entry [3]. This entry must already exist. + + The requestTtl is a time in seconds (between 1 and 31557600) that the + client requests that the entry exists in the directory before being + automatically removed. Servers are not required to accept this value + and might return a different TTL value to the client. Clients must + be able to use this server-dictated value as their CRP. + +4.2 Refresh Response + + If a server implements this extension, then when the request is made + it will return an LDAP PDU containing an ExtendedResponse. An LDAP + ExtendedResponse is defined as follows: + + ExtendedResponse ::= [APPLICATION 24] SEQUENCE { + COMPONENTS OF LDAPResult, + responseName [10] LDAPOID OPTIONAL, + response [11] OCTET STRING OPTIONAL } + + The responseName field contains the same string as that present in + the request. + + The response field will contain as a value the DER-encoding of the + following ASN.1 data type: + + SEQUENCE { + responseTtl [1] INTEGER + } + + The responseTtl field is the time in seconds which the server chooses + to have as the time-to-live field for that entry. It must not be any + smaller than that which the client requested, and it may be larger. + However, to allow servers to maintain a relatively accurate + directory, and to prevent clients from abusing the dynamic + extensions, servers are permitted to shorten a client-requested + time-to-live value, down to a minimum of 86400 seconds (one day). + + If the operation was successful, the errorCode field in the + standardResponse part of an ExtendedResponse will be set to success. + + In case of an error, the responseTtl field will have the value 0, and + the errorCode field will contain an appropriate value, as follows: If + the entry named by entryName could not be located, the errorCode + field will contain "noSuchObject". If the entry is not dynamic, the + errorCode field will contain "objectClassViolation". If the + requester does not have permission to refresh the entry, the + + + + +Yaacovi, et al. Standards Track [Page 5] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + errorCode field will contain "insufficientAccessRights". If the + requestTtl field is too large, the errorCode field will contain + "sizeLimitExceeded". + + If a server does not implement this extension, it will return an LDAP + PDU containing an ExtendedResponse, which contains only the + standardResponse element (the responseName and response elements will + be absent). The LDAPResult element will indicate the protocolError + result code. + + This request is permitted to be invoked when LDAP is carried by a + connectionless transport. + + When using a connection-oriented transport, there is no requirement + that this operation be on the same particular connection as any + other. A client may open multiple connections, or close and then + reopen a connection. + +4.3 X.500/DAP Modify(97) + + X.500/DAP servers can map the Refresh request and response operations + into the X.500/DAP Modify(97) operation. + +5. Schema Additions + + All dynamic entries must have the dynamicObject value in their + objectClass attribute. This object class is defined as follows + (using the ObjectClassDescription notation of [2]): + + ( 1.3.6.1.4.1.1466.101.119.2 NAME 'dynamicObject' + DESC 'This class, if present in an entry, indicates that this entry + has a limited lifetime and may disappear automatically when + its time-to-live has reached 0. There are no mandatory + attributes of this class, however if the client has not + supplied a value for the entryTtl attribute, the server will + provide one.' + SUP top AUXILIARY ) + + Furthermore, the dynamic entry must have the following operational + attribute. It is described using the AttributeTypeDescription + notation of [2]: + + ( 1.3.6.1.4.1.1466.101.119.3 NAME 'entryTtl' + DESC 'This operational attribute is maintained by the server and + appears to be present in every dynamic entry. The attribute + is not present when the entry does not contain the + dynamicObject object class. The value of this attribute is + the time in seconds that the entry will continue to exist + + + +Yaacovi, et al. Standards Track [Page 6] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + before disappearing from the directory. In the absence of + intervening refresh operations, the values returned by + reading the attribute in two successive searches are + guaranteed to be nonincreasing. The smallest permissible + value is 0, indicating that the entry may disappear without + warning. The attribute is marked NO-USER-MODIFICATION since + it may only be changed using the refresh operation.' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE + NO-USER-MODIFICATION USAGE dSAOperation ) + + To allow servers to support dynamic entries in only a part of the + DIT, the following operational attribute is defined. It is + described using the AttributeTypeDescription notation of [2]: + + ( 1.3.6.1.4.1.1466.101.119.4 NAME 'dynamicSubtrees' + DESC 'This operational attribute is maintained by the server and is + present in the Root DSE, if the server supports the dynamic + extensions described in this memo. The attribute contains a + list of all the subtrees in this directory for which the + server supports the dynamic extensions.' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION + USAGE dSAOperation ) + +6. Client and Server Requirements + +6.1 Client Requirements + + Clients can find out if a server supports the dynamic extensions by + checking the supportedExtension field in the root DSE, to see if the + OBJECT IDENTIFIER described in section 4 is present. Since servers + may select to support the dynamic extensions in only some of the + subtrees of the DIT, clients must check the dynamicSubtrees + operational attribute in the root DSE to find out if the dynamic + extensions are supported on a specific subtree. + + Once a dynamic entry has been created, clients are responsible for + invoking the refresh extended operation, in order to keep that entry + present in the directory. + + Clients must not expect that a dynamic entry will be present in the + DIT after it has timed out, however it must not require that the + server remove the entry immediately (some servers may only process + timing out entries at intervals). If the client wishes to ensure the + entry does not exist it should issue a RemoveRequest for that entry. + + Initially, a client needs to know how often it should send refresh + requests to the server. This value is defined as the CRP (Client + Refresh Period) and is set by the server based on the entryTtl. + + + +Yaacovi, et al. Standards Track [Page 7] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + Since the LDAP AddRequest operation is left unchanged and is not + modified in this proposal to return this value, a client must issue a + Refresh extended operation immediately after an Add that created a + dynamic entry. The Refresh Response will return the CRP (in + responseTtl) to the client. + + Clients must not issue the refresh request for dynamic entries which + they have not created. If an anonymous client attempts to do so, a + server is permitted to return insufficientAccessRights (50) in the + RefreshResponse, enforcing the client to bind first. Please note that + servers which allow anonymous clients to create and refresh dynamic + entries will not be able to enforce the above. + + Clients should always be ready to handle the case in which their + entry timed out. In such a case, the Refresh operation will fail + with an error code such as noSuchObject, and the client is expected + to re-create its entry. + + Clients should be prepared to experience refresh operations failing + with protocolError, even though the add and any previous refresh + requests succeeded. This might happen if a proxy between the client + and the server goes down, and another proxy is used which does not + support the Refresh extended operation. + +6.2 Server Requirements + + Servers are responsible for removing dynamic entries when they time + out. Servers are not required to do this immediately. + + Servers must enforce the structural rules listed in above section 3. + + Servers must ensure that the operational attribute described in + section 5 is present in dynamic entries + + Servers may permit anonymous users to refresh entries. However, to + eliminate the possibility of a malicious use of the Refresh + operation, servers may require the refreshing client to bind first. A + server implementation can achieve this by presenting ACLs on the + entryTtl attribute, and returning insufficientAccessRights (50) in + the RefreshResponse, if the client is not allowed to refresh the + entry. Doing this, though, might have performance implications on the + server and might impact the server's scalability. + + Servers may require that a client which attempts to create a dynamic + entry have a remove permission for that entry. + + Servers which implement the dynamic extensions must have the OBJECT + IDENTIFIER, described above in section 4 for the request and + + + +Yaacovi, et al. Standards Track [Page 8] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + + response, present as a value of the supportedExtension field in the + root DSE. They must also have as values in the attributeTypes and + objectClasses attributes of their subschema subentries, the + AttributeTypeDescription and ObjectClassDescription from section 5. + + Servers can limit the support of the dynamic extensions to only some + of the subtrees in the DIT. Servers indicate for which subtrees they + support the extensions, by specifying the OIDs for the supported + subtrees in the dynamicSubtrees attribute described in section 5. If + a server supports the dynamic extensions for all naming contexts it + holds, the dynamicSubtrees attribute may be absent. + +7. Implementation issues + +7.1 Storage of dynamic information + + Dynamic information is expected to change very often. In addition, + Refresh requests are expected to arrive at the server very often. + Disk-based databases that static directory services often use are + likely inappropriate for storing dynamic information. We recommend + that server implementations store dynamic entries in memory + sufficient to avoid paging. This is not a requirement. + + We expect LDAP servers to be able to store static and dynamic + entries. If an LDAP server does not support dynamic entries, it + should respond with an error code such as objectClassViolation. + +7.2 Client refresh behavior + + In some cases, the client might not get a Refresh response. This may + happen as a result of a server crash after receiving the Refresh + request, the TCP/IP socket timing out in the connection case, or the + UDP packet getting lost in the connection-less case. + + It is recommended that in such a case, the client will retry the + Refresh operation immediately, and if this Refresh request does not + get a response as well, it will resort to its original Refresh cycle, + i.e. send a Refresh request at its Client Refresh Period (CRP). + +7.3 Configuration of refresh times + + We recommend that servers will provide administrators with the + ability to configure the default client refresh period (CRP), and + also a minimum and maximum CRP values. This, together with allowing + administrators to request that the server will not change the CRP + dynamically, will allow administrators to set CRP values which will + enforce a low refresh traffic, or - on the other extreme, an highly + up-to-date directory. + + + +Yaacovi, et al. Standards Track [Page 9] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + +8. Replication + + Replication is only partially addressed in this memo. There is a + separate effort in progress at the IETF on replication of static and + dynamic directories. + + it is allowed to replicate a dynamic entry or a static entry with + dynamic attributes. Since the entryTtl is expressed as a relative + time (how many seconds till the entry will expire), replicating it + means that the replicated entry will be "off" by the replication + time. + +9. Localization + + The are no localization issues for this extended operation. + +10. Security Considerations + + Standard LDAP security rules and support apply for the extensions + described in this document, and there are no special security issues + for these extensions. Please note, though, that servers may permit + anonymous clients to refresh entries which they did not create. + Servers are also permitted to control a refresh access to an entry by + requiring clients to bind before issuing a RefreshRequest. This will + have implications on the server performance and scalability. + + Also, Care should be taken in making use of information obtained from + directory servers that has been supplied by client, as it may now be + out of date. In many networks, for example, IP addresses are + automatically assigned when a host connects to the network, and may + be reassigned if that host later disconnects. An IP address obtained + from the directory may no longer be assigned to the host that placed + the address in the directory. This issue is not specific to LDAP or + dynamic directories. + +11. Acknowledgments + + Design ideas included in this document are based on those discussed + in ASID and other IETF Working Groups. + + + + + + + + + + + + +Yaacovi, et al. Standards Track [Page 10] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + +12. Authors' Addresses + + Yoram Yaacovi + Microsoft + One Microsoft way + Redmond, WA 98052 + USA + + Phone: +1 206-936-9629 + EMail: yoramy@microsoft.com + + + Mark Wahl + Innosoft International, Inc. + 8911 Capital of Texas Hwy #4140 + Austin, TX 78759 + USA + + Email: M.Wahl@innosoft.com + + + Tony Genovese + Microsoft + One Microsoft way + Redmond, WA 98052 + USA + + Phone: +1 206-703-0852 + EMail: tonyg@microsoft.com + +13. Bibliography + + [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol (Version 3)", 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] Wahl, M. and S. Kille, "Lightweight Directory Access Protocol + (v3): UTF-8 String Representation of Distinguished Names", RFC + 2253, December 1997. + + + + + + + + + +Yaacovi, et al. Standards Track [Page 11] + +RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 + + +14. Full Copyright Statement + + Copyright (C) The Internet Society (1999). 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. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Yaacovi, et al. Standards Track [Page 12] + diff --git a/doc/rfc/rfc2596.txt b/doc/rfc/rfc2596.txt new file mode 100644 index 0000000000..eeb950c7ed --- /dev/null +++ b/doc/rfc/rfc2596.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group M. Wahl +Request for Comments: 2596 Innosoft International, Inc. +Category: Standards Track T. Howes + Netscape Communications Corp. + May 1999 + + + Use of Language Codes in LDAP + + +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 (1999). All Rights Reserved. + +1. Abstract + + The Lightweight Directory Access Protocol [1] provides a means for + clients to interrogate and modify information stored in a distributed + directory system. The information in the directory is maintained as + attributes [2] of entries. Most of these attributes have syntaxes + which are human-readable strings, and it is desirable to be able to + indicate the natural language associated with attribute values. + + This document describes how language codes [3] are carried in LDAP + and are to be interpreted by LDAP servers. All implementations MUST + be prepared to accept language codes in the LDAP protocols. Servers + may or may not be capable of storing attributes with language codes + in the directory. This document does not specify how to determine + whether particular attributes can or cannot have language codes. + + 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]. + +2. Language Codes + + Section 2 of RFC 1766 [3] describes the language code format which is + used in LDAP. Briefly, it is a string of ASCII alphabetic characters + and hyphens. Examples include "fr", "en-US" and "ja-JP". + + + + +Wahl & Howes Standards Track [Page 1] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + + Language codes are case insensitive. For example, the language code + "en-us" is the same as "EN-US" and "en-US". + + Implementations MUST NOT otherwise interpret the structure of the + code when comparing two codes, and MUST treat them as simply strings + of characters. Client and server implementations MUST allow any + arbitrary string which follows the patterns given in RFC 1766 to be + used as a language code. + +3. Use of Language Codes in LDAP + + This section describes how LDAP implementations MUST interpret + language codes in performing operations. + + In general, an attribute with a language code is to be treated as a + subtype of the attribute without a language code. If a server does + not support storing language codes with attribute values in the DIT, + then it MUST always treat an attribute with a language code as an + unrecognized attribute. + +3.1. Attribute Description + + An attribute consists of a type, a list of options for that type, and + a set of one or more values. In LDAP, the type and the options are + combined into the AttributeDescription, defined in section 4.1.5 of + [1]. This is represented as an attribute type name and a possibly- + empty list of options. One of these options associates a natural + language with values for that attribute. + + language-option = "lang-" lang-code + + lang-code = printable-ascii ; a code as defined in RFC 1766 + + Multiple language options may be present on a particular value. + + The language code has no effect on the character set encoding for + string representations of DirectoryString syntax values; the UTF-8 + representation of UniversalString (ISO 10646) is always used. + + Examples of valid AttributeDescription: + givenName;lang-en-US + CN;lang-ja + + In LDAP and in examples in this document, a directory attribute is + represented as an AttributeDescription with a list of values. Note + that the data could be stored in the LDAP server in a different + representation. + + + + +Wahl & Howes Standards Track [Page 2] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + +3.2. Distinguished Names and Relative Distinguished Names + + No attribute description options are permitted in Distinguished Names + or Relative Distinguished Names. Thus language codes MUST NOT be + used in forming DNs. + +3.3. Search Filter + + If a language code is present in an AttributeDescription in a search + filter, then only attribute values in the directory which match the + base attribute type or its subtype, the language code and the + assertion value match this filter. + + Thus for example a filter of an equality match of type "name;lang- + en-US" and assertion value "Billy Ray", against the following + directory entry + + objectclass: top DOES NOT MATCH (wrong type) + objectclass: person DOES NOT MATCH (wrong type) + name;lang-EN-US: Billy Ray MATCHES + name;lang-EN-US: Billy Bob DOES NOT MATCH (wrong value) + CN;lang-en-us: Billy Ray MATCHES + CN;lang-EN-US;dynamic: Billy Ray MATCHES + CN;lang-en;dynamic: Billy Ray DOES NOT MATCH (differing lang-) + name: Billy Ray DOES NOT MATCH (no lang-) + SN: Ray DOES NOT MATCH (wrong value) + + (Note that "CN" and "SN" are subtypes of "name".) + + Client implementors should however note that providing a language + code in a search filter AttributeDescription will often filter out + desirable values where the language code does not match exactly. For + example, the filter (name;lang-en=Billy Ray) does NOT match the + attribute "name;lang-en-US: Billy Ray". + + If the server does not support storing language codes with attribute + values in the DIT, then any filter which includes a language code + will always fail to match, as it is an unrecognized attribute type. + No error would be returned because of this; a presence filter would + evaluate to FALSE and all other forms to Undefined. + + If no language code is specified in the search filter, then only the + base attribute type and the assertion value need match the value in + the directory. + + Thus for example a filter of an equality match of type "name" and + assertion value "Billy Ray", against the following directory entry + + + + +Wahl & Howes Standards Track [Page 3] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + + objectclass: top DOES NOT MATCH (wrong type) + objectclass: person DOES NOT MATCH (wrong type) + name;lang-EN-US: Billy Ray MATCHES + name;lang-EN-US: Billy Bob DOES NOT MATCH (wrong value) + CN;lang-EN-US;dynamic: Billy Ray MATCHES + CN;lang-en;dynamic: Billy Ray MATCHES + name: Billy Ray MATCHES + SN: Ray DOES NOT MATCH (wrong value) + + Thus in general, clients SHOULD NOT use the language code option in + AttributeDescription fields in search filters. + +3.4. Compare + + A language code can be present in an AttributeDescription used in a + compare request AttributeValueAssertion. This is to be treated by + servers the same as the use of language codes in a search filter with + an equality match, as described in the previous section. If there is + no attribute in the entry with the same subtype and language code, + the noSuchAttributeType error will be returned. + + Thus for example a compare request of type "name" and assertion value + "Johann", against an entry with all the following directory entry + + objectclass: top + objectclass: person + givenName;lang-de-DE: Johann + CN: Johann Sibelius + SN: Sibelius + + will cause the server to return compareTrue. + + However, if the client issued a compare request of type "name;lang- + de" and assertion value "Johann" against the above entry, the request + would fail with the noSuchAttributeType error. + + If the server does not support storing language codes with attribute + values in the DIT, then any comparison which includes a language code + will always fail to locate an attribute type, and noSuchAttributeType + will be returned. + + Thus in general, clients SHOULD NOT use the language code option in + AttributeDescription fields in the compare request. + +3.5. Requested Attributes in Search + + Clients MAY provide language codes in AttributeDescription in the + requested attribute list in a search request. + + + +Wahl & Howes Standards Track [Page 4] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + + If a language code is provided in an attribute description, then only + attribute values in a directory entry which have the same language + code as that provided are to be returned. Thus if a client requests + an attribute "description;lang-en", the server MUST NOT return values + of an attribute "description" or "description;lang-fr". + + Clients MAY provide in the attribute list multiple + AttributeDescription which have the same base attribute type but + different options. For example a client MAY provide both "name;lang- + en" and "name;lang-fr", and this would permit an attribute with + either language code to be returned. Note there would be no need to + provide both "name" and "name;lang-en" since all subtypes of name + would match "name". + + If a server does not support storing language codes with attribute + values in the DIT, then any attribute descriptions in the list which + include language codes are to be ignored, just as if they were + unknown attribute types. + + If a request is made specifying all attributes or an attribute is + requested without providing a language code, then all attribute + values regardless of their language code are returned. + + For example, if the client requests a "description" attribute, and a + matching entry contains + + objectclass: top + objectclass: organization + O: Software GmbH + description: software + description;lang-en: software products + description;lang-de: Softwareprodukte + postalAddress: Berlin 8001 Germany + postalAddress;lang-de: Berlin 8001 Deutschland + + The server will return: + + description: software + description;lang-en: software products + description;lang-de: Softwareprodukte + +3.6. Add Operation + + Clients MAY provide language codes in AttributeDescription in + attributes of a new entry to be created, subject to the limitation + that the client MUST NOT use language codes in the attribute value or + values which form the RDN of the entry. + + + + +Wahl & Howes Standards Track [Page 5] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + + A client MAY provide multiple attributes with the same attribute type + and value, so long as each attribute has a different language code, + and at most one attribute does not have a language code option. + + Servers which support storing language codes in the DIT MUST allow + any attribute it recognizes that has the Directory String syntax to + have a language option associated with it. Servers SHOULD allow + language options to be associated with other attributes. + + For example, the following is a legal request. + + objectclass: top + objectclass: person + objectclass: residentialPerson + name: John Smith + CN: John Smith + CN;lang-en: John Smith + SN: Smith + streetAddress: 1 University Street + streetAddress;lang-en: 1 University Street + streetAddress;lang-fr: 1 rue Universite + houseIdentifier;lang-fr: 9e etage + + If a server does not support storing language codes with attribute + values in the DIT, then it MUST treat an AttributeDescription with a + language code as an unrecognized attribute. If the server forbids the + addition of unrecognized attributes then it MUST fail the add request + with the appropriate result code. + +3.7. Modify Operation + + A client MAY provide a language code in an AttributeDescription as + part of a modification element in the modify operation. + + Attribute types and language codes MUST match exactly against values + stored in the directory. For example, if the modification is a + "delete", then if the stored values to be deleted have a language + code, the language code MUST be provided in the modify operation, and + if the stored values to be deleted do not have a language code, then + no language code is to be provided. + + If the server does not support storing language codes with attribute + values in the DIT, then it MUST treat an AttributeDescription with a + language code as an unrecognized attribute, and MUST fail the request + with an appropriate result code. + + + + + + +Wahl & Howes Standards Track [Page 6] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + +3.8. Diagnostic Messages + + Servers SHOULD use only printable ASCII characters in the + errorMessage field, as not all clients will be able to display the + full range of Unicode. + +4. Differences from X.500(1997) + + X.500(1997) defines a different mechanism, contexts, as the means of + representing language tags. This section summarizes the major + differences in approach. + + a) An X.500 operation which has specified a language code on a value + matches a value in the directory without a language code. + b) LDAP references RFC 1766, which allows for IANA registration of + new tags. + c) LDAP does not allow language codes in distinguished names. + d) X.500 describes subschema administration procedures to allow + language codes to be associated with particular attributes types. + +5. Security Considerations + + There are no known security considerations for this document. See + the security considerations sections of [1] and [2] for security + considerations of LDAP in general. + +6. Acknowledgements + + This document is a product of the IETF ASID and LDAPEXT working + groups. Martin Duerst provided many valuable comments on an earlier + version of this document. + +7. Bibliography + + [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 + X.500 Directory Access Protocol Attribute Syntax Definitions", + RFC 2252, December 1997. + + [3] Alvestrand, H.,"Tags for the Identification of Languages", RFC + 1766, March 1995. + + [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + + + + +Wahl & Howes Standards Track [Page 7] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + +8. Authors' Addresses + + Mark Wahl + Innosoft International, Inc. + 8911 Capital of Texas Hwy Suite 4140 + Austin, TX 78759 USA + + EMail: M.Wahl@innosoft.com + + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd + Mountain View, CA 94043 USA + + Phone: +1 650 937-3419 + EMail: howes@netscape.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Wahl & Howes Standards Track [Page 8] + +RFC 2596 Use of Language Codes in LDAP May 1999 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1999). 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. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Wahl & Howes Standards Track [Page 9] +