+++ /dev/null
-
- Internet-Draft D. Byrne, IBM
- LDAP Extensions WG L. Poitou, Sun
- Intended Category: Standards Track E. Stokes, IBM
- Expires: 20 October 1998
-
- 20 April 1998
-
- Use of Aliases within LDAP
- <draft-byrne-ldap-alias-00.txt>
-
- STATUS OF THIS MEMO
-
- This document is an Internet Draft. Internet Drafts are
- working documents of the Internet Engineering Task Force
- (IETF), its Areas, and its Working Groups. Note that other
- groups may also distribute working documents as Internet
- Drafts.
-
- Internet Drafts are draft documents valid for a maximum of six
- months. Internet Drafts may be updated, replaced, or obsoleted
- by other documents at any time. It is not appropriate to use
- Internet Drafts as reference material or to cite them other
- than as a "working draft" or "work in progress."
-
- To view the entire list of current Internet-Drafts, please
- check the "1id-abstracts.txt" listing contained in the
- Internet-Drafts Shadow Directories on ftp.is.co.za (Africa),
- ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern
- Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East
- Coast), or ftp.isi.edu (US West Coast).
-
- Comments and suggestions on this document are encouraged.
- Comments on this document should be sent to the LDAPEXT
- working group discussion list:
-
- ietf-ldapext@netscape.com
-
- ABSTRACT
-
- This document describes the suggested behavior for aliases for
- LDAPv3 and above to improve LDAP server interoperability .
-
- The key words "MUST", "SHOULD", and "MAY" used in this
- document are to be interpreted as described in [Bradner97].
-
-
- 1. Objectives
-
-
- Aliases may be used within LDAP to reference entries anywhere
- within the directory tree. Conceptually, an alias is simply a
- pointer to the DIT entry it represents. It does not contain
- additional information about that entry; only the location of
- the entry.
-
- The behavior of the alias object within LDAP is not well-
- defined, both in creation of the alias object and the behavior
- when dereferencing the alias.
-
- For successful interoperability, the expected behavior of
- servers when encountering alias objects SHOULD be consistent.
-
- Additionally, it MUST be possible to use aliases without
- changing the LDAPv3 schema as defined in [Wahl] and without
- adding server-dependent data.
-
-
- 2. Schema Definition
-
-
- 2.1 Schema Expansion
-
- The alias objectclass definitions presented in the LDAPv3
- Schema [Wahl] are the basis for aliasing within ldap. The
- alias objectclass is a Structural objectclass with a single
- required attribute; the single valued aliasObjectName.
-
- This definition of the alias objectclass does not allow for
- any attribute other than 'aliasedObjectName' to be used as the
- naming attribute within the RDN. The resulting dn for the
- alias object must therefore be of the form
- "aliasedObjectName=<dn>, <rdn>, <rdn>..." This is not a
- user-friendly name for a directory entry, and quite possibly
- corrupts the naming hierarchy within the directory tree.
-
- In order to remain true the concept of an alias; that it is
- merely a pointer to another entry, an entry of objectclass
- alias SHOULD NOT be combined with any other objectclass. If
- multiple objectclasses are combined, it becomes possible to
- add information to the alias entry without violating the
- schema rules.
-
- While not explicitly specified as either a 'required' or
- 'may', any naming attribute MUST be allowed to form the RDN of
- the alias. Restricting the possible naming attributes would
- potentially corrupt the hierarchy. For example, it would be
- impossible to distinguish between a person alias and an
- organisation alias.
-
- 2.2 AliasObject Objectclass
-
- In order to create an alias object which can be appropriately
- named to that which it represents, the definition of the alias
- object MUST be expanded. A new objectclass must be defined
- which inherits from the current definition of alias but
- extends the attributes allowed within the RDN.
-
- ( 1.3.6.1.4.1.42.2.27.1.2.1
- NAME 'aliasObject'
- DESC objectclass for all alias objects
- SUP 'ALIAS'
- MAY *
- )
-
- The '*' allows any naming attribute to be used in forming the
- RDN of the object.
-
- For example, the following is a correct LDIF:
- dn: cn=John Doe, ou=myOrg, c=US
- objectclass: alias
- objectclass: aliasObject
- aliasedObjectName: cn=President, ou=myOrg, c=US
- cn: John Doe
-
- To prevent the alias from containing extra information about
- the object, the naming attribute SHOULD contain only a single
- value.
-
- For example, the following is not a correct LDIF:
- dn: cn=John Doe, ou=myOrg, c=US
- objectclass: alias
- objectclass: aliasObject
- aliasedObjectName: cn=President, ou=myOrg, c=US
- cn: John Doe
- cn: Doe
-
- Similarly, the following would not be a correct LDIF file
- because it adds extra information to the alias object.
-
- dn: cn=John Doe, ou=myOrg, c=US
- objectclass: alias
- objectclass: aliasObject
- aliasedObjectName: cn=President, ou=myOrg, c=US
- cn: John Doe
- title: President
-
- The naming attribute used to form the RDN of the object SHOULD
- reflect the naming attribute of the referenced object.
- However, there are some cases where the naming attribute MAY
- be different.
-
- Within the X.501 [ITU-T], the attribute used to described the
- aliased object is 'aliasedEntryName'. Since the OID for
- 'aliasedEntryName' and 'aliasedObjectName' are the same for
- both X.500 and LDAP, LDAP servers SHOULD treat the
- 'aliasedEntryName' as a synonym for 'aliasedObjectName'.
-
-
- 3. Alias Behavior
-
- In general alias objects SHOULD NOT be dereferenced during any
- operation other than search unless requested to do so by the
- client.
-
- Since an alias points to another section of the tree, it MUST
- NOT be possible to add an object under an alias object; alias
- objects MUST always be leaf nodes.
-
- During the dereferencing of aliases, a loop is detected if the
- server visits the same alias entry more than once. In this
- case a data integrity error has occurred and the server MUST
- return an error of 'aliasProblem'
-
- If an alias is dereferenced, and the resulting directory entry
- does not exists, a data integrity problem has occurred, and
- the server MUST return an error code of
- 'aliasDereferencingProblem'
-
- If the base entry for an ldapsearch is an alias, and alias
- dereferencing is set to either derefFindBaseObj, or
- derefAlways, the base entry MUST be dereferenced before the
- search is performed. The new base for the search will become
- the entry to which the alias resolves. The search is then
- performed.
-
- If multiple aliases are chained, the alias for the first
- object MUST resolve to the last entry in the chain. For
- example, A, B, and C are alias objects. If A points to B which
- points to C which points to D, A resolves to D when
- dereferencing the alias.
-
- If an alias is dereferenced as part of a search, the alias
- entry itself SHOULD NOT be returned as part of the search.
-
- If an alias matches the search filter, and dereferencing is
- set to 'searching' or 'always', the dereferenced object SHOULD
- be returned, even if it does not match the filter.
-
- If the alias is not dereferenced during the search, and it
- matches the filter, then it SHOULD be returned within the
- search result.
-
- Each directory object matching a filter SHOULD be returned
- only once during a search. If an entry is found twice because
- of aliases pointing to a part of the tree already searched,
- the entry SHOULD NOT be returned to the client a second time.
-
- 4. Scenarios
-
- Using the following LDIF, the scenarios would return the
- expected information as follows:
-
- dn: c=myCountry
- c: myCountry
- objectclass: country
-
- dn: ou=Area1, c=myCountry
- ou: Area1
- aliasedObjectName: o=myCorporation, c=myCountry
- objectclass: alias
- objectclass:aliasObject
-
- dn: o=myCorporation, c=myCountry
- ou: myCorporation
- objectclass:organization
-
- dn: cn=President, o=myCorporation, c=myCountry
- cn: President
- aliasObjectName: cn=John Doe, o=myCorporation, c=myCountry
- objectclass: alias
- objectclass: aliasObject
-
- dn: cn=John Doe, o=myCorporation, c=myCountry
- cn: John Doe
- objectclass: person
-
-
- c = myCountry
- / |
- ou = Area1 -----> o = myCorporation
- | \
- cn=President ---> cn = John Doe
-
- Performing a base search of 'ou = Area1, c=myCountry' with a
- filter of 'objectclass=aliasObject'
- NeverDerefAlias would return 'ou=Area1, c=myCountry'
- DerefFinding would return 'cn=President, o=myCorporation,
- c=myCountry'
- DerefSearching would return 'o=myCorporation,
- c=myCountry'
- DerefAlways would return 'cn=John Doe, o=myCorporation,
- c=myCountry'
-
- Performing a one level search of 'c=myCountry' with a filter
- of 'ou = * '
- NeverDerefAlias would return 'ou=Area1, c=myCountry'
- DerefFinding would return 'ou=Area1, c=myCountry'
- DerefSearching would return 'o=myCorporation,
- c=myCountry'
- DerefAlways would return ' o=myCorporation, c=myCountry'
-
- Performing a full tree search of 'c=myCountry' with a filter
- of ' cn = President '
- NeverDerefAlias would return 'cn=President, o=myCorporation,
- c=myCountry'
- DerefFinding would return 'cn=President, o=myCorporation,
- c=myCountry'
- DerefSearching would return 'cn=John Doe, o=myCorporation,
- c=myCountry'
- DerefAlways would return 'cn=John Doe, o=myCorporation,
- c=myCountry'
-
-
- 6. Security Considerations
-
- Permissions to dereferencing an alias, adding, deleting or
- returning alias entries are decided by the directory server's
- ACL administration policy.
-
-
- 7. References
-
- [LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
-
- [Whal] M.Wahl, A, Coulbeck, T. Howes, S. Kille, "Lightweight
- Directory Access Protocol (v3)": Attribute Syntax Definitions,
- RFC 2252, December 1997.
-
- [Bradner97] Bradner, Scott, "Key Words for use in RFCs to
- Indicate Requirement Levels", RFC 2119.
-
- [ITU-T] ITU-T Rec. X.501, "The Directory: Models", 1993
-
-
- AUTHOR(S) ADDRESS
-
-
- Debbie Byrne
- IBM
- 11400 Burnet Rd
- Austin, TX 78758
- USA
- mail-to: djbyrne@us.ibm.com
- phone: +1 512 838 1930
-
- Ludovic Poitou
- Sun Microsystems
- 32, Chemin du vieux Chene
- 38240 Meylan
- France
- Phone: +33.(0)4.76.41.42.12
- email: ludovic.poitou@france.sun.com
-
- Ellen Stokes
- IBM
- 11400 Burnet Rd
- Austin, TX 78758
- USA
- mail-to: stokes@austin.ibm.com
- phone: +1 512 838 3725
-
-
+++ /dev/null
-
-
-
-
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-INTERNET-DRAFT Change Record Object Class 11 March 1998
-
-
- 7) Updated references to current drafts/proposed standards documents.
-
-Security Considerations
-
- Servers implementing this scheme MUST NOT allow the "changes"
- attribute to be generally readable. The "changes" attribute contains
- all modifications made to an entry, and some changes may contain
- sensitive data, e.g. passwords.
-
- If a server does allow read access on the "changes: attribute to a
- particular bound DN, then that DN should be trusted. For example, two
- cooperating servers may exchange the password for some DN which is
- granted read access to the "changes" attribute of the changeLog. This
- would allow one server to retrieve changes and apply them directly to
- its database.
-
- In situations where the "changes" attribute is not readable by a client,
- that client may still use the entries in the changeLog to construct a
- list of entry DNs which are known to have changed since the last time
- the client synchronized. The client may then read each of those entries,
- subject to whatever access control is in effect on the server,
- and update its local copy of each entry.
-
- Servers implementing this scheme should disallow write access to the
- changelog container object and all entries contained within.
-
-
-
-Acknowledgements
-
- This material is based in part upon work supported by the National
- Science Foundation under Grant No. NCR-9416667.
-
-
-
-References
-
- [1] Good, G., "The LDAP Data Interchange Format", INTERNET-DRAFT
- draft-good-ldap-ldif-03.txt, Netscape Communications Corp., March 1997,
- <URL:ftp://ftp.ietf.org/internet-drafts/draft-good-ldap-ldif-03.txt>
-
- [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
- Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp.,
- ISODE Consortium, July, 1997,
- <URL:ftp://ftp.isi.edu/in-notes/rfc2251.txt>
-
- [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
- Levels", Harvard University, RFC 2119, March 1997,
-
-
-
-Good March 11, 1998 [Page 7]
-\f
-INTERNET-DRAFT Change Record Object Class 11 March 1998
-
-
- <URL:http://ds.internic.net/rfc/rfc2119.txt>
-
-
-Author's Address
-
- Gordon Good
- Netscape Communications Corp.
- 501 E. Middlefield Rd.
- Mailstop MV068
- Mountain View, CA 94043, USA
- Phone: +1 415 937-3825
- EMail: ggood@netscape.com
-
- This Internet Draft expires October 1st, 1998.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Good March 11, 1998 [Page 8]
-\f
+++ /dev/null
-
-
-
-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]
-\f
-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]
-\f
-INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
-
-
- ldif-content = version-spec 1*SEP
- ldif-attrval-record *(1*SEP ldif-attrval-record)
- ldif-changes = version-spec 1*SEP
- ldif-change-record *(1*SEP ldif-change-record)
- ldif-attrval-record = dn-spec SEP 1*(attrval-spec SEP)
- ldif-change-record = dn-spec SEP 1*(changerecord SEP)
-
- version-spec = "version:" *SPACE version-number
- version-number = 1*DIGIT ; version-number MUST be "1" for the
- ; LDIF format described in this document.
-
- dn-spec = ("dn:" *SPACE dn) / ("dn::" *SPACE base64-dn)
- dn = <a distinguished name, as defined in RFC 2253 [3]>
- base64-dn = <a dn which has been base-64 encoded, as
- defined in RFC 1521 [5]>
- rdn = <a relative distinguished name, as defined in RFC
- 2253 [3]>
- base64-rdn = <an rdn which has been base-64 encoded, as
- defined in RFC 1521 [5]>
-
- attrval-spec = attribute-description ((":") / (":" *SPACE value) /
- ("::" *SPACE base64-value) /
- (":<" *SPACE url))
- url = <a Uniform Resource Locator, as defined in [6]>
- ; (See Note 6, below)
- attribute-description = <an attribute description, as defined in [4].
- An attribute description MAY NOT contain a
- colon ":">
- value = 1*safe-initval *safe
- ; (See Note 9, below)
- safe = <any value except CR or LF>
- safe-initval = <any value except CR, LF, colon (":", ASCII 58
- decimal), SPACE, and less-than ("<" , ASCII 60
- decimal)>
- base64-value = <base-64-encoded value, as defined in RFC 1521 [5]>
-
- changerecord = change-add / change-delete / change-modify /
- change-moddn
- change-add = "changetype:" *SPACE "add" 1*(SEP attrval-spec)
- change-delete = "changetype:" *SPACE "delete"
- change-moddn = "changetype:" *SPACE ("modrdn" / "moddn") SEP
- ("newrdn:" *SPACE rdn /
- "newrdn::" *SPACE base-64-rdn) SEP
- "deleteoldrdn:" *SPACE ("0" / "1")
- 0,1*(SEP (("newsuperior:" *SPACE dn) /
- ("newsuperior::" *SPACE base-64-dn)))
- change-modify = "changetype:" *SPACE "modify" 1*(SEP mod-spec)
- mod-spec = mod-add-spec / mod-delete-spec / mod-replace-spec
-
-
-
-Good February 22, 1999 [Page 3]
-\f
-INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
-
-
- mod-add-spec = "add:" *SPACE attribute-description
- 1*(SEP attrval-spec) SEP "-"
- mod-delete-spec = "delete:" *SPACE attribute-description
- *(SEP attrval-spec) SEP "-"
- mod-replace-spec = "replace:" *SPACE attribute-description
- *(SEP attrval-spec) SEP "-"
- SPACE = <ASCII SP, space>
- SEP = (CR LF / LF)
- CR = <ASCII CR, carriage return>
- LF = <ASCII LF, line feed>
- DIGIT = <any ASCII decimal digit (60 - 71 decimal) >
-
-
- Notes on LDIF Syntax
-
- 1) For the LDIF format described in this document, the version number
- MUST be "1". If the version number is absent, implementations MAY
- choose to interpret the contents as an older LDIF file format,
- supported by the University of Michigan ldap-3.3 implementation [8].
-
- 2) Any line, including comment lines, in an LDIF file MAY be wrapped
- by inserting a line separator (SEP) and a SPACE. Any line which
- begins with a single space MUST be treated as a continuation of the
- previous line. When joining folded lines, exactly one space character
- at the beginning of each continued line must be discarded.
-
- 3) Any line which begins with a pound-sign ("#", ASCII 35) is a
- comment line, and MUST be ignored when parsing an LDIF file.
-
- 4) Any dn or value which contains characters other than those defined
- as "safe", or begins with a character other than those defined as
- "safe-initval", above, MUST be base-64 encoded. Other values MAY be
- base-64 encoded.
-
- 5) To represent a zero-length attribute value, use an attrval-spec of
- "attribute-description:". For example, "seeAlso:" represents a
- zero-length "seeAlso" attribute value.
-
- 6) When a URL is specified in an attrval-spec, the following
- conventions apply:
- a) Implementations SHOULD support the file:// URL format. The
- contents of the referenced file are to be included verbatim
- in the interpreted output of the LDIF file.
- b) Implementations MAY support other URL formats. The semantics
- associated with each supported URL will be documented in
- an associated Applicability Statement.
-
- 7) While it is permissible for character values larger than 126 to be
-
-
-
-Good February 22, 1999 [Page 4]
-\f
-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]
-\f
-INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
-
-
- cn:Barbara J Jensen
- cn:Babs Jensen
- sn:Jensen
- uid:bjensen
- telephonenumber:+1 408 555 1212
- description:Babs is a big sailing fan, and travels extensively in search of
- perfect sailing conditions.
- title:Product Manager, Rod and Reel Division
-
- Example 3: A file containing a base-64-encoded value
-
- version: 1
- dn: cn=Gern Jensen, ou=Product Testing, dc=airius, dc=com
- objectclass: top
- objectclass: person
- objectclass: organizationalPerson
- cn: Gern Jensen
- cn: Gern O Jensen
- sn: Jensen
- uid: gernj
- telephonenumber: +1 408 555 1212
- description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJ
- hc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0ICh
- hIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu
-
- Example 4: A file containing an entries with UTF-8-encoded attribute
- values, including language tags. Comments indicate the contents
- of UTF-8-encoded attributes and distinguished names.
-
- version: 1
- dn:: b3U95Za25qWt6YOoLG89QWlyaXVz
- # dn:: ou=<JapaneseOU>,o=Airius
- objectclass: top
- objectclass: organizationalUnit
- ou:: 5Za25qWt6YOo
- # ou:: <JapaneseOU>
- ou;lang-ja:: 5Za25qWt6YOo
- # ou;lang-ja:: <JapaneseOU>
- ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2
- # ou;lang-ja:: <JapaneseOU_in_phonetic_representation>
- ou;lang-en: Sales
- description: Japanese office
-
- dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz
- # dn:: uid=<uid>,ou=<JapaneseOU>,o=Airius
- userpassword: {SHA}O3HSv1MusyL4kTjP+HKI5uxuNoM=
- objectclass: top
- objectclass: person
-
-
-
-Good February 22, 1999 [Page 6]
-\f
-INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
-
-
- objectclass: organizationalPerson
- objectclass: inetOrgPerson
- uid: rogasawara
- mail: rogasawara@airius.co.jp
- givenname;lang-ja:: 44Ot44OJ44OL44O8
- # givenname;lang-ja:: <JapaneseGivenname>
- sn;lang-ja:: 5bCP56yg5Y6f
- # sn;lang-ja:: <JapaneseSn>
- cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
- # cn;lang-ja:: <JapaneseCn>
- title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw==
- # title;lang-ja:: <JapaneseTitle>
- preferredlanguage: ja
- givenname:: 44Ot44OJ44OL44O8
- # givenname:: <JapaneseGivenname>
- sn:: 5bCP56yg5Y6f
- # sn:: <JapaneseSn>
- cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
- # cn:: <JapaneseCn>
- title:: 5Za25qWt6YOoIOmDqOmVtw==
- # title:: <JapaneseTitle>
- givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8
- # givenname;lang-ja;phonetic::
- <JapaneseGivenname_in_phonetic_representation_kana>
- sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ
- # sn;lang-ja;phonetic:: <JapaneseSn_in_phonetic_representation_kana>
- cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA==
- # cn;lang-ja;phonetic:: <JapaneseCn_in_phonetic_representation_kana>
- title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg==
- # title;lang-ja;phonetic:: <JapaneseTitle_in_phonetic_representation_kana>
- givenname;lang-en: Rodney
- sn;lang-en: Ogasawara
- cn;lang-en: Rodney Ogasawara
- title;lang-en: Sales, Director
-
- Example 5: A file containing a reference to an external file
-
- version: 1
- dn: cn=Horatio Jensen, ou=Product Testing, dc=airius, dc=com
- objectclass: top
- objectclass: person
- objectclass: organizationalPerson
- cn: Horatio Jensen
- cn: Horatio N Jensen
- sn: Jensen
- uid: hjensen
- telephonenumber: +1 408 555 1212
- jpegphoto:< file:///usr/local/directory/photos/hjensen.jpg
-
-
-
-Good February 22, 1999 [Page 7]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
-
-
- 4) Moved this section (differences between draft versions) to an
- appendix.
-
- 5) Updated examples to use "dc=airius, dc=com" instead of "o=Ace
- Industry, c=US"
-
- 6) Cleaned up references section.
-
-
-Acknowledgments
-
- The LDAP Interchange Format was developed as part of the University
- of Michigan LDAP reference implementation, and was developed by Tim
- Howes, Mark Smith, and Gordon Good. It is based in part upon work
- supported by the National Science Foundation under Grant No. NCR-
- 9416667.
-
-
-References
-
-
- [1] Howes, T., Smith, M., "A MIME Content-Type for Directory Infor-
- mation", RFC 2425, September 1998,
- <URL:http://www.ietf.org/rfc/rfc2245.txt>
-
- [2] Crocker, D.H., "Standard for the Format of ARPA Internet Text
- Messages", RFC 822, August 1982,
- <URL:http://ds.internic.net/rfc/rfc822.txt>
-
- [3] Wahl, M., Kille, S., Howes, T., "A String Representation of Dis-
- tinguished Names", RFC 2253,
- <URL:http://www.ietf.org/rfc/rfc2253.txt>
-
- [4] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
- Protocol (v3)", RFC 2251, July, 1997,
- <URL:ftp://www.ietf.org/rfc/rfc2251.txt>
-
- [5] Borenstein, N., Freed, N., "MIME (Multipurpose Internet Mail
- Extensions) Part One: Mechanisms for Specifying and Describing
- the Format of Internet Message Bodies", section 5.2, "Base64
- Content-Transfer-Encoding", RFC 1521, December 1993,
- <URL:http://ds.internic.net/rfc/rfc1521.txt>
-
- [6] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
- Locators (URL)", RFC 1738, December 1994,
- <URL:http://ds.internic.net/rfc/rfc1738.txt>
-
- [7] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
-
-
-
-Good February 22, 1999 [Page 11]
-\f
-INTERNET-DRAFT LDAP Data Interchange Format 22 February 1999
-
-
- Levels", Harvard University, RFC 2119, March 1997,
- <URL:http://ds.internic.net/rfc/rfc2119.txt>
-
- [8] The SLAPD and SLURPD Administrators Guide. University of Michi-
- gan, April 1996. <URL:
- http://www.umich.edu/~dirsvcs/ldap/doc/guides/slapd/toc.html>
-
-
-
-Author's Address
-
- Gordon Good
- Netscape Communications Corp.
- 501 E. Middlefield Rd.
- Mailstop MV068
- Mountain View, CA 94043, USA
- Phone: +1 650 937-3825
- EMail: ggood@netscape.com
-
- This Internet Draft expires August 22nd, 1999.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Good February 22, 1999 [Page 12]
-\f
+++ /dev/null
-
-
-
-
-
-
-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
- <draft-ietf-ldapext-ldap-c-api-02.txt>
-
-
-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 <ietf-ldapext@netscape.com>. 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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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 <ldap.h>
-
- 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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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 <draft-ietf-ldapext-sorting-01.txt>, 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 <draft-ietf-ldapext-ldapv3-
- tls-04.txt>, November 1998.
-
-[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
-
-
-
-Expires: 23 August 1999 [Page 65]
-\f
-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]
-\f
-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 <stdio.h>
- #include <ldap.h>
-
- 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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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]
-\f
-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 <stdio.h> 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]
-\f
+++ /dev/null
-Network Working Group M. Smith, Editor
-INTERNET-DRAFT Netscape Communications Corp.
-Intended Category: Standards Track T. Howes
-Obsoletes: RFC 1823 Netscape Communications Corp.
-Expires: 2 December 1999 A. Herron
- Microsoft Corp.
- M. Wahl
- Innosoft International, Inc.
- A. Anantha
- Microsoft Corp.
-
-
- 2 June 1999
-
- The C LDAP Application Program Interface
- <draft-ietf-ldapext-ldap-c-api-03.txt>
-
-
-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 <ietf-ldapext@netscape.com>. 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: 2 December 1999 [Page 1]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 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......................9
-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.......................................20
-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............................................29
-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: 2 December 1999 [Page 2]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-10.13. Deleting an entry...........................................38
-10.14. Extended Operations.........................................39
-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.............................46
-15. Parsing Search Results.........................................47
-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............................66
-23. Appendix B - Namespace Consumed By This Specification..........68
-24. Appendix C - Summary of Requirements for API Extensions........68
-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.........................................69
-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. Changes to the berval structure.............................71
-25.8. API Specification Clarified.................................72
-25.9. Deprecated Functions........................................72
-26. Appendix E - Data Types and Legacy Implementations.............72
-27. Appendix F - Changes Made Since Last Document Revision.........73
-27.1. API Changes.................................................73
-27.2. Editorial Changes...........................................74
-28. Appendix G - Changes Made Since draft-ietf-ldapext-ldap-c-api-.74
-28.1. API Changes.................................................74
-28.2. Editorial changes...........................................75
-
-Expires: 2 December 1999 [Page 3]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 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: 2 December 1999 [Page 4]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 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: 2 December 1999 [Page 5]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 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 <ldap.h>
-
- 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: 2 December 1999 [Page 6]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 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;
-
- typedef ber_len_t; /* actual definition is implementation-specific */
-
- typedef ber_tag_t; /* actual definition is implementation-specific */
-
- struct berval {
- ber_len_t 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
-
-
-
-Expires: 2 December 1999 [Page 7]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-referrals.
-
-The LDAPMessage structure is an opaque data type that is used to return
-entry, reference, result, and error information. An LDAPMessage struc-
-ture 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 ber_len_t type is an unsigned integral data type that is large
-enough to contain the length of the largest piece of data supported by
-the API implementation. Similarly, the ber_tag_t type is an unsigned
-integral data type that is large enough to hold the largest BER tag sup-
-ported by the API implementation. Both of these types should be at
-least 32 bits in size. See the appendix "Data Types and Legacy Imple-
-mentations" for additional considerations.
-
-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
-
-
-
-Expires: 2 December 1999 [Page 8]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
- #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:
-
-
-
-Expires: 2 December 1999 [Page 9]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- #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:
-
- #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 */
-
-
-
-Expires: 2 December 1999 [Page 10]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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.
-
-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
-
-
-
-Expires: 2 December 1999 [Page 11]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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:
-
- #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).
-
-
-
-Expires: 2 December 1999 [Page 12]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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)
- 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
-
-
-
-Expires: 2 December 1999 [Page 13]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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:
-
- LDAP *ldap_open(
- const char *hostname,
- int portno
- );
-Unlike ldap_init(), ldap_open() attempts to make a server connection
-before returning to the caller.
-
-
-
-Expires: 2 December 1999 [Page 14]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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.
-
-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
-
-
-
-Expires: 2 December 1999 [Page 15]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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 *
-
- 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.
-
-
-
-Expires: 2 December 1999 [Page 16]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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:
- 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
-
-
-
-Expires: 2 December 1999 [Page 17]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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
- 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)
-
-
-
-Expires: 2 December 1999 [Page 18]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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)
- Type for invalue parameter: int *
-
- Type for outvalue parameter: int *
-
- Description:
- The code of the most recent LDAP error that occurred for
-
-
-
-Expires: 2 December 1999 [Page 19]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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.
-
-
-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
-
-
-
-Expires: 2 December 1999 [Page 20]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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.
-
-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.
-
-
-
-Expires: 2 December 1999 [Page 21]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-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(
-
-
-
-Expires: 2 December 1999 [Page 22]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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 );
-
- 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.
-
-
-
-Expires: 2 December 1999 [Page 23]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-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.
-
-
-
-
-Expires: 2 December 1999 [Page 24]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-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.
-
-
-
-
-
-
-Expires: 2 December 1999 [Page 25]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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,
- const char *filter,
- char **attrs,
- int attrsonly
- );
-
- int ldap_search_s(
- LDAP *ld,
- const char *base,
- int scope,
- const char *filter,
-
-
-
-Expires: 2 December 1999 [Page 26]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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
- 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.
-
-
-
-Expires: 2 December 1999 [Page 27]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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.
-
-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
-
-
-
-Expires: 2 December 1999 [Page 28]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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 addi-
-tional parameter specifying a local timeout for the search. The local
-search timeout is used to limit the amount of time the API implementa-
-tion 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
-
-
-
-Expires: 2 December 1999 [Page 29]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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,
- const char *dn,
- const char *attr,
- const char *value
- );
-
- int ldap_compare_s(
- LDAP *ld,
- const char *dn,
- const char *attr,
- const char *value
- );
-
-
-
-Expires: 2 December 1999 [Page 30]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-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.
-
-
-
-Expires: 2 December 1999 [Page 31]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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(
- LDAP *ld,
- const char *dn,
- LDAPMod **mods
- );
-
- int ldap_modify_s(
- LDAP *ld,
- const char *dn,
- LDAPMod **mods
- );
-
-Parameters are:
-
-ld The session handle.
-
-
-
-Expires: 2 December 1999 [Page 32]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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.
-
-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
-
-
-
-Expires: 2 December 1999 [Page 33]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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,
- 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,
-
-
-
-Expires: 2 December 1999 [Page 34]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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.
-
-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)
-
-
-
-Expires: 2 December 1999 [Page 35]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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:
-
- 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,
-
-
-
-Expires: 2 December 1999 [Page 36]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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.
-
-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(),
-
-
-
-Expires: 2 December 1999 [Page 37]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
- );
-
- int ldap_delete(
- LDAP *ld,
- const char *dn
- );
-
- int ldap_delete_s(
- LDAP *ld,
- const char *dn
- );
-
-Parameters are:
-
-ld The session handle.
-
-
-
-Expires: 2 December 1999 [Page 38]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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.
-
-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 *requestoid,
- struct berval *requestdata,
-
-
-
-Expires: 2 December 1999 [Page 39]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- LDAPControl **serverctrls,
- LDAPControl **clientctrls,
- int *msgidp
- );
-
- int ldap_extended_operation_s(
- LDAP *ld,
- const char *requestoid,
- struct berval *requestdata,
- 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() func-
- tion. 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
-
-
-
-Expires: 2 December 1999 [Page 40]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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.
-
-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.
-
-
-
-Expires: 2 December 1999 [Page 41]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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,
- 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
-
-
-
-Expires: 2 December 1999 [Page 42]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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)
- 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
-
-
-
-Expires: 2 December 1999 [Page 43]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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(
- 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
-
-
-
-Expires: 2 December 1999 [Page 44]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- );
-
- 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
- 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
-
-
-
-Expires: 2 December 1999 [Page 45]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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
-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
-
-
-
-Expires: 2 December 1999 [Page 46]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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().
-
-
-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.
-
-
-
-
-
-
-
-Expires: 2 December 1999 [Page 47]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-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().
-
-
-
-
-Expires: 2 December 1999 [Page 48]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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".
-
-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.
-
-
-
-
-Expires: 2 December 1999 [Page 49]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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 );
-
- 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.
-
-
-
-Expires: 2 December 1999 [Page 50]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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 );
-
- 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().
-
-
-
-Expires: 2 December 1999 [Page 51]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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(
- 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().
-
-
-
-Expires: 2 December 1999 [Page 52]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
- 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
-
-
-
-Expires: 2 December 1999 [Page 53]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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 {
- ber_len_t bv_len;
- char *bv_val;
- };
-
-As defined earlier in the section "Common Data Structures", a struct
-berval contains an arbitrary sequence of bytes and an indication of its
-length. The bv_len element is an unsigned integer. The bv_val is not
-necessarily zero-terminated. Applications may allocate their own berval
-structures.
-
-As defined earlier in the section "Common Data Structures", the BerEle-
-ment 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
-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
-
-
-
-Expires: 2 December 1999 [Page 54]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-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().
-
-
-
-
-Expires: 2 December 1999 [Page 55]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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 a ber_tag_t specifying the tag to
- override the next element to be written to the ber. This works
- across calls. The integer tag value must contain the tag class,
- constructed bit, and tag value. For example, a tag of "[3]" for
- a constructed 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.
-
-'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.
-
-
-
-Expires: 2 December 1999 [Page 56]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-'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.
-
-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.
-
-
-
-
-Expires: 2 December 1999 [Page 57]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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) {
- goto done;
- }
-
- rc = ber_flatten(ber,bvPtr);
-
- done:
- ber_free(ber,1);
- return rc;
- }
-
-
-
-
-Expires: 2 December 1999 [Page 58]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-16.4. Decoding
-
-The following two symbols are available to applications.
-
- #define LBER_ERROR (ber_tag_t)0xffffffff
- #define LBER_DEFAULT (ber_tag_t)0xffffffff
-
- 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.
-
- ber_tag_t 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.
-
-'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
-
-
-
-Expires: 2 December 1999 [Page 59]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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 a ber_len_t * argument,
- which will point to the length (in bits) of the bitstring
- returned. ldap_memfree must be called to free the bitstring.
- The tag of the element must indicate the primitive form (con-
- structed 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
- 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.
-
- ber_tag_t ber_peek_tag( const BerElement *ber,
-
-
-
-Expires: 2 December 1999 [Page 60]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- ber_len_t *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.
-
- ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *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.
-
- ber_tag_t ber_first_element( BerElement *ber,
- ber_len_t *lenPtr, char **opaquePtr );
-
- ber_tag_t ber_next_element( BerElement *ber,
- ber_len_t *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:
-
- 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 {
-
-
-
-Expires: 2 December 1999 [Page 61]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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;
- ber_len_t len;
- ber_tag_t 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);
-
- if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
- char *opaque;
- ber_tag_t tag;
-
- for (tag = ber_first_element(ber,&len,&opaque);
- tag != LBER_DEFAULT;
- tag = ber_next_element (ber,&len,opaque)) {
-
-
-
-
-Expires: 2 December 1999 [Page 62]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- ber_len_t tlen;
- ber_tag_t ttag;
- 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,"}");
-
- ber_free(ber,1);
-
- return rc;
- }
-
-
-
-
-
-Expires: 2 December 1999 [Page 63]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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 Stan-
-dards 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
-
-
-
-Expires: 2 December 1999 [Page 64]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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 <draft-ietf-ldapext-sorting-01.txt>, 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 <draft-ietf-ldapext-ldapv3-
- tls-04.txt>, November 1998.
-
-[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
- 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.
-
-
-
-
-Expires: 2 December 1999 [Page 65]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
- +1 425 882-8080
- anoopa@microsoft.com
-
-
-22. Appendix A - Sample C LDAP API Code
-
- #include <stdio.h>
- #include <ldap.h>
-
-
-
-
-Expires: 2 December 1999 [Page 66]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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 );
- 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 );
-
-
-
-Expires: 2 December 1999 [Page 67]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- 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
- 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
-
-
-
-Expires: 2 December 1999 [Page 68]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-appendix 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 absence of the extension
-at compile time and also test the version or level of the extension pro-
-vided by an API implementation.
-
-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.
-
-
-
-
-Expires: 2 December 1999 [Page 69]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
- 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
-
-
-
-
-
-
-
-Expires: 2 December 1999 [Page 70]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-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
-were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
-
-
-25.7. Changes to the berval structure
-
-In RFC 1823, the bv_len element of the berval structure was defined as
-an unsigned long. In this specification, the type is implementation-
-specific, although it must be an unsigned integral type that is at least
-32 bits in size. See the appendix "Data Types and Legacy
-
-
-
-Expires: 2 December 1999 [Page 71]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-Implementations" for additional considerations.
-
-
-25.8. 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.9. 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 - Data Types and Legacy Implementations
-
-The data types associated with the length of a ber value (ber_len_t) and
-the tag (ber_tag_t) have been defined in this specification as unsigned
-integral types of implementation-specific size. This was done so that
-
-
-
-Expires: 2 December 1999 [Page 72]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-source and binary compatibility of the C LDAP API can be maintained
-across ILP32 environments (where int, long, and pointers are all 32 bits
-in size) and LP64 environments (where ints remain 32 bits but longs and
-pointers grow to 64 bits).
-
-In older implementations of the C LDAP API, such as those based on RFC
-1823, implementors may have chosen to use an unsigned long for these
-types. If a long data type was used, a port of an application to a 64-
-bit operating system using the LP64 data model would find the size of
-the BER length and tag types used by the C LDAP API to increase. Also,
-if the legacy implementation had chosen to implement the types as an
-unsigned int, adoption of a specification that mandated use of unsigned
-longs would cause a source incompatibility in an LP64 application. By
-using an implementation-specific data type, the C LDAP API implementa-
-tion is free to choose the correct data type and the ability to maintain
-source compatibility.
-
-For example, suppose a legacy implementation chose to define the return
-value of ber_skip_tag() as an unsigned long but wishes to have the
-library return a 32-bit quantity in both ILP32 and LP64 data models.
-The following typedefs for ber_tag_t will provide a fixed sized data
-structure while preserving existing ILP32 source -- all without generat-
-ing compiler warnings:
- #if defined(_LP64)
- typedef unsigned int ber_tag_t;
- #else
- typedef unsigned long ber_tag_t;
- #endif
-The above assumes that the the preprocessor symbol _LP64 is defined if
-and only if the code is being compiled in an LP64 environment. Similar
-code can be used to define an appropriate ber_len_t type.
-
-
-27. Appendix F - Changes Made Since Last Document Revision
-
-The previous version of this document was draft-ietf-ldapext-ldap-c-
-api-02.txt, dated 23 February, 1999. This appendix lists all of the
-changes made to that document to produce this one.
-
-27.1. API Changes
-
- Types: added the ber_len_t and ber_tag_t implementation-specific
- unsigned integral data types to support source and binary compatibil-
- ity between ILP32 and LP64 environments. Changes were made to the
- "Common Data Structures" and "Encoded ASN.1 Value Manipulation" sec-
- tions of this document.
-
-
-
-
-
-Expires: 2 December 1999 [Page 73]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
-27.2. Editorial Changes
-
- General: Added Appendix E - Data Types and Legacy Implementations;
- moved list of recent document changes to Appendices F and G.
-
- "Retrieving Information During Execution" section: removed misplaced
- ldapai_vendor_name and ldapai_vendor_version from the LDAPAPI-
- FeatureInfo structure description.
-
- "Extended Operations" section: changed the names of the "requestoid"
- and "requestdata" parameters in the function prototypes to match the
- parameter descriptions. The old names were "exoid" and "exdata."
-
- Appendix D - "Appendix D - Known Incompatibilities with RFC 1823 ":
- Added note about changes to the berval structure.
-
-
-28. Appendix G - Changes Made Since draft-ietf-ldapext-ldap-c-api-
-01.txt
-
-The version of this document that preceded draft-ietf-ldapext-ldap-c-
-api-02.txt 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 draft-ietf-ldapext-ldap-c-api-02.txt.
-
-
-28.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"
-
-
- 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 pub-
- lication 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.
-
-
-
-
-Expires: 2 December 1999 [Page 74]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- "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.
-
- "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.
-
-
-28.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.
-
-
-
-
-Expires: 2 December 1999 [Page 75]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- "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.
-
- "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.
-
-
-
-
-Expires: 2 December 1999 [Page 76]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- "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
- 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).
-
-
-
-Expires: 2 December 1999 [Page 77]
-
-
-C LDAP API C LDAP Application Program Interface 2 June 1999
-
-
- "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 specifica-
- tion is based was supported by ..." instead of "This original
- material upon which this revision is based was based upon work sup-
- ported 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 <stdio.h> 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: 2 December 1999 [Page 78]
-
-
projects / openldap / commitdiff