]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc2253.txt
Sync with HEAD
[openldap] / doc / rfc / rfc2253.txt
1
2
3
4
5
6
7 Network Working Group                                            M. Wahl
8 Request for Comments: 2253                           Critical Angle Inc.
9 Obsoletes: 1779                                                 S. Kille
10 Category: 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
19 Status 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
27 Copyright Notice
28
29    Copyright (C) The Internet Society (1997).  All Rights Reserved.
30
31 IESG 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
58 Wahl, et. al.              Proposed Standard                    [Page 1]
59 \f
60 RFC 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
74 Abstract
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
89 1.  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
101 2.  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
114 Wahl, et. al.              Proposed Standard                    [Page 2]
115 \f
116 RFC 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
129 2.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
142 2.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
152 2.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
170 Wahl, et. al.              Proposed Standard                    [Page 3]
171 \f
172 RFC 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
187 2.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
226 Wahl, et. al.              Proposed Standard                    [Page 4]
227 \f
228 RFC 2253               LADPv3 Distinguished Names          December 1997
229
230
231 3. 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
238 distinguishedName = [name]                    ; may be empty string
239
240 name       = name-component *("," name-component)
241
242 name-component = attributeTypeAndValue *("+" attributeTypeAndValue)
243
244 attributeTypeAndValue = attributeType "=" attributeValue
245
246 attributeType = (ALPHA 1*keychar) / oid
247 keychar    = ALPHA / DIGIT / "-"
248
249 oid        = 1*DIGIT *("." 1*DIGIT)
250
251 attributeValue = string
252
253 string     = *( stringchar / pair )
254              / "#" hexstring
255              / QUOTATION *( quotechar / pair ) QUOTATION ; only from v2
256
257 quotechar     = <any character except "\" or QUOTATION >
258
259 special    = "," / "=" / "+" / "<" /  ">" / "#" / ";"
260
261 pair       = "\" ( special / "\" / QUOTATION / hexpair )
262 stringchar = <any character except one of special, "\" or QUOTATION >
263
264 hexstring  = 1*hexpair
265 hexpair    = hexchar hexchar
266
267 hexchar    = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
268              / "a" / "b" / "c" / "d" / "e" / "f"
269
270 ALPHA      =  <any ASCII alphabetic character>
271                                          ; (decimal 65-90 and 97-122)
272 DIGIT      =  <any ASCII decimal digit>  ; (decimal 48-57)
273 QUOTATION  =  <the ASCII double quotation mark character '"' decimal 34>
274
275
276
277
278
279
280
281
282 Wahl, et. al.              Proposed Standard                    [Page 5]
283 \f
284 RFC 2253               LADPv3 Distinguished Names          December 1997
285
286
287 4.  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
316 5.  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
338 Wahl, et. al.              Proposed Standard                    [Page 6]
339 \f
340 RFC 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
368 6.  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
394 Wahl, et. al.              Proposed Standard                    [Page 7]
395 \f
396 RFC 2253               LADPv3 Distinguished Names          December 1997
397
398
399 7.  Security Considerations
400
401 7.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
416 7.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
437 8.  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
450 Wahl, et. al.              Proposed Standard                    [Page 8]
451 \f
452 RFC 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
506 Wahl, et. al.              Proposed Standard                    [Page 9]
507 \f
508 RFC 2253               LADPv3 Distinguished Names          December 1997
509
510
511 9.  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
562 Wahl, et. al.              Proposed Standard                   [Page 10]
563 \f