idnits 2.17.1 draft-ietf-ldapbis-dn-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 405 has weird spacing: '...for the purpo...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (29 March 2001) is 8400 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2256bis' is defined on line 354, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 2252 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4523) ** Obsolete normative reference: RFC 2256 (Obsoleted by RFC 4510, RFC 4512, RFC 4517, RFC 4519, RFC 4523) Summary: 11 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Editor: Kurt D. Zeilenga 3 Intended Category: Standard Track OpenLDAP Foundation 4 Expires: 29 September 2001 29 March 2001 5 Obsoletes: 2253 7 Lightweight Directory Access Protocol (v3): 8 UTF-8 String Representation of Distinguished Names 9 11 Status of Memo 13 This document is an Internet-Draft and is in full conformance with all 14 provisions of Section 10 of RFC2026. 16 This document is intended to be, after appropriate review and 17 revision, submitted to the RFC Editor as a Standard Track document 18 replacing RFC 2253. Distribution of this memo is unlimited. 19 Technical discussion of this document will take place on the IETF LDAP 20 Revision Working Group (LDAPbis) mailing list 21 . Please send editorial comments directly 22 to the document editor . 24 Internet-Drafts are working documents of the Internet Engineering Task 25 Force (IETF), its areas, and its working groups. Note that other 26 groups may also distribute working documents as Internet-Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as ``work in progress.'' 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft 34 Shadow Directories can be accessed at http://www.ietf.org/shadow.html. 36 Copyright 2001, The Internet Society. All Rights Reserved. 38 Please see the Copyright section near the end of this document for 39 more information. 41 Abstract 43 The X.500 Directory uses distinguished names as the primary keys to 44 entries in the directory. Distinguished Names are encoded in ASN.1 in 45 the X.500 Directory protocols. In the Lightweight Directory Access 46 Protocol, a string representation of distinguished names is 47 transferred. This specification defines the string format for 48 representing names, which is designed to give a clean representation 49 of commonly used distinguished names, while being able to represent 50 any distinguished name. 52 1. Background 54 This specification assumes familiarity with X.500 [X.500], and the 55 concept of Distinguished Name (DN). It is important to have a common 56 format to be able to unambiguously represent a distinguished name. 57 The primary goal of this specification is ease of encoding and 58 decoding. A secondary goal is to have names that are human readable. 59 It is not expected that LDAP clients with a human user interface would 60 display these strings directly to the user, but would most likely be 61 performing translations (such as expressing attribute type names in 62 one of the local national languages). 64 This document obsoletes RFC 2253. 66 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 67 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 68 document are to be interpreted as described in RFC 2119 [RFC2119]. 70 2. Converting DistinguishedName from ASN.1 to a String 72 In X.501 [X.501] the ASN.1 structure of distinguished name is defined 73 as: 75 DistinguishedName ::= RDNSequence 77 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 79 RelativeDistinguishedName ::= SET SIZE (1..MAX) OF 80 AttributeTypeAndValue 82 AttributeTypeAndValue ::= SEQUENCE { 83 type AttributeType, 84 value AttributeValue } 86 The following sections define the algorithm for converting from an 87 ASN.1 structured representation to a UTF-8 [RFC2279] string 88 representation. 90 2.1. Converting the RDNSequence 92 If the RDNSequence is an empty sequence, the result is the empty or 93 zero length string. 95 Otherwise, the output consists of the string encodings of each 96 RelativeDistinguishedName in the RDNSequence (according to 2.2), 97 starting with the last element of the sequence and moving backwards 98 toward the first. 100 The encodings of adjoining RelativeDistinguishedNames are separated by 101 a comma character (',' ASCII 44). 103 2.2. Converting RelativeDistinguishedName 105 When converting from an ASN.1 RelativeDistinguishedName to a string, 106 the output consists of the string encodings of each 107 AttributeTypeAndValue (according to 2.3), in any order. 109 Where there is a multi-valued RDN, the outputs from adjoining 110 AttributeTypeAndValues are separated by a plus ('+' ASCII 43) 111 character. 113 2.3. Converting AttributeTypeAndValue 115 The AttributeTypeAndValue is encoded as the string representation of 116 the AttributeType, followed by an equals character ('=' ASCII 61), 117 followed by the string representation of the AttributeValue. The 118 encoding of the AttributeValue is given in section 2.4. 120 If the AttributeType is in the following table of attribute types 121 associated with LDAP [RFC2252bis], then the type name string from that 122 table is used, otherwise it is encoded as the dotted-decimal encoding 123 of the AttributeType's OBJECT IDENTIFIER. The dotted-decimal notation 124 is described in [RFC2251bis]. 126 The type name string is not case sensitive. 128 String X.500 AttributeType 129 ------ -------------------------------------------- 130 CN commonName (2.5.4.3) 131 L localityName (2.5.4.7) 132 ST stateOrProvinceName (2.5.4.8) 133 O organizationName (2.5.4.10) 134 OU organizationalUnitName (2.5.4.11) 135 C countryName (2.5.4.6) 136 STREET streetAddress (2.5.4.9) 137 DC domainComponent (0.9.2342.19200300.100.1.25) 138 UID userId (0.9.2342.19200300.100.1.1) 140 2.4. Converting an AttributeValue from ASN.1 to a String 142 If the AttributeValue is of a type which does not have a string 143 representation defined for it, then it is simply encoded as an 144 octothorpe character ('#' ASCII 35) followed by the hexadecimal 145 representation of each of the octets of the BER encoding of the X.500 146 AttributeValue. This form SHOULD be used if the AttributeType is of 147 the dotted-decimal form. 149 Otherwise, if the AttributeValue is of a type which has a string 150 representation, the value is converted first to a UTF-8 string 151 according to its syntax specification (see for example section 6 of 152 [RFC2252bis]). 154 If the UTF-8 string does not have any of the following characters 155 which need escaping, then that string can be used as the string 156 representation of the value. 158 - a space (' ' ASCII 32) or octothorpe ('#' ASCII 35) occurring at the 159 beginning of the string 161 - a space (' ' ASCII 32) character occurring at the end of the string 163 - one of the characters ",", "+", """, "\", "<", ">" or ";" (ASCII 44, 164 43, 34, 92, 60, 62, or 59, respectively) 166 Implementations MAY escape other characters. 168 Each octet of the character to be escaped is replaced by a backslash 169 and two hex digits, which form a single octet in the code of the 170 character. Alternatively, if and only if the character to be escaped 171 is one of 173 ",", "+", """, "\", "<", ">", ";", "#", "=", or " " 174 (ASCII 44, 43, 34, 92, 60, 62, 59, 35, or 32, respectively) 176 it may be prefixed by a backslash ('\' ASCII 92). 178 Examples of the escaping mechanism are shown in section 4. 180 3. Parsing a String back to a Distinguished Name 182 The structure of the UTF-8 [RFC2279] string is specified using the 183 following Augmented BNF [RFC2234] grammar. 185 distinguishedName = [name] 186 ; may be empty 188 name = name-component *(COMMA name-component) 190 name-component = attributeTypeAndValue *(PLUS attributeTypeAndValue) 192 attributeTypeAndValue 193 = attributeType EQUALS attributeValue 195 attributeType = keyword / oid 197 keyword = ALPHA 1*keychar 199 keychar = ALPHA / DIGIT / MINUS 201 oid = 1*DIGIT *(DOT 1*DIGIT) 203 attributeValue = string / hexstring 205 string = *( stringchar / pair ) 206 ; the string MUST NOT start with SHARP or SP 207 ; and MUST NOT end with SP 209 stringchar = 212 pair = ESC ( ESC / special / hexpair ) 214 special = escaped / SHARP / EQUALS / SP 216 escaped = COMMA / PLUS / %x22 / %x3C / %x3E / %3B 217 ; "," / "+" / """ / "<" / ">" / ";" 219 hexstring = SHARP 1*hexpair 221 hexpair = HEX HEX 223 HEX = DIGIT / %x41-46 / %x61-66 224 ; 0-9 / A-F / a-f 226 ALPHA = %x41-5A / %x61-7A 227 ; A-Z / a-z 229 DIGIT = %x30-39 230 ; 0-9 232 SP = %x20 ; space (" ") 233 SHARP = %x23 ; sharp sign ("#") 234 PLUS = %x2B ; plus sign ("+") 235 COMMA = %x2C ; comma (",") 236 MINUS = %x2D ; minus sign ("-") 237 DOT = %x2E ; period (".") 238 EQUALS = %x3D ; equals sign ("=") 239 ESC = %x5C ; backslash ("\") 241 Implementations MUST recognize AttributeType string type names 242 (keywords) listed in the Section 2 table, but MAY recognize other 243 names (keywords). Implementations MAY recognize other DN string 244 representations (such as that described in RFC 1779) but SHALL only 245 generate DN strings in accordance with Section 2 of this document. 247 4. Examples 249 This notation is designed to be convenient for common forms of name. 250 This section gives a few examples of distinguished names written using 251 this notation. First is a name containing three relative 252 distinguished names (RDNs): 254 UID=jsmith,DC=example,DC=net 256 Here is an example name containing three RDNs, in which the first RDN 257 is multi-valued: 259 OU=Sales+CN=J. Smith,DC=example,DC=net 261 This example shows the method of quoting of a comma in a common name: 263 CN=John Smith\, III,DC=example,DC=net 265 An example name in which a value contains a carriage return character: 267 CN=Before\0dAfter,DC=example,DC=net 269 An example name in which an RDN was of an unrecognized type. The 270 value is the BER encoding of an OCTET STRING containing two octets 271 0x48 and 0x69. 273 1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com 275 Finally, an example of an RDN commonName value consisting of 5 276 letters: 278 Unicode Letter Description 10646 code UTF-8 Quoted 279 =============================== ========== ====== ======= 280 LATIN CAPITAL LETTER L U0000004C 0x4C L 281 LATIN SMALL LETTER U U00000075 0x75 u 282 LATIN SMALL LETTER C WITH CARON U0000010D 0xC48D \C4\8D 283 LATIN SMALL LETTER I U00000069 0x69 i 284 LATIN SMALL LETTER C WITH ACUTE U00000107 0xC487 \C4\87 286 could be written in printable ASCII (useful for debugging purposes): 288 CN=Lu\C4\8Di\C4\87 290 5. Security Considerations 292 The following security considerations are specific to the handling of 293 distinguished names. LDAP security considerations are discussed in 294 [RFC2251bis] and its normative references. 296 5.1. Disclosure 298 Distinguished Names typically consist of descriptive information about 299 the entries they name, which can be people, organizations, devices or 300 other real-world objects. This frequently includes some of the 301 following kinds of information: 303 - the common name of the object (i.e. a person's full name) 304 - an email or TCP/IP address 305 - its physical location (country, locality, city, street address) 306 - organizational attributes (such as department name or affiliation) 308 Most countries have privacy laws regarding the publication of 309 information about people. 311 5.2. Use of Distinguished Names in Security Applications 313 The transformations of an AttributeValue value from its X.501 form to 314 an LDAP string representation are not always reversible back to the 315 same BER or DER form. An example of a situation which requires the 316 DER form of a distinguished name is the verification of an X.509 317 certificate. 319 For example, a distinguished name consisting of one RDN with one AVA, 320 in which the type is commonName and the value is of the TeletexString 321 choice with the letters 'Sam' would be represented in LDAP as the 322 string CN=Sam. Another distinguished name in which the value is still 323 'Sam' but of the PrintableString choice would have the same 324 representation CN=Sam. 326 Applications which require the reconstruction of the DER form of the 327 value SHOULD NOT use the string representation of attribute syntaxes 328 when converting a distinguished name to the LDAP format. Instead, 329 they SHOULD use the hexadecimal form prefixed by the octothorpe ('#') 330 as described in the first paragraph of section 2.4. 332 6. References 334 [X.500] "The Directory -- overview of concepts, models and 335 services," ITU-T Rec. X.500(1993). 337 [X.501] "The Directory -- Models," ITU-T Rec. X.501(1993). 339 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 340 Requirement Levels", RFC 2119. 342 [RFC2234] Crocker, D., and P. Overell, "Augmented BNF for Syntax 343 Specifications: ABNF", RFC 2234, November 1997. 345 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 346 10646", RFC 2279, January 1998. 348 [RFC2251bis] LDAPbis WG, "Lightweight Directory Access Protocol (v3)", 349 a work in progress. 351 [RFC2252bis] LDAPbis WG, "LDAPv3: Attribute Syntax Definitions", a 352 work in progress. 354 [RFC2256bis] LDAPbis WG, "LDAPv3: User Schema", a work in progress. 356 7. Acknowledgment 358 This document is an update to RFC 2253, by Mark Wahl, Tim Howes, and 359 Steve Kille. RFC 2253 was a product of the IETF ASID Working Group. 361 This document is a product of the IETF LDAPbis Working Group. 363 8. Document Editor's Address 364 Kurt D. Zeilenga 365 OpenLDAP Foundation 366 368 Appendix A. Changes made since RFC 2253 370 This appendix is provided for informational purposes and is not a 371 normative part of this specification. 373 The following substantive changes were made to RFC 2253: 374 - Removed IESG Note. The IESG Note is addressed by RFC 2829. 375 - Replaced specification of additional requirements for LDAPv2 376 implementations which also support LDAPv3 (Section 4) with a 377 statement (in Section 3) allowing recongization of alternative 378 string representations. 379 - Updated 2.3 to clarify which table is the published table of names 380 which may be appear in DNs. Remove "as an example" language. 381 Added statement (in Section 3) allowing recongization of 382 additional names. - Updated 2.3 to indicate attribute type name 383 strings are not case sensitive. 384 - Updated 2.4 to allow hex pair escaping of all characters and 385 clarified escaping for when multiple octet UTF-8 characters are 386 present. 387 - Rewrote Section 3 to use ABNF as defined in RFC 2234. 388 - Rewrote Section 3 ABNF to be consistent with 2.4. 389 - Rewrote examples 390 - Added reference to documentations containing LDAP-specific 391 security considerations. 393 In addition, numerous editorial changes were made. 395 Copyright 2001, The Internet Society. All Rights Reserved. 397 This document and translations of it may be copied and furnished to 398 others, and derivative works that comment on or otherwise explain it 399 or assist in its implementation may be prepared, copied, published and 400 distributed, in whole or in part, without restriction of any kind, 401 provided that the above copyright notice and this paragraph are 402 included on all such copies and derivative works. However, this 403 document itself may not be modified in any way, such as by removing 404 the copyright notice or references to the Internet Society or other 405 Internet organizations, except as needed for the purpose of 406 developing Internet standards in which case the procedures for 407 copyrights defined in the Internet Standards process must be followed, 408 or as required to translate it into languages other than English. 410 The limited permissions granted above are perpetual and will not be 411 revoked by the Internet Society or its successors or assigns. 413 This document and the information contained herein is provided on an 414 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET 415 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 416 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 417 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 418 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.