LDAP API Overview

Lightweight Directory Access Protocol (LDAP) is an Internet protocol to access directory servers. The directories on the Internet may be "pure" LDAP directories; that is, they only communicate through LDAP, or they may be X.500 or other types of servers that allow access through LDAP. Access to servers that are not pure LDAP servers is accomplished through an LDAP gateway. Gateways from LDAP to other protocols also are common. Client programs that allow a user to access an LDAP directory are called LDAP clients. Applications that extract information from an LDAP directory are referred to as LDAP-enabled.

The LDAP client is part of the i5/OS^(TM). The LDAP client is used by i5/OS and customer applications for access to LDAP-enabled directories in the network. The directories being accessed may or may not be located on an i5/OS server. The applications access the LDAP client by using these client APIs. TCP/IP is always used to access remote directories, and the administrator can configure the connection to use the Secure Sockets Layer (SSL). Also, the administrator can select to use Kerberos.

The LDAP APIs are designed to provide a suite of functions that can be used to develop directory enabled applications. Directory-enabled applications typically connect to one or more directories and perform various directory-related operations, such as:

• Adding entries
• Searching the directory and obtaining the resulting list of entries
• Deleting entries
• Modifying entries
• Renaming entries

• Phone numbers
• E-mail addresses
• Fax numbers
• Mailing addresses

Increasingly, directories are being used to manage and publish other types of information, including:

• Configuration information
• Public key certificates (managed by certification authorities)
• Access control information
• Locating information (how to find a service)

The LDAP APIs provide for both synchronous and asynchronous access to a directory. Asynchronous access makes it easy for your application to do other work while waiting for the results of a potentially lengthy directory operation to be returned by the server.

Typical API Usage

The basic interaction is as follows. A connection is made to an LDAP server by calling ldap_init (or ldap_ssl_init, which is used to establish a secure connection over Secure Sockets Layer (SSL)).

An LDAP bind operation is performed by calling ldap_simple_bind or ldap_sasl_bind. The bind operation is used to authenticate to the directory server. Note that the LDAP V3 API and protocol permits the bind to be skipped, in which case the access rights associated with anonymous access are obtained.

Next, other operations are performed by calling one of the synchronous or asynchronous routines (that is, ldap_search_s or ldap_search followed by ldap_result).

Results returned from these routines are interpreted by calling the LDAP parsing routines, which include operations such as:

• ldap_first_entry, ldap_next_entry
• ldap_get_dn
• ldap_first_attribute, ldap_next_attribute
• ldap_get_values
• ldap_parse_result (new for LDAP V3)
• etc.

The LDAP connection is terminated by calling ldap_unbind.

The ldap_set_rebind_proc routine can be used to define the entry-point of a routine to be called when an LDAP bind operation needs to occur when handling a client referral to another server.

Displaying Results

Results obtained from the ldap search routines can be accessed by calling ldap_first_entry and ldap_next_entry to step through the entries returned, ldap_first_attribute and ldap_next_attribute to step through an entry's attributes, ldap_get_values to retrieve a given attribute's value, and then calling printf or some other display or usage method to display the values.

Uniform Resource Locators (URLS)

The ldap_is_ldap_url routines can be used to test a URL to see if it is an LDAP URL, to parse LDAP URLs into their component pieces, and to initiate searches directly using an LDAP URL.

Examples of these routines are ldap_url_parse, ldap_url_search_s, and ldap_is_ldap_url.

Secure Socket Layer (SSL) Support

The LDAP APIs have been extended to support connections that are protected by the Secure Socket Layer (SSL) protocol. This can be used to provide strong authentication between the client and server, as well as data encryption of LDAP messages that flow between the client and the LDAP server. The ldap_ssl_client_init() and ldap_ssl_init() APIs are provided to initialize the SSL function, and to create a secure SSL connection (respectively).

When using ldap_ssl_client_init(), the application ID used is QIBM_GLD_DIRSRV_CLIENT, identified as client application "Directory Services Client" in Digital Certificate Manager (DCM). To use i5/OS application IDs other than the default which have an association to a certificate store and a particular certificate in that store, the following i5/OS-specific APIs are provided:

Version 2 API

• ldap_app_ssl_start_np() (deprecated)

Version 3 API

• ldap_app_ssl_client_init_np()

When using ldap_ssl_init(), the server is not contacted until the connection is used; that is, by ldap_bind() or ldap_search(). If an SSL error occurs while trying to connect, the SSL error code can be retrieved for the connection with the ldap_get_option() API using the LDAP_OPT_EXT_ERROR option.