Lightweight Directory Access Protocol (LDAP)

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 are also 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 OS/400. The LDAP client is used by OS/400 and customer applications for access to LDAP-enabled directories in the network. The directories being accessed may or may not be located on an AS/400. 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 either use the Secure Sockets Layer (SSL) or not.

Note: To use the Directory Services APIs, you need to install the OS/400 Directory Services feature. You can install this feature by using the GO LICPGM function of OS/400. Select the Install licensed programs option on the Work with Licensed Programs display, and the OS/400 Directory Services option on the Install Licensed Programs display.

Select one of the following for more information:

      LDAP Version Support 
      LDAP API Overview 

LDAP Version Support

The LDAP toolkit has been enhanced to support both LDAP Version 2 and LDAP Version 3 APIs and protocols. The LDAP toolkit APIs and protocols are based upon the Internet Draft, which is classified as a "work in progress."

The LDAP API provides typical directory functions such as read, write and search. With the advent of support for LDAP Version 3 APIs and protocols, the following features are also supported:

• LDAP V3 referrals
• Improved internationalization with UTF-8 support for Distinguished Names (DNs) and strings that are passed into, and returned from the LDAP APIs (when running as an LDAP V3 application and LDAP_OPT_UTF8_IO is set to LDAP_UTF8_XLATE_OFF). The default, when running as an LDAP V3 or V2 application, for DNs and strings that are passed into or returned from LDAP APIs are limited to the local codepage character set.

  In general, The connection associated LDAP Version 3 APIs ( APIs that have ld as one of thier parameter ) are designed to accept and return string data in either UTF-8 encoded format or in the local code page format depending on the LDAP_OPT_UTF8_IO option value set using the ldap_set_option() API to LDAP_UTF8_XLATE_ON (the default) or LDAP_UTF8_XLATE_OFF.
  The following LDAP APIs (and related APIs) will accept and return UTF-8 encoded string data when LDAP_OPT_UTF8_IO option is set to LDAP_UTF8_XLATE_OFF. Otherwise they accept or return string data in the local code page (the default).

  • ldap_add (and family)
  • ldap_bind (and family)
  • ldap_compare (and family)
  • ldap_delete (and family)
  • ldap_parse_reference_np
  • ldap_get_dn
  • ldap_get_values
  • ldap_modify (and family)
  • ldap_parse_result
  • ldap_rename (and family)
  • ldap_search (and family)
  • ldap_url_search (and family)

  APIs that are NOT associated with a connection (APIs that do not have ld as one of thier parameter), always expect and return string data (DNs, for example) in local code page.
  The following LDAP APIs (and related APIs) will accept and return string data in the local code page.

  • ldap_explode_dn
  • ldap_explode_rdn
  • ldap_server_locate
  • ldap_server_conf_save
  • ldap_is_ldap_url
  • ldap_default_dn_set/get
• The ability for an application to access schema information published by LDAP V3 servers (see Accessing Schema Information).
• Certain LDAP Version 3 operations can be extended with the use of controls. Controls can be sent to a server, or returned to the client with any LDAP message. This type of control is called a server control.

  The LDAP API also supports a client-side extension mechanism, which can be used to define client controls. The client-side controls affect the behavior of the LDAP client library, and are never sent to the server. Note that client-side controls are not defined for this client library.

  A common data structure is used to represent both server-side and client-side controls:

        typedef struct ldapcontrol {
                char            *ldctl_oid;
                struct berval   ldctl_value;
                char            ldctl_iscritical;
        } LDAPControl, *PLDAPControl;
  

  The LDAPControl fields have the following definitions:

  ldctl_oid

  Specifies the control type, represented as a string.

  ldctl_value

  Specifies the data associated with the control. Note that the control may not include data.

  ldctl_iscritical

  Specifies whether the control is critical or not. If the field is non-zero, the operation will be carried out only if it is recognized and supported by the server (or the client for client-side controls).

With this toolkit, an application that uses the ldap_open API defaults to the LDAP V2 protocol. In this way, existing LDAP applications will continue to work, and can interoperate with both LDAP V2 servers and LDAP V3 servers.

An application that uses the ldap_init API defaults to the LDAP V3 protocol (with optional bind). An LDAP V3 application will not necessarily interoperate with an LDAP server that supports only LDAP V2 protocols.

Note that an application can use the ldap_set_option API to change its LDAP protocol version. This should be done after using ldap_open or ldap_init but before issuing a bind or other operation that results in contacting the server.

LDAP API Overview

The set of LDAP APIs are designed to provide a suite of functions that can be used to develop directory enabled applications. Directory enabled applications will 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
• Modifyin entries
• Renaming entries

• phone numbers
• email addresses
• fax numbers
• mailing addresses
• etc.

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)
• etc.

The LDAP API provides 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.

Complete sample programs are provided that perform the following operations:

• ldapsearch (searches the directory)
• ldapmodify (modifies information in the directory)
• ldapdelete (deletes information from the directory)
• ldapmodrdn (modifies the Relative Distinguished Name of an entry in the directory)

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. 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 (e.g., 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 API has 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).

Accessing Schema Information

LDAP V3 servers permit applications to access schema and other related information. For example, the ldapsearch utility can be used to obtain attributeTypes, objectClasses, supportedLDAPVersion and subschemaSubentry from IBM's DSSeries X.500 Directory Server, as follows:

ldapsearch -V 3 -h hostname -p port -s one -b "o=deltawing, c=au" "objectClass=*"
           attributeTypes objectClasses supportedLDAPVersion subschemaSubentry

Note that the "-V 3" option is used to force ldapsearch to bind as an LDAP V3 application. Also note that the ldapsearch example shown above should be entered on a single line.

Similarly, attributeTypes and objectClasses can be accessed in an LDAP V3 Netscape directory server using:

ldapsearch -V 3 -h hostname -p port -b "cn=schema" -s base "objectclass=*"

Note Some of the material contained in this document is a derivative of the LDAP man pages provided with the University of Michigan LDAP reference implementation (Version 3.3).