One document matched: draft-ietf-asid-ldapv3-dn-01.txt

Differences from draft-ietf-asid-ldapv3-dn-00.txt

             Lightweight Directory Access Protocol (v3):
          UTF-8 String Representation of Distinguished Names
                  <draft-ietf-asid-ldapv3-dn-01.txt>

Status of this Memo

   This document is an Internet-Draft.  Internet-Drafts are working 
   documents of the Internet Engineering Task Force (IETF), its areas, and
   its working groups.  Note that other groups may also distribute working
   documents as Internet-Drafts.
 
   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference material
   or to cite them other than as "work in progress."
 
   To learn the current status of any Internet-Draft, please check the
   "1id-abstracts.txt" listing  contained in the Internet-Drafts Shadow
   Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
   ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).

Abstract

   The X.500 Directory uses distinguished names as the primary keys to
   entries in the directory.  Distinguished Names are encoded in ASN.1
   in the X.500 Directory protocols.  In the Lightweight Directory 
   Access Protocol, a string representation of distinguished names is
   transferred.  This specification defines the string format for representing 
   names, which is designed to give a clean representation of commonly used
   distinguished names, while being able to represent any distinguished name.

1.  Background

   This specification assumes familiarity with X.500 [1], and the concept of
   Distinguished Name.  It is important to have a common format to be
   able to unambiguously represent a distinguished name.  The primary goal
   of this specification is ease of encoding and decoding.  A secondary
   goal is to have names that are human readable.  It is not expected that
   LDAP clients with a human user interface would display these strings 
   directly to the user, but would most likely be performing translations
   (such as expressing attribute type names in the local national language).








INTERNET-DRAFT        draft-ietf-asid-ldapv3-dn-01.txt     February 1997

Wahl, Kille      String Representations of Distinguished Names    Page 2


2.  A Notation for Distinguished Name

   In X.501 [2] the ASN.1 structure of Distinguished Name is defined as:

       DistinguishedName ::= RDNSequence

       RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

       RelativeDistinguishedName ::= SET SIZE (1..MAX) OF 
        AttributeTypeAndValue

       AttributeTypeAndValue ::= SEQUENCE {
        type  AttributeType,
        value AttributeValue }

   The following sections 2.1 and 2.2 define the algorithm for converting 
   between an ASN.1 structured representation and a UTF-8 string 
   representation.

2.1  Converting DistinguishedName from ASN.1 to a String 

   If the RDNSequence is an empty sequence, the result is the empty
   or zero length string. 

   Otherwise, the output consists of the string encodings of each 
   RelativeDistinguishedName in the RDNSequence (according to 2.2),
   starting with the last element of the sequence and moving backwards 
   toward the first.  

   The encodings of adjoining RelativeDistinguishedNames are separated by 
   either a comma or a semicolon character.  There may be space 
   characters present on either side of the comma or semicolon.

   Either the comma or the semicolon character is to be used to separate
   all the RelativeDistinguishedNames in a particular string.

2.1.2.  Converting RelativeDistinguishedName from ASN.1 to a String

   When converting from an ASN.1 RelativeDistinguishedName to a 
   string, the output consists of the string encodings of each 
   AttributeTypeAndValue (according to 2.1.3), in any order.  

   Where there is a multi-valued RDN, the outputs from adjoining 
   AttributeTypeAndValues are separated by a plus character.

2.1.3.  Converting AttributeTypeAndValue from ASN.1 to a String

   The AttributeTypeAndValue is encoded as the string representation
   of the AttributeType, followed by an equals character, followed by the 
   string representation of the AttributeValue.



INTERNET-DRAFT        draft-ietf-asid-ldapv3-dn-01.txt     February 1997

Wahl, Kille      String Representations of Distinguished Names    Page 3


   If the AttributeType is one defined in Table 1, in a published table
   of LDAP attribute types, or in the IANA-maintained register of valid 
   attribute types, then the string from that table is used, otherwise it is 
   encoded as the dotted-decimal encoding of the AttributeType's OBJECT 
   IDENTIFIER.  The dotted-decimal notation is described in [3].

          Table 1:  Standardized Attribute Types used in RDNs

                       String  AttributeType 
                       ------------------------------
                       CN      commonName
                       L       localityName
                       ST      stateOrProvinceName
                       O       organizationName
                       OU      organizationalUnitName
                       C       countryName
                       STREET  streetAddress
                       DC      domainComponent


2.1.4.  Converting AttributeValue from ASN.1 to a String  

   If the AttributeValue is of a type which does not have a string 
   representation defined in [4], then it is simply encoded as an octothorpe 
   character ("#") followed by the hexidecimal representation of the bytes of 
   the BER encoding of AttributeValue.

   Otherwise, if the AttributeValue is of a type which has a string 
   representation, the value is converted first to a UTF-8 string according to 
   that specification.

   If the UTF-8 string does not have any of the following characters which need
   escaping, then that string can be used as the string representation of the
   value.

    o   a space character occurring at the beginning of the string

    o   a space character occurring at the end of the string

    o   a space character adjoining another space character

    o   non-printing characters other than the single space, such as 
        control characters 0-31 or 127

    o   one of the characters ",", "+", "=", """, "\", "<", ">", "#" or ";"

   There are two possible escaping mechanisms.  If the string does not contain
   the double quote character, then the entire string can be surrounded by 
   double quote characters, and that used as the encoding.  The alternative
   is to prefix each of the characters which need escaping by a backslash
   character.  Examples of these mechanisms are shown in section 3.
      

INTERNET-DRAFT        draft-ietf-asid-ldapv3-dn-01.txt     February 1997

Wahl, Kille      String Representations of Distinguished Names    Page 4


2.2. Parsing a String back to a Distinguished Name

   The structure of the string is specified in a BNF grammar, based on the 
   grammar defined in RFC 822, with the terminals enclosed in <> [5].  

   <distinguishedName> ::= <name> | ""               -- empty string

   <name> ::= <name-component> ( <spaced-separator> )
          | <name-component> <spaced-separator> <name>

   <spaced-separator> ::= <optional-space>
                   <separator>
                   <optional-space>

   <separator> ::=  "," | ";"

   <optional-space> ::=  *( " " )

   <name-component> ::= <attributeTypeAndValue>
           | <attributeTypeAndValue> <optional-space> "+"
             <optional-space> <name-component>

   <attributeTypeAndValue> ::= 
       <attributeType> <optional-space> "=" <optional-space> <attributeValue>

   <attributeType> ::= 1*( <keychar> ) | <oid> | "OID." <oid> | "oid." <oid>
   <keychar> ::= letters, numbers, and space

   <oid> ::= <digitstring> | <digitstring> "." <oid>
   <digitstring> ::= 1*<digit>
   <digit> ::= digits 0-9

   <attributeValue> ::= <string>

   <string> ::= *( <stringchar> | <pair> )
            | '"' *( <stringchar> | <special> | <pair> ) '"'
            | "#" <hex>

   <special> ::= "," | "=" | <control> | "+" | "<" |  ">" | "#" | ";"
   <control> :: characters 0-31 and 127

   <pair> ::= "\" ( <special> | "\" | '"')
   <stringchar> ::= any character except <special> or "\" or '"'

   <hex> ::= 2*<hexchar>
   <hexchar> ::= 0-9, a-f, A-F


   Implementations parsing a string must also allow an oid in the attribute
   type to be prefixed by the characters "oid." or "OID.".



INTERNET-DRAFT        draft-ietf-asid-ldapv3-dn-01.txt     February 1997

Wahl, Kille      String Representations of Distinguished Names    Page 5

3.  Differences from RFC 1779

   The following changes have been made in this version of the specification:
 
    o  The use of angle brackets to surround the strings is not described, as
       this is not used in LDAP. Also the grammar for UFNs has been removed. 
       However it is suggested that angle brackets may be used in preference to
       quotes or other characters as delimiters when including distinguished 
       names in paragraphs.
 
    o  Only space characters, not newlines, are shown between RDNs.

    o  The AttributeType name "DC" has been added.

    o  The "oid" prefix in attribute types is removed.

4.  Examples

   This notation is designed to be convenient for common forms of name.
   This section gives a few examples of distinguished names written
   using this notation:

   CN=Steve Kille, O=Isode Limited, C=GB
   CN=Christian Huitema, O=INRIA, C=FR
   
   Here is an example of a multi-valued Relative Distinguished Name,
   where the namespace is flat within an organization, and department is
   used to disambiguate certain names:

   OU=Sales + CN=J. Smith, O=Widget Inc., C=US

   These examples show both methods quoting of a comma in an
   Organization name:

   CN=L. Eagle, O="Sue, Grabbit and Runn", C=GB
   CN=L. Eagle, O=Sue\, Grabbit and Runn, C=GB

   An example name in which a value contains a newline character:

   CN="Before
   After", O=Test, C=GB

5.  References

   [1] The Directory -- overview of concepts, models and services.
       ITU-T Rec. X.500(1993).

   [2] The Directory -- Models. ITU-T Rec. X.501(1993).

   [3] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol 
       (v3)", INTERNET DRAFT, draft-ietf-asid-ldapv3-protocol-04.txt.
       February 1997.


INTERNET-DRAFT        draft-ietf-asid-ldapv3-dn-01.txt     February 1997

Wahl, Kille      String Representations of Distinguished Names    Page 6


   [4] M. Wahl, S. Kille, T. Howes, A. Coulbeck, "Lightweight Directory Access 
       Protocol (v3): Standard and Pilot Attribute Definitions", INTERNET 
       DRAFT, draft-ietf-asid-ldapv3-attributes-04.txt.
       February 1997.

   [5] D. Crocker, "Standard of the Format of ARPA-Internet Text
       Messages", STD 11, RFC 822, August 1982.


6.  Security Considerations

   Security issues are not discussed in this memo.

7.  Author's Address


   Mark Wahl
   Critical Angle Inc.
   4815 W. Braker Lane #502-385
   Austin, TX 78759
   USA

   EMail:  M.Wahl@critical-angle.com


   Steve Kille
   Isode Ltd.
   The Dome
   The Square
   Richmond, Surrey
   TW9 1DT
   England

   Phone:  +44-181-332-9091
   EMail:  S.Kille@ISODE.COM


















INTERNET-DRAFT        draft-ietf-asid-ldapv3-dn-01.txt     February 1997