[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02

LDAP Data Interchange Format (LDIF)                         Gordon Good
INTERNET-DRAFT                                  Netscape Communications
                                                           30 July 1997

   The LDAP Data Interchange Format (LDIF) - Technical Specification
                 Filename: draft-ietf-asid-ldif-02.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).

   Distribution of this memo is unlimited.  Editorial comments should be
   sent to the author (ggood@netscape.com).  Technical discussion will take
   place on the IETF ASID mailing list (ietf-asid@umich.edu).

   This Internet Draft expires February 1st, 1998.


Abstract

   This document describes a file format suitable for describing
   directory information or modifications made to directory information.
   The file format, known as LDIF, for LDAP Data Interchange Format, is
   typically used to import and export directory information between
   LDAP-based directory servers, or to describe a set of changes which
   are to be applied to a directory.

   There are a number of situations where a common interchange format is
   desirable.  For example, one might wish to export a copy of the
   contents of a directory server to a file, move that file to a
   different machine, and import the contents into a second directory
   server.




Good                    IETF ASID Working Group                 [Page 1]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


   Additionally, by using a well-defined interchange format, development
   of data import tools from legacy systems is facilitated.  A fairly
   simple set of tools written in awk or perl can, for example, convert
   a database of personnel information into an LDIF file, which can then
   be imported into a directory server, regardless of the internal
   database representation the target directory server uses.

   The key words "MUST", "MAY", and "SHOULD" used in this document are
   to be interpreted as described in [7].

Background and Intended Usage

   The LDIF format was originally developed and used in the University
   of Michigan LDAP implementation.  The first use of LDIF was in
   describing directory entries.  Later, the format was expanded to
   allow representation of changes to directory entries.

   Relationship to the application/directory MIME content-type

   The application/directory MIME content-type [1] is a general
   framework and format for conveying directory information, and is
   independent of any particular directory service.  It is preferred, in
   most cases, to LDIF, for conveying directory information.  The LDIF
   format is a simpler format which is perhaps easier to create, and
   also may be used, as noted, to describe a set of changes to be
   applied to a directory.



Definition of the LDAP Data Interchange Format


   The LDIF format is used to convey directory information, or a
   description of a set of changes made to directory entries.  An LDIF
   file consists of a series of records separated by line separators.  A
   record consists of a sequence of lines describing a directory entry,
   or a sequence of lines describing a set of changes to a single
   directory entry.  An LDIF file specifies a set of directory entries,
   or a set of changes to be applied to directory entries, but not both.

   There is a one-to-one correlation between LDAP operations which
   modify the directory (add, delete, modify, and modrdn), and the types
   of changerecords described below ("add", "delete", "modify", and
   "modrdn" or "moddn").  This correspondence is intentional, and
   permits a straightforward translation from LDIF changerecords to
   protocol operations.

Formal Syntax Definition of LDIF



