Up to Contents

Back to Copyright Notices

This document is based on the draft LDAPv3 API specification, to which revisions have been made to describe the features of the Innosoft LDAP Client SDK. The specification defines a C language application program interface to the Lightweight Directory Access Protocol (LDAP). It 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.

LDAP is the lightweight directory access protocol, described in RFC 2251 and RFC 2252 It can provide a lightweight frontend to the X.500 directory, 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 information 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 attribute (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 political, 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 RFC 2253.

Operations are provided to authenticate, search for and retrieve information, 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 functions.

An application generally uses the C LDAP API in four simple steps.

• Initialize an LDAP session with a default LDAP server. The ldap_init() function returns a handle to the session, allowing multiple connections to be open at once.
• Authenticate to the LDAP server. The ldap_bind() function and friends support a variety of authentication methods.
• Perform some LDAP operations and obtain some results. ldap_search() and friends return results which can be parsed by ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc.
• Close the session. The ldap_unbind() function closes the connection.

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 routines return an indication of the outcome of the operation (e.g, the constant LDAP_SUCCESS or some other error code). The asynchronous routines return the message id of the operation initiated. 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().

Results and errors are returned in an opaque structure called LDAPMessage. 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 routines in more detail.

LDAP version 3 servers may return referrals to other servers. By default, implementations of this API will attempt to follow referrals automatically for the application. This behavior can be disabled globally (using the ldap_set_option() call) or on a per-request basis through the use of a client control.

As in the LDAPv3 protocol itself, all DNs and string values that are passed into or produced by the C LDAP API are represented as UTF-8 characters.

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.

Changes from RFC 1823

Many new functions have been added to provide access to LDAPv3 features. In addition, there are three changes which are not backwards compatible with the earlier API.

• The internal layout of the LDAP structure is no longer exposed to users of the API. The ldap_get_option() and ldap_set_option() calls should be used to access fields of this structure.
• The ldap_modrdn() and ldap_modrdn_s() calls defined in RFC 1823 are incompatible with those of the University of Michigan LDAP 3.3 API. In this implementation they are replaced by the following calls:

            int ldap_modrdn2( 
                  LDAP *ld, 
                  char *dn, 
                  char *newrdn,
                  int deleteoldrdn 
            );
  
            int ldap_modrdn2_s( 
                  LDAP *ld, 
                  char *dn, 
                  char *newrdn,
                  int deleteoldrdn
            );
  
  

• The strings returned by ldap_first_attribute() and ldap_next_attribute() are no longer static, but are allocated on each call. They must be freed by the caller using ldap_memfree().

Up to Contents

Forward to Common Data Structures