Lightweight Directory Access Protocol (LDAP)

Chapter 9-12

Lightweight Directory Access Protocol (LDAP)

Overview

The Lightweight Directory Access Protocol (LDAP) is an open industry standard that has evolved to provide an easy way to administer information that is to be shared among many distributed applications. 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.

LDAP defines a standard method for accessing and updating information in a directory. A directory is a specialized database that lists information about objects, arranged in some order, that give details about each object. A main difference between a directory and a general database is that a directory is accessed (read or searched) much more often than it is updated (written).

The information contained in an LDAP directory is based on an entry. 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 and how those values behave during directory operations. 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. A globally unique name for an entry, called a distinguished name (DN), is constructed by concatenating the sequence of RDNs from the entry up to the root of the tree.

The LDAP C API provides functions to authenticate, search for and retrieve information, modify information, and add and delete entries from the tree. A thorough knowledge of the LDAP directory and its format, as well as Domino administration of the LDAP server and directory, are necessary prerequisites to using this API. Please refer to the Domino Administration Help documentation for a complete description of LDAP administration.

*Note:
Starting with the HCL C API Toolkit 6.0.5/6.5.4, the ldap_xxx and ber_xxx function names have changed. You may still use the same ldap_xxx and ber_xxx function names in your source code, but they are subject to the macro substitutions in ldap.h. This was done to prevent collisions with other ldap implementations, for example when Domino DB2 is configured to authenticate using ldap. Only UNIX applications built prior to the HCL C API Toolkit 6.0.5/6.5.4 that use the ldap_xxx functions will be affected. These applications must be rebuilt in order to run on Domino 7.0 or later so that they use the new macro substitutions.

Getting Started

The Lightweight Directory Access Protocol (LDAP) is a C API that lets you write your own applications that will send requests to, and receive responses from, an LDAP Server.

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

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.
Authenticate to the LDAP server. The ldap_simple_bind and related functions support a variety of authentication methods.
Perform some LDAP operations and obtain some results. ldap_search and related functions return results which can be parsed by ldap_parse_result, ldap_first_entry, ldap_next_entry, etc.
Close the session. The ldap_unbind function closes the connection.

Please see the HCL C API Reference for a detailed description of any of the functions mentioned or implied in this chapter.

Synchronous vs. Asynchronous Operations

Operations can be performed either synchronously or asynchronously depending on which type of function is called. The names of the synchronous functions end in _s. For example, a synchronous search can be completed by calling ldap_search_s while 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 result code). The asynchronous routines make available to the caller 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 or ldap_abandon_ext. Note that there is no requirement that an LDAP API implementation not block when handling asynchronous API functions; the term "asynchronous" as used in this document refers to the fact that the sending of LDAP requests can be separated from the receiving of LDAP responses.

Obtaining results

Many of the LDAP API routines return result codes, some of which indicate local API errors and some of which are LDAP resultCodes that are
returned by servers. All of the result codes are non-negative integers. 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.

The LDAP C API function ldap_result is used to obtain the result of a previous asynchronously initiated operation. Note that depending on how it is called, ldap_result can 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" can 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. However, it MAY be tied to the session handle. Therefore, a chain of messages returned by calling ldap_result or by calling a synchronous search routine will never be affected by subsequent LDAP API calls except for ldap_msgfree (which is used to dispose of a chain of messages) and the unbind calls (which dispose of a session handle), or functions defined by extensions of this API.

Lightweight Basic Encoding Rules (LBER)

LBER is the Lightweight version of the Basic Encoding Rules (BER) for LDAP.

The LDAP C API provides functions to encode and decode BER encoded ASN.1 values. Abstract Syntax Notation One (ASN.1) is a language for defining standards.

Note that the LBER-related functions defined in this API all provide a method for determining success or failure but generally do not provide access to specific error codes. Therefore, applications that require precise error information when encoding or decoding ASN.1 values should not use these functions.

Please see the HCL C API Reference Database for a detailed description of any of the functions or data types mentioned or implied in this chapter.

Full LDAP Documentation

HCL C API Notes/Domino Reference

The HCL C API Notes/Domino Reference is a Domino database included as part of the HCL C API Toolkit for Domino and Notes. It documents the LDAP functions, data types, and symbolic values in detail.

Sample program

The sample program ldap_msc, located in the admin directory, is included as part of the HCL C API Toolkit for Domino and Notes. This program is intended to illustrate the basic practical usage of a cross section of the Lightweight Directory Assistance Protocol (LDAP) functions, data types and symbolic values, as implemented via a C API program.

Using the LDAP functionality of the C API Toolkit for Notes/Domino, this program will: