git.sur5r.net Git - openldap/blob - 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