Good                    IETF ASID Working Group                 [Page 2]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


   The following definition uses the augmented Backus-Naur Form
   specified in RFC 822 [2].

   ldif-file            = ldif-content / ldif-changes
   ldif-content         = 0,1*(version-spec 1*SEP)
                          ldif-attrval-record *(1*SEP ldif-attrval-record)
   ldif-changes         = 0,1*(version-spec 1*SEP)
                          ldif-change-record *(1*SEP ldif-change-record)
   ldif-attrval-record  = dn-spec SEP 1*(attrval-spec)
   ldif-change-record   = dn-spec SEP 1*(changerecord SEP)

   version-spec         = "version:" *SPACE version-number
   version-number       = 1*DIGIT  ; version-number MUST be "1" for the
                                   ; LDIF format described in this document.

   dn-spec              = ("dn:" *SPACE dn) / ("dn::" *SPACE base64-dn)
   dn                   = <a distinguished name, as defined in RFC 1779 [3]>
   base64-dn            = <a dn which has been base-64 encoded, as
                          defined in RFC 1521 [5]>
   rdn                  = <a relative distinguished name, as defined in RFC
                          1779 [3]>
   base64-rdn           = <an rdn which has been base-64 encoded, as
                          defined in RFC 1521 [5]>

   attrval-spec         = attribute-description ((":") / (":" *SPACE value) /
                          ("::" *SPACE base64-value) /
                          (":<" *SPACE url))
   url                  = <a Uniform Resource Locator, as defined in [6]>
                                  ; (See Note 6, below)
   attribute-description = <an attribute description, as defined in [4],
                           and augmented with the additional option
                           "charset-option", defined below.  An attribute
                           description MAY NOT contain a colon ":">
   charset-option       = "charset=" ( "*" / charset-name )
   charset-name         = a character set name, as registered with IANA [10]
   value                = 1*safe-initval *safe
   safe                 = <ASCII values 040 - 0377 octal (32 - 255 decimal)>
   safe-initval         = <ASCII values 040 - 0377 octal (32 - 255 decimal),
                          excluding colon (":", ASCII 58 decimal), SPACE, and
                          less-than ("<" , ASCII 60 decimal)>
   base64-value         = <base-64-encoded value, as defined in RFC 1521 [5]>

   changerecord         = change-add / change-delete / change-modify /
                          change-moddn
   change-add           = "changetype:" *SPACE "add" 1*(SEP attrval-spec)
   change-delete        = "changetype:" *SPACE "delete"
   change-moddn         = "changetype:" *SPACE ("modrdn" / "moddn") SEP
                          ("newrdn:" *SPACE rdn /



Good                    IETF ASID Working Group                 [Page 3]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


                           "newrdn::" *SPACE base-64-rdn) SEP
                          "deleteoldrdn:" *SPACE ("0" / "1")
                          0,1*(SEP (("newsuperior:" *SPACE dn) /
                          ("newsuperior:: *SPACE base-64-dn)))
   change-modify        = "changetype:" *SPACE "modify" 1*(SEP mod-spec)
   mod-spec             = mod-add-spec / mod-delete-spec / mod-replace-spec
   mod-add-spec         = "add:" *SPACE attribute-description
                          1*(SEP attrval-spec) SEP "-"
   mod-delete-spec      = "delete:" *SPACE attribute-description
                          *(SEP attrval-spec) SEP "-"
   mod-replace-spec     = "replace:" *SPACE attribute-description
                          *(SEP attrval-spec) SEP "-"
   SPACE                = <ASCII SP, space>
   SEP                  = (CR LF / LF)
   CR                   = <ASCII CR, carriage return>
   LF                   = <ASCII LF, line feed>
   DIGIT                = <any ASCII decimal digit (60 - 71 decimal) >


   Notes on LDIF Syntax

   1) The version number is optional.  If absent, version 0 is assumed,
   which corresponds to the version of LDIF supported by the University
   of Michigan ldap-3.3 reference implementation [8].  For the LDIF
   format described in this document, the version number MUST be "1".

   2) Any line in an LDIF file MAY be wrapped by inserting a line
   separator (SEP) and a SPACE.  Any line which begins with a single
   space MUST be treated as a continuation of the previous line.

   3) Any line which begins with a pound-sign ("#", ASCII 35) is a
   comment line, and MUST be ignored when parsing an LDIF file.

   4) Any dn or value which contains characters other than those defined
   as "safe," or begins with a character other than those defined as
   "safe-initval", above, MUST be base-64 encoded.  Other values MAY be
   base-64 encoded.

   5) To represent a zero-length attribute value, use an attrval-spec of
   "attribute-description:".  For example, "seeAlso:" represents a
   zero-length "seeAlso" attribute value.

   6) When a URL is specified in an attrval-spec, the following
   conventions apply:
      a) Implementations SHOULD support the file:// URL format.  The
         contents of the referenced file are to be included verbatim
         in the interpreted output of the LDIF file.
      b) Implementations MAY support other URL formats.  The semantics



Good                    IETF ASID Working Group                 [Page 4]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


         associated with each supported URL will be documented in
         an associated Applicability Statement.

   7) An option, "charset" may be included with other attribute options
   in the attribute-description.  This option describes the character
   set encoding used in the associated attribute value.  A special value
   of "*" represents the native, or default, character set in use on the
   platform.  For example, a tool might allow a command-line parameter
   which specifies the default character set.  Attribute values tagged
   with the "charset=*" option will be converted from this default
   charset.  If no "charset" option appears in an attribute description,
   the associated value SHOULD be treated as if encoded in LDAP format;
   that is, UTF-8 for string values, or other format as determined by
   the syntax of the attribute type.

   Programs which generate LDIF files SHOULD NOT add "charset" options
   to attribute descriptions.  Instead, the attribute values should be
   encoded in UTF-8, for interoperability.  Programs which interpret
   LDIF files and update directory entries MUST NOT place "charset" tags
   in the options field of the attribute description.  Instead, the
   attribute values MUST be encoded in UTF-8

   8) While it is permissible for character values larger than 126 to be
   contained in an attribute value, implementations SHOULD base-64
   encode any value which contains such characters when generating LDIF.
   However, implementations MAY leave the values unencoded.  This
   relaxation is designed to allow editing of LDIF files containing, for
   example, Latin-1 content, with existing tools.

