home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldif-00.txt < prev    next >
Text File  |  1996-11-26  |  16KB  |  451 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. LDAP Data Interchange Format (LDIF)                         Gordon Good
  8. INTERNET-DRAFT                                  Netscape Communications
  9.                                                        25 November 1996
  10.  
  11.                 The LDAP Data Interchange Format (LDIF)
  12.                  Filename: draft-ietf-asid-ldif-00.txt
  13.  
  14. Status of this Memo
  15.  
  16.    This document is an Internet-Draft.  Internet-Drafts are working
  17.    documents of the Internet Engineering Task Force (IETF), its
  18.    areas, and its working groups.  Note that other groups may also
  19.    distribute working documents as Internet-Drafts.
  20.  
  21.    Internet-Drafts are draft documents valid for a maximum of six
  22.    months and may be updated, replaced, or obsoleted by other
  23.    documents at any time.  It is inappropriate to use Internet-
  24.    Drafts as reference material or to cite them other than as
  25.    ``work in progress.''
  26.  
  27.    To learn the current status of any Internet-Draft, please check
  28.    the ``1id-abstracts.txt'' listing contained in the Internet-
  29.    Drafts Shadow Directories on ds.internic.net (US East Coast),
  30.    nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or
  31.    munnari.oz.au (Pacific Rim).
  32.  
  33.    Distribution of this memo is unlimited.  Editorial comments should be
  34.    sent to the author (ggood@netscape.com).  Technical discussion will take
  35.    place on the IETF ASID mailing list (ietf-asid@umich.edu).
  36.  
  37.    This Internet Draft expires May 1st, 1997.
  38.  
  39.  
  40. Abstract
  41.  
  42.    This document describes a file format suitable for describing
  43.    directory information and modifications made to directory
  44.    information.  The file format, known as LDIF, for LDAP Data
  45.    Interchange Format, is typically used to import and export directory
  46.    information between LDAP-based directory servers, and to describe a
  47.    set of changes which are to be applied to a directory.
  48.  
  49.    There are a number of situations where a common interchange format is
  50.    desirable.  For example, one might wish to export a copy of the
  51.    contents of a directory server to a file, move that file to a
  52.    different machine, and import the contents into a second directory
  53.    server.
  54.  
  55.  
  56.  
  57.  
  58. Good                    IETF ASID Working Group                 [Page 1]
  59.  
  60. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  61.  
  62.  
  63.    Additionally, by using a well-defined interchange format, development
  64.    of data import tools from legacy systems is facilitated.  A fairly
  65.    simple set of tools written in awk or perl can, for example, convert
  66.    a database of personnel information into an LDIF file, which can then
  67.    be imported into a directory server, regardless of the internal
  68.    database representation the target directory server uses.
  69.  
  70.  
  71. Background and Intended Usage
  72.  
  73.    The LDIF format was originally developed and used in the University
  74.    of Michigan LDAP implementation.  The first use of LDIF was in
  75.    describing directory entries.  Later, the format was expanded to
  76.    allow representation of changes to directory entries.
  77.  
  78.    Relationship to the application/directory MIME content-type
  79.  
  80.    The application/directory MIME content-type [1] is a general
  81.    framework and format for conveying directory information, and is
  82.    independent of any particular directory service.  It is preferred, in
  83.    most cases, to LDIF, for conveying directory information.  The LDIF
  84.    format is a simpler format which is perhaps easier to create, and
  85.    also may be used, as noted, to describe a set of changes to be
  86.    applied to a directory.
  87.  
  88.  
  89.  
  90. Definition of the LDAP Data Interchange Format
  91.  
  92.  
  93.    The LDIF format is used to convey directory information, or a
  94.    description of a set of changes made to directory entries.  An LDIF
  95.    file consists of a series of records separated by a line separator.
  96.    Each record consists of a sequence of lines describing a directory
  97.    entry, or a sequence of lines describing a set of changes to a single
  98.    directory entry.
  99.  
  100.  
  101. Formal Syntax Definition of LDIF
  102.  
  103.    The following definition uses the augmented Backus-Naur Form
  104.    specified in RFC 822 [2].
  105.  
  106.    ldif-file            = 0,1*(version-spec SEP) ldif-record *(SEP ldif-record)
  107.  
  108.    version-spec         = "version:" *SPACE version-number
  109.    version-number       = 1*DIGIT  ; version-number must be "1" for the
  110.                                    ; LDIF format described in this document.
  111.  
  112.  
  113.  
  114. Good                    IETF ASID Working Group                 [Page 2]
  115.  
  116. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  117.  
  118.  
  119.    ldif-record          = dn-spec SEP ldif-content SEP
  120.  
  121.    dn-spec              = "dn:" *SPACE dn
  122.    dn                   = <a distinguished name, as defined in RFC 1779 [3]>
  123.    rdn                  = <a relative distinguished name, as defined in RFC
  124.                           1779 [3]>
  125.  
  126.    ldif-content         = 1*(attrval-spec SEP) / (changerecord SEP)
  127.    attrval-spec         = attrname (":" *SPACE value) /
  128.                           ("::" *SPACE base64-value) /
  129.                           (":<" *SPACE file-spec)
  130.    file-spec            = <a file name, as defined by local operating
  131.                            system conventions>
  132.    attrname             = <an attribute name, as defined in
  133.                            draft-ietf-asid-ldapv3-attributes-03.txt [4]
  134.                            Attribute names may not contain a colon ":">
  135.    value                = 1*safe-initval *safe
  136.    safe                 = <ASCII values 040 - 0176 octal (32 - 126 decimal)>
  137.    safe-initval         = <ASCII values 040 - 0176 octal (32 - 126 decimal),
  138.                           excluding colon (":", ASCII 58 decimal), SPACE, and
  139.                           less-than ("<" , ASCII 60 decimal)>
  140.    base64-value         = <base-64-encoded value, as defined in RFC 1521 [5]>
  141.  
  142.    changerecord         = change-add / change-delete / change-modify /
  143.                           change-moddn
  144.    change-add           = "changetype:" *SPACE "add" 1*(SEP attrval-spec)
  145.    change-delete        = "changetype:" *SPACE "delete"
  146.    change-moddn         = "changetype:" *SPACE ("modrdn" / "moddn") SEP
  147.                           "newrdn:" *SPACE rdn SEP
  148.                           "deleteoldrdn:" *SPACE ("0" / "1")
  149.                           0,1*(SEP "newsuperior:" *SPACE dn)
  150.    change-modify        = "changetype:" *SPACE "modify" 1*(SEP mod-spec)
  151.    mod-spec             = mod-add-spec / mod-delete-spec / mod-replace-spec
  152.    mod-add-spec         = "add:" *SPACE attrname 1*(SEP attrval-spec) SEP "-"
  153.    mod-delete-spec      = "delete:" *SPACE attrname *(SEP attrval-spec) SEP "-"
  154.    mod-replace-spec     = "replace:" *SPACE attrname *(SEP attrval-spec) SEP
  155.                           "-"
  156.    SPACE                = <ASCII SP, space>
  157.    SEP                  = (CR LF / LF)
  158.    CR                   = <ASCII CR, carriage return>
  159.    LF                   = <ASCII LF, line feed>
  160.    DIGIT                = <any ASCII decimal digit (60 - 71 decimal) >
  161.  
  162.  
  163.    Notes on LDIF Syntax
  164.  
  165.    1) The version number is optional.  If absent, version 0 is assumed,
  166.    which corresponds to the version of LDIF supported by the University
  167.  
  168.  
  169.  
  170. Good                    IETF ASID Working Group                 [Page 3]
  171.  
  172. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  173.  
  174.  
  175.    of Michigan ldap-3.3 reference implementation.  For the LDIF format
  176.    described in this document, the version number must be "1".
  177.  
  178.    2) Any line in an LDIF file may be wrapped by inserting a line
  179.    separator (SEP) and a SPACE.  Any line which begins with a single
  180.    space must be treated as a continuation of the previous line.
  181.  
  182.    3) Any line which begins with a pound-sign ("#", ASCII 35) is taken
  183.    to be a comment line, and must be ignored when parsing an LDIF file.
  184.  
  185.    4) Any value which contains characters other than those defined as
  186.    "safe," or begins with a character other than those defined as
  187.    "safe-initval", above, must be base-64 encoded.
  188.  
  189.    5) Since a filespec is expressed in the native naming context of a
  190.    particular operating system, such file names are inherently non-
  191.    portable.
  192.  
  193.  
  194.  
  195. Differences from the University of Michigan LDAP-3.3 implementation
  196.  
  197.    The LDIF format described in this document differs from the format
  198.    recognized by the University of Michigan LDAP reference
  199.    implementation in several ways:
  200.  
  201.    1) The syntax of the attrval-spec has been extended.  The U-M
  202.    implementation only recognized two formats:  "attribute-name:
  203.    attribute-value" and "attribute-name::  base-64-encoded-attribute-
  204.    value".  The new definition now also supports a format "attribute-
  205.    name:< file-spec", which specifies that the value for the attribute
  206.    named "attribute-name" can be found in the file named by "file-spec".
  207.  
  208.    2) Comment lines are supported in this version.
  209.  
  210.    3) A file format version number is supported in this version.
  211.  
  212.    4) Support for describing the LDAPv3 modifyDN operation is included
  213.    in this version.
  214.  
  215.  
  216. Examples of LDAP Data Interchange Format
  217.  
  218.  
  219.    Example 1: An simple LDAP file with two entries
  220.  
  221.    dn: cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US
  222.    objectclass: top
  223.  
  224.  
  225.  
  226. Good                    IETF ASID Working Group                 [Page 4]
  227.  
  228. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  229.  
  230.  
  231.    objectclass: person
  232.    objectclass: organizationalPerson
  233.    cn: Barbara Jensen
  234.    cn: Barbara J Jensen
  235.    cn: Babs Jensen
  236.    sn: Jensen
  237.    uid: bjensen
  238.    telephonenumber: +1 408 555 1212
  239.    description: A big sailing fan.
  240.  
  241.    dn: cn=Bjorn Jensen, ou=Accounting, o=Ace Industry, c=US
  242.    objectclass: top
  243.    objectclass: person
  244.    objectclass: organizationalPerson
  245.    cn: Bjorn Jensen
  246.    sn: Jensen
  247.    telephonenumber: +1 408 555 1212
  248.  
  249.    Example 2: A file containing an entry with a folded attribute
  250.  
  251.    dn:cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US
  252.    objectclass:top
  253.    objectclass:person
  254.    objectclass:organizationalPerson
  255.    cn:Barbara Jensen
  256.    cn:Barbara J Jensen
  257.    cn:Babs Jensen
  258.    sn:Jensen
  259.    uid:bjensen
  260.    telephonenumber:+1 408 555 1212
  261.    description:Babs is a big sailing fan, and travels extensively in search of
  262.     perfect sailing conditions.
  263.    title:Product Manager, Rod and Reel Division
  264.  
  265.    Example 3: A file containing a base-64-encoded value
  266.  
  267.    dn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US
  268.    objectclass: top
  269.    objectclass: person
  270.    objectclass: organizationalPerson
  271.    cn: Gern Jensen
  272.    cn: Gern O Jensen
  273.    sn: Jensen
  274.    uid: gernj
  275.    telephonenumber: +1 408 555 1212
  276.    description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJ
  277.     hc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0ICh
  278.     hIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu
  279.  
  280.  
  281.  
  282. Good                    IETF ASID Working Group                 [Page 5]
  283.  
  284. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  285.  
  286.  
  287.    Example 4: A file containing a reference to an external file
  288.  
  289.    dn: cn=Horatio Jensen, ou=Product Testing, o=Ace Industry, c=US
  290.    objectclass: top
  291.    objectclass: person
  292.    objectclass: organizationalPerson
  293.    cn: Horatio Jensen
  294.    cn: Horatio N Jensen
  295.    sn: Jensen
  296.    uid: hjensen
  297.    telephonenumber: +1 408 555 1212
  298.    jpegphoto:< /usr/local/directory/photos/hjensen.jpg
  299.  
  300.    Example 5: A file containing a series of change records and comments
  301.  
  302.    # Add a new entry
  303.    dn: cn=Fiona Jensen, ou=Marketing, o=Ace Industry, c=US
  304.    changetype: add
  305.    objectclass: top
  306.    objectclass: person
  307.    objectclass: organizationalPerson
  308.    cn: Fiona Jensen
  309.    sn: Jensen
  310.    uid: fiona
  311.    telephonenumber: +1 408 555 1212
  312.    jpegphoto:< /usr/local/directory/photos/fiona.jpg
  313.  
  314.    # Delete an existing entry
  315.    dn: cn=Robert Jensen, ou=Marketing, o=Ace Industry, c=US
  316.    changetype: delete
  317.  
  318.    # Modify an entry's relative distinguished name
  319.    dn: cn=Paul Jensen, ou=Product Development, o=Ace Industry, c=US
  320.    changetype: modrdn
  321.    newrdn: cn=Paula Jensen
  322.    deleteoldrdn: 1
  323.  
  324.    # Rename and entry and move all of its children to a new location in
  325.    # the directory tree (only implemented by LDAPv3 servers).
  326.    dn: ou=PD Accountants, ou=Product Development, o=Ace Industry, c=US
  327.    changetype: modrdn
  328.    newrdn: ou=Product Development Accountants
  329.    deleteoldrdn: 0
  330.    newsuperior: ou=Accounting, o=Ace Industry, c=US
  331.  
  332.    # Modify an entry: add an additional value to the postaladdress attribute,
  333.    # completely delete the description attribute, replace the telephonenumber
  334.    # attribute with two values, and delete a specific value from the
  335.  
  336.  
  337.  
  338. Good                    IETF ASID Working Group                 [Page 6]
  339.  
  340. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  341.  
  342.  
  343.    # facsimiletelephonenumber attribute
  344.    dn: cn=Paula Jensen, ou=Product Development, o=Ace Industry, c=US
  345.    changetype: modify
  346.    add: postaladdress
  347.    postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086
  348.    -
  349.    delete: description
  350.    -
  351.    replace: telephonenumber
  352.    telephonenumber: +1 408 555 1234
  353.    telephonenumber: +1 408 555 5678
  354.    -
  355.    delete: facsimiletelephonenumber
  356.    facsimiletelephonenumber: +1 408 555 9876
  357.    -
  358.  
  359.  
  360. Security Considerations
  361.  
  362.    Given typical directory applications, an LDIF file is likely to
  363.    contain sensitive personal data.  Appropriate measures should be
  364.    taken to protect the privacy of those persons whose data is contained
  365.    in an LDIF file.
  366.  
  367.    Since ":<" directives can cause any external file to be included when
  368.    processing an LDIF file, one should be cautious of accepting LDIF
  369.    files from external sources.  A "trojan" LDIF file could name a file
  370.    with sensitive contents and cause it to be included in a directory
  371.    entry, which a hostile entity could read via LDAP.
  372.  
  373.  
  374. Acknowledgments
  375.  
  376.    The LDAP Interchange Format was developed as part of the University
  377.    of Michigan LDAP reference implementation, and was developed by Tim
  378.    Howes, Mark Smith, and Gordon Good.  It is based in part upon work
  379.    supported by the National Science Foundation under Grant No.  NCR-
  380.    9416667.
  381.  
  382.  
  383. References
  384.  
  385.    [1] Howes, T., Smith, M., "A MIME Content-Type for Directory
  386.    Information", INTERNET-DRAFT draft-ietf-asid-mime-direct-02.txt,
  387.    Netscape Communications Corp., <URL:ftp://ietf.org/internet-
  388.    drafts/draft-ietf-asid-mime-direct-02.txt>
  389.  
  390.    [2] Crocker,  D.H., "Standard for the Format of ARPA Internet Text
  391.  
  392.  
  393.  
  394. Good                    IETF ASID Working Group                 [Page 7]
  395.  
  396. INTERNET-DRAFT        LDAP Data Interchange Format      25 November 1996
  397.  
  398.  
  399.    Messages", RFC 822, University of Delaware, August 1982,
  400.    <URL:http://ds.internic.net/rfc/rfc822.txt>
  401.  
  402.    [3] Kille, S., "A String Representation of Distinguished Names", RFC
  403.    1779, ISODE Consortium, March 1995,
  404.    <URL:http://ds.internic.net/rfc/rfc1779.txt>
  405.  
  406.    [4] Wahl, M., Coulbeck, A., Howes, T., Kille, S., "Lightweight
  407.    Directory Access Protocol: Standard and Pilot Attribute Definitions",
  408.    INTERNET-DRAFT draft-ietf-asid-ldapv3-attributes-03.txt, Critical
  409.    Angle, Inc., ISODE Consortium, Netscape Communications Corp.,
  410.    October, 1996, <URL:ftp://ietf.org/internet-drafts/draft-ietf-asid-
  411.    ldapv3-attributes-03.txt>
  412.  
  413.    [5] Borenstein, N., Freed, N., "MIME (Multipurpose Internet Mail
  414.    Extensions) Part One: Mechanisms for Specifying and Describing the
  415.    Format of Internet Message Bodies", section 5.2, "Base64 Content-
  416.    Transfer-Encoding", RFC 1521, Bellcore, Innosoft, December 1993,
  417.    <URL:http://ds.internic.net/rfc/rfc1521.txt>
  418.  
  419.  
  420. Author's Address
  421.  
  422.    Gordon Good
  423.    Netscape Communications Corp.
  424.    501 E. Middlefield Rd.
  425.    Mountain View, CA 94043, USA
  426.    Phone:  +1 415 937-3825
  427.    EMail:  ggood@netscape.com
  428.  
  429.                 This Internet Draft expires May 1st, 1997.
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Good                    IETF ASID Working Group                 [Page 8]
  451.