upstream/openldap
1
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2025-12-24 00:29:35 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Don't include revision number in file name (to allow in place updating)

Browse source
This commit is contained in:
Kurt Zeilenga 1999-08-18 20:07:09 +00:00
parent fc2b55f53d
commit 2ebdf71808
5 changed files with 8200 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

324
doc/drafts/draft-byrne-ldap-alias-xx.txt Normal file
View file

@ -0,0 +1,324 @@
Internet-Draft D. Byrne, IBM
LDAP Extensions WG L. Poitou, Sun
Intended Category: Standards Track E. Stokes, IBM
Expires: 20 October 1998
20 April 1998
Use of Aliases within LDAP
<draft-byrne-ldap-alias-00.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. Internet Drafts may be updated, replaced, or obsoleted
by other documents at any time. It is not appropriate to use
Internet Drafts as reference material or to cite them other
than as a "working draft" or "work in progress."
To view the entire list of current Internet-Drafts, please
check the "1id-abstracts.txt" listing contained in the
Internet-Drafts Shadow Directories on ftp.is.co.za (Africa),
ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern
Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East
Coast), or ftp.isi.edu (US West Coast).
Comments and suggestions on this document are encouraged.
Comments on this document should be sent to the LDAPEXT
working group discussion list:
ietf-ldapext@netscape.com
ABSTRACT
This document describes the suggested behavior for aliases for
LDAPv3 and above to improve LDAP server interoperability .
The key words "MUST", "SHOULD", and "MAY" used in this
document are to be interpreted as described in [Bradner97].
1. Objectives
Aliases may be used within LDAP to reference entries anywhere
within the directory tree. Conceptually, an alias is simply a
pointer to the DIT entry it represents. It does not contain
additional information about that entry; only the location of
the entry.
The behavior of the alias object within LDAP is not well-
defined, both in creation of the alias object and the behavior
when dereferencing the alias.
For successful interoperability, the expected behavior of
servers when encountering alias objects SHOULD be consistent.
Additionally, it MUST be possible to use aliases without
changing the LDAPv3 schema as defined in [Wahl] and without
adding server-dependent data.
2. Schema Definition
2.1 Schema Expansion
The alias objectclass definitions presented in the LDAPv3
Schema [Wahl] are the basis for aliasing within ldap. The
alias objectclass is a Structural objectclass with a single
required attribute; the single valued aliasObjectName.
This definition of the alias objectclass does not allow for
any attribute other than 'aliasedObjectName' to be used as the
naming attribute within the RDN. The resulting dn for the
alias object must therefore be of the form
"aliasedObjectName=<dn>, <rdn>, <rdn>..." This is not a
user-friendly name for a directory entry, and quite possibly
corrupts the naming hierarchy within the directory tree.
In order to remain true the concept of an alias; that it is
merely a pointer to another entry, an entry of objectclass
alias SHOULD NOT be combined with any other objectclass. If
multiple objectclasses are combined, it becomes possible to
add information to the alias entry without violating the
schema rules.
While not explicitly specified as either a 'required' or
'may', any naming attribute MUST be allowed to form the RDN of
the alias. Restricting the possible naming attributes would
potentially corrupt the hierarchy. For example, it would be
impossible to distinguish between a person alias and an
organisation alias.
2.2 AliasObject Objectclass
In order to create an alias object which can be appropriately
named to that which it represents, the definition of the alias
object MUST be expanded. A new objectclass must be defined
which inherits from the current definition of alias but
extends the attributes allowed within the RDN.
( 1.3.6.1.4.1.42.2.27.1.2.1
NAME 'aliasObject'
DESC objectclass for all alias objects
SUP 'ALIAS'
MAY *
)
The '*' allows any naming attribute to be used in forming the
RDN of the object.
For example, the following is a correct LDIF:
dn: cn=John Doe, ou=myOrg, c=US
objectclass: alias
objectclass: aliasObject
aliasedObjectName: cn=President, ou=myOrg, c=US
cn: John Doe
To prevent the alias from containing extra information about
the object, the naming attribute SHOULD contain only a single
value.
For example, the following is not a correct LDIF:
dn: cn=John Doe, ou=myOrg, c=US
objectclass: alias
objectclass: aliasObject
aliasedObjectName: cn=President, ou=myOrg, c=US
cn: John Doe
cn: Doe
Similarly, the following would not be a correct LDIF file
because it adds extra information to the alias object.
dn: cn=John Doe, ou=myOrg, c=US
objectclass: alias
objectclass: aliasObject
aliasedObjectName: cn=President, ou=myOrg, c=US
cn: John Doe
title: President
The naming attribute used to form the RDN of the object SHOULD
reflect the naming attribute of the referenced object.
However, there are some cases where the naming attribute MAY
be different.
Within the X.501 [ITU-T], the attribute used to described the
aliased object is 'aliasedEntryName'. Since the OID for
'aliasedEntryName' and 'aliasedObjectName' are the same for
both X.500 and LDAP, LDAP servers SHOULD treat the
'aliasedEntryName' as a synonym for 'aliasedObjectName'.
3. Alias Behavior
In general alias objects SHOULD NOT be dereferenced during any
operation other than search unless requested to do so by the
client.
Since an alias points to another section of the tree, it MUST
NOT be possible to add an object under an alias object; alias
objects MUST always be leaf nodes.
During the dereferencing of aliases, a loop is detected if the
server visits the same alias entry more than once. In this
case a data integrity error has occurred and the server MUST
return an error of 'aliasProblem'
If an alias is dereferenced, and the resulting directory entry
does not exists, a data integrity problem has occurred, and
the server MUST return an error code of
'aliasDereferencingProblem'
If the base entry for an ldapsearch is an alias, and alias
dereferencing is set to either derefFindBaseObj, or
derefAlways, the base entry MUST be dereferenced before the
search is performed. The new base for the search will become
the entry to which the alias resolves. The search is then
performed.
If multiple aliases are chained, the alias for the first
object MUST resolve to the last entry in the chain. For
example, A, B, and C are alias objects. If A points to B which
points to C which points to D, A resolves to D when
dereferencing the alias.
If an alias is dereferenced as part of a search, the alias
entry itself SHOULD NOT be returned as part of the search.
If an alias matches the search filter, and dereferencing is
set to 'searching' or 'always', the dereferenced object SHOULD
be returned, even if it does not match the filter.
If the alias is not dereferenced during the search, and it
matches the filter, then it SHOULD be returned within the
search result.
Each directory object matching a filter SHOULD be returned
only once during a search. If an entry is found twice because
of aliases pointing to a part of the tree already searched,
the entry SHOULD NOT be returned to the client a second time.
4. Scenarios
Using the following LDIF, the scenarios would return the
expected information as follows:
dn: c=myCountry
c: myCountry
objectclass: country
dn: ou=Area1, c=myCountry
ou: Area1
aliasedObjectName: o=myCorporation, c=myCountry
objectclass: alias
objectclass:aliasObject
dn: o=myCorporation, c=myCountry
ou: myCorporation
objectclass:organization
dn: cn=President, o=myCorporation, c=myCountry
cn: President
aliasObjectName: cn=John Doe, o=myCorporation, c=myCountry
objectclass: alias
objectclass: aliasObject
dn: cn=John Doe, o=myCorporation, c=myCountry
cn: John Doe
objectclass: person
c = myCountry
/ |
ou = Area1 -----> o = myCorporation
| \
cn=President ---> cn = John Doe
Performing a base search of 'ou = Area1, c=myCountry' with a
filter of 'objectclass=aliasObject'
NeverDerefAlias would return 'ou=Area1, c=myCountry'
DerefFinding would return 'cn=President, o=myCorporation,
c=myCountry'
DerefSearching would return 'o=myCorporation,
c=myCountry'
DerefAlways would return 'cn=John Doe, o=myCorporation,
c=myCountry'
Performing a one level search of 'c=myCountry' with a filter
of 'ou = * '
NeverDerefAlias would return 'ou=Area1, c=myCountry'
DerefFinding would return 'ou=Area1, c=myCountry'
DerefSearching would return 'o=myCorporation,
c=myCountry'
DerefAlways would return ' o=myCorporation, c=myCountry'
Performing a full tree search of 'c=myCountry' with a filter
of ' cn = President '
NeverDerefAlias would return 'cn=President, o=myCorporation,
c=myCountry'
DerefFinding would return 'cn=President, o=myCorporation,
c=myCountry'
DerefSearching would return 'cn=John Doe, o=myCorporation,
c=myCountry'
DerefAlways would return 'cn=John Doe, o=myCorporation,
c=myCountry'
6. Security Considerations
Permissions to dereferencing an alias, adding, deleting or
returning alias entries are decided by the directory server's
ACL administration policy.
7. References
[LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
Access Protocol (v3)", RFC 2251, December 1997.
[Whal] M.Wahl, A, Coulbeck, T. Howes, S. Kille, "Lightweight
Directory Access Protocol (v3)": Attribute Syntax Definitions,
RFC 2252, December 1997.
[Bradner97] Bradner, Scott, "Key Words for use in RFCs to
Indicate Requirement Levels", RFC 2119.
[ITU-T] ITU-T Rec. X.501, "The Directory: Models", 1993
AUTHOR(S) ADDRESS
Debbie Byrne
IBM
11400 Burnet Rd
Austin, TX 78758
USA
mail-to: djbyrne@us.ibm.com
phone: +1 512 838 1930
Ludovic Poitou
Sun Microsystems
32, Chemin du vieux Chene
38240 Meylan
France
Phone: +33.(0)4.76.41.42.12
email: ludovic.poitou@france.sun.com
Ellen Stokes
IBM
11400 Burnet Rd
Austin, TX 78758
USA
mail-to: stokes@austin.ibm.com
phone: +1 512 838 3725

449
doc/drafts/draft-good-ldap-changelog-xx.txt Normal file
View file

@ -0,0 +1,449 @@
Change Record Object Class Definition Gordon Good
INTERNET-DRAFT Netscape Communications
11 March 1998
Definition of an Object Class to Hold LDAP Change Records
Filename: draft-good-ldap-changelog-00.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).
This Internet Draft expires October 1st, 1998.
Abstract
In order to support more flexible replication methods, it is
desirable to specify some manner in which an LDAP client may retrieve
a set of changes which have been applied to an LDAP server's
database. The client, which may be another LDAP server, may then
choose to update its own replicated copy of the data. This document
specifies an object class which may be used to represent changes
applied to an LDAP server. It also specifies a method for
discovering the location of the container object which holds these
change records, so that clients and servers have a common rendezvous
point for this information.
Background and Intended Usage
This document describes an objectclass which can be used to represent
Good March 11, 1998 [Page 1]
INTERNET-DRAFT Change Record Object Class 11 March 1998
changes which have been applied to a directory server. It also
suggests a common location for a container which holds these objects.
A client may update its local copy of directory information by
reading the entries within this container, and applying the changes
to its local database.
The key words "MUST", "MAY", and "SHOULD" used in this document are
to be interpreted as described in [3].
New Attribute Types Used in the changeLogEntry Object Class
( 2.16.840.1.113730.3.1.5
NAME 'changeNumber'
DESC 'a number which uniquely identifies a change made to a
directory entry'
SYNTAX 'INTEGER'
EQUALITY 'integerMatch'
ORDERING 'integerOrderingMatch' )
( 2.16.840.1.113730.3.1.6
NAME 'targetDN'
DESC 'the DN of the entry which was modified'
EQUALITY distinguishedNameMatch
SYNTAX 'DN' )
( 2.16.840.1.113730.3.1.7
NAME 'changeType'
DESC 'the type of change made to an entry'
EQUALITY caseIgnoreMatch
SYNTAX 'DirectoryString' )
( 2.16.840.1.113730.3.1.8
NAME 'changes'
DESC 'a set of changes to apply to an entry'
SYNTAX 'OctetString' )
( 2.16.840.1.113730.3.1.9
NAME 'newRDN'
DESC 'the new RDN of an entry which is the target of a
modrdn operation'
EQUALITY distinguishedNameMatch
SYNTAX 'DN' )
( 2.16.840.1.113730.3.1.10
NAME 'deleteOldRDN'
DESC 'a flag which indicates if the old RDN should be retained
as an attribute of the entry'
EQUALITY booleanMatch
Good March 11, 1998 [Page 2]
INTERNET-DRAFT Change Record Object Class 11 March 1998
SYNTAX 'BOOLEAN' )
( 2.16.840.1.113730.3.1.11
NAME 'newSuperior'
DESC 'the new parent of an entry which is the target of a
moddn operation'
EQUALITY distinguishedNameMatch
SYNTAX 'DN' )
Schema Definition of the changeLogEntry Object Class
( 2.16.840.1.113730.3.2.1
NAME 'changeLogEntry'
SUP top
STRUCTURAL
MUST (
changeNumber $ targetDN $ changeType
)
MAY (
changes $ newRDN $ deleteOldRDN $ newSuperior
)
)
Discussion of changeLogEntry Attributes:
changeNumber: the change number, as assigned by the supplier. This
integer MUST strictly increase as new entries are added, and must
always be unique within a given server. Syntax: INTEGER
targetdn: the distinguished name of the entry which was added,
modified or deleted. In the case of a modrdn operation, the targetdn
gives the DN of the entry before it was modified. Syntax: DN
changeType: the type of change. One of: "add", "delete", "modify",
"modrdn". Later RFCs may define additional values for changeType.
Syntax: DirectoryString
changes: the changes which were made to the directory server. These
changes are in LDIF format, which is described in [1].
Syntax: OctetString
newRDN: the new RDN (Relative Distinguished Name) of the entry, if the
changeType is "modrdn". If the changeType attribute does not have the
value "modrdn", then there should be no values contained in the newRDN
attribute.
Good March 11, 1998 [Page 3]
INTERNET-DRAFT Change Record Object Class 11 March 1998
Syntax: DN
deleteOldRDN: a flag which tells whether the old RDN of the entry
should be retained as a distinguished attribute of the entry, or
should be deleted. A value of "FALSE" indicates that the RDN should be
retained as a distinguished attribute, and a value of "TRUE" indicates
that it should not be retained as a distinguished attribute of the
entry. If any value other than "TRUE" or "FALSE" is contained in the
deleteOldRDN attribute, or if the deleteOldRDN contains multiple
values, the RDN should be retained as a distinguished attribute (that
is, "FALSE" is the default if no values are present, or if illegal
values are present).
Syntax: BOOLEAN
newSuperior: if present, gives the name of the entry which
becomes the immediate superior of the existing entry. This optional
attribute reflects LDAPv3 functionality, and MUST NOT be generated
by LDAPv2 servers [2].
Syntax: DN
Discussion of the changeLogEntry object class
The changeLogEntry object class is used to represent changes made to a
directory server. The set of changes made to a directory server, then,
is given by the ordered set of all entries within the changelog
container, ordered by changeNumber.
A client may synchronize its local copy of a remote directory server's
contents by searching the remote server's changelog container for any
entries where the changenumber is greater than or equal to the last
change previously retrieved from that server. If the entry with the
changenumber matching the last change retrieved is not returned in the
search results, then the server's changelog has been trimmed. The
client must then fall back to reading the entire directory to bring its
copy in sync with the server's.
Assuming that the client has successfully retrieved one or more changelog
entries from the server, it can then use the information contained in each
entry to update the corresponding entry (named by the targetDN attribute)
in its local copy of the database.
Note that, due to access control restrictions, the client is not guaranteed
read access to the "changes" attribute. If the client discovers that the
"changes" attribute has no values, then it must read the entry given by
the targetDN attribute, possibly only retrieving attributes it deems
"interesting". However, in the case of delete and modrdn operations, there
Good March 11, 1998 [Page 4]
INTERNET-DRAFT Change Record Object Class 11 March 1998
is never a "changes" attribute, so it is never necessary to read the target
entry in these cases.
Examples of the changeLogEntry object class
In each example below, the "changes" attribute is shown in plain text,
with embedded newlines. This is done for clarity. It is intended that
newlines be stored in the entry literally, not encoded in any way.
If a "changes" attribute value is stored in an LDIF file, it must
base-64 encoded.
Example 1: A changeLogEntry representing the addition of a
new entry to the directory
dn: changenumber=1923, cn=changelog
changenumber: 1923
targetdn: cn=Barbara Jensen, ou=Accounting, o=Ace Industry, c=US
changetype: add
changes: cn: Barbara Jensen\ncn: Babs Jensen\nsn: Jensen\n
givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: babs@ace.com\n
objectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\n
objectclass: inetOrgPerson
Example 2: A changeLogEntry representing the deletion of an entry
from the directory
dn: changenumber=2933, cn=changelog
changenumber: 2933
targetdn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US
changetype: delete
Example 3: A changeLogEntry representing the modification of an entry
in the directory
dn: changenumber=5883, cn=changelog
changenumber: 5883
targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US
changetype: modify
changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n
add: telephonenumber\ntelephonenumber: +1 212 555 1212\n-
Example 4: A changeLogEntry representing a modrdn operation performed
on an entry in the directory
dn: changenumber=10042, cn=changelog
changenumber: 10042
Good March 11, 1998 [Page 5]
INTERNET-DRAFT Change Record Object Class 11 March 1998
targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US
changetype: modrdn
newrdn: cn=Bjorn J Jensen
deleteoldrdn: FALSE
Location of the container containing changeLogEntry objects
For LDAPv3 servers, the location of the container which holds
changeLogEntry objects is obtained by reading the "changeLog" attribute
of a server's root DSE. For example, if the container's root is
"cn=changelog", then the root DSE must have an attribute named
"changeLog" with the value "cn=changelog".
The "changelog" attribute is defined as follows:
( 2.16.840.1.113730.3.1.35
NAME 'changelog'
DESC 'the distinguished name of the entry which contains
the set of entries comprising this server's changelog'
EQUALITY distinguishedNameMatch
SYNTAX 'DN'
)
For LDAPv2 servers, the name of the changelog container must be
"cn=changelog".
Differences from previous versions of this document
Differences between draft-ietf-asid-changelog-00.txt and
draft-ietf-asid-changelog-01.txt
1) Fixed a deficiency in the syntax of the changeNumber attribute. The
attribute now has INTEGER syntax, with appropriate matching and
ordering rules defined.
2) Removed unneeded substring matching rules from the changeType and
deleteOldRDN attribute definitions.
3) Made use of MAY, SHOULD, etc. consistent with RFC 2119.
4) Renamed document (now an individual submission).
5) Changed syntax of "changes" attribute from "Binary" to "OctetString".
6) Removed references to X.500 supplier and consumer-initiated
replication.
Good March 11, 1998 [Page 6]
INTERNET-DRAFT Change Record Object Class 11 March 1998
7) Updated references to current drafts/proposed standards documents.
Security Considerations
Servers implementing this scheme MUST NOT allow the "changes"
attribute to be generally readable. The "changes" attribute contains
all modifications made to an entry, and some changes may contain
sensitive data, e.g. passwords.
If a server does allow read access on the "changes: attribute to a
particular bound DN, then that DN should be trusted. For example, two
cooperating servers may exchange the password for some DN which is
granted read access to the "changes" attribute of the changeLog. This
would allow one server to retrieve changes and apply them directly to
its database.
In situations where the "changes" attribute is not readable by a client,
that client may still use the entries in the changeLog to construct a
list of entry DNs which are known to have changed since the last time
the client synchronized. The client may then read each of those entries,
subject to whatever access control is in effect on the server,
and update its local copy of each entry.
Servers implementing this scheme should disallow write access to the
changelog container object and all entries contained within.
Acknowledgements
This material is based in part upon work supported by the National
Science Foundation under Grant No. NCR-9416667.
References
[1] Good, G., "The LDAP Data Interchange Format", INTERNET-DRAFT
draft-good-ldap-ldif-03.txt, Netscape Communications Corp., March 1997,
<URL:ftp://ftp.ietf.org/internet-drafts/draft-good-ldap-ldif-03.txt>
[2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp.,
ISODE Consortium, July, 1997,
<URL:ftp://ftp.isi.edu/in-notes/rfc2251.txt>
[3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
Levels", Harvard University, RFC 2119, March 1997,
Good March 11, 1998 [Page 7]
INTERNET-DRAFT Change Record Object Class 11 March 1998
<URL:http://ds.internic.net/rfc/rfc2119.txt>
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 October 1st, 1998.
Good March 11, 1998 [Page 8]

672
doc/drafts/draft-good-ldap-ldif-xx.txt Normal file
View file

@ -0,0 +1,672 @@
LDAP Data Interchange Format (LDIF) Gordon Good
INTERNET-DRAFT Netscape Communications
22 February 1999
The LDAP Data Interchange Format (LDIF) - Technical Specification
Filename: draft-good-ldap-ldif-03.txt
Status of this Memo
This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026.
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 view the list Internet-Draft Shadow Directories, see
http://www.ietf.org/shadow.html.
This Internet Draft expires August 22nd, 1999.
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.
Background and Intended Usage
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.
Additionally, by using a well-defined interchange format, development
Good February 22, 1999 [Page 1]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
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. Thie file can
then be imported into a directory server, regardless of the internal
database representation the target directory server uses.
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. The LDIF format is
a simpler format which is perhaps easier to create, and also may also
be used, as noted, to describe a set of changes to be applied to a
directory.
The key words "MUST", "MAY", and "SHOULD" used in this document are
to be interpreted as described in [7].
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 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
The following definition uses the augmented Backus-Naur Form
specified in RFC 822 [2].
ldif-file = ldif-content / ldif-changes
Good February 22, 1999 [Page 2]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
ldif-content = version-spec 1*SEP
ldif-attrval-record *(1*SEP ldif-attrval-record)
ldif-changes = version-spec 1*SEP
ldif-change-record *(1*SEP ldif-change-record)
ldif-attrval-record = dn-spec SEP 1*(attrval-spec SEP)
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 2253 [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
2253 [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].
An attribute description MAY NOT contain a
colon ":">
value = 1*safe-initval *safe
; (See Note 9, below)
safe = <any value except CR or LF>
safe-initval = <any value except CR, LF, 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 /
"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
Good February 22, 1999 [Page 3]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
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) For the LDIF format described in this document, the version number
MUST be "1". If the version number is absent, implementations MAY
choose to interpret the contents as an older LDIF file format,
supported by the University of Michigan ldap-3.3 implementation [8].
2) Any line, including comment lines, 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. When joining folded lines, exactly one space character
at the beginning of each continued line must be discarded.
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
associated with each supported URL will be documented in
an associated Applicability Statement.
7) While it is permissible for character values larger than 126 to be
Good February 22, 1999 [Page 4]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
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
UTF-8 data.
8) Attribute values contained in LDIF files represent directory data,
and therefore MUST be valid UTF-8 strings. Implementations which read
LDIF MAY interpret files in which the values are stored in some other
character set encoding, but implementations MUST NOT generate LDIF
content which does not contain valid UTF-8 data.
9) Values that end with SPACE SHOULD be base-64 encoded.
Examples of LDAP Data Interchange Format
Example 1: An simple LDAP file with two entries
version: 1
dn: cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
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, dc=airius, dc=com
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
version: 1
dn:cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
objectclass:top
objectclass:person
objectclass:organizationalPerson
cn:Barbara Jensen
Good February 22, 1999 [Page 5]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
cn:Barbara J Jensen
cn:Babs Jensen
sn:Jensen
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
version: 1
dn: cn=Gern Jensen, ou=Product Testing, dc=airius, dc=com
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 an entries with UTF-8-encoded attribute
values, including language tags. Comments indicate the contents
of UTF-8-encoded attributes and distinguished names.
version: 1
dn:: b3U95Za25qWt6YOoLG89QWlyaXVz
# dn:: ou=<JapaneseOU>,o=Airius
objectclass: top
objectclass: organizationalUnit
ou:: 5Za25qWt6YOo
# ou:: <JapaneseOU>
ou;lang-ja:: 5Za25qWt6YOo
# ou;lang-ja:: <JapaneseOU>
ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2
# ou;lang-ja:: <JapaneseOU_in_phonetic_representation>
ou;lang-en: Sales
description: Japanese office
dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz
# dn:: uid=<uid>,ou=<JapaneseOU>,o=Airius
userpassword: {SHA}O3HSv1MusyL4kTjP+HKI5uxuNoM=
objectclass: top
objectclass: person
Good February 22, 1999 [Page 6]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: rogasawara
mail: rogasawara@airius.co.jp
givenname;lang-ja:: 44Ot44OJ44OL44O8
# givenname;lang-ja:: <JapaneseGivenname>
sn;lang-ja:: 5bCP56yg5Y6f
# sn;lang-ja:: <JapaneseSn>
cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
# cn;lang-ja:: <JapaneseCn>
title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw==
# title;lang-ja:: <JapaneseTitle>
preferredlanguage: ja
givenname:: 44Ot44OJ44OL44O8
# givenname:: <JapaneseGivenname>
sn:: 5bCP56yg5Y6f
# sn:: <JapaneseSn>
cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
# cn:: <JapaneseCn>
title:: 5Za25qWt6YOoIOmDqOmVtw==
# title:: <JapaneseTitle>
givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8
# givenname;lang-ja;phonetic::
<JapaneseGivenname_in_phonetic_representation_kana>
sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ
# sn;lang-ja;phonetic:: <JapaneseSn_in_phonetic_representation_kana>
cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA==
# cn;lang-ja;phonetic:: <JapaneseCn_in_phonetic_representation_kana>
title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg==
# title;lang-ja;phonetic:: <JapaneseTitle_in_phonetic_representation_kana>
givenname;lang-en: Rodney
sn;lang-en: Ogasawara
cn;lang-en: Rodney Ogasawara
title;lang-en: Sales, Director
Example 5: A file containing a reference to an external file
version: 1
dn: cn=Horatio Jensen, ou=Product Testing, dc=airius, dc=com
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
Good February 22, 1999 [Page 7]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
Example 6: A file containing a series of change records and comments
version: 1
# Add a new entry
dn: cn=Fiona Jensen, ou=Marketing, dc=airius, dc=com
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, dc=airius, dc=com
changetype: delete
# Modify an entry's relative distinguished name
dn: cn=Paul Jensen, ou=Product Development, dc=airius, dc=com
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, dc=airius, dc=com
changetype: modrdn
newrdn: ou=Product Development Accountants
deleteoldrdn: 0
newsuperior: ou=Accounting, dc=airius, dc=com
# 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, dc=airius, dc=com
changetype: modify
add: postaladdress
postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086
-
delete: description
-
replace: telephonenumber
telephonenumber: +1 408 555 1234
telephonenumber: +1 408 555 5678
-
Good February 22, 1999 [Page 8]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
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
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.
Appendix A: Differences from previous versions of this document
This section summarizes the differences between previous revisions of
this draft, as an aid to document reviewers. This section will be
deleted prior to publication as an RFC.
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
1) The BNF has been modified such that a simple attribute name
Good February 22, 1999 [Page 9]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
("attrname") has been replaced with an "attribute-description" as
defined in the LDAPv3 protocol document [4]. 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.
Differences between draft-ietf-asid-ldif-02.txt and draft-good-ldap-
ldif-00.txt
1) The "charset-option" and "charset-name" productions were removed
from the BNF, due to objections within the working group. UTF-8 is
the only character set which may be used in LDIF.
2) Examples were reworked to reflect the above change, and to include
an example of a non-western language represented in UTF-8.
Differences between draft-ietf-good-ldif-00.txt and draft-good-ldap-
ldif-01.txt
1) Added version identifiers to the examples - they were missing.
2) Clarified that LDIF file must use UTF-8.
Differences between draft-ietf-good-ldif-01.txt and draft-good-ldap-
ldif-02.txt
1) Added a recommendation that values ending in SPACE should be
base-64 encoded.
2) Clarified the procedure for joining folded lines.
3) Updated header to reflect new IETF I-D guidelines.
Differences between draft-ietf-good-ldif-02.txt and draft-good-ldap-
ldif-03.txt
1) Fixed reference from RFC 1779 to RFC 2253.
2) Version string is now required.
3) Comment lines may be folded (this is now explicitly mentioned in
note 2).
Good February 22, 1999 [Page 10]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
4) Moved this section (differences between draft versions) to an
appendix.
5) Updated examples to use "dc=airius, dc=com" instead of "o=Ace
Industry, c=US"
6) Cleaned up references section.
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", RFC 2425, September 1998,
<URL:http://www.ietf.org/rfc/rfc2245.txt>
[2] Crocker, D.H., "Standard for the Format of ARPA Internet Text
Messages", RFC 822, August 1982,
<URL:http://ds.internic.net/rfc/rfc822.txt>
[3] Wahl, M., Kille, S., Howes, T., "A String Representation of Dis-
tinguished Names", RFC 2253,
<URL:http://www.ietf.org/rfc/rfc2253.txt>
[4] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
Protocol (v3)", RFC 2251, July, 1997,
<URL:ftp://www.ietf.org/rfc/rfc2251.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, December 1993,
<URL:http://ds.internic.net/rfc/rfc1521.txt>
[6] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
Locators (URL)", RFC 1738, December 1994,
<URL:http://ds.internic.net/rfc/rfc1738.txt>
[7] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
Good February 22, 1999 [Page 11]
INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
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/~dirsvcs/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 650 937-3825
EMail: ggood@netscape.com
This Internet Draft expires August 22nd, 1999.
Good February 22, 1999 [Page 12]

2440
doc/drafts/draft-ietf-ldapext-acl-model-xx.txt Normal file
View file

File diff suppressed because it is too large Load diff

4315
doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt Normal file
View file

File diff suppressed because it is too large Load diff