Differences from previous versions of this document

   Differences between draft-ietf-asid-ldif-00.txt and draft-ietf-asid-
   ldif-01.txt

   1) The BNF has been modified to explicitly disallow ldif content and
   change records in the same file.  In other words, a given LDIF file
   is either a series of directory entries, or a series of
   modifications.  An LDIF file MUST NOT contain both types of records.

   2) External references are now URLs, instead of simple filenames.

   3) The BNF has been modified to allow base-64-encoded distinguished
   names.

   4) Multiple separators are now permitted between records.

   Differences between draft-ietf-asid-ldif-01.txt and draft-ietf-asid-
   ldif-02.txt



Good                    IETF ASID Working Group                 [Page 5]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


   1) The BNF has been modified such that a simple attribute name
   ("attrname") has been replaced with an "attribute-description" as
   defined in the LDAPv3 protocol document [9].  This permits language
   codes and other attribute options to be carried in an LDIF file.

   2) A new option, "charset", may be used in attribute descriptions.
   This facilitates multi-lingual character set conversion.

   3) The definition of the "safe" and "safe-initval" productions has
   been relaxed to allow non-ASCII characters with values greater than
   126.  This permits more natural expression of character sets such as
   Latin-1 in LDIF files.

Examples of LDAP Data Interchange Format


   Example 1: An simple LDAP file with two entries

   dn: cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   cn: Barbara Jensen
   cn: Barbara J Jensen
   cn: Babs Jensen
   sn: Jensen
   uid: bjensen
   telephonenumber: +1 408 555 1212
   description: A big sailing fan.

   dn: cn=Bjorn Jensen, ou=Accounting, o=Ace Industry, c=US
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   cn: Bjorn Jensen
   sn: Jensen
   telephonenumber: +1 408 555 1212

   Example 2: A file containing an entry with a folded attribute value

   dn:cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US
   objectclass:top
   objectclass:person
   objectclass:organizationalPerson
   cn:Barbara Jensen
   cn:Barbara J Jensen
   cn:Babs Jensen
   sn:Jensen



Good                    IETF ASID Working Group                 [Page 6]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


   uid:bjensen
   telephonenumber:+1 408 555 1212
   description:Babs is a big sailing fan, and travels extensively in search of
    perfect sailing conditions.
   title:Product Manager, Rod and Reel Division

   Example 3: A file containing a base-64-encoded value

   dn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   cn: Gern Jensen
   cn: Gern O Jensen
   sn: Jensen
   uid: gernj
   telephonenumber: +1 408 555 1212
   description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJ
    hc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0ICh
    hIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu

   Example 4: A file containing a reference to an external file

   dn: cn=Horatio Jensen, ou=Product Testing, o=Ace Industry, c=US
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   cn: Horatio Jensen
   cn: Horatio N Jensen
   sn: Jensen
   uid: hjensen
   telephonenumber: +1 408 555 1212
   jpegphoto:< file:///usr/local/directory/photos/hjensen.jpg

   Example 5: A file containing a value in non-UTF-8 encoding

   dn: cn=Rolf Sorensen, ou=Product Development, o=Ace Industry, c=US
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   cn: Rolf Sorensen
   cn;charset=ISO-8859-1:: Um9sZiBT+HJlbnNlbg==
   sn: Sorensen
   sn;charset=ISO-8859-1:: U/hyZW5zZW4K
   uid: rsor
   telephonenumber: +1 408 555 1212

   Example 6: A file containing a series of change records and comments



Good                    IETF ASID Working Group                 [Page 7]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


   # Add a new entry
   dn: cn=Fiona Jensen, ou=Marketing, o=Ace Industry, c=US
   changetype: add
   objectclass: top
   objectclass: person
   objectclass: organizationalPerson
   cn: Fiona Jensen
   sn: Jensen
   uid: fiona
   telephonenumber: +1 408 555 1212
   jpegphoto:< file:///usr/local/directory/photos/fiona.jpg

   # Delete an existing entry
   dn: cn=Robert Jensen, ou=Marketing, o=Ace Industry, c=US
   changetype: delete

   # Modify an entry's relative distinguished name
   dn: cn=Paul Jensen, ou=Product Development, o=Ace Industry, c=US
   changetype: modrdn
   newrdn: cn=Paula Jensen
   deleteoldrdn: 1

   # Rename an entry and move all of its children to a new location in
   # the directory tree (only implemented by LDAPv3 servers).
   dn: ou=PD Accountants, ou=Product Development, o=Ace Industry, c=US
   changetype: modrdn
   newrdn: ou=Product Development Accountants
   deleteoldrdn: 0
   newsuperior: ou=Accounting, o=Ace Industry, c=US

   # Modify an entry: add an additional value to the postaladdress attribute,
   # completely delete the description attribute, replace the telephonenumber
   # attribute with two values, and delete a specific value from the
   # facsimiletelephonenumber attribute
   dn: cn=Paula Jensen, ou=Product Development, o=Ace Industry, c=US
   changetype: modify
   add: postaladdress
   postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086
   -
   delete: description
   -
   replace: telephonenumber
   telephonenumber: +1 408 555 1234
   telephonenumber: +1 408 555 5678
   -
   delete: facsimiletelephonenumber
   facsimiletelephonenumber: +1 408 555 9876
   -



