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