idnits 2.17.1 draft-ietf-ldapbis-dn-06.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? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. 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. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 442 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 (20 July 2001) is 8287 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 400, 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: 13 errors (**), 0 flaws (~~), 3 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: 20 January 2002 20 July 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 mailing list . 21 Please send editorial comments directly to the document editor 22 . 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 . The list of 34 Internet-Draft Shadow Directories can be accessed at 35 . 37 Copyright 2001, The Internet Society. All Rights Reserved. 39 Please see the Copyright section near the end of this document for 40 more information. 42 Abstract 44 The X.500 Directory uses distinguished names as the primary keys to 45 entries in the directory. Distinguished Names are encoded in ASN.1 in 46 the X.500 Directory protocols. In the Lightweight Directory Access 47 Protocol, a string representation of distinguished names is 48 transferred. This specification defines the string format for 49 representing names, which is designed to give a clean representation 50 of commonly used distinguished names, while being able to represent 51 any distinguished name. 53 1. Background 55 This specification assumes familiarity with X.500 [X.500], and the 56 concept of Distinguished Name (DN). It is important to have a common 57 format to be able to unambiguously represent a distinguished name. 58 The primary goal of this specification is ease of encoding and 59 decoding. A secondary goal is to have names that are human readable. 60 It is not expected that LDAP clients with a human user interface would 61 display these strings directly to the user, but would most likely be 62 performing translations (such as expressing attribute type names in 63 one of the local national languages). 65 This document obsoletes RFC 2253. 67 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 68 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 69 document are to be interpreted as described in RFC 2119 [RFC2119]. 71 2. Converting DistinguishedName from ASN.1 to a String 73 In X.501 [X.501] the ASN.1 structure of distinguished name is defined 74 as: 76 DistinguishedName ::= RDNSequence 78 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 80 RelativeDistinguishedName ::= SET SIZE (1..MAX) OF 81 AttributeTypeAndValue 83 AttributeTypeAndValue ::= SEQUENCE { 84 type AttributeType, 85 value AttributeValue } 87 The following sections define the RECOMMENDED algorithm for converting 88 from an ASN.1 structured representation to a UTF-8 [RFC2279] string 89 representation. 91 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 is also 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 159 the beginning of the string 161 - a space (' ' ASCII 32) character occurring at the end of the 162 string 164 - one of the characters ",", "+", """, "\", "<", ">" or ";" (ASCII 165 44, 43, 34, 92, 60, 62, or 59, respectively) 167 - the null (ASCII 0) character 169 Implementations can escape other characters. 171 Each octet of the character to be escaped is replaced by a backslash 172 and two hex digits, which form a single octet in the code of the 173 character. Alternatively, if and only if the character to be escaped 174 is one of 176 ",", "+", """, "\", "<", ">", ";", "#", "=", or " " 177 (ASCII 44, 43, 34, 92, 60, 62, 59, 35, or 32, respectively) 179 it can be prefixed by a backslash ('\' ASCII 92). 181 Examples of the escaping mechanism are shown in Section 4. 183 3. Parsing a String back to a Distinguished Name 184 The structure of the UTF-8 [RFC2279] string is specified using the 185 following Augmented BNF [RFC2234] grammar. 187 distinguishedName = [name] 188 ; may be empty 190 name = name-component *(COMMA name-component) 192 name-component = attributeTypeAndValue *(PLUS attributeTypeAndValue) 194 attributeTypeAndValue 195 = attributeType EQUALS attributeValue 197 attributeType = keyword / oid 199 keyword = ALPHA 1*keychar 201 keychar = ALPHA / DIGIT / MINUS 203 oid = number *(DOT number) 205 number = ( LDIGIT *DIGIT ) / DIGIT 207 attributeValue = string / hexstring 209 string = *( stringchar / pair ) 210 ; the string MUST NOT start with SHARP or SP 211 ; and MUST NOT end with SP 213 stringchar = 216 pair = ESC ( ESC / special / hexpair ) 218 special = escaped / SHARP / EQUALS / SP 220 escaped = COMMA / PLUS / %x22 / %x3C / %x3E / %x3B 221 ; "," / "+" / """ / "<" / ">" / ";" 223 hexstring = SHARP 1*hexpair 225 hexpair = HEX HEX 227 HEX = DIGIT / %x41-46 / %x61-66 228 ; 0-9 / A-F / a-f 230 ALPHA = %x41-5A / %x61-7A 231 ; A-Z / a-z 233 LDIGIT = %x31-39 234 ; 1-9 236 DIGIT = %x30 / LDIGIT 237 ; 0-9 239 SP = %x20 ; space (" ") 240 SHARP = %x23 ; octothorpe (or sharp sign) ("#") 241 PLUS = %x2B ; plus sign ("+") 242 COMMA = %x2C ; comma (",") 243 MINUS = %x2D ; minus sign ("-") 244 DOT = %x2E ; period (".") 245 EQUALS = %x3D ; equals sign ("=") 246 ESC = %x5C ; backslash ("\") 247 NULL = %x00 ; null (0) 249 Implementations MUST recognize AttributeType string type names 250 (keywords) listed in the Section 2.3 table, but MAY recognize other 251 names. Implementations MAY recognize other DN string representations 252 (such as that described in RFC 1779). As there is no requirement for 253 other names or alternative DN string representations to be recognized, 254 implementations SHOULD only generate DN strings in accordance with 255 Section 2 of this document. 257 4. Examples 259 This notation is designed to be convenient for common forms of name. 260 This section gives a few examples of distinguished names written using 261 this notation. First is a name containing three relative 262 distinguished names (RDNs): 264 UID=jsmith,DC=example,DC=net 266 Here is an example name containing three RDNs, in which the first RDN 267 is multi-valued: 269 OU=Sales+CN=J. Smith,DC=example,DC=net 271 This example shows the method of escaping of a comma in a common name: 273 CN=John Smith\, III,DC=example,DC=net 275 An example name in which a value contains a carriage return character: 277 CN=Before\0dAfter,DC=example,DC=net 279 An example name in which an RDN was of an unrecognized type. The 280 value is the BER encoding of an OCTET STRING containing two octets 281 0x48 and 0x69. 283 1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com 285 Finally, an example of an RDN commonName value consisting of 5 286 letters: 288 Unicode Letter Description 10646 code UTF-8 Quoted 289 =============================== ========== ====== ======= 290 LATIN CAPITAL LETTER L U0000004C 0x4C L 291 LATIN SMALL LETTER U U00000075 0x75 u 292 LATIN SMALL LETTER C WITH CARON U0000010D 0xC48D \C4\8D 293 LATIN SMALL LETTER I U00000069 0x69 i 294 LATIN SMALL LETTER C WITH ACUTE U00000107 0xC487 \C4\87 296 could be written in printable ASCII (useful for debugging purposes): 298 CN=Lu\C4\8Di\C4\87 300 5. Security Considerations 302 The following security considerations are specific to the handling of 303 distinguished names. LDAP security considerations are discussed in 304 [RFC2251bis] and its normative references. 306 5.1. Disclosure 308 Distinguished Names typically consist of descriptive information about 309 the entries they name, which can be people, organizations, devices or 310 other real-world objects. This frequently includes some of the 311 following kinds of information: 313 - the common name of the object (i.e. a person's full name) 314 - an email or TCP/IP address 315 - its physical location (country, locality, city, street address) 316 - organizational attributes (such as department name or affiliation) 318 Most countries have privacy laws regarding the publication of 319 information about people. 321 5.2. Use of Distinguished Names in Security Applications 323 The transformations of an AttributeValue value from its X.501 form to 324 an LDAP string representation are not always reversible back to the 325 same BER or DER form. An example of a situation which requires the 326 DER form of a distinguished name is the verification of an X.509 327 certificate. 329 For example, a distinguished name consisting of one RDN with one AVA, 330 in which the type is commonName and the value is of the TeletexString 331 choice with the letters 'Sam' would be represented in LDAP as the 332 string CN=Sam. Another distinguished name in which the value is still 333 'Sam' but of the PrintableString choice would have the same 334 representation CN=Sam. 336 Applications which require the reconstruction of the DER form of the 337 value SHOULD NOT use the string representation of attribute syntaxes 338 when converting a distinguished name to the LDAP format. Instead, 339 they SHOULD use the hexadecimal form prefixed by the octothorpe ('#') 340 as described in the first paragraph of Section 2.3. 342 5.3. Use of Other Names 344 Attribute type names are not unique. A string representation 345 generated with names other than those in the Section 2.3 table is 346 ambiguous. That is, two applications may recognize the string as 347 representing two different DNs possibly associated with two different 348 entries. This may lead to a wide range of unexpected behaviors which 349 can have both direct and indirect impacts upon security. 351 For example, a distinguished name consisting of one RDN with one AVA, 352 in which the type known locally as FOO and the value is of the 353 octetString "BAR" could be represented in LDAP as the string FOO=BAR. 354 As the name FOO does not uniquely identify an attribute type, the DN 355 FOO=BAR is ambiguous. That is, FOO could be recognized as the 356 attribute type 1.1.1 by one application and 1.2.3.4 in another and not 357 recognized by another. This may lead to operations not behaving as 358 intended. 360 Applications desiring to generate an unambiguous string representation 361 of a DN SHOULD generate string representation per section 2, not use 362 names other than those in the Section 2.3 table, and while taking 5.2 363 into consideration. 365 6. Acknowledgment 367 This document is an update to RFC 2253, by Mark Wahl, Tim Howes, and 368 Steve Kille. RFC 2253 was a product of the IETF ASID Working Group. 370 This document is a product of the IETF LDAPbis Working Group. 372 7. Document Editor's Address 374 Kurt D. Zeilenga 375 OpenLDAP Foundation 376 378 References 380 [X.500] "The Directory -- overview of concepts, models and 381 services," ITU-T Rec. X.500(1993). 383 [X.501] "The Directory -- Models," ITU-T Rec. X.501(1993). 385 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 386 Requirement Levels", RFC 2119. 388 [RFC2234] Crocker, D., and P. Overell, "Augmented BNF for Syntax 389 Specifications: ABNF", RFC 2234, November 1997. 391 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 392 10646", RFC 2279, January 1998. 394 [RFC2251bis] LDAPbis WG, "Lightweight Directory Access Protocol (v3)", 395 a work in progress. 397 [RFC2252bis] LDAPbis WG, "LDAPv3: Attribute Syntax Definitions", a 398 work in progress. 400 [RFC2256bis] LDAPbis WG, "LDAPv3: User Schema", a work in progress. 402 Appendix A. Changes made since RFC 2253 404 This appendix is provided for informational purposes only, it is not a 405 normative part of this specification. 407 The following substantive changes were made to RFC 2253: 408 - Removed IESG Note. The IESG Note is addressed by RFC 2829. 409 - Replaced specification of additional requirements for LDAPv2 410 implementations which also support LDAPv3 (Section 4) with a 411 statement (in Section 3) allowing recognition of alternative 412 string representations. 413 - Updated 2.3 to clarify which table is the published table of names 414 which may be appear in DNs. Remove "as an example" language. 415 Added statement (in Section 3) allowing recognition of additional 416 names. Added security consideration (Section 5.3) regarding the 417 use of other names. 419 - Updated 2.3 to indicate attribute type name strings are not case 420 sensitive. 421 - Updated 2.4 to allow hex pair escaping of all characters and 422 clarified escaping for when multiple octet UTF-8 characters are 423 present. 424 - Rewrote Section 3 to use ABNF as defined in RFC 2234. 425 - Rewrote Section 3 ABNF to be consistent with 2.4. 426 - Rewrote examples. 427 - Added reference to documentations containing LDAP-specific 428 security considerations. 430 In addition, numerous editorial changes were made. 432 Copyright 2001, The Internet Society. All Rights Reserved. 434 This document and translations of it may be copied and furnished to 435 others, and derivative works that comment on or otherwise explain it 436 or assist in its implementation may be prepared, copied, published and 437 distributed, in whole or in part, without restriction of any kind, 438 provided that the above copyright notice and this paragraph are 439 included on all such copies and derivative works. However, this 440 document itself may not be modified in any way, such as by removing 441 the copyright notice or references to the Internet Society or other 442 Internet organizations, except as needed for the purpose of 443 developing Internet standards in which case the procedures for 444 copyrights defined in the Internet Standards process must be followed, 445 or as required to translate it into languages other than English. 447 The limited permissions granted above are perpetual and will not be 448 revoked by the Internet Society or its successors or assigns. 450 This document and the information contained herein is provided on an 451 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET 452 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 453 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 454 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 455 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.