1 2 3 4 5 6 7Network Working Group M. Wahl 8Request for Comments: 2253 Critical Angle Inc. 9Obsoletes: 1779 S. Kille 10Category: Standards Track Isode Ltd. 11 T. Howes 12 Netscape Communications Corp. 13 December 1997 14 15 16 Lightweight Directory Access Protocol (v3): 17 UTF-8 String Representation of Distinguished Names 18 19Status of this Memo 20 21 This document specifies an Internet standards track protocol for the 22 Internet community, and requests discussion and suggestions for 23 improvements. Please refer to the current edition of the "Internet 24 Official Protocol Standards" (STD 1) for the standardization state 25 and status of this protocol. Distribution of this memo is unlimited. 26 27Copyright Notice 28 29 Copyright (C) The Internet Society (1997). All Rights Reserved. 30 31IESG Note 32 33 This document describes a directory access protocol that provides 34 both read and update access. Update access requires secure 35 authentication, but this document does not mandate implementation of 36 any satisfactory authentication mechanisms. 37 38 In accordance with RFC 2026, section 4.4.1, this specification is 39 being approved by IESG as a Proposed Standard despite this 40 limitation, for the following reasons: 41 42 a. to encourage implementation and interoperability testing of 43 these protocols (with or without update access) before they 44 are deployed, and 45 46 b. to encourage deployment and use of these protocols in read-only 47 applications. (e.g. applications where LDAPv3 is used as 48 a query language for directories which are updated by some 49 secure mechanism other than LDAP), and 50 51 c. to avoid delaying the advancement and deployment of other Internet 52 standards-track protocols which require the ability to query, but 53 not update, LDAPv3 directory servers. 54 55 56 57 58Wahl, et. al. Proposed Standard [Page 1] 59 60RFC 2253 LADPv3 Distinguished Names December 1997 61 62 63 Readers are hereby warned that until mandatory authentication 64 mechanisms are standardized, clients and servers written according to 65 this specification which make use of update functionality are 66 UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION 67 IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL. 68 69 Implementors are hereby discouraged from deploying LDAPv3 clients or 70 servers which implement the update functionality, until a Proposed 71 Standard for mandatory authentication in LDAPv3 has been approved and 72 published as an RFC. 73 74Abstract 75 76 The X.500 Directory uses distinguished names as the primary keys to 77 entries in the directory. Distinguished Names are encoded in ASN.1 78 in the X.500 Directory protocols. In the Lightweight Directory 79 Access Protocol, a string representation of distinguished names is 80 transferred. This specification defines the string format for 81 representing names, which is designed to give a clean representation 82 of commonly used distinguished names, while being able to represent 83 any distinguished name. 84 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in RFC 2119 [6]. 88 891. Background 90 91 This specification assumes familiarity with X.500 [1], and the 92 concept of Distinguished Name. It is important to have a common 93 format to be able to unambiguously represent a distinguished name. 94 The primary goal of this specification is ease of encoding and 95 decoding. A secondary goal is to have names that are human readable. 96 It is not expected that LDAP clients with a human user interface 97 would display these strings directly to the user, but would most 98 likely be performing translations (such as expressing attribute type 99 names in one of the local national languages). 100 1012. Converting DistinguishedName from ASN.1 to a String 102 103 In X.501 [2] the ASN.1 structure of distinguished name is defined as: 104 105 DistinguishedName ::= RDNSequence 106 107 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName 108 109 110 111 112 113 114Wahl, et. al. Proposed Standard [Page 2] 115 116RFC 2253 LADPv3 Distinguished Names December 1997 117 118 119 RelativeDistinguishedName ::= SET SIZE (1..MAX) OF 120 AttributeTypeAndValue 121 122 AttributeTypeAndValue ::= SEQUENCE { 123 type AttributeType, 124 value AttributeValue } 125 126 The following sections define the algorithm for converting from an 127 ASN.1 structured representation to a UTF-8 string representation. 128 1292.1. Converting the RDNSequence 130 131 If the RDNSequence is an empty sequence, the result is the empty or 132 zero length string. 133 134 Otherwise, the output consists of the string encodings of each 135 RelativeDistinguishedName in the RDNSequence (according to 2.2), 136 starting with the last element of the sequence and moving backwards 137 toward the first. 138 139 The encodings of adjoining RelativeDistinguishedNames are separated 140 by a comma character (',' ASCII 44). 141 1422.2. Converting RelativeDistinguishedName 143 144 When converting from an ASN.1 RelativeDistinguishedName to a string, 145 the output consists of the string encodings of each 146 AttributeTypeAndValue (according to 2.3), in any order. 147 148 Where there is a multi-valued RDN, the outputs from adjoining 149 AttributeTypeAndValues are separated by a plus ('+' ASCII 43) 150 character. 151 1522.3. Converting AttributeTypeAndValue 153 154 The AttributeTypeAndValue is encoded as the string representation of 155 the AttributeType, followed by an equals character ('=' ASCII 61), 156 followed by the string representation of the AttributeValue. The 157 encoding of the AttributeValue is given in section 2.4. 158 159 If the AttributeType is in a published table of attribute types 160 associated with LDAP [4], then the type name string from that table 161 is used, otherwise it is encoded as the dotted-decimal encoding of 162 the AttributeType's OBJECT IDENTIFIER. The dotted-decimal notation is 163 described in [3]. As an example, strings for a few of the attribute 164 types frequently seen in RDNs include: 165 166 167 168 169 170Wahl, et. al. Proposed Standard [Page 3] 171 172RFC 2253 LADPv3 Distinguished Names December 1997 173 174 175 String X.500 AttributeType 176 ------------------------------ 177 CN commonName 178 L localityName 179 ST stateOrProvinceName 180 O organizationName 181 OU organizationalUnitName 182 C countryName 183 STREET streetAddress 184 DC domainComponent 185 UID userid 186 1872.4. Converting an AttributeValue from ASN.1 to a String 188 189 If the AttributeValue is of a type which does not have a string 190 representation defined for it, then it is simply encoded as an 191 octothorpe character ('#' ASCII 35) followed by the hexadecimal 192 representation of each of the bytes of the BER encoding of the X.500 193 AttributeValue. This form SHOULD be used if the AttributeType is of 194 the dotted-decimal form. 195 196 Otherwise, if the AttributeValue is of a type which has a string 197 representation, the value is converted first to a UTF-8 string 198 according to its syntax specification (see for example section 6 of 199 [4]). 200 201 If the UTF-8 string does not have any of the following characters 202 which need escaping, then that string can be used as the string 203 representation of the value. 204 205 o a space or "#" character occurring at the beginning of the 206 string 207 208 o a space character occurring at the end of the string 209 210 o one of the characters ",", "+", """, "\", "<", ">" or ";" 211 212 Implementations MAY escape other characters. 213 214 If a character to be escaped is one of the list shown above, then it 215 is prefixed by a backslash ('\' ASCII 92). 216 217 Otherwise the character to be escaped is replaced by a backslash and 218 two hex digits, which form a single byte in the code of the 219 character. 220 221 Examples of the escaping mechanism are shown in section 5. 222 223 224 225 226Wahl, et. al. Proposed Standard [Page 4] 227 228RFC 2253 LADPv3 Distinguished Names December 1997 229 230 2313. Parsing a String back to a Distinguished Name 232 233 The structure of the string is specified in a BNF grammar, based on 234 the grammar defined in RFC 822 [5]. Server implementations parsing a 235 DN string generated by an LDAPv2 client MUST also accept (and ignore) 236 the variants given in section 4 of this document. 237 238distinguishedName = [name] ; may be empty string 239 240name = name-component *("," name-component) 241 242name-component = attributeTypeAndValue *("+" attributeTypeAndValue) 243 244attributeTypeAndValue = attributeType "=" attributeValue 245 246attributeType = (ALPHA 1*keychar) / oid 247keychar = ALPHA / DIGIT / "-" 248 249oid = 1*DIGIT *("." 1*DIGIT) 250 251attributeValue = string 252 253string = *( stringchar / pair ) 254 / "#" hexstring 255 / QUOTATION *( quotechar / pair ) QUOTATION ; only from v2 256 257quotechar = <any character except "\" or QUOTATION > 258 259special = "," / "=" / "+" / "<" / ">" / "#" / ";" 260 261pair = "\" ( special / "\" / QUOTATION / hexpair ) 262stringchar = <any character except one of special, "\" or QUOTATION > 263 264hexstring = 1*hexpair 265hexpair = hexchar hexchar 266 267hexchar = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 268 / "a" / "b" / "c" / "d" / "e" / "f" 269 270ALPHA = <any ASCII alphabetic character> 271 ; (decimal 65-90 and 97-122) 272DIGIT = <any ASCII decimal digit> ; (decimal 48-57) 273QUOTATION = <the ASCII double quotation mark character '"' decimal 34> 274 275 276 277 278 279 280 281 282Wahl, et. al. Proposed Standard [Page 5] 283 284RFC 2253 LADPv3 Distinguished Names December 1997 285 286 2874. Relationship with RFC 1779 and LDAPv2 288 289 The syntax given in this document is more restrictive than the syntax 290 in RFC 1779. Implementations parsing a string generated by an LDAPv2 291 client MUST accept the syntax of RFC 1779. Implementations MUST NOT, 292 however, generate any of the RFC 1779 encodings which are not 293 described above in section 2. 294 295 Implementations MUST allow a semicolon character to be used instead 296 of a comma to separate RDNs in a distinguished name, and MUST also 297 allow whitespace characters to be present on either side of the comma 298 or semicolon. The whitespace characters are ignored, and the 299 semicolon replaced with a comma. 300 301 Implementations MUST allow an oid in the attribute type to be 302 prefixed by one of the character strings "oid." or "OID.". 303 304 Implementations MUST allow for space (' ' ASCII 32) characters to be 305 present between name-component and ',', between attributeTypeAndValue 306 and '+', between attributeType and '=', and between '=' and 307 attributeValue. These space characters are ignored when parsing. 308 309 Implementations MUST allow a value to be surrounded by quote ('"' 310 ASCII 34) characters, which are not part of the value. Inside the 311 quoted value, the following characters can occur without any 312 escaping: 313 314 ",", "=", "+", "<", ">", "#" and ";" 315 3165. Examples 317 318 This notation is designed to be convenient for common forms of name. 319 This section gives a few examples of distinguished names written 320 using this notation. First is a name containing three relative 321 distinguished names (RDNs): 322 323 CN=Steve Kille,O=Isode Limited,C=GB 324 325 Here is an example name containing three RDNs, in which the first RDN 326 is multi-valued: 327 328 OU=Sales+CN=J. Smith,O=Widget Inc.,C=US 329 330 This example shows the method of quoting of a comma in an 331 organization name: 332 333 CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB 334 335 336 337 338Wahl, et. al. Proposed Standard [Page 6] 339 340RFC 2253 LADPv3 Distinguished Names December 1997 341 342 343 An example name in which a value contains a carriage return 344 character: 345 346 CN=Before\0DAfter,O=Test,C=GB 347 348 An example name in which an RDN was of an unrecognized type. The 349 value is the BER encoding of an OCTET STRING containing two bytes 350 0x48 and 0x69. 351 352 1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB 353 354 Finally, an example of an RDN surname value consisting of 5 letters: 355 356 Unicode Letter Description 10646 code UTF-8 Quoted 357 =============================== ========== ====== ======= 358 LATIN CAPITAL LETTER L U0000004C 0x4C L 359 LATIN SMALL LETTER U U00000075 0x75 u 360 LATIN SMALL LETTER C WITH CARON U0000010D 0xC48D \C4\8D 361 LATIN SMALL LETTER I U00000069 0x69 i 362 LATIN SMALL LETTER C WITH ACUTE U00000107 0xC487 \C4\87 363 364 Could be written in printable ASCII (useful for debugging purposes): 365 366 SN=Lu\C4\8Di\C4\87 367 3686. References 369 370 [1] The Directory -- overview of concepts, models and services. 371 ITU-T Rec. X.500(1993). 372 373 [2] The Directory -- Models. ITU-T Rec. X.501(1993). 374 375 [3] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory 376 Access Protocol (v3)", RFC 2251, December 1997. 377 378 [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight 379 Directory Access Protocol (v3): Attribute Syntax Definitions", 380 RFC 2252, December 1997. 381 382 [5] Crocker, D., "Standard of the Format of ARPA-Internet Text 383 Messages", STD 11, RFC 822, August 1982. 384 385 [6] Bradner, S., "Key words for use in RFCs to Indicate Requirement 386 Levels", RFC 2119. 387 388 389 390 391 392 393 394Wahl, et. al. Proposed Standard [Page 7] 395 396RFC 2253 LADPv3 Distinguished Names December 1997 397 398 3997. Security Considerations 400 4017.1. Disclosure 402 403 Distinguished Names typically consist of descriptive information 404 about the entries they name, which can be people, organizations, 405 devices or other real-world objects. This frequently includes some 406 of the following kinds of information: 407 408 - the common name of the object (i.e. a person's full name) 409 - an email or TCP/IP address 410 - its physical location (country, locality, city, street address) 411 - organizational attributes (such as department name or affiliation) 412 413 Most countries have privacy laws regarding the publication of 414 information about people. 415 4167.2. Use of Distinguished Names in Security Applications 417 418 The transformations of an AttributeValue value from its X.501 form to 419 an LDAP string representation are not always reversible back to the 420 same BER or DER form. An example of a situation which requires the 421 DER form of a distinguished name is the verification of an X.509 422 certificate. 423 424 For example, a distinguished name consisting of one RDN with one AVA, 425 in which the type is commonName and the value is of the TeletexString 426 choice with the letters 'Sam' would be represented in LDAP as the 427 string CN=Sam. Another distinguished name in which the value is 428 still 'Sam' but of the PrintableString choice would have the same 429 representation CN=Sam. 430 431 Applications which require the reconstruction of the DER form of the 432 value SHOULD NOT use the string representation of attribute syntaxes 433 when converting a distinguished name to the LDAP format. Instead, 434 they SHOULD use the hexadecimal form prefixed by the octothorpe ('#') 435 as described in the first paragraph of section 2.4. 436 4378. Authors' Addresses 438 439 Mark Wahl 440 Critical Angle Inc. 441 4815 W. Braker Lane #502-385 442 Austin, TX 78759 443 USA 444 445 EMail: M.Wahl@critical-angle.com 446 447 448 449 450Wahl, et. al. Proposed Standard [Page 8] 451 452RFC 2253 LADPv3 Distinguished Names December 1997 453 454 455 Steve Kille 456 Isode Ltd. 457 The Dome 458 The Square 459 Richmond, Surrey 460 TW9 1DT 461 England 462 463 Phone: +44-181-332-9091 464 EMail: S.Kille@ISODE.COM 465 466 467 Tim Howes 468 Netscape Communications Corp. 469 501 E. Middlefield Rd, MS MV068 470 Mountain View, CA 94043 471 USA 472 473 Phone: +1 650 937-3419 474 EMail: howes@netscape.com 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506Wahl, et. al. Proposed Standard [Page 9] 507 508RFC 2253 LADPv3 Distinguished Names December 1997 509 510 5119. Full Copyright Statement 512 513 Copyright (C) The Internet Society (1997). All Rights Reserved. 514 515 This document and translations of it may be copied and furnished to 516 others, and derivative works that comment on or otherwise explain it 517 or assist in its implementation may be prepared, copied, published 518 and distributed, in whole or in part, without restriction of any 519 kind, provided that the above copyright notice and this paragraph are 520 included on all such copies and derivative works. However, this 521 document itself may not be modified in any way, such as by removing 522 the copyright notice or references to the Internet Society or other 523 Internet organizations, except as needed for the purpose of 524 developing Internet standards in which case the procedures for 525 copyrights defined in the Internet Standards process must be 526 followed, or as required to translate it into languages other than 527 English. 528 529 The limited permissions granted above are perpetual and will not be 530 revoked by the Internet Society or its successors or assigns. 531 532 This document and the information contained herein is provided on an 533 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 534 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 535 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 536 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 537 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562Wahl, et. al. Proposed Standard [Page 10] 563 564