LDAP Data Interchange Format (LDIF) Gordon Good
INTERNET-DRAFT Netscape Communications
9 June 1997
The LDAP Data Interchange Format (LDIF) - Technical Specification
Filename: draft-ietf-asid-ldif-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).
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 December 9th, 1997.
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 9 June 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 9 June 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 =
base64-dn =
rdn =
base64-rdn =
attrval-spec = attrname ((":") / (":" *SPACE value) /
("::" *SPACE base64-value) /
(":<" *SPACE url))
url =
; (See Note 6, below)
attrname =
value = 1*safe-initval *safe
safe =
safe-initval =
base64-value =
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 /
"newrdn::" *SPACE base-64-rdn) SEP
"deleteoldrdn:" *SPACE ("0" / "1")
0,1*(SEP (("newsuperior:" *SPACE dn) /
Good IETF ASID Working Group [Page 3]
INTERNET-DRAFT LDAP Data Interchange Format 9 June 1997
("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 attrname 1*(SEP attrval-spec) SEP "-"
mod-delete-spec = "delete:" *SPACE attrname *(SEP attrval-spec) SEP "-"
mod-replace-spec = "replace:" *SPACE attrname *(SEP attrval-spec) SEP
"-"
SPACE =
SEP = (CR LF / LF)
CR =
LF =
DIGIT =
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
"attrname:".
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
associated with each supported URL will be documented in
an associated Applicability Statement.
Differences from previous versions of this document
Differences from draft-ietf-asid-ldif-00.txt
Good IETF ASID Working Group [Page 4]
INTERNET-DRAFT LDAP Data Interchange Format 9 June 1997
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.
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 5]
INTERNET-DRAFT LDAP Data Interchange Format 9 June 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 series of change records and comments
# 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
Good IETF ASID Working Group [Page 6]
INTERNET-DRAFT LDAP Data Interchange Format 9 June 1997
# 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
-
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
Good IETF ASID Working Group [Page 7]
INTERNET-DRAFT LDAP Data Interchange Format 9 June 1997
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.,
[2] Crocker, D.H., "Standard for the Format of ARPA Internet Text
Messages", RFC 822, University of Delaware, August 1982,
[3] Kille, S., "A String Representation of Distinguished Names", RFC
1779, ISODE Consortium, March 1995,
[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-03.txt,
Critical Angle, Inc., ISODE Consortium, Netscape Communications
Corp., October, 1996,
[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,
[6] Uniform Resource Locators (URL). T. Berners-Lee, L. Masinter,
M. McCahill, Request for Comment (RFC) 1738, December 1994.
Good IETF ASID Working Group [Page 8]
INTERNET-DRAFT LDAP Data Interchange Format 9 June 1997
[7] Key Words for use in RFCs to Indicate Requirement Levels, S.
Bradner, RFC 2119, March 1997.
[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.
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 December 9th, 1997.
Good IETF ASID Working Group [Page 9]