From 2ebdf718080bb16d2118be70e7a49f9f4eb44c70 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Wed, 18 Aug 1999 20:07:09 +0000 Subject: [PATCH] Don't include revision number in file name (to allow in place updating) --- doc/drafts/draft-byrne-ldap-alias-xx.txt | 324 ++ doc/drafts/draft-good-ldap-changelog-xx.txt | 449 ++ doc/drafts/draft-good-ldap-ldif-xx.txt | 672 +++ .../draft-ietf-ldapext-acl-model-xx.txt | 2440 ++++++++++ .../draft-ietf-ldapext-ldap-c-api-xx.txt | 4315 +++++++++++++++++ 5 files changed, 8200 insertions(+) create mode 100644 doc/drafts/draft-byrne-ldap-alias-xx.txt create mode 100644 doc/drafts/draft-good-ldap-changelog-xx.txt create mode 100644 doc/drafts/draft-good-ldap-ldif-xx.txt create mode 100644 doc/drafts/draft-ietf-ldapext-acl-model-xx.txt create mode 100644 doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt diff --git a/doc/drafts/draft-byrne-ldap-alias-xx.txt b/doc/drafts/draft-byrne-ldap-alias-xx.txt new file mode 100644 index 0000000000..0595ecdfe0 --- /dev/null +++ b/doc/drafts/draft-byrne-ldap-alias-xx.txt @@ -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 + + + 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=, , ..." 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 + + diff --git a/doc/drafts/draft-good-ldap-changelog-xx.txt b/doc/drafts/draft-good-ldap-changelog-xx.txt new file mode 100644 index 0000000000..708c8552f6 --- /dev/null +++ b/doc/drafts/draft-good-ldap-changelog-xx.txt @@ -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, + + + [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access + Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp., + ISODE Consortium, July, 1997, + + + [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 + + + + + +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] + diff --git a/doc/drafts/draft-good-ldap-ldif-xx.txt b/doc/drafts/draft-good-ldap-ldif-xx.txt new file mode 100644 index 0000000000..56654338ee --- /dev/null +++ b/doc/drafts/draft-good-ldap-ldif-xx.txt @@ -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 = + base64-dn = + rdn = + base64-rdn = + + attrval-spec = attribute-description ((":") / (":" *SPACE value) / + ("::" *SPACE base64-value) / + (":<" *SPACE url)) + url = + ; (See Note 6, below) + attribute-description = + value = 1*safe-initval *safe + ; (See Note 9, below) + 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) / + ("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 = + SEP = (CR LF / LF) + CR = + LF = + DIGIT = + + + 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=,o=Airius + objectclass: top + objectclass: organizationalUnit + ou:: 5Za25qWt6YOo + # ou:: + ou;lang-ja:: 5Za25qWt6YOo + # ou;lang-ja:: + ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2 + # ou;lang-ja:: + ou;lang-en: Sales + description: Japanese office + + dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz + # dn:: uid=,ou=,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:: + sn;lang-ja:: 5bCP56yg5Y6f + # sn;lang-ja:: + cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA== + # cn;lang-ja:: + title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw== + # title;lang-ja:: + preferredlanguage: ja + givenname:: 44Ot44OJ44OL44O8 + # givenname:: + sn:: 5bCP56yg5Y6f + # sn:: + cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA== + # cn:: + title:: 5Za25qWt6YOoIOmDqOmVtw== + # title:: + givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8 + # givenname;lang-ja;phonetic:: + + sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ + # sn;lang-ja;phonetic:: + cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA== + # cn;lang-ja;phonetic:: + title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg== + # title;lang-ja;phonetic:: + 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, + + + [2] Crocker, D.H., "Standard for the Format of ARPA Internet Text + Messages", RFC 822, August 1982, + + + [3] Wahl, M., Kille, S., Howes, T., "A String Representation of Dis- + tinguished Names", RFC 2253, + + + [4] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access + Protocol (v3)", RFC 2251, July, 1997, + + + [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, + + + [6] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource + Locators (URL)", RFC 1738, December 1994, + + + [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, + + + [8] The SLAPD and SLURPD Administrators Guide. University of Michi- + gan, April 1996. + + + +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] + diff --git a/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt b/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt new file mode 100644 index 0000000000..f390148bef --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt @@ -0,0 +1,2440 @@ + + + + + + + + Internet-Draft E. Stokes + LDAP Extensions WG D. Byrne + Intended Category: Standards Track B. Blakley + Expires: 15 October 1999 IBM + 15 April 1999 + + Access Control Model for LDAP + + + 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." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be + accessed at http://www.ietf.org/shadow.html. + + 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 access control model for the + Lightweight Directory Application Protocol (LDAP) + directory service. It includes a description of the + model, the LDAP controls, and the extended operations to + the LDAP protocol. A separate document defines the + corresponding application programming interfaces (APIs). + RFC2219 [Bradner97] terminology is used. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 1] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 1. Introduction + + The ability to securely access (replicate and distribute) + directory information throughout the network is necessary + for successful deployment. LDAP's acceptance as an + access protocol for directory information is driving the + need to provide an access control model definition for + LDAP directory content among servers within an enterprise + and the Internet. Currently LDAP does not define an + access control model, but is needed to ensure consistent + secure access across heterogeneous LDAP implementations. + The major objective is to provide a simple, but secure, + highly efficient access control model for LDAP while also + providing the appropriate flexibility to meet the needs + of both the Internet and enterprise environments and + policies. This document defines the model and the + protocol extensions (controls and extended operations). + A separate document defines the corresponding application + programming interfaces (APIs). + + + 2. Overview + + Access Control mechanisms evaluate requests for access to + protected resources and make decisions about whether + those requests should be granted or denied. In order to + make a grant/deny decision about a request for access to + a protected resource, an access control mechanism needs + to evaluate policy data. This policy data describes + security-relevant characteristics of the requesting + subject and the rules which govern the use of the target + object. + + This proposal defines the protocol elements for + transmission of this access control policy data in an + LDAP environment and an attribute that defines the access + control mechanism in effect for a given part of the LDAP + namespace. The instantiation of an access control model + at the directory server is not defined in this document. + By defining only what flows on the wire allows existing + access control mechanisms to be used at the directory + server. + + No mechanisms are defined in this document to control + access to access control information or for storage of + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 2] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + access control information at the server; this is vendor + dependent. + + A separate requirements document for access control + exists. The access control model used the requirements + documents as a guideline for the development of this + specification and are reflected in this specification to + the extent that the working group could agree on an + access control model. + + The access control model defines + + - A wire protocol for interoperability: The existing + LDAP protocol flows for add, delete, modify, etc are + used to manipulate access control information. + There are additional LDAP controls and extended + protocol operations defined to further help + management of access control information: + getEffectiveRights, listSubjectRights, and + specifyCredentials. + + - LDAP Directory Interchange Format (LDIF) for + application portability: The LDIF is defined for + access control information (ACI). This LDIF is also + used as input to the LDAP APIs so access control + information can be addressed uniformly independent + of how that information is stored and addressed at + the server. + + - A set of attributes to identity the access control + mechanisms supported by a server. + + Encoding of access control information on the wire is per + the LDAPv3 specifications. + + + 3. Terminology + + An "access control list" contains the access control + policy information controlling access to an object or + collection of objects. An access control list consists + of a set of access control list entries. + + An "access control list entry" defines a single subject + security attribute's granted rights for the objects + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 3] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + governed by the access control list to which it belongs. + + The "access control policy information" (acpi) for an + object or a collection of objects defines which subject + security attributes entitle a subject to which granted + rights. The access control policy information for an + object is stored in an access control list. + + An "access decision" is a boolean-valued function which + answers the question: "can the subject with these subject + security attributes perform this operation on this + object?" + + An "access decision function" is an algorithm which makes + an access decision based on subject security attributes, + access control policy information, an object identifier, + and an operation name (possibly augmented by additional + contextual information). + + An "access decision function interface" is a programmatic + interface through which applications can request an + access decision. + + An "access identity" is an identity which is used by an + access decision function to make an access decision. + + An "audit identity" is an identity which does not, in the + absence of additional information, enable a party + receiving and examining it to determine which subject it + belongs to. + + A "credential" is a collection of subject security + attributes. + + "effective rights" are the complete set of rights a + subject is entitled to based on all access control lists + which apply to a specific object and based on all of the + subject's security attributes. + + "granted rights" are the complete set of rights an access + control list entitles a subject to based on a specific + subject security attribute. + + A "group" is a privilege attribute asserting a subject's + membership in the collection of subjects whose name is + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 4] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + that of the group. + + An "identity" is a subject security attribute which is + unique to a single subject. + + An "object" is the target of operations in an information + system. + + An "operation" is the result of executing the code + accessed through a named entry point in an information + system. + + An "operation name" is the name of the entry point + through which an operation is invoked in an information + system. + + A "privilege attribute" is a subject security attribute + which may be shared by several subjects. + + "required rights" are the complete set of rights needed + to authorize a requester to perform a specific operation + on an object of a specific type. + + A "right" is the basic unit of access control policy + administration. For each object type in an information + system, a security administrator defines a set of + required rights for each operation. For each object in + the system, a security administrator defines a set of + granted rights for each subject security attribute. When + an access decision is required, an access decision + function checks to make sure that the requester's subject + security attributes have been granted all required rights + needed to perform the requested operation on the + specified target object. + + A "role" is a privilege attribute asserting a subject's + organizational position and entitlement to perform the + operations appropriate to that organizational position. + + A "subject" is an entity which intiates actions in an + information system. + + A "subject security attribute" is a defined property + which is used by a security policy evaluation system to + make policy decisions. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 5] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 4. The Model + + + 4.1 Access Control Activity Lifecycle + + The access control proposal described in this draft + addresses four activities: + + - Creation of subject security attribute information + and access control policy information + + - Retrieval of subject security attribute information + at the time an access request is made + + - Evaluation of access requests against policy, + resulting in an access decision + + - Replication of access control policy information + from one server to another + + 4.2 Access Control Information Model + + This document does not define formats for storage of + access control information; it does define the + operational semantics of access control operations. + + + + + + + + + + + + + + + + + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 6] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + The diagram below illustrates the componentry of an LDAP + system and the placement of the function specified in + this draft. + + +-------------+ + | Application | + +-------------+ + +--------+ + | LDAP | + | Client | + +--------+ + | + | + | <-- LDAP Extended Access Control + Controls + | or Extended Access Control + Operations + v + +-----------------------------+ + | LDAP Server (e.g. SLAPD) | + +-----------------------------+ + . | + . | + . | + . | + v v + +----------+ +-----------+ + | Access | | | + | Control |<.....| Datastore | + | Manager | | | + +----------+ +-----------+ + + LDAP clients use the controls and extended operations + specified in this document to administer access control + policy enforced by LDAP servers. Servers may store + access control information in any way they choose. In + particular, servers may use the access control mechanisms + of their datastores to store and enforce LDAP access + control, or they may implement access control managers + external to their datastores. Datastores and external + access control managers may implement any access control + rule syntax and semantics they choose, as long as the + semantics is compatible with that defined in the section + titled "Operational Semantics of Access Control + Operations" (found after the control and extended + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 7] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + operation definition). + + The access control administration mechanisms specified in + this document are neutral with respect to policy + inheritance mechanisms, explicit vs. implicit denial, + and group nesting. + + 4.3 Bind and Credentials + + A bind authenticates a principal to the directory. A + principal is represented by a DN. A principal has a set + of credentials that are used for determining whether + access to resources specified in ldap operations. These + credentials may be pushed to the server by the client or + may be pulled by the server from the directory data. + Credentials may be local with respect to the server. If + not local (owned by another server or administrative + scope), then the server may decide to define a trust + model that states how to evaluate the trust of a + credential at bind time. The definition of such a trust + model is outside the scope of this document. + + + 5. Access Control Information Schema + + + 5.1 Attributes + + + 5.1.1 Root DSE Attribute for Access Control Mechanism + + The following attribute may be included in the Root DSE. + + ( + NAME 'supportedACIMechanisms' + DESC list of access control mechanisms supported + by this directory server + SYNTAX LDAPOID + ) + + Two access control mechanisms are defined by this + document: + LDAPv3 + X500 + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 8] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + Other vendor access control mechanisms can be defined (by + OID) and are the responsibility of those vendors to + provide the definition and OID. + + 5.1.2 Subschema Attribute for Access Control Mechanism + + A given naming context must provide information about + which access control mechanism is in effect for that + portion of the namespace. The following attribute must + be in each subschema entry associated with a naming + context whose access control mechanism is different from + adjacent naming contexts supported by that directory + server. + + - aCIMechanism lists the value (an OID) that defines + the access control mechanism in effect for the scope + of that subschema entry + + 5.2 Other Defined Parameters/OIDs + + + 5.2.1 Rights Families and Rights + + The following rights families are defined: + LDAPv3 + X500 + + Other parties can (and will) define other rights + families. It is the responsibility of those parties to + provide the definition and OID. + + 5.2.1.1 LDAPv3 Rights Family + + Access rights can apply to an entire object or to + attributes of the object. Each of the LDAP access rights + are discrete. One permission does not imply another + permission. The rights may be ORed together to provide + the desired rights list. + + Rights which apply to attributes are: + + 1 Read Read attribute values + 2 Write Write attribute values + 4 Search Search entries with specified attributes + 8 Compare Compare attributes + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 9] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + Rights that apply to an entire object are: + + 16 Add Add an object below this object + 32 Delete Delete this object + + Rights that apply to the object to which the directory + object points are: + + 64 Manage Perform a privileged operation; used to + restrict access to operations which + read or write especially sensitive data + 128 Use Execute; useful in controlling access to + the objects referred to by directory + entries than in controlling access to + the directory entries themselves + 256 Get Get retrieves the attribute values + 512 Set Set writes the attribute values + + 5.2.1.2 The X.500 Rights Family + + + + 5.2.2 DN Types + + The following DN Types are defined: + + - access-id, OID= + + - group, OID= + + - role, OID= + + access-id, group, and role MUST be supported. An acess- + id is a non-collection (non-group and non-role objects) + DN that can be authenticated. + + Other parties can (and will) define other DN Types. It + is the responsibility of those parties to provide the + definition and OID. + + + 6. Access Control Parameters for LDAP Controls & Extended + Operations + + This section defines the parameters used in the access + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 10] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + control LDAP controls and extended operations in this + document. + + targetDN specifies the initial directory entry in DN + syntax on which the control or extended operation is + performed. + + whichObject specifies whether the access control + information which is get/set is for the target directory + entry (ENTRY) or the target directory entry and its + subtree (SUBTREE). + + rightsFamily specifies the family of rights that will be + get/set for the control or extended operation performed. + A rights family has a defined set of rights. + + rightsList in the SearchResultEntry is of the form + specified in the LDIF BNF for . + + dnType speficies the type of subject security attribute. + Defined types are access-id, group, and role. + + subjectDN is a LDAP string that defines the subject or + value of the dnType. The subjectDN may be a DN or + another string such as IPAddress (dotted-decimal string + representation) on which access control is get/set. If + the subject is an entry in the directory, then the syntax + of the LDAP string is DN. We define two well-known + subjectDNs, the strings + + - public - meaning public access for all users + + - this - meaning the user whose name matches the entry + being accessed + + Four operations are defined: + + - ACI_GRANT grants the rights specified in the + rightsList for the given subject. If an access + control list does not exist for the specified + entry/attribute, then the access control list is + created with the granted rights for the given + subject. If the access control list already exists + for the specified entry/attribute, then the access + control list is modified to grant the rights for the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 11] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + given subject. + + - ACI_DENY denies the rights specified in the + rightsList for the given subject. No implementation + is implied for this operation. For example, denial + of rights may be implemented as explicit denial + (negative rights) on the access control list or + removal of rights from the access control list. + + - ACI_REPLACE replaces the entire access control list + for the specified entry/attribute. If an access + control list does not exist for the specified + entry/attribute, then the access control list is + created with the granted rights for the given + subject. + + - ACI_DELETE deletes the entire access control list + for the specified entry/attribute. + + attrs specifies the list of attributes against which the + operation is performed. attrs can be defined using a + LDAP filter expression. + + + 7. Access Control Information (ACI) Controls + + The access control information controls provide a way to + manipulate access control information in conjunction with + an LDAP operation such as ldap_add, ldap_modify, or + ldap_search. Three LDAP controls are defined for + transmission of access control information. These + controls allow access control information to be get/set + while manipulating other directory information. The + controls are: + + - getEffectiveRights to obtain the effective rights + for a given directory entry(s) for a given subject + during a ldap_search operation + + - listSubjectRights to get the access control + information for a given directory entry(s) during a + ldap_search operation + + - specifyCredentials to specify a set of credentials + for the bind identity (DN) during a ldap_bind + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 12] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + operation + + 7.1 getEffectiveRights Control + + + 7.1.1 Request Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as + defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE) at the client's option. The + controlValue is an OCTET STRING, whose value is the BER + encoding of a value of the following SEQUENCE: + + getEffectiveRightsRequest ::= SEQUENCE { + targetDN LDAPDN, + effectiveRightsRequest SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + subjectDN LDAPString, + } + } + + The targetDN specifies the initial directory entry in DN + syntax on which the getEffectiveRights control is + performed. request is a set of sequences that state the + whichObject (entry or entry plus subtree) and specifics + of the control request to be performed. One or more + rightsFamily can be be obtained for a given subjectDN ad + dnType. A "*" in the rightsFamily field indicates that + the rights for all rights families defined for the + subjectDN / dnType are to be returned. This control is + applied to the scope set by the ldap_search operation, + i.e. base, one-level, subtree. + + 7.1.2 Response Control + + This control is included in the ldap_search_response + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 13] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + message as part of the controls field of the LDAPMessage, + as defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE). The controlValue is an OCTET + STRING, whose value is the BER encoding of a value of the + following SEQUENCE: + + getEffectiveRightsResponse ::= { + result ENUMERATED { + success (0), + operationsError (1), + unavailableCriticalExtension (12), + noSuchAttribute (16), + undefinedAttributeType (17), + invalidAttributeSyntax (21), + unavailable (52), + unwillingToPerform (53), + other (80) + } + } + + The effective rights returned are returned with each + attribute returned by the search result. So, the result + for ldap_search is: + + SearchResultEntry ::= [APPLICATION 4] SEQUENCE { + objectName LDAPDN, + rightsAttributes PartialEffectiveRightsList } + + PartialEffectiveRightsList ::= SEQUENCE OF SEQUENCE { + rightFamily LDAPOID, + rightsList ENUMERATED, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + } + } + + Although this extends the search operation, there are no + incompatibilities between versions. LDAPv2 cannot send a + control, hence the above structure cannot be returned to + a LDAPv2 client. A LDAPv3 client cannot send this + request to a LDAPv2 server. A LDAPv3 server not + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 14] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + supporting this control cannot return the additional + data. + + 7.1.3 Client-Server Interaction + + The getEffectiveRightsRequest control requests the rights + that MUST be in effect for requested directory + entry/attribute based on the subject DN. The server that + consumes the search operation looks up the rights for the + returned directory information based on the subject DN + and returns that rights information. + + There are six possible scenarios that may occur as a + result of the getEffectiveRights control being included + on the search request: + + + 1. If the server does not support this control and the + client specified TRUE for the control's criticality + field, then the server MUST return + unavailableCriticalExtension as a return code in + the searchResponse message and not send back any + other results. This behavior is specified in + section 4.1.12 of [LDAPv3]. + + 2. If the server does not support this control and the + client specified FALSE for the control's + criticality field, then the server MUST ignore the + control and process the request as if it were not + present. This behavior is specified in section + 4.1.12 of [LDAPv3]. + + 3. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified TRUE for the + control's criticality field, then the server SHOULD + do the following: return + unavailableCriticalExtension as a return code in + the searchResult message. + + 4. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified FALSE for the + control's criticality field, then the server should + process as 'no rights returned for that family' and + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 15] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + include the result Unavailable in the + getEffectiveRightsResponse control in the + searchResult message. + + 5. If the server supports this control and can return + the rights per the rightsFamily information, then + it should include the getEffectiveRightsResponse + control in the searchResult message with a result + of success. + + 6. If the search request failed for any other reason, + then the server SHOULD omit the + getEffectiveRightsResponse control from the + searchResult message. + + The client application is assured that the correct rights + are returned for scope of the search operation if and + only if the getEffectiveRightsResponse control returns + the rights. If the server omits the + getEffectiveRightsResponse control from the searchResult + message, the client SHOULD assume that the control was + ignored by the server. + + The getEffectiveRightsResponse control, if included by + the server in the searchResponse message, should have the + getEffectiveRightsResult set to either success if the + rights are returned or set to the appropriate error code + as to why the rights could not be returned. + + The server may not be able to return a right because it + may not exist in that directory object's attribute; in + this case, the rights request is ignored with success. + + 7.2 listSubjectRights Control + + + 7.2.1 Request Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as + defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE) at the client's option. The + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 16] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + controlValue is an OCTET STRING, whose value is the BER + encoding of a value of the following SEQUENCE: + + listSubjectRightsRequest ::= SEQUENCE { + targetDN LDAPDN, + listRightsRequest SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + listSubjectDN LDAPString | "*", + } + } + + The targetDN specifies the initial directory entry in DN + syntax on which the listSubjectRights control is + performed. request is a set of sequences that state the + whichObject (entry or entry plus subtree) and specifics + of the control request to be performed. One or more + rightsFamily can be be obtained for a given subjectDN ad + dnType. A "*" in the rightsFamily field indicates that + the rights for all rights families defined for the + subjectDN / dnType are to be returned. A "*" in the + dnType field indicates that all dnTypes are processed by + this request. A "*" in the subjectDN field indicates + that all subjectDNs are processed by this request. The + scope of the operation is controlled by the scope set in + the ldap_search operation. + + 7.2.2 Response Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as defined + in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE). The controlValue is an OCTET + STRING, whose value is the BER encoding of a value of the + following SEQUENCE: + + listSubjectRightsResponse ::= { + result ENUMERATED { + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 17] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + success (0), + operationsError (1), + unavailableCriticalExtension (12), + noSuchAttribute (16), + undefinedAttributeType (17), + invalidAttributeSyntax (21), + unavailable (52), + unwillingToPerform (53), + other (80) + } + } + + The subjects' rights returned are returned with each + attribute returned by the search result. So, the result + for ldap_search is: + + SearchResultEntry ::= [APPLICATION 4] SEQUENCE { + objectName LDAPDN, + attributes PartialSubjRightsAttributeList } + + PartialSubjRightsAttributeList ::= SEQUENCE OF SEQUENCE + { + rightFamily LDAPOID, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + subjectDnType LDAPOID, + subjectDN LDAPString, + rightsList ENUMERATED + } + + Although this extends the search operation, there are no + incompatibilities between versions. LDAPv2 cannot send a + control, hence the above structure cannot be returned to + a LDAPv2 client. A LDAPv3 client cannot send this + request to a LDAPv2 server. A LDAPv3 server not + supporting this control cannot return the additional + data. + + 7.2.3 Client-Server Interaction + + The listSubjectRightsRequest control specifies the rights + that MUST be returned for the scope of the search. The + server that consumes the search operation looks up the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 18] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + rights for the returned directory information and returns + the result as search information associated with the + scope of that search. + + There are six possible scenarios that may occur as a + result of the listSubjectRights control being included on + the search request: + + + 1. If the server does not support this control and the + client specified TRUE for the control's criticality + field, then the server MUST return + unavailableCriticalExtension as a return code in + the searchResponse message and not send back any + other results. This behavior is specified in + section 4.1.12 of [LDAPv3]. + + 2. If the server does not support this control and the + client specified FALSE for the control's + criticality field, then the server MUST ignore the + control and process the request as if it were not + present. This behavior is specified in section + 4.1.12 of [LDAPv3]. + + 3. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified TRUE for the + control's criticality field, then the server SHOULD + do the following: return + unavailableCriticalExtension as a return code in + the searchResult message and omit the + listSubjectRightsResponse control in the + searchResult message. + + 4. If the server supports this control but for some + reason such as cannot process specified + rightsFamily and the client specified FALSE for the + control's criticality field, then the server should + process as 'no rights returned for that family' and + include the result Unavailable in the + listSubjectRightsResponse control in the + searchResult message. + + 5. If the server supports this control and can return + the rights per the rightsFamily information, then + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 19] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + it should include the listSubjectRightsResponse + control in the searchResult message with a result + of success. + + 6. If the search request failed for any other reason, + then the server SHOULD omit the + listSubjectRightsResponse control from the + searchResult message. + + The client application is assured that the correct rights + are returned for the scope of the search operation if and + only if the listSubjectRightsResponse control returns the + rights. If the server omits the + listSubjectRightsResponse control from the searchResponse + message, the client SHOULD assume that the control was + ignored by the server. + + The listSubjectRightsResponse control, if included by the + server in the searchResponse message, should have the + searchResult set to either success if the rights were + returned or set to the appropriate error code as to why + the rights could not be returned. + + The server may not be able to return a right because it + may not exist in that directory object's attribute; in + this case, the rights request is ignored with success. + + 7.3 specifyCredentials Control + + + 7.3.1 Request Control + + This control is included in the ldap_bind message as + part of the controls field of the LDAPMessage, as + defined in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE) at the client's option. The + controlValue is an OCTET STRING, whose value is the BER + encoding of a value of the following SEQUENCE: + + specifyCredentialRequest ::= SEQUENCE { + credential LDAPString + } + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 20] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + } + + The credential specifies the credential (e.g. groups, + roles, etc) that the client is requesting be associated + with the bind DN for access control determination in + subsequent ldap operations. This provides a 'push' model + for credentials where the client attempts to 'push' the + credential to the server. The server may process at bind + time as follows: + + - server may unconditionally ignore + + - server may unconditionally accept + + - server may define trust model and evaluate of the + trust of each credential + + If this control is not used, it is assumed that the + server determines (pulls) the credentials associated with + the bind DN when needed in subsequent ldap operations to + provide access control. + + 7.3.2 Response Control + + This control is included in the ldap_search message as + part of the controls field of the LDAPMessage, as defined + in Section 4.1.12 of [LDAPv3]. + + The controlType is set to . The + criticality MAY be either TRUE or FALSE (where absent is + also equivalent to FALSE). The controlValue is an OCTET + STRING, whose value is the BER encoding of a value of the + following SEQUENCE: + + specifyCredentialsResponse ::= { + result ENUMERATED { + success (0), + operationsError (1), + unavailableCriticalExtension (12), + unavailable (52), + unwillingToPerform (53), + other (80) + } + } + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 21] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + No data is returned; just the result is returned. + + Although this extends the bind operation, there are no + incompatibilities between versions. LDAPv2 cannot send a + control. A LDAPv3 client cannot send this request to a + LDAPv2 server. A LDAPv3 server not supporting this + control cannot return the additional data. + + 7.3.3 Client-Server Interaction + + The specifyCredentialsRequest control specifies the + credentials that the client was the server to use for + access control in subsequent ldap operations. The server + that consumes the bind operation may unconditionally + accept, ignore, or evaluate the trust of the specified + credentials at bind time and returns only a success or + failure response (no data returned). + + There are six possible scenarios that may occur as a + result of the specifyCredential control being included on + the bind request: + + + 1. If the server does not support this control and the + client specified TRUE for the control's criticality + field, then the server MUST return + unavailableCriticalExtension as a return code in + the bindResponse message. This behavior is + specified in section 4.1.12 of [LDAPv3]. + + 2. If the server does not support this control and the + client specified FALSE for the control's + criticality field, then the server MUST ignore the + control and process the request as if it were not + present. This behavior is specified in section + 4.1.12 of [LDAPv3]. + + 3. If the server supports this control but for some + reason such as cannot process specified credential + (e.g. server decided to evaluate the trust of that + credential and the result is the server not + trusting all the credentials or unconditionally + ignores the credential) and the client specified + TRUE for the control's criticality field, then the + server SHOULD do the following: return + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 22] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + unavailableCriticalExtension as a return code in + the bindResult message and omit the + specifyCredentialResponse control in the bindResult + message. + + 4. If the server supports this control but for some + reason such as cannot process specified credential + (e.g. server decided to evaluate the trust of that + credential and the result is the server not + trusting all the credentials or unconditionally + ignores the credential) and the client specified + FALSE for the control's criticality field, then the + server should process as 'credential ignored' and + include the result Unavailable in the + specifyCredentialResponse control in the bindResult + message. + + 5. If the server supports this control and evaulates + the trust of that credential and the result is the + server trusting all the credentials, then it should + include the specifyCredentialResponse control in + the bindResult message with a result of success. + + 6. If the bind request failed for any other reason, + then the server SHOULD omit the + specifyCredentialResponse control from the + bindResult message. + + The client application is assured that the correct + credentials are used by the server when specified by the + client for subsequent ldap operations if and only if the + specifyCredentialResponse is successful. If the server + omits the specifyCredentialResponse control from the + searchResponse message, the client SHOULD assume that the + control was ignored by the server. + + The specifyCredentialResponse control, if included by the + server in the bindResponse message, should have the + bindResult set to either success if the credentials were + accepted by the server or set to the appropriate error + code as to why the credentials were not accepted. + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 23] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 8. Access Control Extended Operations + + Two extended operations (analogous to the controls) are + defined for transmission of access control information. + These operations help with the management of access + control information independent of manipulating other + directory information. The extended operations are: + + - LDAP Get Effective Rights to obtain the effective + rights for a given directory entry for a given + subject + + - LDAP List Subject Rights to get the access control + information for a given directory entry + + 8.1 LDAP Get Effective Rights Operation + + ldapGetEffectiveRightsRequest ::= [APPLICATION 23] + SEQUENCE { + requestName [0] , + requestValue [1] OCTET STRING OPTIONAL } + + where + + requestValue ::= SEQUENCE { + targetDN LDAPDN, + updates SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + subjectDN LDAPString, + } + } + + + The requestName is a dotted-decimal representation of the + OBJECT IDENTIFIER corresponding to the request. The + requestValue is information in a form defined by that + request, encapsulated inside an OCTET STRING. + + The server will respond to this with an LDAPMessage + containing the ExtendedResponse which is a rights list. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 24] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + ldpGetEffectiveRightsResponse ::= [APPLICATION 24] + SEQUENCE { + COMPONENTS OF LDAPResult, + responseName [10] OPTIONAL, + effectiveRights [11] OCTET STRING OPTIONAL } + + where + + effectiveRights ::= SEQUENCE OF SEQUENCE { + rightFamily LDAPOID, + rightsList ENUMERATED, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + subjectDnType LDAPOID, + subjectDN LDAPSTRING + } + + If the server does not recognize the request name, it + MUST return only the response fields from LDAPResult, + containing the protocolError result code. + + 8.2 LDAP List Subject Rights + + ldapListSubjectRightsRequest ::= [APPLICATION 23] + SEQUENCE { + requestName [0] , + requestValue [1] OCTET STRING } + + where + + requestValue ::= SEQUENCE { + targetDN LDAPDN, + updates SEQUENCE OF SEQUENCE { + rightsFamily LDAPOID | "*", + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + dnType LDAPOID | "*", + listSubjectDN LDAPString | "*", + } + } + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 25] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + The requestName is a dotted-decimal representation of the + OBJECT IDENTIFIER corresponding to the request. The + requestValue is information in a form defined by that + request, encapsulated inside an OCTET STRING. + + The server will respond to this with an LDAPMessage + containing the ExtendedResponse which is a result code. + + ldapListSubjectRightsResponse ::= [APPLICATION 24] + SEQUENCE { + COMPONENTS OF LDAPResult, + responseName [10] OPTIONAL, + subjectRightsList [11] OCTET STRING OPTIONAL } + + where + + subjectRightsList ::= SEQUENCE OF SEQUENCE { + rightFamily LDAPOID, + whichObject ENUMERATED { + LDAP_ENTRY (1), + LDAP_SUBTREE (2) + }, + subjectDnType LDAPOID, + subjectDN LDAPString, + perms SEQUENCE OF SEQUENCE { + rightsList ENUMERATED, + attrs LDAPSTRING + } + } + } + + If the server does not recognize the request name, it + MUST return only the response fields from LDAPResult, + containing the protocolError result code. + + + + 9. Operational Semantics of Access Control Operations + + The semantics of access control operations described in + this document are defined operationally in terms of + "histories". A history is a sequence of actions (x1, x2, + ..., xN). + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 26] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + We consider five types of actions: + + - LDAP Access Control Policy Update actions: + invocations of the LDAP Update Access Extended + Operation or LDAP Update Access Control. + + - LDAP Access Control Policy Query operations: + invocations of the LDAP Get Effective Access + Extended Operation, LDAP Get Effective Access + Control, LDAP List Subject Rights Extended + Operation, or LDAP List Subject Rights Control. + + - Datastore Access Control Policy Update Actions: any + operation implemented by the server which LDAP is + using as its datastore which changes the access + policy enforced with respect to attempts to access + LDAP directory entries and their attributes. + + - LDAP Access Request operations: invocations of LDAP + entry or attribute access operations (Read, Update, + Search, Compare, etc...). + + - Other operations: anything else, including Datastore + operations which do not change the access policy + enforced by the server. + + + The semantics of histories are defined as follows: + + - LDAP Update (Replace), LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation, and no rights not + granted by the Update operation. + + - LDAP Update (Grant), LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation. The Query may show + that the subject also has other rights not granted + by the Update operation, depending on the policy in + force before the Update operation. + + - LDAP Update (Deny), LDAP Query + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 27] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + The Query will show that the subject does not have + any right denied by the Update operation. The Query + may show that the subject has rights not denied by + the Update operation, depending on the policy in + force before the Update operation. + + - LDAP Update (Replace), LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request will fail with an access- + denied exception if it requires any right not + granted by the Update operation. + + - LDAP Update (Grant), LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request may succeed if it requires + rights not granted by the Update operation, + depending on the policy in force before the Update + operation. + + - LDAP Update (Deny), LDAP Access Request + + The Request will fail with an access-denied + exception if it requires any right denied to the + requesting subject by the Update operation. If the + Request requires only rights which were not denied + by the Update operation, it may succeed, depending + on the policy in force before the Update operation. + + - LDAP Update (Replace), Other, LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation, and no rights not + granted by the Update operation. + + - LDAP Update (Grant), Other, LDAP Query + + The Query will show that the subject has all rights + granted by the Update operation. The Query may show + that the subject also has other rights not granted + by the Update operation, depending on the policy in + force before the Update operation. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 28] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + - LDAP Update (Deny), Other, LDAP Query + + The Query will show that the subject does not have + any right denied by the Update operation. The Query + may show that the subject has rights not denied by + the Update operation, depending on the policy in + force before the Update operation. + + - LDAP Update (Replace), Other, LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request will fail with an access- + denied exception if it requires any right not + granted by the Update operation. + + - LDAP Update (Grant), Other, LDAP Access Request + + The Request will succeed if it requires only rights + granted to the requesting subject by the Update + operation. The Request may succeed if it requires + rights not granted by the Update operation, + depending on the policy in force before the Update + operation. + + - LDAP Update (Deny), Other, LDAP Access Request + + The Request will fail with an access-denied + exception if it requires any right denied to the + requesting subject by the Update operation. If the + Request requires only rights which were not denied + by the Update operation, it may succeed, depending + on the policy in force before the Update operation. + + - LDAP Update (Replace), Datastore Update, LDAP Query + + The result of the Query is not defined. + + - LDAP Update (Grant), Datastore Update, LDAP Query + + The result of the Query is not defined. + + - LDAP Update (Deny), Datastore Update, LDAP Query + + The result of the Query is not defined. + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 29] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + - LDAP Update (Replace), Datastore Update, LDAP Access + Request + + The result of the Access Request is not defined. + + - LDAP Update (Grant), Datastore Update, LDAP Access + Request + + The result of the Access Request is not defined. + + - LDAP Update (Deny), Datastore Update, LDAP Access + Request + + The result of the Access Request is not defined. + + + + 10. LDIF Syntax for Access Control Information + + + 10.1 LDIF Purpose + + The intent of the LDIF is to design a common interchange + format. Any given LDAP server should be able to translate + the below defined LDIF into a meaningful request. Each + server should be able to understand each part of the + LDIF; there should not be any ambiguity into what any + part of the syntax means. + + While the end goal is to have a common behavior model + between different LDAP server implementations, the LDIF + alone will not ensure identical ACL processing behavior + between servers. The semantics of how a server + interprets the aci syntax are not defined here. What + 'deny' means on server1 might be different than on + server2. + + The LDIF maintains an assumption that the receiving + server supports inheritance within the security model. If + the server does not support inheritance, the receiving + server must expand any inherited information based on the + scope flag. + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 30] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + 10.2 ACL Attributes + + There are three attributes which are allowed on all + directory objects: aci, vendorAci and policyOwner. The + syntax of these attributes is defined below. The aci, + vendorAci and policyOwner attribute are all multivalued. + In determining the order of the syntax, the DN was left + until the end for parsing reasons. Examples follow the + BNF + + + 10.2.1 VendorACI_ + + The Vendor specific ACI information is listed in its own + attribute. The assumption here is that if the vendor's + need to provide information in an additional attribute, + then the vendor specific information would not + necessarily be of the same syntax as the ACI attribute + which would have < acl syntax> . + + + 10.2.2 Policy Owner_ + + The intent behind policy ownership is that it controls + administrative subdomains. It can also control who has + permission to set / change acls for implementations that + do not have an acl controlling access to itself. If + there are multiple policy owners it is implementation + specific as to the behavior of whether policy owner #1 + can override policy owner # 2. + + The syntax for policyOwner includes the 'scope' flag. + Servers which do not support inheritance must expand the + policyOwner inheritance similar to the expansion of the + ACI. If the policy owner is not specified for any + object in the tree, behavior is implementation defined. + For instance, if no object anywhere in the tree has a + policy owner, then the server could simply assert that + the 'root DN' is considered the policy owner for all + objects. An alternate approach might be that the + implementation defines the entryDN to be the policy + owner. + + The policyOwner and ACI are left as distinct attributes + for several reasons. They syntax of the policy owner is + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 31] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + very similar to the syntax of the ACI. In parsing, it + would be difficult to tell when one stops and the other + begins (especially since there are no reserved characters + in LDAP Dns ). Additionally, the inheritance models of + the administrative subdomains may be different then the + models guiding the ACI inheritance. Since there is no + flag to tell if a given ACI is explicit vs inherited, + combining the two sets of information ties the + policyOwner inheritance to ACI inheritance. Additionally, + keeping the information separate makes it easier for the + applications to construct views of various models by only + requesting the information they need. + + + 10.2.3 ACI + + The aci attribute is defined using < acl syntax>. Within + the acl syntax, the family OID describes the permissions, + dnType, subhectDn and scope that will be found in the + following string. The permissions for the IETF family + are found below. The family OID is listed first in the + syntax to be consistent with other LDAP LDIF definitions + which list OIDs first. If the OID within the ACI + attribute is listed as other than the IETF family oid, + the syntax is the same as l isted below, but one or more + of the scope, dnType, subjectDn or permissions may vary + from the IETF defined syntax. + + Within the acl syntax, there is a string which describes + the rights. This is a composite of the permissions and + resources to which the user is being granted or denied + access. The set of permissions is fixed. Either of the + actions "grant" | "deny" may be used when creating or + updating an aci. + + Using the BNF defined below, it is possible for the + permission string to be empty. The aci + + aci: + 1.2.3.4#subtree#grant;;attribute1$grant;r,s;[all]#group#cn=Dept + XYZ, c=US + + mean that this group is granted permission to read and + search all attributes except attribute1. + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 32] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + Similarly, the aci + + aci: 1.2.3.4#subtree#group#cn=Dept XYZ, c=US simply + means that no permissions have been defined for this + group. It is up to the server implementation as to + whether the group does or does not receive permission to + attributes on an entry with an empty rights list. + + The attributeString is an attribute Name (defined to be a + printable string). If the string refers to an attribute + not defined in the given server's schema, the server + SHOULD report an error. Another option for the + attributeString is "[entry]". This is provided to + describe permissions which apply to an entire object. + This could mean actions such as delete the object, or add + a child object. The third option for attributeString is + "[all]" which means the permission set should apply to + all attributes. + + If the keyword "[all]" and another attribute are both + specified within an aci, the more specific permission set + for the attribute overrides the less specific permission + set for "[all]". If two acis contain identical + familyOID, scope, DnTypes and DNs, the permission given + DN is specified in two distinct acis on any given entry, + the rights lists can be combined into one list. For + example: + + aci: 1.2.3.4#subtree#group#grant;r,w;[all]#cn=Dept XYZ + aci: 1.2.3.4#subtree#group#grant;r;attribute1#cn=Dept + XYZ + + is the equivalent of + + aci: + 1.2.3.4#subtree#group#grant;r,w;[all];r,attribute1#cn=Dept + XYZ + + Multiple attributeStrings can be listed after any given + permission set; for instance, "r,w ; attribute1, + attribute2". This means that if the server supports a + attribute aggregation mechanism, attribute1 and + attribute2 should be considered to be part of the same + group. If the server does not support a grouping + mechanism, the permission set applies independently to + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 33] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + attribute1 and attribute2. For servers that do not + support attribute grouping, "r,w ; attribute1, + attribute2" results in the same operations as " r,w; + attribute1; r,w; attribute2 " + + Within the vendorACI, the oid determines the format or + the printable string to follow. + + + 10.3 Modifying the ACI Values + + The attribute: value pairs listed below would be possible + inputs for normal LDAP operations such as ldapadd and + ldapmodify. Within the ldapmodify command there are + three changetypes: add, delete, replace. + + Replace works similarly to all other attributes. If the + attribute value does not exist, create the value. If the + attribute does exist, replace the value. If the aci + value is replaced, all aci values are replaced. Given an + aci for an entry: + + aci: + 1.2.3.4#subtree#deny;r,w;[all];grant;rsc;attirbute2#group#cn=Dept + ABC + aci: + 1.2.3.4#subtree#grant;r,;[all];grant;rsc;attirbute1#group#cn=Dept + XYZ + + perform the following change: + + dn: cn=someEntry + changetype: replace + add: aci + aci: 1.2.3.4#subtree#grant;r,w;[all];#group#cn=Dept LMN + + The resulting acl is: + + aci: 1.2.3.4#subtree#grant;r,w;[all];#group#cn=Dept LMN + + (aci values for Dept XYZ and ABC are lost through the + replace) + + During an ldapmodify-add, if the aci does not exist, the + create the aci with the specific aci value(s). If the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 34] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + aci does exist, then add the specified values to the + given aci. For example a given aci: + + aci: 1.2.3.4#subtree#group#grant;r,w;[all]#cn=Dept XYZ + + with a modification: + dn: cn=someEntry + changetype: add + add: aci + aci: 1.2.3.4#subtree#group#grant;r;attribute1#cn=Dept + XYZ + + would yield an aci value of: + + aci: + 1.2.3.4#subtree#group#grant;r,w;[all];r,attribute1#cn=Dept + XYZ + + To delete an entire acl, use ldapmodify - delete without + specifying a value for the aci. The entry would then + inherit its aci from some other node in the tree + depending on the server inheritance model. + + dn: cn = some Entry + changetype: delete + delete: aci + + During an ldapmodify-delete, there are two possible + interpretations of the delete. + + dn: cn = some Entry + changetype: delete + delete: aci + aci: < > (see below) + + Interpretation 1. + + aci: 1.2.3.4#subtree#group#cn=Dept XYZ + would delete the entire aci for the group cn=Dept XYZ + + Interpretation 2. + + aci: + 1.2.3.4#subtree#grant;rsc;attribute1#group#cn=Dept XYZ + would delete the 'grant;rsc;attribute1' portion of the + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 35] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + aci + for the group cn=Dept XYZ + + before ldapmodify - delete: + aci: + 1.2.3.4#subtree#group#grant;r,w;[all];grant;rsc;attribute1#cn=Dept + XYZ + + after ldapmodify - delete of attribute1 + aci: 1.2.3.4#subtree#group#grant;r,w;[all];#cn=Dept + XYZ + + if the delete is for an attribute not existing within + the aci, nothing + is changed in the expected outcome. For example, if now + attribute2 + is deleted, + + aci: 1.2.3.4#subtree#grant;[attribute2]#group#cn=Dept + XYZ + + the resulting aci would still be + + aci: 1.2.3.4#subtree#group#grant;r,w;[all];#cn=Dept + XYZ + + + 10.4 BNF + + ::= + ::= + '#' + + + ::= + '#' + + '#' + + + '#' + + '#' + + + ::= + '#' + + '#' + + + '#' + + + ::= + ::= < oid > + + :: "entry" | "subtree" + + :: "access-id" | "role" | "group" + ::= [ ] | [ < right > + [ '$' + ] * ] + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 36] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + ::= + ';' + + + ';' + + + ::= "grant" | "deny" + + ::= [ ] | [ < permission > + + [ ',' + ] * ] + ::= [ + + [ ',' + ] * ] + + ::= "[all]" | "[entry]" | + + + : "a" | "d" | "r" | "s" | "w" | "c" + | "g" | "s" | "m" | "u" + These are the permissions defined for + the IETF family OID. + + + 10.5 Examples + + Suppose IETFFamilyOID = 1.2.3.4 + + The following two examples show an administrative + subdomain being established. The first example shows a + single user being assigned the policyOwner for the entire + domain. The second example shows a group of ids assigned + to the policy Owner. + + policyOwner: 1.2.3.4#subtree#access-id#cn=Hoyt + + policyOwner: 1.2.3.4#subtree#group#cn=System Owners, + o=Company + + The next example shows an aci attribute where a group + "cn=Dept XYZ, c=US" is being given permissions to read, + search and compare attribute1. The permission should + apply to the entire subtree below the node containing + this aci. + + aci: 1.2.3.4#subtree#group#grant;r,s,c;attribute1#cn=Dept + XYZ, c=US + + The next example shows an ACI attribute where a role + "cn=SysAdmins,o=Company" is being given permissions to + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 37] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + add objects below this node, and read, search and compare + attributes2 and 3. The permission should apply to the + entire subtree below the node containing this ACI. + + aci: + 1.2.3.4#subtree#role#grant;a;[entry]$grant;r,s,c;attribute2,attribute3#cn=SysAdmins,o=Company + + + + 11. Security Considerations + + This draft proposes protocol elements for transmission of + security policy information. Security considerations are + discussed throughout this draft. Because subject + security attribute information is used to evaluate + decision requests, it is security-sensitive information + and must be protected against unauthorized modification + whenever it is stored or transmitted. + + + + 12. References + + [LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight + Directory Access Protocol (v3)", RFC 2251, December 1997. + + [ECMA] ECMA, "Security in Open Systems: A Security + Framework" ECMA TR/46, July 1988 + + [REQTS] Stokes, Byrne, Blakley, "Access Control + Requirements for LDAP, INTERNET-DRAFT , August 1998. + + [ATTR] M.Wahl, A, Coulbeck, T. Howes, S. Kille, + "Lightweight Directory Access Protocol (v3)": Attribute + Syntax Definitions, RFC 2252, December 1997. + + [UTF] M. Wahl, S. Kille, "Lightweight Directory Access + Protocol (v3)": A UTF-8 String Representation of + Distinguished Names", RFC 2253, December 1997. + + [Bradner97] Bradner, Scott, "Key Words for use in RFCs to + Indicate Requirement Levels", RFC 2119. + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 38] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + AUTHOR(S) ADDRESS + + Ellen Stokes Bob Blakley + IBM Dascom + 11400 Burnet Rd + Austin, TX 78758 Austin, TX + USA USA + mail-to: stokes@austin.ibm.com mail-to: blakley@dascom.com + phone: +1 512 838 3725 + fax: +1 512 838 8597 + + + Debbie Byrne + IBM + 11400 Burnet Rd + Austin, TX 78758 + USA + mail-to: djbyrne@us.ibm.com + phone: +1 512 838 1960 + fax: +1 512 838 0156 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 39] + + + + + + Internet-Draft Access Control Model 15 April 1999 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stokes, Byrne, Blakley Expires 15 October 1999 [Page 40] + + + + + + + + + + CONTENTS + + + 1. Introduction....................................... 2 + + 2. Overview........................................... 2 + + 3. Terminology........................................ 3 + + 4. The Model.......................................... 6 + 4.1 Access Control Activity Lifecycle............ 6 + 4.2 Access Control Information Model............. 6 + 4.3 Bind and Credentials......................... 8 + + 5. Access Control Information Schema.................. 8 + 5.1 Attributes................................... 8 + 5.1.1 Root DSE Attribute for Access + Control Mechanism 8 + 5.1.2 Subschema Attribute for Access + Control Mechanism 9 + 5.2 Other Defined Parameters/OIDs................ 9 + 5.2.1 Rights Families and Rights 9 + 5.2.2 DN Types 10 + + 6. Access Control Parameters for LDAP Controls & + Extended Operations................................ 10 + + 7. Access Control Information (ACI) Controls.......... 12 + 7.1 getEffectiveRights Control................... 13 + 7.1.1 Request Control 13 + 7.1.2 Response Control 13 + 7.1.3 Client-Server Interaction 15 + 7.2 listSubjectRights Control.................... 16 + 7.2.1 Request Control 16 + 7.2.2 Response Control 17 + 7.2.3 Client-Server Interaction 18 + 7.3 specifyCredentials Control................... 20 + 7.3.1 Request Control 20 + 7.3.2 Response Control 21 + 7.3.3 Client-Server Interaction 22 + + 8. Access Control Extended Operations................. 24 + 8.1 LDAP Get Effective Rights Operation.......... 24 + 8.2 LDAP List Subject Rights..................... 25 + + + + + - i - + + + + + + + + + + + + 9. Operational Semantics of Access Control + Operations......................................... 26 + + 10. LDIF Syntax for Access Control Information......... 30 + 10.1 LDIF Purpose................................. 30 + 10.2 ACL Attributes............................... 31 + 10.2.1 VendorACI 31 + 10.2.2 Policy Owner 31 + 10.2.3 ACI 32 + 10.3 Modifying the ACI Values..................... 34 + 10.4 BNF.......................................... 36 + 10.5 Examples..................................... 37 + + 11. Security Considerations............................ 38 + + 12. References......................................... 38 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - ii - + + + + diff --git a/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt b/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt new file mode 100644 index 0000000000..0ed82cf4b1 --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt @@ -0,0 +1,4315 @@ + + + + + + +Network Working Group M. Smith, Editor +INTERNET-DRAFT Netscape Communications Corp. +Intended Category: Standards Track T. Howes +Obsoletes: RFC 1823 Netscape Communications Corp. +Expires: 23 August 1999 A. Herron + Microsoft Corp. + M. Wahl + Innosoft International, Inc. + A. Anantha + Microsoft Corp. + + + 23 February 1999 + + The C LDAP Application Program Interface + + + +1. 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 docu- +ments 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." + +The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt. + +The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html. + +This draft document will be submitted to the RFC Editor as a Standards +Track document. Distribution of this memo is unlimited. Technical dis- +cussion of this document will take place on the IETF LDAP Extension +Working Group mailing list . Please send +editorial comments directly to the authors. + +Copyright (C) The Internet Society (1997-1999). All Rights Reserved. + +Please see the Copyright section near the end of this document for more +information. + + + + +Expires: 23 August 1999 [Page 1] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +2. Introduction + +This document defines a C language application program interface (API) +to the Lightweight Directory Access Protocol (LDAP). This document +replaces the previous definition of this API, defined in RFC 1823, +updating it to include support for features found in version 3 of the +LDAP protocol. New extended operation functions were added to support +LDAPv3 features such as controls. In addition, other LDAP API changes +were made to support information hiding and thread safety. + +The C LDAP API is designed to be powerful, yet simple to use. It defines +compatible synchronous and asynchronous interfaces to LDAP to suit a +wide variety of applications. This document gives a brief overview of +the LDAP model, then an overview of how the API is used by an applica- +tion program to obtain LDAP information. The API calls are described in +detail, followed by appendices that provide example code demonstrating +use of the API, the namespace consumed by the API, a summary of require- +ments for API extensions, known incompatibilities with RFC 1823, and a +list of changes made since the last revision of this document. + + +3. Table of Contents + +1. Status of this Memo............................................1 +2. Introduction...................................................2 +3. Table of Contents..............................................2 +4. Overview of the LDAP Model.....................................4 +5. Overview of LDAP API Use.......................................4 +6. Header File Requirements.......................................6 +7. Common Data Structures.........................................7 +8. Retrieving Information About the API Implementation............8 +8.1. Retrieving Information at Compile Time......................8 +8.2. Retrieving Information During Execution.....................10 +9. LDAP Error Codes...............................................13 +10. Performing LDAP Operations.....................................14 +10.1. Initializing an LDAP Session................................14 +10.2. LDAP Session Handle Options.................................15 +10.3. Working With Controls.......................................21 +10.3.1. A Client Control That Governs Referral Processing........22 +10.4. Authenticating to the directory.............................22 +10.5. Closing the session.........................................25 +10.6. Searching...................................................26 +10.7. Reading an Entry............................................30 +10.8. Listing the Children of an Entry............................30 +10.9. Comparing a Value Against an Entry..........................30 +10.10. Modifying an entry..........................................32 +10.11. Modifying the Name of an Entry..............................34 +10.12. Adding an entry.............................................36 + + + +Expires: 23 August 1999 [Page 2] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +10.13. Deleting an entry...........................................38 +10.14. Extended Operations.........................................40 +11. Abandoning An Operation........................................41 +12. Obtaining Results and Peeking Inside LDAP Messages.............42 +13. Handling Errors and Parsing Results............................44 +14. Stepping Through a List of Results.............................47 +15. Parsing Search Results.........................................48 +15.1. Stepping Through a List of Entries or References............48 +15.2. Stepping Through the Attributes of an Entry.................49 +15.3. Retrieving the Values of an Attribute.......................50 +15.4. Retrieving the name of an entry.............................51 +15.5. Retrieving controls from an entry...........................52 +15.6. Parsing References..........................................53 +16. Encoded ASN.1 Value Manipulation...............................54 +16.1. General.....................................................54 +16.2. Encoding....................................................55 +16.3. Encoding Example............................................58 +16.4. Decoding....................................................59 +16.5. Decoding Example............................................61 +17. Security Considerations........................................64 +18. Acknowledgements...............................................64 +19. Copyright......................................................64 +20. Bibliography...................................................65 +21. Authors' Addresses.............................................66 +22. Appendix A - Sample C LDAP API Code............................67 +23. Appendix B - Namespace Consumed By This Specification..........68 +24. Appendix C - Summary of Requirements for API Extensions........69 +24.1. Compatibility...............................................69 +24.2. Style.......................................................69 +24.3. Dependence on Externally Defined Types......................69 +24.4. Compile Time Information....................................69 +24.5. Runtime Information.........................................70 +24.6. Values Used for Session Handle Options......................70 +25. Appendix D - Known Incompatibilities with RFC 1823.............70 +25.1. Opaque LDAP Structure.......................................70 +25.2. Additional Error Codes......................................70 +25.3. Freeing of String Data with ldap_memfree()..................71 +25.4. Changes to ldap_result()....................................71 +25.5. Changes to ldap_first_attribute() and ldap_next_attribute...71 +25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......71 +25.7. API Specification Clarified.................................72 +25.8. Deprecated Functions........................................72 +26. Appendix E - Changes Made Since Last Document Revision.........72 +26.1. API Changes.................................................73 +26.2. Editorial changes...........................................74 + + + + + + +Expires: 23 August 1999 [Page 3] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +4. Overview of the LDAP Model + +LDAP is the lightweight directory access protocol, described in [2] and +[6]. It can provide a lightweight frontend to the X.500 directory [1], +or a stand-alone service. In either mode, LDAP is based on a client- +server model in which a client makes a TCP connection to an LDAP server, +over which it sends requests and receives responses. + +The LDAP information model is based on the entry, which contains infor- +mation about some object (e.g., a person). Entries are composed of +attributes, which have a type and one or more values. Each attribute has +a syntax that determines what kinds of values are allowed in the attri- +bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those +values behave during directory operations (e.g., is case significant +during comparisons). + +Entries may be organized in a tree structure, usually based on politi- +cal, geographical, and organizational boundaries. Each entry is uniquely +named relative to its sibling entries by its relative distinguished name +(RDN) consisting of one or more distinguished attribute values from the +entry. At most one value from each attribute may be used in the RDN. +For example, the entry for the person Babs Jensen might be named with +the "Barbara Jensen" value from the commonName attribute. + +A globally unique name for an entry, called a distinguished name or DN, +is constructed by concatenating the sequence of RDNs from the entry up +to the root of the tree. For example, if Babs worked for the University +of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, +o=University of Michigan, c=US". The DN format used by LDAP is defined +in [4]. + +Operations are provided to authenticate, search for and retrieve infor- +mation, modify information, and add and delete entries from the tree. +The next sections give an overview of how the API is used and detailed +descriptions of the LDAP API calls that implement all of these func- +tions. + + +5. Overview of LDAP API Use + +An application generally uses the C LDAP API in four simple steps. + + 1. Initialize an LDAP session with a primary LDAP server. The + ldap_init() function returns a handle to the session, allowing + multiple connections to be open at once. + + 2. Authenticate to the LDAP server. The ldap_sasl_bind() function + and friends support a variety of authentication methods. + + + +Expires: 23 August 1999 [Page 4] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + 3. Perform some LDAP operations and obtain some results. + ldap_search() and friends return results which can be parsed by + ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc. + + 4. Close the session. The ldap_unbind() function closes the connec- + tion. + +Operations can be performed either synchronously or asynchronously. The +names of the synchronous functions end in _s. For example, a synchronous +search can be completed by calling ldap_search_s(). An asynchronous +search can be initiated by calling ldap_search(). All synchronous rou- +tines return an indication of the outcome of the operation (e.g, the +constant LDAP_SUCCESS or some other error code). The asynchronous rou- +tines make available to the caller the message id of the operation ini- +tiated. This id can be used in subsequent calls to ldap_result() to +obtain the result(s) of the operation. An asynchronous operation can be +abandoned by calling ldap_abandon() or ldap_abandon_ext(). + +Results and errors are returned in an opaque structure called LDAPMes- +sage. Routines are provided to parse this structure, step through +entries and attributes returned, etc. Routines are also provided to +interpret errors. Later sections of this document describe these rou- +tines in more detail. + +LDAP version 3 servers may return referrals and references to other +servers. By default, implementations of this API will attempt to follow +referrals automatically for the application. This behavior can be dis- +abled globally (using the ldap_set_option() call) or on a per-request +basis through the use of a client control. + +All DN and string attribute values passed into or produced by this C +LDAP API are represented using the character set of the underlying LDAP +protocol version in use. When this API is used with LDAPv3, DN and +string values are represented as UTF-8[10] characters. When this API is +used with LDAPv2, the US-ASCII[12] or T.61[12] character set are used. +Future documents may specific additional APIs supporting other character +sets. + +For compatibility with existing applications, implementations of this +API will by default use version 2 of the LDAP protocol. Applications +that intend to take advantage of LDAP version 3 features will need to +use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to +switch to version 3. + +Note that this API is designed for use in environments where the 'int' +type is at least 32 bits in size. + + + + + +Expires: 23 August 1999 [Page 5] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +6. Header File Requirements + +To promote portability of applications, implementations of this C LDAP +API must conform to the following requirements of the header files used +by applications to access the services of this API: + +Name and Inclusion + Applications are only required to include a single header file + named ldap.h to access all of the API services described in this + document. Therefore, the following C source program must com- + pile without errors: + + #include + + int + main() + { + return 0; + } + + Note that it is permissible for the ldap.h header file to + include other implementation-specific header files. + +Implementations SHOULD also provide a header file named lber.h to faci- +late development of applications desiring compatibility with older LDAP +implementations. The lber.h header file may be empty. + + +Idempotence + All header files should be idempotent; that is, if they are + included more than once the effect is as if they had only been + included once. + +Must Be Included Before API Is Used + An application must include the ldap.h header file before + referencing any of the function or type definitions described in + this API specification. + +Mutual Independence + If possible, header files should be mutually independent with + minimal dependence on system or any other header files. + +Use of the 'const' Keyword + This API specification is defined in terms of ISO C[13]. It + makes use of function prototypes and the 'const' keyword. The + use of 'const' in this specification is limited to simple, non- + array function parameters to avoid forcing applications to + declare parameters and variables that accept return values from + + + +Expires: 23 August 1999 [Page 6] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP API functions as 'const.' Implementations specifically + designed to be used with non-ISO C translators may provide func- + tion declarations without prototypes or function prototypes + without specification of 'const' arguments. + +Definition of 'struct timeval' + This API specification uses the 'struct timeval' type. Imple- + mentations of this API should ensure that the struct timeval + type is by default defined as a consequence of including the + ldap.h header file. Because struct timeval is usually defined + in one or more system header files, it is possible for header + file conflicts to occur if ldap.h also defines it or arranges + for it to be defined by including another header file. There- + fore, applications may want to arrange for struct timeval to be + defined before they include ldap.h. To support this, the ldap.h + header file must not itself define struct timeval if the prepro- + cessor symbol LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h + is included. + + +7. Common Data Structures + +Some data structures that are common to several LDAP API functions are +defined here: + + typedef struct ldap LDAP; + + typedef struct ldapmsg LDAPMessage; + + typedef struct berelement BerElement; + + struct berval { + unsigned long bv_len; + char *bv_val; + }; + + struct timeval { + long tv_sec; + long tv_usec; + }; + +The LDAP structure is an opaque data type that represents an LDAP ses- +sion Typically this corresponds to a connection to a single server, but +it may encompass several server connections in the face of LDAPv3 refer- +rals. + +The LDAPMessage structure is an opaque data type that is used to return +entry, reference, result, and error information. An LDAPMessage + + + +Expires: 23 August 1999 [Page 7] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +structure may represent the beginning of a list, or chain of messages +that consists of a series of entries, references, and result messages as +returned by LDAP operations such as search. LDAP API functions such as +ldap_parse_result() that operate on message chains that may contain more +than one result message always operate on the first result message in +the chain. See the "Obtaining Results and Peeking Inside LDAP Messages" +section of this document for more information. + +The BerElement structure is an opaque data type that is used to hold +data and state information about encoded data. It is described in more +detail in the section "Encoded ASN.1 Value Manipulation" later in this +document. + +The berval structure is used to represent arbitrary binary data and its +fields have the following meanings: + +bv_len Length of data in bytes. + +bv_val A pointer to the data itself. + + +The timeval structure is used to represent an interval of time and its +fields have the following meanings: + +tv_sec Seconds component of time interval. + +tv_usec Microseconds component of time interval. + +See the earlier section "Header File Requirements" for more information +on struct timeval. + + +8. Retrieving Information About the API Implementation + +Applications developed to this specification need to be able to deter- +mine information about the particular API implementation they are using +both at compile time and during execution. + + +8.1. Retrieving Information at Compile Time + +All conformant implementations MUST include the following five defini- +tions in a header file so compile time tests can be done by LDAP +software developers: + + #define LDAP_API_VERSION level + #define LDAP_VERSION_MIN min-version + #define LDAP_VERSION_MAX max-version + + + +Expires: 23 August 1999 [Page 8] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + #define LDAP_VENDOR_NAME "vend-name" + #define LDAP_VENDOR_VERSION vend-version + +where: + + "level" is replaced with the RFC number given to this C LDAP API + specification when it is published as a standards track RFC. + + min-version is replaced with the lowest LDAP protocol version sup- + ported by the implementation. + + max-version is replaced with the highest LDAP protocol version sup- + ported by the implementation. This should be 3. + + "vend-name" is replaced with a text string that identifies the + party that supplies the API implementation. + + "vend-version" is a supplier-specific version number multiplied + times 100. + +Note that the LDAP_VENDOR_NAME macro may be defined as "" if no vendor +name is available and the LDAP_VENDOR_VERSION macro may be defined as 0 +if no vendor-specific version information is available. + +For example, if this specification is published as RFC 88888, Netscape +Communication's version 4.0 implementation that supports LDAPv2 and v3 +might include macro definitions like these: + + #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */ + #define LDAP_VERSION_MIN 2 + #define LDAP_VERSION_MAX 3 + #define LDAP_VENDOR_NAME "Netscape Communications Corp." + #define LDAP_VENDOR_VERSION 400 /* version 4.0 */ + +and application code can test the C LDAP API version level using a +construct such as this one: + + #if (LDAP_API_VERSION >= 88888) + /* use features supported in RFC 88888 or later */ + #endif + +Until such time as this document is published as an RFC, implementations +should use the value 2000 plus the revision number of this draft for +LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION +for revision 03 of this draft is 2003. + +Documents that extend this specification SHOULD define a macro of the +form: + + + +Expires: 23 August 1999 [Page 9] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + #define LDAP_API_FEATURE_x level + +where "x" is replaced with a name (textual identifier) for the feature +and "level" is replaced with the number of the RFC that specifies the +API extension. The name SHOULD NOT begin with the string "X_". + +For example, if C LDAP API extensions for Transport Layer Security [9] +were published in RFC 99999, that RFC might require conformant implemen- +tations to define a macro like this: + + #define LDAP_API_FEATURE_TLS 99999 + + +Private or experimental API extensions may be indicated by defining a +macro of this same form where "x" (the extension's name) begins with the +string "X_" and "level" is replaced with a integer number that is +specific to the extension. + + +8.2. Retrieving Information During Execution + +The ldap_get_option() call (described in greater detail later in this +document) can be used during execution in conjunction with an option +parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic +information about the API and about the specific implementation being +used. The ld parameter to ldap_get_option() can be either NULL or a +valid LDAP session handle which was obtained by calling ldap_init(). +The optdata parameter to ldap_get_option() MUST be the address of an +LDAPAPIInfo structure which is defined as follows: + + typedef struct ldapapiinfo { + int ldapai_info_version; /* version of this struct (1) */ + int ldapai_api_version; /* revision of API supported */ + int ldapai_protocol_version; /* highest LDAP version supported */ + char **ldapai_extensions; /* names of API extensions */ + char *ldapai_vendor_name; /* name of supplier */ + int ldapai_vendor_version; /* supplier-specific version times 100 */ + } LDAPAPIInfo; + +In addition, API implementations MUST include the following macro defin- +ition: + + #define LDAP_API_INFO_VERSION 1 + +Note that the ldapai_info_version field of the LDAPAPIInfo structure +should be set to the value LDAP_API_INFO_VERSION (1) before calling +ldap_get_option() so that it can be checked for consistency. All other +fields are set by the ldap_get_option() function. + + + +Expires: 23 August 1999 [Page 10] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +The members of the LDAPAPIInfo structure are: + +ldapai_info_version + A number that identifies the version of the LDAPAPIInfo struc- + ture. This should be set to the value LDAP_API_INFO_VERSION + (1) before calling ldap_get_option(). If the value received + is not recognized by the API implementation, the + ldap_get_option() function sets ldapai_info_version to a valid + value that would be recognized, sets the ldapai_api_version to + the correct value, and returns an error without filling in any + of the other fields in the LDAPAPIInfo structure. + +ldapai_api_version + A number that matches that assigned to the C LDAP API RFC sup- + ported by the API implementation. This should match the value + of the LDAP_API_VERSION macro defined earlier. + +ldapai_protocol_version + The highest LDAP protocol version supported by the implementa- + tion. For example, if LDAPv3 is the highest version supported + then this field will be set to 3. + +ldapai_extensions + A NULL-terminated array of character strings that lists the + names of the API extensions supported by the LDAP API imple- + mentation. These names will typically match the textual iden- + tifiers that appear in the "x" portion of the + LDAP_API_FEATURE_x macros described above, although the pre- + cise value MUST be defined by documents that specify C LDAP + API extensions. If no API extensions are supported, this + field will be set to NULL. The caller is responsible for + disposing of the memory occupied by this array by passing it + to ldap_value_free() which is described later in this docu- + ment. To retrieve more information about a particular exten- + sion, the ldap_get_option() call can be used with an option + parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt- + data parameter to the ldap_get_option() MUST be the address of + an LDAPAPIFeatureInfo structure which is defined as follows: + + typedef struct ldap_apifeature_info { + int ldapaif_info_version; /* version of this struct (1) */ + char *ldapaif_name; /* name of supported feature */ + int ldapaif_version; /* revision of supported feature */ + } LDAPAPIFeatureInfo; + + In addition, API implementations MUST include the following + macro definition: + + + + +Expires: 23 August 1999 [Page 11] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + #define LDAP_FEATURE_INFO_VERSION 1 + + Note that the ldapaif_info_version field of the LDAPAPI- + FeatureInfo structure should be set to the value + LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field + should be set to the extension name string as described below + before ldap_get_option() is called. The call will fill in the + ldapaif_version field of the LDAPAPIFeatureInfo structure. + + The members of the LDAPAPIFeatureInfo structure are: + + ldapaif_info_version + A number that identifies the version of the LDAPAPI- + FeatureInfo structure. This should be set to the value + LDAP_FEATURE_INFO_VERSION (1) before calling + ldap_get_option(). If the value received is not recognized + by the API implementation, the ldap_get_option() function + sets ldapaif_info_version to a valid value that would be + recognized and returns an error without filling in the + ldapaif_version field in the LDAPAPIFeatureInfo structure. + + ldapaif_name + The name of an extension, as returned in the + ldapai_extensions array of the LDAPAPIInfo structure and as + specified in the document that describes the extension. + + ldapaif_version + This field will be set as a result of calling + ldap_get_option(). It is a number that matches that + assigned to the C LDAP API extension RFC supported for this + extension. For private or experimental API extensions, the + value is extension-specific. In either case, the value of + ldapaxi_ext_version should be identical to the value of the + LDAP_API_FEATURE_x macro defined for the extension + (described above). + +ldapai_vendor_name + A zero-terminated string that contains the name of the party + that produced the LDAP API implementation. This field may be + set to NULL if no name is available. If non-NULL, the caller + is responsible for disposing of the memory occupied by passing + this pointer to ldap_memfree() which is described later in + this document. This value SHOULD match the value of the + LDAP_VENDOR_NAME macro described earlier in this document. + +ldapai_vendor_version + An implementation-specific version number multiplied by 100. + For example, if the implementation version is 4.0 then this + + + +Expires: 23 August 1999 [Page 12] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + field will be set to 400. If no version information is avail- + able, this field will be set to 0. This value SHOULD match + the value of the LDAP_VENDOR_VERSION macro described earlier + in this document. + + +9. LDAP Error Codes + +Many of the LDAP API routines return LDAP error codes, some of which +indicate local errors and some of which may be returned by servers. All +of the LDAP error codes returned will be positive integers. Supported +error codes are (hexadecimal values are given in parentheses after the +constant): + + LDAP_SUCCESS (0x00) + LDAP_OPERATIONS_ERROR (0x01) + LDAP_PROTOCOL_ERROR (0x02) + LDAP_TIMELIMIT_EXCEEDED (0x03) + LDAP_SIZELIMIT_EXCEEDED (0x04) + LDAP_COMPARE_FALSE (0x05) + LDAP_COMPARE_TRUE (0x06) + LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) + LDAP_STRONG_AUTH_REQUIRED (0x08) + LDAP_REFERRAL (0x0a) -- new in LDAPv3 + LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 + LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 + LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 + LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3 + LDAP_NO_SUCH_ATTRIBUTE (0x10) + LDAP_UNDEFINED_TYPE (0x11) + LDAP_INAPPROPRIATE_MATCHING (0x12) + LDAP_CONSTRAINT_VIOLATION (0x13) + LDAP_TYPE_OR_VALUE_EXISTS (0x14) + LDAP_INVALID_SYNTAX (0x15) + LDAP_NO_SUCH_OBJECT (0x20) + LDAP_ALIAS_PROBLEM (0x21) + LDAP_INVALID_DN_SYNTAX (0x22) + LDAP_IS_LEAF (0x23) -- not used in LDAPv3 + LDAP_ALIAS_DEREF_PROBLEM (0x24) + LDAP_INAPPROPRIATE_AUTH (0x30) + LDAP_INVALID_CREDENTIALS (0x31) + LDAP_INSUFFICIENT_ACCESS (0x32) + LDAP_BUSY (0x33) + LDAP_UNAVAILABLE (0x34) + LDAP_UNWILLING_TO_PERFORM (0x35) + LDAP_LOOP_DETECT (0x36) + LDAP_NAMING_VIOLATION (0x40) + LDAP_OBJECT_CLASS_VIOLATION (0x41) + + + +Expires: 23 August 1999 [Page 13] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) + LDAP_NOT_ALLOWED_ON_RDN (0x43) + LDAP_ALREADY_EXISTS (0x44) + LDAP_NO_OBJECT_CLASS_MODS (0x45) + LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP + LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 + LDAP_OTHER (0x50) + LDAP_SERVER_DOWN (0x51) + LDAP_LOCAL_ERROR (0x52) + LDAP_ENCODING_ERROR (0x53) + LDAP_DECODING_ERROR (0x54) + LDAP_TIMEOUT (0x55) + LDAP_AUTH_UNKNOWN (0x56) + LDAP_FILTER_ERROR (0x57) + LDAP_USER_CANCELLED (0x58) + LDAP_PARAM_ERROR (0x59) + LDAP_NO_MEMORY (0x5a) + LDAP_CONNECT_ERROR (0x5b) + LDAP_NOT_SUPPORTED (0x5c) + LDAP_CONTROL_NOT_FOUND (0x5d) + LDAP_NO_RESULTS_RETURNED (0x5e) + LDAP_MORE_RESULTS_TO_RETURN (0x5f) + LDAP_CLIENT_LOOP (0x60) + LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) + + +10. Performing LDAP Operations + +This section describes each LDAP operation API call in detail. All func- +tions take a "session handle," a pointer to an LDAP structure containing +per-connection information. Many routines return results in an LDAPMes- +sage structure. These structures and others are described as needed +below. + + +10.1. Initializing an LDAP Session + +ldap_init() initializes a session with an LDAP server. The server is not +actually contacted until an operation is performed that requires it, +allowing various options to be set after initialization. + + LDAP *ldap_init( + const char *hostname, + int portno + ); + +Use of the following routine is deprecated: + + + + +Expires: 23 August 1999 [Page 14] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ldap_open( + const char *hostname, + int portno + ); +Unlike ldap_init(), ldap_open() attempts to make a server connection +before returning to the caller. + +Parameters are: + +hostname Contains a space-separated list of hostnames or dotted strings + representing the IP address of hosts running an LDAP server to + connect to. Each hostname in the list can include an optional + port number which is separated from the host itself with a + colon (:) character. The hosts will be tried in the order + listed, stopping with the first one to which a successful con- + nection is made. + + Note: A suitable representation for including a literal IPv6[11] + address in the hostname parameter is desired, but has not yet been + determined or implemented in practice. + +portno Contains the TCP port number to connect to. The default LDAP + port of 389 can be obtained by supplying the constant + LDAP_PORT. If a host includes a port number then this parame- + ter is ignored. + +ldap_init() and ldap_open() both return a "session handle," a pointer to +an opaque structure that should be passed to subsequent calls pertaining +to the session. These routines return NULL if the session cannot be ini- +tialized in which case the operating system error reporting mechanism +can be checked to see why the call failed. + +Note that if you connect to an LDAPv2 server, one of the LDAP bind calls +described below must be completed before other operations can be per- +formed on the session. LDAPv3 does not require that a bind operation be +completed before other operations can be performed. + +The calling program can set various attributes of the session by calling +the routines described in the next section. + + +10.2. LDAP Session Handle Options + +The LDAP session handle returned by ldap_init() is a pointer to an +opaque data type representing an LDAP session. In RFC 1823 this data +type was a structure exposed to the caller, and various fields in the +structure could be set to control aspects of the session, such as size +and time limits on searches. + + + +Expires: 23 August 1999 [Page 15] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +In the interest of insulating callers from inevitable changes to this +structure, these aspects of the session are now accessed through a pair +of accessor functions, described below. + +ldap_get_option() is used to access the current value of various +session-wide parameters. ldap_set_option() is used to set the value of +these parameters. Note that some options are READ-ONLY and cannot be +set; it is an error to call ldap_set_option() and attempt to set a +READ-ONLY option. + +Note that if automatic referral following is enabled (the default), any +connections created during the course of following referrals will +inherit the options associated with the session that sent the original +request that caused the referrals to be returned. + + int ldap_get_option( + LDAP *ld, + int option, + void *outvalue + ); + + int ldap_set_option( + LDAP *ld, + int option, + const void *invalue + ); + + #define LDAP_OPT_ON ((void *)1) + #define LDAP_OPT_OFF ((void *)0) + + +Parameters are: + +ld The session handle. If this is NULL, a set of global defaults is + accessed. New LDAP session handles created with ldap_init() or + ldap_open() inherit their characteristics from these global + defaults. + +option The name of the option being accessed or set. This parameter + should be one of the following constants, which have the indi- + cated meanings. After the constant the actual hexadecimal value + of the constant is listed in parentheses. + + + LDAP_OPT_API_INFO (0x00) + Type for invalue parameter: not applicable (option is READ-ONLY) + + Type for outvalue parameter: LDAPAPIInfo * + + + +Expires: 23 August 1999 [Page 16] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + Description: + Used to retrieve some basic information about the LDAP API + implementation at execution time. See the section "Retriev- + ing Information About the API Implementation" above for more + information. This option is READ-ONLY and cannot be set. + + LDAP_OPT_DESC (0x01) + Type for invalue parameter: not applicable (option is READ- + ONLY) + + Type for outvalue parameter: int * + + Description: + The underlying socket descriptor corresponding to the pri- + mary LDAP connection. This option is READ-ONLY and cannot + be set. + + LDAP_OPT_DEREF (0x02) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + Determines how aliases are handled during search. It can + have one of the following values: LDAP_DEREF_NEVER (0x00), + LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or + LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value + means aliases should be dereferenced during the search but + not when locating the base object of the search. The + LDAP_DEREF_FINDING value means aliases should be derefer- + enced when locating the base object but not during the + search. + + LDAP_OPT_SIZELIMIT (0x03) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + A limit on the number of entries to return from a search. + A value of LDAP_NO_LIMIT (0) means no limit. + + LDAP_OPT_TIMELIMIT (0x04) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + + + +Expires: 23 August 1999 [Page 17] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + A limit on the number of seconds to spend on a search. A + value of LDAP_NO_LIMIT (0) means no limit. This value is + passed to the server in the search request only; it does + not affect how long the C LDAP API implementation itself + will wait locally for search results. The timeout parame- + ter passed to ldap_search_ext_s() or ldap_result() -- both + of which are described later in this document -- can be + used to specify both a local and server side time limit. + + LDAP_OPT_REFERRALS (0x08) + Type for invalue parameter: void * (LDAP_OPT_ON or + LDAP_OPT_OFF) + + Type for outvalue parameter: int * + + Description: + Determines whether the LDAP library automatically follows + referrals returned by LDAP servers or not. It can be set + to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any + non-NULL pointer value passed to ldap_set_option() enables + this option. When reading the current setting using + ldap_get_option(), a zero value means off and any non-zero + value means on. + + LDAP_OPT_RESTART (0x09) + Type for invalue parameter: void * (LDAP_OPT_ON or + LDAP_OPT_OFF) + + Type for outvalue parameter: int * + + Description: + Determines whether LDAP I/O operations should automati- + cally be restarted if they abort prematurely. It should be + set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; + any non-NULL pointer value passed to ldap_set_option() + enables this option. When reading the current setting + using ldap_get_option(), a zero value means off and any + non-zero value means on. This option is useful if an LDAP + I/O operation may be interrupted prematurely, for example + by a timer going off, or other interrupt. + + LDAP_OPT_PROTOCOL_VERSION (0x11) + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + This option indicates the version of the LDAP protocol + + + +Expires: 23 August 1999 [Page 18] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + used when communicating with the primary LDAP server. It + must be one of the constants LDAP_VERSION2 (2) or + LDAP_VERSION3 (3). If no version is set the default is + LDAP_VERSION2 (2). + + LDAP_OPT_SERVER_CONTROLS (0x12) + Type for invalue parameter: LDAPControl ** + + Type for outvalue parameter: LDAPControl *** + + Description: + A default list of LDAP server controls to be sent with + each request. See the Working With Controls section + below. + + LDAP_OPT_CLIENT_CONTROLS (0x13) + Type for invalue parameter: LDAPControl ** + + Type for outvalue parameter: LDAPControl *** + + Description: + A default list of client controls that affect the LDAP + session. See the Working With Controls section below. + + LDAP_OPT_API_FEATURE_INFO (0x15) + Type for invalue parameter: not applicable (option is READ- + ONLY) + + Type for outvalue parameter: LDAPAPIFeatureInfo * + + Description: + Used to retrieve version information about LDAP API + extended features at execution time. See the section + "Retrieving Information About the API Implementation" + above for more information. This option is READ-ONLY and + cannot be set. + + LDAP_OPT_HOST_NAME (0x30) + Type for invalue parameter: char * + + Type for outvalue parameter: char ** + + Description: + The host name (or list of hosts) for the primary LDAP + server. See the definition of the hostname parameter to + ldap_init() for the allowed syntax. + + LDAP_OPT_ERROR_NUMBER (0x31) + + + +Expires: 23 August 1999 [Page 19] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + Type for invalue parameter: int * + + Type for outvalue parameter: int * + + Description: + The code of the most recent LDAP error that occurred for + this session. + + LDAP_OPT_ERROR_STRING (0x32) + Type for invalue parameter: char * + + Type for outvalue parameter: char ** + + Description: + The message returned with the most recent LDAP error that + occurred for this session. + + + outvalue The address of a place to put the value of the option. The + actual type of this parameter depends on the setting of the + option parameter. For outvalues of type char ** and LDAP- + Control **, a copy of the data that is associated with the + LDAP session ld is returned; callers should dispose of the + memory by calling ldap_memfree() or ldap_controls_free(). + + invalue A pointer to the value the option is to be given. The actual + type of this parameter depends on the setting of the option + parameter. The data associated with invalue is copied by the + API implementation to allow callers of the API to dispose of + or otherwise change their copy of the data after a success- + ful call to ldap_set_option(). If a value passed for + invalue is invalid or cannot be accepted by the implementa- + tion, ldap_set_option() should return -1 to indicate an + error. + +Both ldap_get_option() and ldap_set_option() return 0 if successful and +-1 if an error occurs. + +Standards track documents that extend this specification and specify new +options MUST use values for option macros that are between 0x1000 and +0x3FFF inclusive. Private and experimental extensions MUST use values +for the option macros that are between 0x4000 and 0x7FFF inclusive. All +values below 0x1000 and above 0x7FFF that are not defined in this docu- +ment are reserved and MUST NOT be used. + + + + + + + +Expires: 23 August 1999 [Page 20] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +10.3. Working With Controls + +LDAPv3 operations can be extended through the use of controls. Controls +may be sent to a server or returned to the client with any LDAP message. +These controls are referred to as server controls. + +The LDAP API also supports a client-side extension mechanism through the +use of client controls. These controls affect the behavior of the LDAP +API only and are never sent to a server. A common data structure is +used to represent both types of controls: + + typedef struct ldapcontrol { + char *ldctl_oid; + struct berval ldctl_value; + char ldctl_iscritical; + } LDAPControl, *PLDAPControl; + +The fields in the ldapcontrol structure have the following meanings: + +ldctl_oid The control type, represented as a string. + +ldctl_value The data associated with the control (if any). To + specify a zero-length value, set ldctl_value.bv_len to + zero and ldctl_value.bv_val to a zero-length string. + To indicate that no data is associated with the con- + trol, set ldctl_value.bv_val to NULL. + +ldctl_iscritical Indicates whether the control is critical of not. If + this field is non-zero, the operation will only be car- + ried out if the control is recognized by the server + and/or client. Note that the LDAP unbind and abandon + operations have no server response, so clients SHOULD + NOT mark server controls critical when used with these + two operations. + +Some LDAP API calls allocate an ldapcontrol structure or a NULL- +terminated array of ldapcontrol structures. The following routines can +be used to dispose of a single control or an array of controls: + + void ldap_control_free( LDAPControl *ctrl ); + void ldap_controls_free( LDAPControl **ctrls ); + +A set of controls that affect the entire session can be set using the +ldap_set_option() function (see above). A list of controls can also be +passed directly to some LDAP API calls such as ldap_search_ext(), in +which case any controls set for the session through the use of +ldap_set_option() are ignored. Control lists are represented as a NULL- +terminated array of pointers to ldapcontrol structures. + + + +Expires: 23 August 1999 [Page 21] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Server controls are defined by LDAPv3 protocol extension documents; for +example, a control has been proposed to support server-side sorting of +search results [7]. + +One client control is defined in this document (described in the follow- +ing section). Other client controls may be defined in future revisions +of this document or in documents that extend this API. + + +10.3.1. A Client Control That Governs Referral Processing + +As described previously in the section "LDAP Session Handle Options," +applications can enable and disable automatic chasing of referrals on a +session-wide basic by using the ldap_set_option() function with the +LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer- +ral chasing on per-request basis. A client control with an OID of +1.2.840.113556.1.4.616 exists to provide this functionality. + + /* OID for referrals client control */ + #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" + + /* Flags for referrals client control value */ + #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020 + #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040 + +To create a referrals client control, the ldctl_oid field of an LDAPCon- +trol structure should be set to LDAP_CONTROL_REFERRALS +("1.2.840.113556.1.4.616") and the ldctl_value field should be set to a +4-octet value that contains a set of flags. The ldctl_value.bv_len +field should always be set to 4. The ldctl_value.bv_val field should +point to a 4-octet integer flags value. This flags value can be set to +zero to disable automatic chasing of referrals and LDAPv3 references +altogether. Alternatively, the flags value can be set to the value +LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020) to indicate that only +LDAPv3 search continuation references should be automatically chased by +the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS +(0x00000040) to indicate that only LDAPv3 referrals should be automati- +cally chased, or the logical OR of the two flag values (0x00000060) to +indicate that both referrals and references should be automatically +chased. + + +10.4. Authenticating to the directory + +The following functions are used to authenticate an LDAP client to an +LDAP directory server. + +The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do + + + +Expires: 23 August 1999 [Page 22] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +general and extensible authentication over LDAP through the use of the +Simple Authentication Security Layer [8]. The routines both take the dn +to bind as, the method to use, as a dotted-string representation of an +OID identifying the method, and a struct berval holding the credentials. +The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to +request simple authentication, or the simplified routines +ldap_simple_bind() or ldap_simple_bind_s() can be used. + + int ldap_sasl_bind( + LDAP *ld, + const char *dn, + const char *mechanism, + const struct berval *cred, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_sasl_bind_s( + LDAP *ld, + const char *dn, + const char *mechanism, + const struct berval *cred, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + struct berval **servercredp + ); + + int ldap_simple_bind( + LDAP *ld, + const char *dn, + const char *passwd + ); + + int ldap_simple_bind_s( + LDAP *ld, + const char *dn, + const char *passwd + ); + + The use of the following routines is deprecated: + + int ldap_bind( LDAP *ld, const char *dn, const char *cred, + int method ); + + int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, + int method ); + + + + +Expires: 23 August 1999 [Page 23] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + int ldap_kerberos_bind( LDAP *ld, const char *dn ); + + int ldap_kerberos_bind_s( LDAP *ld, const char *dn ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to bind as. + +mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica- + tion, or a text string identifying the SASL method. + +cred The credentials with which to authenticate. Arbitrary + credentials can be passed using this parameter. The format + and content of the credentials depends on the setting of + the mechanism parameter. + +passwd For ldap_simple_bind(), the password to compare to the + entry's userPassword attribute. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_sasl_bind() call succeeds. + +servercredp This result parameter will be filled in with the creden- + tials passed back by the server for mutual authentication, + if given. An allocated berval structure is returned that + should be disposed of by calling ber_bvfree(). NULL may be + passed to ignore this field. + +Additional parameters for the deprecated routines are not described. +Interested readers are referred to RFC 1823. + +The ldap_sasl_bind() function initiates an asynchronous bind operation +and returns the constant LDAP_SUCCESS if the request was successfully +sent, or another LDAP error code if not. See the section below on error +handling for more information about possible errors and how to interpret +them. If successful, ldap_sasl_bind() places the message id of the +request in *msgidp. A subsequent call to ldap_result(), described below, +can be used to obtain the result of the bind. + +The ldap_simple_bind() function initiates a simple asynchronous bind +operation and returns the message id of the operation initiated. A sub- +sequent call to ldap_result(), described below, can be used to obtain + + + +Expires: 23 August 1999 [Page 24] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +the result of the bind. In case of error, ldap_simple_bind() will return +-1, setting the session error parameters in the LDAP structure appropri- +ately. + +The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions +both return the result of the operation, either the constant +LDAP_SUCCESS if the operation was successful, or another LDAP error code +if it was not. See the section below on error handling for more informa- +tion about possible errors and how to interpret them. + +Note that if an LDAPv2 server is contacted, no other operations over the +connection should be attempted before a bind call has successfully com- +pleted. + +Subsequent bind calls can be used to re-authenticate over the same con- +nection, and multistep SASL sequences can be accomplished through a +sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). + + +10.5. Closing the session + +The following functions are used to unbind from the directory, close +open connections, and dispose of the session handle. + + int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, + LDAPControl **clientctrls ); + + int ldap_unbind( LDAP *ld ); + + int ldap_unbind_s( LDAP *ld ); + +Parameters are: + +ld The session handle. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn- +chronously in the sense that they send an unbind request to the server, +close all open connections associated with the LDAP session handle, and +dispose of all resources associated with the session handle before +returning. Note, however, that there is no server response to an LDAP +unbind operation. All three of the unbind functions return LDAP_SUCCESS +(or another LDAP error code if the request cannot be sent to the LDAP +server). After a call to one of the unbind functions, the session han- +dle ld is invalid and it is illegal to make any further LDAP API calls + + + +Expires: 23 August 1999 [Page 25] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +using ld. + +The ldap_unbind() and ldap_unbind_s() functions behave identically. The +ldap_unbind_ext() function allows server and client controls to be +included explicitly, but note that since there is no server response to +an unbind request there is no way to receive a response to a server con- +trol sent with an unbind request. + + + +10.6. Searching + +The following functions are used to search the LDAP directory, returning +a requested set of attributes for each entry matched. There are five +variations. + + int ldap_search_ext( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + struct timeval *timeout, + int sizelimit, + int *msgidp + ); + + int ldap_search_ext_s( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + struct timeval *timeout, + int sizelimit, + LDAPMessage **res + ); + + int ldap_search( + LDAP *ld, + const char *base, + int scope, + + + +Expires: 23 August 1999 [Page 26] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + const char *filter, + char **attrs, + int attrsonly + ); + + int ldap_search_s( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + LDAPMessage **res + ); + + int ldap_search_st( + LDAP *ld, + const char *base, + int scope, + const char *filter, + char **attrs, + int attrsonly, + struct timeval *timeout, + LDAPMessage **res + ); + +Parameters are: + +ld The session handle. + +base The dn of the entry at which to start the search. + +scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), + or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the + search. + +filter A character string as described in [3], representing the + search filter. The value NULL can be passed to indicate + that the filter "(objectclass=*)" which matches all entries + should be used. Note that if the caller of the API is + using LDAPv2, only a subset of the filter functionality + described in [3] can be successfully used. + +attrs A NULL-terminated array of strings indicating which attri- + butes to return for each matching entry. Passing NULL for + this parameter causes all available user attributes to be + retrieved. The special constant string LDAP_NO_ATTRS + ("1.1") can be used as the only string in the array to + + + +Expires: 23 August 1999 [Page 27] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + indicate that no attribute types should be returned by the + server. The special constant string LDAP_ALL_USER_ATTRS + ("*") can be used in the attrs array along with the names + of some operational attributes to indicate that all user + attributes plus the listed operational attributes should be + returned. + +attrsonly A boolean value that should be zero if both attribute types + and values are to be returned, non-zero if only types are + wanted. + +timeout For the ldap_search_st() function, this specifies the local + search timeout value (if it is NULL, the timeout is infin- + ite). For the ldap_search_ext() and ldap_search_ext_s() + functions, this specifies both the local search timeout + value and the operation time limit that is sent to the + server within the search request. For the + ldap_search_ext() and ldap_search_ext_s() functions, pass- + ing a NULL value for timeout causes the global default + timeout stored in the LDAP session handle (set by using + ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter) to + be sent to the server with the request but an infinite + local search timeout to be used. + +sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls, + this is a limit on the number of entries to return from the + search. A value of LDAP_NO_LIMIT (0) means no limit. + +res For the synchronous calls, this is a result parameter which + will contain the results of the search upon completion of + the call. If no results are returned, *res is set to NULL. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_search_ext() call succeeds. + +There are three options in the session handle ld which potentially +affect how the search is performed. They are: + +LDAP_OPT_SIZELIMIT + A limit on the number of entries to return from the search. + A value of LDAP_NO_LIMIT (0) means no limit. Note that the + value from the session handle is ignored when using the + ldap_search_ext() or ldap_search_ext_s() functions. + + + + +Expires: 23 August 1999 [Page 28] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +LDAP_OPT_TIMELIMIT + A limit on the number of seconds to spend on the search. A + value of LDAP_NO_LIMIT (0) means no limit. Note that the + value from the session handle is ignored when using the + ldap_search_ext() or ldap_search_ext_s() functions. + +LDAP_OPT_DEREF + One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING + (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS + (0x03), specifying how aliases should be handled during the + search. The LDAP_DEREF_SEARCHING value means aliases should + be dereferenced during the search but not when locating the + base object of the search. The LDAP_DEREF_FINDING value + means aliases should be dereferenced when locating the base + object but not during the search. + +The ldap_search_ext() function initiates an asynchronous search opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_search_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the results from the search. These results +can be parsed using the result parsing routines described in detail +later. + +Similar to ldap_search_ext(), the ldap_search() function initiates an +asynchronous search operation and returns the message id of the opera- +tion initiated. As for ldap_search_ext(), a subsequent call to +ldap_result(), described below, can be used to obtain the result of the +bind. In case of error, ldap_search() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_search_ext_s(), ldap_search_s(), and +ldap_search_st() functions all return the result of the operation, +either the constant LDAP_SUCCESS if the operation was successful, or +another LDAP error code if it was not. See the section below on error +handling for more information about possible errors and how to interpret +them. Entries returned from the search (if any) are contained in the +res parameter. This parameter is opaque to the caller. Entries, attri- +butes, values, etc., should be extracted by calling the parsing routines +described below. The results contained in res should be freed when no +longer in use by calling ldap_msgfree(), described later. + +The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 +server controls, client controls, and allow varying size and time limits +to be easily specified for each search operation. The ldap_search_st() +function is identical to ldap_search_s() except that it takes an + + + +Expires: 23 August 1999 [Page 29] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +additional parameter specifying a local timeout for the search. The +local search timeout is used to limit the amount of time the API imple- +mentation will wait for a search to complete. After the local search +timeout expires, the API implementation will send an abandon operation +to abort the search operation. + +10.7. Reading an Entry + +LDAP does not support a read operation directly. Instead, this operation +is emulated by a search with base set to the DN of the entry to read, +scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or +NULL. attrs contains the list of attributes to return. + + +10.8. Listing the Children of an Entry + +LDAP does not support a list operation directly. Instead, this operation +is emulated by a search with base set to the DN of the entry to list, +scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or +NULL. attrs contains the list of attributes to return for each child +entry. + +10.9. Comparing a Value Against an Entry + +The following routines are used to compare a given attribute value +assertion against an LDAP entry. There are four variations: + + int ldap_compare_ext( + LDAP *ld, + const char *dn, + const char *attr, + struct berval *bvalue + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_compare_ext_s( + LDAP *ld, + const char *dn, + const char *attr, + struct berval *bvalue, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_compare( + LDAP *ld, + + + +Expires: 23 August 1999 [Page 30] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + const char *dn, + const char *attr, + const char *value + ); + + int ldap_compare_s( + LDAP *ld, + const char *dn, + const char *attr, + const char *value + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to compare against. + +attr The attribute to compare against. + +bvalue The attribute value to compare against those found in the + given entry. This parameter is used in the extended rou- + tines and is a pointer to a struct berval so it is possible + to compare binary values. + +value A string attribute value to compare against, used by the + ldap_compare() and ldap_compare_s() functions. Use + ldap_compare_ext() or ldap_compare_ext_s() if you need to + compare binary values. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_compare_ext() call succeeds. + +The ldap_compare_ext() function initiates an asynchronous compare opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_compare_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the result of the compare. + +Similar to ldap_compare_ext(), the ldap_compare() function initiates an +asynchronous compare operation and returns the message id of the opera- +tion initiated. As for ldap_compare_ext(), a subsequent call to + + + +Expires: 23 August 1999 [Page 31] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +ldap_result(), described below, can be used to obtain the result of the +bind. In case of error, ldap_compare() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both +return the result of the operation, either the constant LDAP_SUCCESS if +the operation was successful, or another LDAP error code if it was not. +See the section below on error handling for more information about pos- +sible errors and how to interpret them. + +The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 +server controls and client controls. + + +10.10. Modifying an entry + +The following routines are used to modify an existing LDAP entry. There +are four variations: + + typedef struct ldapmod { + int mod_op; + char *mod_type; + union { + char **modv_strvals; + struct berval **modv_bvals; + } mod_vals; + } LDAPMod; + #define mod_values mod_vals.modv_strvals + #define mod_bvalues mod_vals.modv_bvals + + int ldap_modify_ext( + LDAP *ld, + const char *dn, + LDAPMod **mods, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_modify_ext_s( + LDAP *ld, + const char *dn, + LDAPMod **mods, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_modify( + + + +Expires: 23 August 1999 [Page 32] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ld, + const char *dn, + LDAPMod **mods + ); + + int ldap_modify_s( + LDAP *ld, + const char *dn, + LDAPMod **mods + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to modify. + +mods A NULL-terminated array of modifications to make to the + entry. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_modify_ext() call succeeds. + +The fields in the LDAPMod structure have the following meanings: + +mod_op The modification operation to perform. It should be one of + LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or + LDAP_MOD_REPLACE (0x02). This field also indicates the + type of values included in the mod_vals union. It is logi- + cally ORed with LDAP_MOD_BVALUES (0x80) to select the + mod_bvalues form. Otherwise, the mod_values form is used. + +mod_type The type of the attribute to modify. + +mod_vals The values (if any) to add, delete, or replace. Only one of + the mod_values or mod_bvalues variants should be used, + selected by ORing the mod_op field with the constant + LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of + zero-terminated strings and mod_bvalues is a NULL- + terminated array of berval structures that can be used to + pass binary values such as images. + +For LDAP_MOD_ADD modifications, the given values are added to the +entry, creating the attribute if necessary. + + + +Expires: 23 August 1999 [Page 33] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +For LDAP_MOD_DELETE modifications, the given values are deleted from the +entry, removing the attribute if no values remain. If the entire attri- +bute is to be deleted, the mod_vals field should be set to NULL. + +For LDAP_MOD_REPLACE modifications, the attribute will have the listed +values after the modification, having been created if necessary, or +removed if the mod_vals field is NULL. All modifications are performed +in the order in which they are listed. + +The ldap_modify_ext() function initiates an asynchronous modify opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_modify_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the result of the modify. + +Similar to ldap_modify_ext(), the ldap_modify() function initiates an +asynchronous modify operation and returns the message id of the opera- +tion initiated. As for ldap_modify_ext(), a subsequent call to +ldap_result(), described below, can be used to obtain the result of the +modify. In case of error, ldap_modify() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both +return the result of the operation, either the constant LDAP_SUCCESS if +the operation was successful, or another LDAP error code if it was not. +See the section below on error handling for more information about pos- +sible errors and how to interpret them. + +The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 +server controls and client controls. + + +10.11. Modifying the Name of an Entry + +In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and +ldap_modrdn2_s() routines were used to change the name of an LDAP entry. +They could only be used to change the least significant component of a +name (the RDN or relative distinguished name). LDAPv3 provides the +Modify DN protocol operation that allows more general name change +access. The ldap_rename() and ldap_rename_s() routines are used to +change the name of an entry, and the use of the ldap_modrdn(), +ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre- +cated. + + int ldap_rename( + LDAP *ld, + + + +Expires: 23 August 1999 [Page 34] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + const char *dn, + const char *newrdn, + const char *newparent, + int deleteoldrdn, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + + ); + int ldap_rename_s( + LDAP *ld, + const char *dn, + const char *newrdn, + const char *newparent, + int deleteoldrdn, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + Use of the following routines is deprecated. + + int ldap_modrdn( + LDAP *ld, + const char *dn, + const char *newrdn + ); + int ldap_modrdn_s( + LDAP *ld, + const char *dn, + const char *newrdn + ); + int ldap_modrdn2( + LDAP *ld, + const char *dn, + const char *newrdn, + int deleteoldrdn + ); + int ldap_modrdn2_s( + LDAP *ld, + const char *dn, + const char *newrdn, + int deleteoldrdn + ); + +Parameters are: + +ld The session handle. + + + + +Expires: 23 August 1999 [Page 35] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +dn The name of the entry whose DN is to be changed. + +newrdn The new RDN to give the entry. + +newparent The new parent, or superior entry. If this parameter is + NULL, only the RDN of the entry is changed. The root DN + may be specified by passing a zero length string, "". The + newparent parameter should always be NULL when using ver- + sion 2 of the LDAP protocol; otherwise the server's + behavior is undefined. + +deleteoldrdn This parameter only has meaning on the rename routines if + newrdn is different than the old RDN. It is a boolean + value, if non-zero indicating that the old RDN value(s) + should be removed, if zero indicating that the old RDN + value(s) should be retained as non-distinguished values of + the entry. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_rename() call succeeds. + +The ldap_rename() function initiates an asynchronous modify DN operation +and returns the constant LDAP_SUCCESS if the request was successfully +sent, or another LDAP error code if not. See the section below on error +handling for more information about possible errors and how to interpret +them. If successful, ldap_rename() places the DN message id of the +request in *msgidp. A subsequent call to ldap_result(), described below, +can be used to obtain the result of the rename. + +The synchronous ldap_rename_s() returns the result of the operation, +either the constant LDAP_SUCCESS if the operation was successful, or +another LDAP error code if it was not. See the section below on error +handling for more information about possible errors and how to interpret +them. + +The ldap_rename() and ldap_rename_s() functions both support LDAPv3 +server controls and client controls. + + +10.12. Adding an entry + +The following functions are used to add entries to the LDAP directory. +There are four variations: + + + + +Expires: 23 August 1999 [Page 36] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + int ldap_add_ext( + LDAP *ld, + const char *dn, + LDAPMod **attrs, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_add_ext_s( + LDAP *ld, + const char *dn, + LDAPMod **attrs, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_add( + LDAP *ld, + const char *dn, + LDAPMod **attrs + ); + + int ldap_add_s( + LDAP *ld, + const char *dn, + LDAPMod **attrs + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to add. + +attrs The entry's attributes, specified using the LDAPMod struc- + ture defined for ldap_modify(). The mod_type and mod_vals + fields should be filled in. The mod_op field is ignored + unless ORed with the constant LDAP_MOD_BVALUES, used to + select the mod_bvalues case of the mod_vals union. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_add_ext() call succeeds. + + + + +Expires: 23 August 1999 [Page 37] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Note that the parent of the entry being added must already exist or the +parent must be empty (i.e., equal to the root DN) for an add to succeed. + +The ldap_add_ext() function initiates an asynchronous add operation and +returns the constant LDAP_SUCCESS if the request was successfully sent, +or another LDAP error code if not. See the section below on error han- +dling for more information about possible errors and how to interpret +them. If successful, ldap_add_ext() places the message id of the +request in *msgidp. A subsequent call to ldap_result(), described below, +can be used to obtain the result of the add. + +Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- +chronous add operation and returns the message id of the operation ini- +tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), +described below, can be used to obtain the result of the add. In case of +error, ldap_add() will return -1, setting the session error parameters +in the LDAP structure appropriately. + +The synchronous ldap_add_ext_s() and ldap_add_s() functions both return +the result of the operation, either the constant LDAP_SUCCESS if the +operation was successful, or another LDAP error code if it was not. See +the section below on error handling for more information about possible +errors and how to interpret them. + +The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server +controls and client controls. + + + +10.13. Deleting an entry + +The following functions are used to delete a leaf entry from the LDAP +directory. There are four variations: + + int ldap_delete_ext( + LDAP *ld, + const char *dn, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_delete_ext_s( + LDAP *ld, + const char *dn, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + + +Expires: 23 August 1999 [Page 38] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + + int ldap_delete( + LDAP *ld, + const char *dn + ); + + int ldap_delete_s( + LDAP *ld, + const char *dn + ); + +Parameters are: + +ld The session handle. + +dn The name of the entry to delete. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_delete_ext() call succeeds. + +Note that the entry to delete must be a leaf entry (i.e., it must have +no children). Deletion of entire subtrees in a single operation is not +supported by LDAP. + +The ldap_delete_ext() function initiates an asynchronous delete opera- +tion and returns the constant LDAP_SUCCESS if the request was success- +fully sent, or another LDAP error code if not. See the section below on +error handling for more information about possible errors and how to +interpret them. If successful, ldap_delete_ext() places the message id +of the request in *msgidp. A subsequent call to ldap_result(), described +below, can be used to obtain the result of the delete. + +Similar to ldap_delete_ext(), the ldap_delete() function initiates an +asynchronous delete operation and returns the message id of the opera- +tion initiated. As for ldap_delete_ext(), a subsequent call to +ldap_result(), described below, can be used to obtain the result of the +delete. In case of error, ldap_delete() will return -1, setting the ses- +sion error parameters in the LDAP structure appropriately. + +The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both +return the result of the operation, either the constant LDAP_SUCCESS if +the operation was successful, or another LDAP error code if it was not. +See the section below on error handling for more information about pos- +sible errors and how to interpret them. + + + +Expires: 23 August 1999 [Page 39] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 +server controls and client controls. + + +10.14. Extended Operations + +The ldap_extended_operation() and ldap_extended_operation_s() routines +allow extended LDAP operations to be passed to the server, providing a +general protocol extensibility mechanism. + + int ldap_extended_operation( + LDAP *ld, + const char *exoid, + struct berval *exdata, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + int *msgidp + ); + + int ldap_extended_operation_s( + LDAP *ld, + const char *exoid, + struct berval *exdata, + LDAPControl **serverctrls, + LDAPControl **clientctrls, + char **retoidp, + struct berval **retdatap + ); + +Parameters are: + +ld The session handle. + +requestoid The dotted-OID text string naming the request. + +requestdata The arbitrary data required by the operation (if NULL, no + data is sent to the server). + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +msgidp This result parameter will be set to the message id of the + request if the ldap_extended_operation() call succeeds. + +retoidp Pointer to a character string that will be set to an allo- + cated, dotted-OID text string returned by the server. This + string should be disposed of using the ldap_memfree() + + + +Expires: 23 August 1999 [Page 40] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + function. If no OID was returned, *retoidp is set to NULL. + +retdatap Pointer to a berval structure pointer that will be set an + allocated copy of the data returned by the server. This + struct berval should be disposed of using ber_bvfree(). If + no data is returned, *retdatap is set to NULL. + +The ldap_extended_operation() function initiates an asynchronous +extended operation and returns the constant LDAP_SUCCESS if the request +was successfully sent, or another LDAP error code if not. See the sec- +tion below on error handling for more information about possible errors +and how to interpret them. If successful, ldap_extended_operation() +places the message id of the request in *msgidp. A subsequent call to +ldap_result(), described below, can be used to obtain the result of the +extended operation which can be passed to ldap_parse_extended_result() +to obtain the OID and data contained in the response. + +The synchronous ldap_extended_operation_s() function returns the result +of the operation, either the constant LDAP_SUCCESS if the operation was +successful, or another LDAP error code if it was not. See the section +below on error handling for more information about possible errors and +how to interpret them. The retoid and retdata parameters are filled in +with the OID and data from the response. If no OID or data was +returned, these parameters are set to NULL. + +The ldap_extended_operation() and ldap_extended_operation_s() functions +both support LDAPv3 server controls and client controls. + + +11. Abandoning An Operation + +The following calls are used to abandon an operation in progress: + + int ldap_abandon_ext( + LDAP *ld, + int msgid, + LDAPControl **serverctrls, + LDAPControl **clientctrls + ); + + int ldap_abandon( + LDAP *ld, + int msgid + ); + + +ld The session handle. + + + + +Expires: 23 August 1999 [Page 41] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +msgid The message id of the request to be abandoned. + +serverctrls List of LDAP server controls. + +clientctrls List of client controls. + +ldap_abandon_ext() abandons the operation with message id msgid and +returns the constant LDAP_SUCCESS if the abandon was successful or +another LDAP error code if not. See the section below on error handling +for more information about possible errors and how to interpret them. + +ldap_abandon() is identical to ldap_abandon_ext() except that it does +not accept client or server controls and it returns zero if the abandon +was successful, -1 otherwise. + +After a successful call to ldap_abandon() or ldap_abandon_ext(), results +with the given message id are never returned from a subsequent call to +ldap_result(). There is no server response to LDAP abandon operations. + + +12. Obtaining Results and Peeking Inside LDAP Messages + +ldap_result() is used to obtain the result of a previous asynchronously +initiated operation. Note that depending on how it is called, +ldap_result() may actually return a list or "chain" of result messages. +The ldap_result() function only returns messages for a single request, +so for all LDAP operations other than search only one result message is +expected; that is, the only time the "result chain" may contain more +than one message is if results from a search operation are returned. +Once a chain of messages has been returned to the caller, it is no +longer tied in any caller-visible way to the LDAP request that produced +it. Therefore, a chain of messages returned by calling ldap_result() or +by calling a synchronous search routine will never be affected by subse- +quent LDAP API calls (except for ldap_msgfree() which is used to dispose +of a chain of messages). + +ldap_msgfree() frees the result messages (possibly an entire chain of +messages) obtained from a previous call to ldap_result() or from a call +to a synchronous search routine. + +ldap_msgtype() returns the type of an LDAP message. ldap_msgid() +returns the message ID of an LDAP message. + + int ldap_result( + LDAP *ld, + int msgid, + int all, + struct timeval *timeout, + + + +Expires: 23 August 1999 [Page 42] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAPMessage **res + ); + + int ldap_msgfree( LDAPMessage *res ); + + int ldap_msgtype( LDAPMessage *res ); + + int ldap_msgid( LDAPMessage *res ); + +Parameters are: + +ld The session handle. + +msgid The message id of the operation whose results are to be + returned, or the constant LDAP_RES_ANY (-1) if any result is + desired. + +all Specifies how many messages will be retrieved in a single call + to ldap_result(). This parameter only has meaning for search + results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one + message at a time. Pass LDAP_MSG_ALL (0x01) to request that + all results of a search be received before returning all + results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to + indicate that all messages retrieved so far should be returned + in the result chain. + +timeout A timeout specifying how long to wait for results to be + returned. A NULL value causes ldap_result() to block until + results are available. A timeout value of zero seconds speci- + fies a polling behavior. + +res For ldap_result(), a result parameter that will contain the + result(s) of the operation. If no results are returned, *res is + set to NULL. For ldap_msgfree(), the result chain to be freed, + obtained from a previous call to ldap_result(), + ldap_search_s(), or ldap_search_st(). If res is NULL, nothing + is done and ldap_msgfree() returns zero. + +Upon successful completion, ldap_result() returns the type of the first +result returned in the res parameter. This will be one of the following +constants. + + LDAP_RES_BIND (0x61) + LDAP_RES_SEARCH_ENTRY (0x64) + LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 + LDAP_RES_SEARCH_RESULT (0x65) + LDAP_RES_MODIFY (0x67) + LDAP_RES_ADD (0x69) + + + +Expires: 23 August 1999 [Page 43] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP_RES_DELETE (0x6B) + LDAP_RES_MODDN (0x6D) + LDAP_RES_COMPARE (0x6F) + LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 + +ldap_result() returns 0 if the timeout expired and -1 if an error +occurs, in which case the error parameters of the LDAP session handle +will be set accordingly. + +ldap_msgfree() frees the result structure pointed to by res and returns +the type of the message it freed. If res is NULL, nothing is done and +the value zero is returned. + +ldap_msgtype() returns the type of the LDAP message it is passed as a +parameter. The type will be one of the types listed above, or -1 on +error. + +ldap_msgid() returns the message ID associated with the LDAP message +passed as a parameter. + + +13. Handling Errors and Parsing Results + +The following calls are used to extract information from results and +handle errors returned by other LDAP API routines. Note that +ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ- +ically be used in addition to ldap_parse_result() to retrieve all the +result information from SASL Bind and Extended Operations respectively. + + int ldap_parse_result( + LDAP *ld, + LDAPMessage *res, + int *errcodep, + char **matcheddnp, + char **errmsgp, + char ***referralsp, + LDAPControl ***serverctrlsp, + int freeit + ); + + int ldap_parse_sasl_bind_result( + LDAP *ld, + LDAPMessage *res, + struct berval **servercredp, + int freeit + ); + + int ldap_parse_extended_result( + + + +Expires: 23 August 1999 [Page 44] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ld, + LDAPMessage *res, + char **retoidp, + struct berval **retdatap, + int freeit + ); + + char *ldap_err2string( int err ); + + The use of the following routines is deprecated. + + int ldap_result2error( + LDAP *ld, + LDAPMessage *res, + int freeit + ); + + void ldap_perror( LDAP *ld, const char *msg ); + +Parameters are: + +ld The session handle. + +res The result of an LDAP operation as returned by + ldap_result() or one of the synchronous API operation + calls. + +errcodep This result parameter will be filled in with the LDAP error + code field from the LDAPMessage message. This is the indi- + cation from the server of the outcome of the operation. + NULL may be passed to ignore this field. + +matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result + parameter will be filled in with a DN indicating how much + of the name in the request was recognized. NULL may be + passed to ignore this field. The matched DN string should + be freed by calling ldap_memfree() which is described later + in this document. + +errmsgp This result parameter will be filled in with the contents + of the error message field from the LDAPMessage message. + The error message string should be freed by calling + ldap_memfree() which is described later in this document. + NULL may be passed to ignore this field. + +referralsp This result parameter will be filled in with the contents + of the referrals field from the LDAPMessage message, indi- + cating zero or more alternate LDAP servers where the + + + +Expires: 23 August 1999 [Page 45] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + request should be retried. The referrals array should be + freed by calling ldap_value_free() which is described later + in this document. NULL may be passed to ignore this field. + +serverctrlsp This result parameter will be filled in with an allocated + array of controls copied out of the LDAPMessage message. + The control array should be freed by calling + ldap_controls_free() which was described earlier. + +freeit A boolean that determines whether the res parameter is + disposed of or not. Pass any non-zero value to have these + routines free res after extracting the requested informa- + tion. This is provided as a convenience; you can also use + ldap_msgfree() to free the result later. If freeit is + non-zero, the entire chain of messages represented by res + is disposed of. + +servercredp For SASL bind results, this result parameter will be filled + in with the credentials passed back by the server for + mutual authentication, if given. An allocated berval struc- + ture is returned that should be disposed of by calling + ber_bvfree(). NULL may be passed to ignore this field. + +retoidp For extended results, this result parameter will be filled + in with the dotted-OID text representation of the name of + the extended operation response. This string should be + disposed of by calling ldap_memfree(). NULL may be passed + to ignore this field. + +retdatap For extended results, this result parameter will be filled + in with a pointer to a struct berval containing the data in + the extended operation response. It should be disposed of + by calling ber_bvfree(). NULL may be passed to ignore this + field. + +err For ldap_err2string(), an LDAP error code, as returned by + ldap_parse_result() or another LDAP API call. + +Additional parameters for the deprecated routines are not described. +Interested readers are referred to RFC 1823. + +All three of the ldap_parse_*_result() routines skip over messages of +type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking +for a result message to parse. They return the constant LDAP_SUCCESS if +the result was successfully parsed and another LDAP error code if not. +Note that the LDAP error code that indicates the outcome of the opera- +tion performed by the server is placed in the errcodep +ldap_parse_result() parameter. If a chain of messages that contains + + + +Expires: 23 August 1999 [Page 46] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +more than one result message is passed to these routines they always +operate on the first result in the chain. + +ldap_err2string() is used to convert a numeric LDAP error code, as +returned by one of the three ldap_parse_*_result() routines, or one of +the synchronous API operation calls, into an informative zero-terminated +character string message describing the error. It returns a pointer to +static data. + + +14. Stepping Through a List of Results + +The ldap_first_message() and ldap_next_message() routines are used to +step through the list of messages in a result chain returned by +ldap_result(). For search operations, the result chain may actually +include referral messages, entry messages, and result messages. +ldap_count_messages() is used to count the number of messages returned. +The ldap_msgtype() function, described above, can be used to distinguish +between the different message types. + + LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); + + LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); + + int ldap_count_messages( LDAP *ld, LDAPMessage *res ); + +Parameters are: + +ld The session handle. + +res The result chain, as obtained by a call to one of the synchronous + search routines or ldap_result(). + +msg The message returned by a previous call to ldap_first_message() + or ldap_next_message(). + +ldap_first_message() and ldap_next_message() will return NULL when no +more messages exist in the result set to be returned. NULL is also +returned if an error occurs while stepping through the entries, in which +case the error parameters in the session handle ld will be set to indi- +cate the error. + +ldap_count_messages() returns the number of messages contained in a +chain of results. It can also be used to count the number of messages +that remain in a chain if called with a message, entry, or reference +returned by ldap_first_message(), ldap_next_message(), +ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), +ldap_next_reference(). + + + +Expires: 23 August 1999 [Page 47] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +15. Parsing Search Results + +The following calls are used to parse the entries and references +returned by ldap_search() and friends. These results are returned in an +opaque structure that should only be accessed by calling the routines +described below. Routines are provided to step through the entries and +references returned, step through the attributes of an entry, retrieve +the name of an entry, and retrieve the values associated with a given +attribute in an entry. + + +15.1. Stepping Through a List of Entries or References + +The ldap_first_entry() and ldap_next_entry() routines are used to step +through and retrieve the list of entries from a search result chain. +The ldap_first_reference() and ldap_next_reference() routines are used +to step through and retrieve the list of continuation references from a +search result chain. ldap_count_entries() is used to count the number +of entries returned. ldap_count_references() is used to count the number +of references returned. + + LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); + + LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); + + LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); + + LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); + + int ldap_count_entries( LDAP *ld, LDAPMessage *res ); + + int ldap_count_references( LDAP *ld, LDAPMessage *res ); + +Parameters are: + +ld The session handle. + +res The search result, as obtained by a call to one of the synchro- + nous search routines or ldap_result(). + +entry The entry returned by a previous call to ldap_first_entry() or + ldap_next_entry(). + +ref The reference returned by a previous call to + ldap_first_reference() or ldap_next_reference(). + +ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and +ldap_next_reference() all return NULL when no more entries or references + + + +Expires: 23 August 1999 [Page 48] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +exist in the result set to be returned. NULL is also returned if an +error occurs while stepping through the entries or references, in which +case the error parameters in the session handle ld will be set to indi- +cate the error. + +ldap_count_entries() returns the number of entries contained in a chain +of entries. It can also be used to count the number of entries that +remain in a chain if called with a message, entry or reference returned +by ldap_first_message(), ldap_next_message(), ldap_first_entry(), +ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). + +ldap_count_references() returns the number of references contained in a +chain of search results. It can also be used to count the number of +references that remain in a chain. + + +15.2. Stepping Through the Attributes of an Entry + +The ldap_first_attribute() and ldap_next_attribute() calls are used to +step through the list of attribute types returned with an entry. + + char *ldap_first_attribute( + LDAP *ld, + LDAPMessage *entry, + BerElement **ptr + ); + + char *ldap_next_attribute( + LDAP *ld, + LDAPMessage *entry, + BerElement *ptr + ); + + void ldap_memfree( char *mem ); + +Parameters are: + +ld The session handle. + +entry The entry whose attributes are to be stepped through, as returned + by ldap_first_entry() or ldap_next_entry(). + +ptr In ldap_first_attribute(), the address of a pointer used inter- + nally to keep track of the current position in the entry. In + ldap_next_attribute(), the pointer returned by a previous call to + ldap_first_attribute(). The BerElement type itself is an opaque + structure that is described in more detail later in this document + in the section "Encoded ASN.1 Value Manipulation". + + + +Expires: 23 August 1999 [Page 49] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +mem A pointer to memory allocated by the LDAP library, such as the + attribute type names returned by ldap_first_attribute() and + ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem + is NULL, nothing is done. + +ldap_first_attribute() and ldap_next_attribute() will return NULL when +the end of the attributes is reached, or if there is an error, in which +case the error parameters in the session handle ld will be set to indi- +cate the error. + +Both routines return a pointer to an allocated buffer containing the +current attribute name. This should be freed when no longer in use by +calling ldap_memfree(). + +ldap_first_attribute() will allocate and return in ptr a pointer to a +BerElement used to keep track of the current position. This pointer +should be passed in subsequent calls to ldap_next_attribute() to step +through the entry's attributes. After a set of calls to +ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it +should be freed by calling ber_free( ptr, 0 ). Note that it is very +important to pass the second parameter as 0 (zero) in this call, since +the buffer associated with the BerElement does not point to separately +allocated memory. + +The attribute type names returned are suitable for passing in a call to +ldap_get_values() and friends to retrieve the associated values. + + +15.3. Retrieving the Values of an Attribute + +ldap_get_values() and ldap_get_values_len() are used to retrieve the +values of a given attribute from an entry. ldap_count_values() and +ldap_count_values_len() are used to count the returned values. +ldap_value_free() and ldap_value_free_len() are used to free the values. + + char **ldap_get_values( + LDAP *ld, + LDAPMessage *entry, + const char *attr + ); + + struct berval **ldap_get_values_len( + LDAP *ld, + LDAPMessage *entry, + const char *attr + ); + + int ldap_count_values( char **vals ); + + + +Expires: 23 August 1999 [Page 50] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + int ldap_count_values_len( struct berval **vals ); + + void ldap_value_free( char **vals ); + + void ldap_value_free_len( struct berval **vals ); + +Parameters are: + +ld The session handle. + +entry The entry from which to retrieve values, as returned by + ldap_first_entry() or ldap_next_entry(). + +attr The attribute whose values are to be retrieved, as returned by + ldap_first_attribute() or ldap_next_attribute(), or a caller- + supplied string (e.g., "mail"). + +vals The values returned by a previous call to ldap_get_values() or + ldap_get_values_len(). + +Two forms of the various calls are provided. The first form is only +suitable for use with non-binary character string data. The second _len +form is used with any kind of data. + +ldap_get_values() and ldap_get_values_len() return NULL if no values are +found for attr or if an error occurs. + +ldap_count_values() and ldap_count_values_len() return -1 if an error +occurs such as the vals parameter being invalid. + +Note that the values returned are dynamically allocated and should be +freed by calling either ldap_value_free() or ldap_value_free_len() when +no longer in use. + + +15.4. Retrieving the name of an entry + +ldap_get_dn() is used to retrieve the name of an entry. +ldap_explode_dn() and ldap_explode_rdn() are used to break up a name +into its component parts. ldap_dn2ufn() is used to convert the name into +a more "user friendly" format. + + char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); + + char **ldap_explode_dn( const char *dn, int notypes ); + + char **ldap_explode_rdn( const char *rdn, int notypes ); + + + + +Expires: 23 August 1999 [Page 51] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + char *ldap_dn2ufn( const char *dn ); + +Parameters are: + +ld The session handle. + +entry The entry whose name is to be retrieved, as returned by + ldap_first_entry() or ldap_next_entry(). + +dn The dn to explode, such as returned by ldap_get_dn(). + +rdn The rdn to explode, such as returned in the components of the + array returned by ldap_explode_dn(). + +notypes A boolean parameter, if non-zero indicating that the dn or rdn + components should have their type information stripped off + (i.e., "cn=Babs" would become "Babs"). + +ldap_get_dn() will return NULL if there is some error parsing the dn, +setting error parameters in the session handle ld to indicate the error. +It returns a pointer to newly allocated space that the caller should +free by calling ldap_memfree() when it is no longer in use. Note the +format of the DNs returned is given by [4]. + +ldap_explode_dn() returns a NULL-terminated char * array containing the +RDN components of the DN supplied, with or without types as indicated by +the notypes parameter. The components are returned in the order they +appear in the dn. The array returned should be freed when it is no +longer in use by calling ldap_value_free(). + +ldap_explode_rdn() returns a NULL-terminated char * array containing the +components of the RDN supplied, with or without types as indicated by +the notypes parameter. The components are returned in the order they +appear in the rdn. The array returned should be freed when it is no +longer in use by calling ldap_value_free(). + +ldap_dn2ufn() converts the DN into the user friendly format described in +[5]. The UFN returned is newly allocated space that should be freed by a +call to ldap_memfree() when no longer in use. + + +15.5. Retrieving controls from an entry + +ldap_get_entry_controls() is used to extract LDAP controls from an +entry. + + + int ldap_get_entry_controls( + + + +Expires: 23 August 1999 [Page 52] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP *ld, + LDAPMessage *entry, + LDAPControl ***serverctrlsp + ); + +Parameters are: + +ld The session handle. + +entry The entry to extract controls from, as returned by + ldap_first_entry() or ldap_next_entry(). + +serverctrlsp This result parameter will be filled in with an allocated + array of controls copied out of entry. The control array + should be freed by calling ldap_controls_free(). If ser- + verctrlsp is NULL, no controls are returned. + +ldap_get_entry_controls() returns an LDAP error code that indicates +whether the reference could be successfully parsed (LDAP_SUCCESS if all +goes well). + + + +15.6. Parsing References + +ldap_parse_reference() is used to extract referrals and controls from a +SearchResultReference message. + + + int ldap_parse_reference( + LDAP *ld, + LDAPMessage *ref, + char ***referralsp, + LDAPControl ***serverctrlsp, + int freeit + ); + +Parameters are: + +ld The session handle. + +ref The reference to parse, as returned by ldap_result(), + ldap_first_reference(), or ldap_next_reference(). + +referralsp This result parameter will be filled in with an allocated + array of character strings. The elements of the array are + the referrals (typically LDAP URLs) contained in ref. The + array should be freed when no longer in used by calling + + + +Expires: 23 August 1999 [Page 53] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + ldap_value_free(). If referralsp is NULL, the referral + URLs are not returned. + +serverctrlsp This result parameter will be filled in with an allocated + array of controls copied out of ref. The control array + should be freed by calling ldap_controls_free(). If ser- + verctrlsp is NULL, no controls are returned. + +freeit A boolean that determines whether the ref parameter is + disposed of or not. Pass any non-zero value to have this + routine free ref after extracting the requested informa- + tion. This is provided as a convenience; you can also use + ldap_msgfree() to free the result later. + +ldap_parse_reference() returns an LDAP error code that indicates whether +the reference could be successfully parsed (LDAP_SUCCESS if all goes +well). + + +16. Encoded ASN.1 Value Manipulation + +This section describes routines which may be used to encode and decode +BER-encoded ASN.1 values, which are often used inside of control and +extension values. + +With the exceptions of two new functions ber_flatten() and ber_init(), +these functions are compatible with the University of Michigan LDAP 3.3 +implementation of BER. + + +16.1. General + + struct berval { + unsigned long bv_len; + char *bv_val; + }; + +A struct berval contains a sequence of bytes and an indication of its +length. The bv_val is not necessarily zero-terminated. bv_len must +always be a nonnegative number. Applications may allocate their own +berval structures. + +As defined earlier, the BerElement structure is an opaque structure: + + typedef struct berelement BerElement; + +It contains not only a copy of the encoded value, but also state infor- +mation used in encoding or decoding. Applications cannot allocate their + + + +Expires: 23 August 1999 [Page 54] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +own BerElement structures. The internal state is neither thread- +specific nor locked, so two threads should not manipulate the same +BerElement value simultaneously. + +A single BerElement value cannot be used for both encoding and decoding. + + void ber_bvfree( struct berval *bv ); + +ber_bvfree() frees a berval returned from this API. Both the bv->bv_val +string and the berval itself are freed. Applications should not use +ber_bvfree() with bervals which the application has allocated. + + void ber_bvecfree( struct berval **bv ); + +ber_bvecfree() frees an array of bervals returned from this API. Each +of the bervals in the array are freed using ber_bvfree(), then the array +itself is freed. + + struct berval *ber_bvdup( const struct berval *bv ); + +ber_bvdup() returns a copy of a berval. The bv_val field in the +returned berval points to a different area of memory than the bv_val +field in the argument berval. The NULL pointer is returned on error +(e.g. out of memory). + + void ber_free( BerElement *ber, int fbuf ); + +ber_free() frees a BerElement which is returned from the API calls +ber_alloc_t() or ber_init(). Each BerElement must be freed by the +caller. The second argument fbuf should always be set to 1 to ensure +that the internal buffer used by the BER functions is freed as well as +the BerElement container itself. + + +16.2. Encoding + + BerElement *ber_alloc_t( int options ); + +ber_alloc_t() constructs and returns BerElement. The NULL pointer is +returned on error. The options field contains a bitwise-or of options +which are to be used when generating the encoding of this BerElement. +One option is defined and must always be supplied: + + #define LBER_USE_DER 0x01 + +When this option is present, lengths will always be encoded in the +minimum number of octets. Note that this option does not cause values +of sets to be rearranged in tag and byte order or default values to be + + + +Expires: 23 August 1999 [Page 55] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +removed, so these functions are not sufficient for generating DER output +as defined in X.509 and X.680. If the caller takes responsibility for +ordering values of sets correctly and removing default values, DER out- +put as defined in X.509 and X.680 can be produced. + +Unrecognized option bits are ignored. + +The BerElement returned by ber_alloc_t() is initially empty. Calls to +ber_printf() will append bytes to the end of the ber_alloc_t(). + + int ber_printf( BerElement *ber, const char *fmt, ... ) + +The ber_printf() routine is used to encode a BER element in much the +same way that sprintf() works. One important difference, though, is +that state information is kept in the ber argument so that multiple +calls can be made to ber_printf() to append to the end of the BER ele- +ment. ber must be a pointer to a BerElement returned by ber_alloc_t(). +ber_printf() interprets and formats its arguments according to the for- +mat string fmt. ber_printf() returns -1 if there is an error during +encoding and a positive number if successful. As with sprintf(), each +character in fmt refers to an argument to ber_printf(). + +The format string can contain the following format characters: + +'t' Tag. The next argument is an int specifying the tag to override + the next element to be written to the ber. This works across + calls. The int value must contain the tag class, constructed + bit, and tag value. For example, a tag of "[3]" for a con- + structed type is 0xA3. All implementations must support tags + that fit in a single octet (i.e., where the tag value is less + than 32) and they may support larger tags. + +'b' Boolean. The next argument is an int, containing either 0 for + FALSE or 0xff for TRUE. A boolean element is output. If this + format character is not preceded by the 't' format modifier, the + tag 0x01 is used for the element. + +'i' Integer. The next argument is an int, containing the integer in + the host's byte order. An integer element is output. If this + format character is not preceded by the 't' format modifier, the + tag 0x02 is used for the element. + +'X' Bitstring. The next two arguments are a char * pointer to the + start of the bitstring, followed by an int containing the number + of bits in the bitstring. A bitstring element is output, in + primitive form. If this format character is not preceded by the + 't' format modifier, the tag 0x03 is used for the element. + + + + +Expires: 23 August 1999 [Page 56] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +'n' Null. No argument is required. An ASN.1 NULL element is out- + put. If this format character is not preceded by the 't' format + modifier, the tag 0x05 is used for the element. + +'o' Octet string. The next two arguments are a char *, followed by + an int with the length of the string. The string may contain + null bytes and need not be zero-terminated. An octet string + element is output, in primitive form. If this format character + is not preceded by the 't' format modifier, the tag 0x04 is used + for the element. + +'s' Octet string. The next argument is a char * pointing to a + zero-terminated string. An octet string element in primitive + form is output, which does not include the trailing '\0' (null) + byte. If this format character is not preceded by the 't' format + modifier, the tag 0x04 is used for the element. + +'v' Several octet strings. The next argument is a char **, an array + of char * pointers to zero-terminated strings. The last element + in the array must be a NULL pointer. The octet strings do not + include the trailing '\0' (null) byte. Note that a construct + like '{v}' is required to get an actual SEQUENCE OF octet + strings. The 't' format modifier cannot be used with this for- + mat character. + +'V' Several octet strings. A NULL-terminated array of berval *'s is + supplied. Note that a construct like '{V}' is required to get an + actual SEQUENCE OF octet strings. The 't' format modifier cannot + be used with this format character. + +'{' Begin sequence. No argument is required. If this format char- + acter is not preceded by the 't' format modifier, the tag 0x30 + is used. + +'}' End sequence. No argument is required. The 't' format modifier + cannot be used with this format character. + +'[' Begin set. No argument is required. If this format character + is not preceded by the 't' format modifier, the tag 0x31 is + used. + +']' End set. No argument is required. The 't' format modifier can- + not be used with this format character. + +Each use of a '{' format character must be matched by a '}' character, +either later in the format string, or in the format string of a subse- +quent call to ber_printf() for that BerElement. The same applies to the +'[' and ']' format characters. + + + +Expires: 23 August 1999 [Page 57] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Sequences and sets nest, and implementations of this API must maintain +internal state to be able to properly calculate the lengths. + + int ber_flatten( const BerElement *ber, struct berval **bvPtr ); + +The ber_flatten routine allocates a struct berval whose contents are a +BER encoding taken from the ber argument. The bvPtr pointer points to +the returned berval, which must be freed using ber_bvfree(). This rou- +tine returns 0 on success and -1 on error. + +The ber_flatten API call is not present in U-M LDAP 3.3. + +The use of ber_flatten on a BerElement in which all '{' and '}' format +modifiers have not been properly matched is an error (i.e., -1 will be +returned by ber_flatten() if this situation is exists). + + +16.3. Encoding Example + +The following is an example of encoding the following ASN.1 data type: + + Example1Request ::= SEQUENCE { + s OCTET STRING, -- must be printable + val1 INTEGER, + val2 [0] INTEGER DEFAULT 0 + } + + + int encode_example1(const char *s,int val1,int val2,struct berval **bvPtr) + { + BerElement *ber; + int rc = -1; + + ber = ber_alloc_t(LBER_USE_DER); + + if (ber == NULL) return -1; + + if (ber_printf(ber,"{si",s,val1) == -1) { + goto done; + } + + if (val2 != 0) { + if (ber_printf(ber,"ti",0x80,val2) == -1) { + goto done; + } + } + + if (ber_printf(ber,"}") == -1) { + + + +Expires: 23 August 1999 [Page 58] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + goto done; + } + + rc = ber_flatten(ber,bvPtr); + + done: + ber_free(ber,1); + return rc; + } + + +16.4. Decoding + +The following two symbols are available to applications. + + #define LBER_ERROR 0xffffffffUL + #define LBER_DEFAULT 0xffffffffUL + + BerElement *ber_init( const struct berval *bv ); + +The ber_init function constructs a BerElement and returns a new BerEle- +ment containing a copy of the data in the bv argument. ber_init returns +the NULL pointer on error. + + unsigned long ber_scanf( BerElement *ber, const char *fmt, ... ); + +The ber_scanf() routine is used to decode a BER element in much the same +way that sscanf() works. One important difference, though, is that some +state information is kept with the ber argument so that multiple calls +can be made to ber_scanf() to sequentially read from the BER element. +The ber argument must be a pointer to a BerElement returned by +ber_init(). ber_scanf interprets the bytes according to the format +string fmt, and stores the results in its additional arguments. +ber_scanf() returns LBER_ERROR on error, and a different value on suc- +cess. + +The format string contains conversion specifications which are used to +direct the interpretation of the BER element. The format string can +contain the following characters: + +'a' Octet string. A char ** argument should be supplied. Memory is + allocated, filled with the contents of the octet string, zero- + terminated, and the pointer to the string is stored in the argu- + ment. The returned value must be freed using ldap_memfree. The + tag of the element must indicate the primitive form (constructed + strings are not supported) but is otherwise ignored and dis- + carded during the decoding. This format cannot be used with + octet strings which could contain null bytes. + + + +Expires: 23 August 1999 [Page 59] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +'O' Octet string. A struct berval ** argument should be supplied, + which upon return points to an allocated struct berval contain- + ing the octet string and its length. ber_bvfree() must be + called to free the allocated memory. The tag of the element + must indicate the primitive form (constructed strings are not + supported) but is otherwise ignored during the decoding. + +'b' Boolean. A pointer to an int should be supplied. The int value + stored will be 0 for FALSE or nonzero for TRUE. The tag of the + element must indicate the primitive form but is otherwise + ignored during the decoding. + +'i' Integer. A pointer to an int should be supplied. The int value + stored will be in host byte order. The tag of the element must + indicate the primitive form but is otherwise ignored during the + decoding. ber_scanf() will return an error if the integer can- + not be stored in an int. + +'B' Bitstring. A char ** argument should be supplied which will + point to the allocated bits, followed by an unsigned long * + argument, which will point to the length (in bits) of the bit- + string returned. ldap_memfree must be called to free the bit- + string. The tag of the element must indicate the primitive form + (constructed bitstrings are not supported) but is otherwise + ignored during the decoding. + +'n' Null. No argument is required. The element is verified to have + a zero-length value and is skipped. The tag is ignored. + +'v' Several octet strings. A char *** argument should be supplied, + which upon return points to an allocated NULL-terminated array + of char *'s containing the octet strings. NULL is stored if the + sequence is empty. ldap_memfree must be called to free each + element of the array and the array itself. The tag of the + sequence and of the octet strings are ignored. + +'V' Several octet strings (which could contain null bytes). A + struct berval *** should be supplied, which upon return points + to a allocated NULL-terminated array of struct berval *'s con- + taining the octet strings and their lengths. NULL is stored if + the sequence is empty. ber_bvecfree() can be called to free the + allocated memory. The tag of the sequence and of the octet + strings are ignored. + +'x' Skip element. The next element is skipped. No argument is + required. + +'{' Begin sequence. No argument is required. The initial sequence + + + +Expires: 23 August 1999 [Page 60] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + tag and length are skipped. + +'}' End sequence. No argument is required. + +'[' Begin set. No argument is required. The initial set tag and + length are skipped. + +']' End set. No argument is required. + + unsigned long ber_peek_tag( BerElement *ber, unsigned long *lenPtr ); + +ber_peek_tag() returns the tag of the next element to be parsed in the +BerElement argument. The length of this element is stored in the +*lenPtr argument. LBER_DEFAULT is returned if there is no further data +to be read. The ber argument is not modified. + + unsigned long ber_skip_tag( BerElement *ber, unsigned long *lenPtr ); + +ber_skip_tag() is similar to ber_peek_tag(), except that the state +pointer in the BerElement argument is advanced past the first tag and +length, and is pointed to the value part of the next element. This rou- +tine should only be used with constructed types and situations when a +BER encoding is used as the value of an OCTET STRING. The length of the +value is stored in *lenPtr. + + unsigned long ber_first_element( BerElement *ber, + unsigned long *lenPtr, char **opaquePtr ); + + unsigned long ber_next_element( BerElement *ber, + unsigned long *lenPtr, char *opaque ); + +ber_first_element() and ber_next_element() are used to traverse a SET, +SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls +ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, +and calls ber_peek_tag() for the first element inside the constructed +value. LBER_DEFAULT is returned if the constructed value is empty. +ber_next_element() positions the state at the start of the next element +in the constructed type. LBER_DEFAULT is returned if there are no +further values. + +The len and opaque values should not be used by applications other than +as arguments to ber_next_element(), as shown in the example below. + + +16.5. Decoding Example + +The following is an example of decoding an ASN.1 data type: + + + + +Expires: 23 August 1999 [Page 61] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + Example2Request ::= SEQUENCE { + dn OCTET STRING, -- must be printable + scope ENUMERATED { b (0), s (1), w (2) }, + ali ENUMERATED { n (0), s (1), f (2), a (3) }, + size INTEGER, + time INTEGER, + tonly BOOLEAN, + attrs SEQUENCE OF OCTET STRING, -- must be printable + [0] SEQUENCE OF SEQUENCE { + type OCTET STRING -- must be printable, + crit BOOLEAN DEFAULT FALSE, + value OCTET STRING + } OPTIONAL } + + #define TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */ + + int decode_example2(struct berval *bv) + { + BerElement *ber; + unsigned long len, res; + int scope, ali, size, time, tonly; + char *dn = NULL, **attrs = NULL; + int i,rc = 0; + + ber = ber_init(bv); + if (ber == NULL) { + fputs("ERROR ber_init failed\n", stderr); + return -1; + } + + res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali, + &size,&time,&tonly,&attrs); + + if (res == LBER_ERROR) { + fputs("ERROR ber_scanf failed\n", stderr); + ber_free(ber,1); + return -1; + } + + /* *** use dn */ + ldap_memfree(dn); + + for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { + /* *** use attrs[i] */ + ldap_memfree(attrs[i]); + } + ldap_memfree(attrs); + + + + +Expires: 23 August 1999 [Page 62] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) { + char *opaque; + unsigned long tag; + + for (tag = ber_first_element(ber,&len,&opaque); + tag != LBER_DEFAULT; + tag = ber_next_element (ber,&len,opaque)) { + + unsigned long ttag, tlen; + char *type; + int crit; + struct berval *value; + + if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { + fputs("ERROR cannot parse type\n", stderr); + break; + } + /* *** use type */ + ldap_memfree(type); + + ttag = ber_peek_tag(ber,&tlen); + if (ttag == 0x01) { /* boolean */ + if (ber_scanf(ber,"b", + &crit) == LBER_ERROR) { + fputs("ERROR cannot parse crit\n", + stderr); + rc = -1; + break; + } + } else if (ttag == 0x04) { /* octet string */ + crit = 0; + } else { + fputs("ERROR extra field in controls\n", + stderr ); + break; + } + + if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { + fputs("ERROR cannot parse value\n", stderr); + rc = -1; + break; + } + /* *** use value */ + ber_bvfree(value); + } + } + + ber_scanf(ber,"}"); + + + +Expires: 23 August 1999 [Page 63] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + + ber_free(ber,1); + + return rc; + } + + + +17. Security Considerations + +LDAPv2 supports security through protocol-level authentication using +clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen- +tication Security Layer) methods. LDAPv3 also supports operation over a +secure transport layer using Transport Layer Security TLS [9]. Readers +are referred to the protocol documents for discussion of related secu- +rity considerations. + +Implementations of this API should be cautious when handling authentica- +tion credentials. In particular, keeping long-lived copies of creden- +tials without the application's knowledge is discouraged. + + +18. Acknowledgements + +Many members of the IETF ASID and LDAPEXT working groups as well as +members of the Internet at large have provided useful comments and +suggestions that have been incorporated into this document. Chris +Weider deserves special mention for his contributions as co-author of +earlier revisions of this document. + +The original material upon which this specification is based was sup- +ported by the National Science Foundation under Grant No. NCR-9416667. + + +19. Copyright + +Copyright (C) The Internet Society (1997-1999). All Rights Reserved. + +This document and translations of it may be copied and furnished to oth- +ers, and derivative works that comment on or otherwise explain it or +assist in its implementation may be prepared, copied, published and dis- +tributed, in whole or in part, without restriction of any kind, provided +that the above copyright notice and this paragraph are included on all +such copies and derivative works. However, this document itself may not +be modified in any way, such as by removing the copyright notice or +references to the Internet Society or other Internet organizations, +except as needed for the purpose of developing Internet standards in +which case the procedures for copyrights defined in the Internet + + + +Expires: 23 August 1999 [Page 64] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +Standards process must be followed, or as required to translate it into +languages other than English. + +The limited permissions granted above are perpetual and will not be +revoked by the Internet Society or its successors or assigns. + +This document and the information contained herein is provided on an "AS +IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK +FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT +LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT +INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- +NESS FOR A PARTICULAR PURPOSE. + + +20. Bibliography + +[1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation + X.520. + +[2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, + "Lightweight Directory Access Protocol (v3): Attribute Syntax + Definitions", RFC 2252, December 1997. + +[3] T. Howes, "The String Representation of LDAP Search Filters," RFC + 2254, December 1997. + +[4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol + (v3): A UTF-8 String Representation of Distinguished Names", RFC + 2253, December 1997. + +[5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- + ing," RFC 1781, March 1995. + +[6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol + (v3)", RFC 2251, December 1997. + +[7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control + Extension for Server Side Sorting of Search Results", INTERNET- + DRAFT , 7 August 1998. + +[8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC + 2222, October 1997. + +[9] "Lightweight Directory Access Protocol (v3): Extension for Tran- + sport Layer Security", INTERNET-DRAFT , November 1998. + +[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC + + + +Expires: 23 August 1999 [Page 65] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + 2044, October 1996. + +[11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995. + +[12] "Character Mnemonics and Character Sets," RFC 1345, June 1992. + +[13] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997. + + +21. Authors' Addresses + + Mark Smith (document editor) + Netscape Communications Corp. + 501 E. Middlefield Rd., Mailstop MV068 + Mountain View, CA 94043 + USA + +1 650 937-3477 + mcs@netscape.com + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Rd., Mailstop MV068 + Mountain View, CA 94043 + USA + +1 650 937-3419 + howes@netscape.com + + Andy Herron + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + +1 425 882-8080 + andyhe@microsoft.com + + Mark Wahl + Innosoft International, Inc. + 8911 Capital of Texas Hwy, Suite 4140 + Austin, TX 78759 + USA + +1 626 919 3600 + Mark.Wahl@innosoft.com + + Anoop Anantha + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + + + +Expires: 23 August 1999 [Page 66] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + +1 425 882-8080 + anoopa@microsoft.com + + +22. Appendix A - Sample C LDAP API Code + + #include + #include + + main() + { + LDAP *ld; + LDAPMessage *res, *e; + int i, rc; + char *a, *dn; + BerElement *ptr; + char **vals; + + /* open an LDAP session */ + if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) + return 1; + + /* authenticate as nobody */ + if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) { + fprintf( stderr, "ldap_simple_bind_s: %s\n", + ldap_err2string( rc )); + ldap_unbind( ld ); + return 1; + } + + /* search for entries with cn of "Babs Jensen", return all attrs */ + if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US", + LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) + != LDAP_SUCCESS ) { + fprintf( stderr, "ldap_search_s: %s\n", + ldap_err2string( rc )); + if ( res == NULL ) { + ldap_unbind( ld ); + return 1; + } + } + + /* step through each entry returned */ + for ( e = ldap_first_entry( ld, res ); e != NULL; + e = ldap_next_entry( ld, e ) ) { + /* print its name */ + dn = ldap_get_dn( ld, e ); + printf( "dn: %s\n", dn ); + + + +Expires: 23 August 1999 [Page 67] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + ldap_memfree( dn ); + + /* print each attribute */ + for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; + a = ldap_next_attribute( ld, e, ptr ) ) { + printf( "\tattribute: %s\n", a ); + + /* print each value */ + vals = ldap_get_values( ld, e, a ); + for ( i = 0; vals[i] != NULL; i++ ) { + printf( "\t\tvalue: %s\n", vals[i] ); + } + ldap_value_free( vals ); + ldap_memfree( a ); + } + if ( ptr != NULL ) { + ber_free( ptr, 0 ); + } + } + /* free the search results */ + ldap_msgfree( res ); + + /* close and free connection resources */ + ldap_unbind( ld ); + + return 0; + } + + +23. Appendix B - Namespace Consumed By This Specification + +The following 2 prefixes are used in this specification to name func- +tions: + ldap_ + ber_ + +The following 6 prefixes are used in this specification to name struc- +tures, unions, and typedefs: + ldap + LDAP + PLDAP + ber + Ber + timeval + +The following 3 prefixes are used in this specification to name #defined +macros: + LDAP + + + +Expires: 23 August 1999 [Page 68] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LBER_ + mod_ + + +24. Appendix C - Summary of Requirements for API Extensions + +As the LDAP protocol is extended, this C LDAP API will need to be +extended as well. For example, an LDAPv3 control extension has already +been defined for server-side sorting of search results [7]. This appen- +dix summarizes the requirements for extending this API. + +24.1. Compatibility + +Extensions to this document should not, by default, alter the behavior +of any of the APIs specified in this document. If an extension option- +ally changes the behavior of any existing C LDAP API function calls, the +behavior change must be well documented. + +24.2. Style + +Extensions to this API should follow the general style and naming con- +ventions used in this document. For example, function names should +start with "ldap_" or "ber_" and consist entirely of lowercase letters, +digits, and underscore ('_') characters. More information can be found +in the preceding appendix called "Namespace Consumed By This Specifica- +tion." + +24.3. Dependence on Externally Defined Types + +Extensions to this API should minimize dependencies on types and macros +that are defined in system header files and generally use only intrinsic +types that are part of the C language, types defined in this specifica- +tion, or types defined in the extension document itself. + +24.4. Compile Time Information + +Extensions to this API should conform to the requirements contained in +the "Retrieving Information at Compile Time" section of this document. +That is, extensions should define a macro of the form: + + #define LDAP_API_FEATURE_x level + +so that applications can detect the presence or absense of the extension +at compile time and also test the version or level of the extension pro- +vided by an API implementation. + + + + + + +Expires: 23 August 1999 [Page 69] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +24.5. Runtime Information + +Extensions to this API should conform to the requirements contained in +the "Retrieving Information During Execution" section of this document. +That is, each extension should be given a character string name and that +name should appear in the ldapai_extensions array field of the LDAPAPI- +Info structure following a successful call to ldap_get_option() with an +option parameter value of LDAP_OPT_API_INFO. In addition, information +about the extension should be available via a call to ldap_get_option() +with an option parameter value of LDAP_OPT_API_FEATURE_INFO. + +24.6. Values Used for Session Handle Options + +Extensions to this API that add new session options (for use with the +ldap_get_option() and ldap_set_option() functions) should meet the +requirements contained in the last paragraph of the "LDAP Session Handle +Options" section of this document. Specifically, standards track docu- +ments MUST use values for option macros that are between 0x1000 and +0x3FFF inclusive and private and experimental extensions MUST use values +for the option macros that are between 0x4000 and 0x7FFF inclusive. + + +25. Appendix D - Known Incompatibilities with RFC 1823 + +This appendix lists known incompatibilities between this API specifica- +tion and the one contained in RFC 1823, beyond the additional API func- +tions added in support of LDAPv3. + + +25.1. Opaque LDAP Structure + +In RFC 1823, some fields in the LDAP structure were exposed to applica- +tion programmers. To provide a cleaner interface and to make it easier +for implementations to evolve over time without sacrificing binary com- +patibility with older applications, the LDAP structure is now entirely +opaque. The new ldap_set_option() and ldap_get_option() calls can be +used to manipulate per-session and global options. + + +25.2. Additional Error Codes + +The following new error code macros were introduced to support LDAPv3: + LDAP_REFERRAL + LDAP_ADMINLIMIT_EXCEEDED + LDAP_UNAVAILABLE_CRITICAL_EXTENSION + LDAP_CONFIDENTIALITY_REQUIRED + LDAP_SASL_BIND_IN_PROGRESS + LDAP_AFFECTS_MULTIPLE_DSAS + + + +Expires: 23 August 1999 [Page 70] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + LDAP_CONNECT_ERROR + LDAP_NOT_SUPPORTED + LDAP_CONTROL_NOT_FOUND + LDAP_NO_RESULTS_RETURNED + LDAP_MORE_RESULTS_TO_RETURN + LDAP_CLIENT_LOOP + LDAP_REFERRAL_LIMIT_EXCEEDED + + +25.3. Freeing of String Data with ldap_memfree() + +All strings received from the API (e.g., those returned by the +ldap_get_dn() or ldap_dn2ufn() functions) should be freed by calling +ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree() +function. + + +25.4. Changes to ldap_result() + +The meaning of the all parameter to ldap_result has changed slightly. +Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There +is also a new possible value, LDAP_MSG_RECEIVED (0x02). + +The result type LDAP_RES_MODDN is now returned where RFC 1823 returned +LDAP_RES_MODRDN. The actual value for these two macros is the same +(0x6D). + + +25.5. Changes to ldap_first_attribute() and ldap_next_attribute + +Each non-NULL return value should be freed by calling ldap_memfree() +after use. In RFC 1823, these two functions returned a pointer to a +per-session buffer, which was not very thread-friendly. + +After the last call to ldap_first_attribute() or ldap_next_attribute(), +the value set in the ptr parameter should be freed by calling ber_free( +ptr, 0 ). RFC 1823 did not mention that the ptr value should be freed. + +The type of the ptr parameter was changed from void * to BerElement *. + + +25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions + +In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a +parameter called deleteoldrdn. This does not match the great majority +of implementations, so in this specification the deleteoldrdn parameter +was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional +functions that support deleteoldrdn and are widely implemented as well + + + +Expires: 23 August 1999 [Page 71] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +were added to this specification: ldap_modrdn2() and ldap_modrdn2_s(). + + +25.7. API Specification Clarified + +RFC 1823 left many things unspecified, including behavior of various +memory disposal functions when a NULL pointer is presented, requirements +for header files, values of many macros, and so on. This specification +is more complete and generally tighter than the one in RFC 1823. + + +25.8. Deprecated Functions + +A number of functions that are in RFC 1823 are labeled as "deprecated" +in this specification. In most cases, a replacement that provides +equivalent functionality has been defined. The deprecated functions +are: + + ldap_bind() + Use ldap_simple_bind() or ldap_sasl_bind() instead. + + ldap_bind_s() + Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead. + + ldap_kerberos_bind() and ldap_kerberos_bind_s() + No equivalent functions are provided. + + ldap_modrdn() and ldap_modrdn2() + Use ldap_rename() instead. + + ldap_modrdn_s() and ldap_modrdn2_s() + Use ldap_rename_s() instead. + + ldap_open() + Use ldap_init() instead. + + ldap_perror() + Use ldap_err2string() instead. + + ldap_result2error() + Use ldap_parse_result() instead. + + +26. Appendix E - Changes Made Since Last Document Revision + +The previous version of this document was draft-ietf-ldapext-ldap-c- +api-01.txt, dated 7 August 1998. This appendix lists all of the changes +made to that document to produce the one you are reading now. + + + +Expires: 23 August 1999 [Page 72] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + +26.1. API Changes + + General: added the 'const' keyword to function prototypes where + appropriate. + + Added two new sections that specify additional features and require- + ments for API implementors: + "Header File Requirements" + "A Client Control That Governs Referral Processing" + + "Retrieving Information at Compile Time" section: added + LDAP_VERSION_MIN, LDAP_VERSION_MAX, LDAP_VENDOR_NAME, and + LDAP_VENDOR_VERSION macros. Corrected LDAP_API_VERSION example code + to use >= instead of >. Added note about what value to use for + LDAP_API_VERSION prior to publication of this draft as an RFC (2000 + + draft revision number). + + "Retrieving Information During Execution" section: added + LDAP_API_INFO_VERSION macro and clarified the text to explain the + behavior when there is a mismatch between LDAPAPIInfo structure ver- + sions. Added LDAP_OPT_API_FEATURE_INFO to allow applications to + retrieve version information about API extended features. + + "LDAP Session Handle Options" section: Added macro definitions for + LDAP_OPT_ON and LDAP_OPT_OFF and changed the "invalue" type for + Boolean options from "int" to "void *". For consistency, we now + require that applications dispose of "char *" and "LDAPControl *" + values that are returned. Added note about which option value ranges + are to be used for various purposes. + + "Closing the session" section: added new function ldap_unbind_ext() + to allow controls to be used with unbind operations. + + "Searching" section: added requirement that *res be set to NULL by + synchronous calls that fail to return any results. + + "Modifying the Name of an Entry" section: added function prototypes + for ldap_modrdn2() and ldap_modrdn2_s() and corrected the ones for + ldap_modrdn() and ldap_modrdn_s() to match the most widely imple- + mented APIs. + + "Obtaining Results and Peeking Inside LDAP Messages" section: added + requirement that "*res" be set to NULL when ldap_result() fails to + return any results. Added requirement that ldap_msgfree() accept a + NULL "res" parameter. + + "Stepping Through the Attributes of an Entry" section: added + requirement that ldap_memfree() accept a NULL "mem" parameter. + + + +Expires: 23 August 1999 [Page 73] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + "Encoded ASN.1 Value Manipulation - Encoding" section: added note + that implementations may support tags with a value larger than 32 + (but this is not required). + + "Encoded ASN.1 Value Manipulation - Decoding" section: changed the + LBER_ERROR and LBER_DEFAULT macros to end in "UL" instead of "L" + since all the functions that return these two values return an + "unsigned long" value. + + +26.2. Editorial changes + + + Removed section: "Appendix - Outstanding Issues." + + Added two new editorial sections: + "Appendix - Summary of Requirements for API Extensions" + "Appendix - Known Incompatibilities with RFC 1823". + + General: replaced all occurrences of "LDAP C API" with "C LDAP API" + for consistency. + + "Status of Memo" section: added a statement that this document is in + full conformance with all provisions of Section 10 of RFC2026. Also + revised the text about the Internet Draft current and shadow direc- + tories to match the latest I-D guidelines. + + Document authors: removed Chris Weider from the list of authors (at + his own request) and added an explicit mention of him in the "Ack- + nowledgements" section. Updated Mark Wahl's company affiliation in + document preface. Added "(document editor)" after Mark Smith's name + in the "Authors' Addresses" section. + + Copyright: updated the year to 1999. + + "Introduction" section: expanded the sentence that mentioned the sam- + ple code appendix to mention all of the appendices. + + "Overview of LDAP API Use" section: numbered the four simple steps + for using the API. Added mention of the referrals client control. + Clarified the text on character sets. Replaced mention of + ldap_bind() with ldap_sasl_bind() because the former is deprecated. + Added note that this API is designed for use in environments where + the 'int' type is at least 32 bits in size. + + "Common Data Structures" section: added definition of BerElement so + it is defined before it is used. Added reference back to "Header + File Requirements" for "struct timeval" related considerations. + + + +Expires: 23 August 1999 [Page 74] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + "Initializing an LDAP Session" section: moved note about ldap_open() + attempting to make a server connection closer to the ldap_open() + function prototype. Added note that using literal IPv6 addresses in + the "hostname" parameter is not yet supported. + + "LDAP Session Handle Options" section: replaced one instance of + "Formerly" with "In RFC 1823." Added note about inheritance of + options when automatic referral following is enabled. Added + LDAP_OPT_API_INFO and LDAP_OPT_API_FEATURE_INFO for completeness (not + previously included in this section). Replaced erroneous references + to the "Using Controls" section with references to the "Working With + Controls" section. In the text describing the LDAP_OPT_HOST_NAME + option, added a reference to the "hostname" parameter of ldap_init() + for the syntax of the option value. Clarified that ldap_set_option() + makes a copy of the "invalue" data. + + "Working With Controls" section: added a note to remind the reader + that server controls that are marked critical should not be used with + unbind and abandon operations since those two operations have no + server response. + + "Closing the session" section: made it clear that all open connec- + tions associated with a session handle are closed when any of the + unbind API functions are called. + + "Searching" section: added note that only a subset of the filter + functionality is available when communicating with an LDAPv2 server. + Clarified text to explain when a local timeout is used and when it is + not. + + "Abandoning An Operation" section: removed some redundant text from + the paragraph that explains the differences between ldap_abandon() + and ldap_abandon_ext(). + + "Obtaining Results and Peeking Inside LDAP Messages" section: clari- + fied that ldap_result() only returns messages for one request at a + time. + + "Handling Errors and Parsing Results" section: replace a few + occurrences of LDAPResult with LDAPMessage (there is no type called + LDAPResult). Changed the names of the "resultoidp" and "resultdatap" + parameters to "retoidp" and "retdatap" to avoid confusion with LDAP + result messages. + + "Stepping Through a List of Entries or References" section: added "or + References" to the section name to better reflect its contents. + Added missing description of "ref" parameter. Added mention of + ldap_first_reference() and ldap_next_reference() in sentence about + + + +Expires: 23 August 1999 [Page 75] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + function return values. + + "Stepping Through the Attributes of an Entry" section: added forward + reference for BerElement type. + + "Parsing References" section: in the description of the "ref" parame- + ter, changed the phrase "these routines" to the more accurate "this + routine." + + "Encoded ASN.1 Value Manipulation - General" section: changed text to + make sense given that the definition of BerElement now appears first + in the "Common Data Structures" section. + + "Encoded ASN.1 Value Manipulation - Encoding" section: Changed the + style of function prototypes to better match the rest of the docu- + ment. Corrected a typo in the ber_bvdup() description ("as the" + replaced with "than the"). Changed "null" to "NULL" where appropri- + ate to be consistent with use elsewhere in the document. Removed + mention of sequences from the discussion of the LBER_USE_DER option. + Fixed some truncated sentences (by adding some missing '\' characters + to the nroff document source). + + "Encoded ASN.1 Value Manipulation - Encoding Example" section: sim- + plified the error handling in the example code through the use of a + 'goto' statement. + + "Encoded ASN.1 Value Manipulation - Decoding" section: Changed the + style of function prototypes to better match the rest of the docu- + ment. Changed "null" to "NULL" and "null-terminated" to "zero- + terminated" where appropriate to be consistent with use elsewhere in + the document. Fixed a typo (the text now says "an allocated" instead + of "a allocated."). Clarified the description of the 'n' format + character for ber_scanf(). + + "Encoded ASN.1 Value Manipulation - Decoding Example" section: + changed code to not define a macro that begins with "LDAP" since that + prefix is reserved for the API. Removed an extra 'i' from the format + string used in the first call to ber_scanf(). Changed error report- + ing code to send messages to stderr instead of stdout. Changed + declaration of "res" local variable from "int" to "unsigned long" and + corrected one test of the ber_scanf() return value to test against + LBER_ERROR instead of -1. Fixed improperly rendered strings (by + adding '\' characters to the nroff source for this document so that + '\t' and '\n' are correctly rendered). + + "Acknowledgements" section: added the mention of Chris Weider. + Rephrased the text that gives credit to the National Science Founda- + tion (it now says "The original material upon which this + + + +Expires: 23 August 1999 [Page 76] + +C LDAP API C LDAP Application Program Interface 23 February 1999 + + + specification is based was supported by ..." instead of "This origi- + nal material upon which this revision is based was based upon work + supported by ..." + + In the "Bibliography" section: Added a reference to RFC 1345 and + ANSI/ISO C. Updated the LDAPv3 TLS and Sorting references to point + to the latest revisions of those documents. + + "Appendix - Sample C LDAP API Code": added #include to the + sample code. Changed the code to demonstrate good error handling by + freeing all memory and calling ldap_unbind() before returning. + Replaced calls to exit() with return statements. Fixed improperly + rendered strings (by adding '\' characters to the nroff source for + this document so that '\t' and '\n' are correctly rendered). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Expires: 23 August 1999 [Page 77] + -- 2.39.5