Good                    IETF ASID Working Group                 [Page 8]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


Security Considerations

   Given typical directory applications, an LDIF file is likely to
   contain sensitive personal data.  Appropriate measures should be
   taken to protect the privacy of those persons whose data is contained
   in an LDIF file.

   Since ":<" directives can cause external content to be included when
   processing an LDIF file, one should be cautious of accepting LDIF
   files from external sources.  A "trojan" LDIF file could name a file
   with sensitive contents and cause it to be included in a directory
   entry, which a hostile entity could read via LDAP.

   LDIF does not provide any method for carrying authentication
   information with an LDIF file.  Users of LDIF files must take care to
   verify the integrity of an LDIF file received from an external
   source.

Acknowledgments

   The LDAP Interchange Format was developed as part of the University
   of Michigan LDAP reference implementation, and was developed by Tim
   Howes, Mark Smith, and Gordon Good.  It is based in part upon work
   supported by the National Science Foundation under Grant No.  NCR-
   9416667.


References


   [1]  Howes, T., Smith, M., "A MIME Content-Type for Directory Infor-
        mation", INTERNET-DRAFT draft-ietf-asid-mime-direct-02.txt,
        Netscape Communications Corp., <URL:ftp://ietf.org/internet-
        drafts/draft-ietf-asid-mime-direct-02.txt>

   [2]  Crocker,  D.H., "Standard for the Format of ARPA Internet Text
        Messages", RFC 822, University of Delaware, August 1982,
        <URL:http://ds.internic.net/rfc/rfc822.txt>

   [3]  Kille, S., "A String Representation of Distinguished Names", RFC
        1779, ISODE Consortium, March 1995,
        <URL:http://ds.internic.net/rfc/rfc1779.txt>

   [4]  Wahl, M., Coulbeck, A., Howes, T., Kille, S., "Lightweight
        Directory Access Protocol: Standard and Pilot Attribute Defini-
        tions", INTERNET-DRAFT draft-ietf-asid-ldapv3-attributes-06.txt,
        Critical Angle, Inc., ISODE Consortium, Netscape Communications
        Corp., July, 1997, <URL:ftp://ietf.org/internet-drafts/draft-



Good                    IETF ASID Working Group                 [Page 9]


INTERNET-DRAFT        LDAP Data Interchange Format          30 July 1997


        ietf-asid-ldapv3-attributes-03.txt>

   [5]  Borenstein, N., Freed, N., "MIME (Multipurpose Internet Mail
        Extensions) Part One: Mechanisms for Specifying and Describing
        the Format of Internet Message Bodies", section 5.2, "Base64
        Content-Transfer-Encoding", RFC 1521, Bellcore, Innosoft,
        December 1993, <URL:http://ds.internic.net/rfc/rfc1521.txt>

   [6]  T. Berners-Lee,  L.  Masinter, M. McCahill, "Uniform Resource
        Locators (URL)", CERN, Xerox Corporation, University of Min-
        nesota, Request for Comment (RFC) 1738, December 1994,
        <URL:http://ds.internic.net/rfc/rfc1738.txt>

   [7]  S. Bradner, "Key Words for use in RFCs to Indicate Requirement
        Levels", Harvard University, RFC 2119, March 1997,
        <URL:http://ds.internic.net/rfc/rfc2119.txt>

   [8]  The SLAPD and SLURPD Administrators Guide.  University of Michi-
        gan, April 1996.  <URL:
        http://www.umich.edu/~rsug/ldap/doc/guides/slapd/toc.html>

   [9]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Pro-
        tocol (v3)", INTERNET-DRAFT draft-ietf-asid-ldapv3-protocol-
        06.txt, Critical Angle, Inc., Netscape Communications Corp.,
        ISODE Consortium, July 1997, <URL:ftp://ietf.org/internet-
        drafts/draft-ietf-asid-ldapv3-protocol-06.txt>

   [10] Internet Assigned Numbers Authority, "CHARACTER SETS",
        <URL:ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets>



Author's Address

        Gordon Good
        Netscape Communications Corp.
        501 E. Middlefield Rd.
        Mailstop MV068
        Mountain View, CA 94043, USA
        Phone:  +1 415 937-3825
        EMail:  ggood@netscape.com

                This Internet Draft expires February 1st, 1998.








Good                    IETF ASID Working Group                [Page 10]


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/