Debian Codegraph @

rfc2253.html

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