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 on the Internet Draft, which is classified as a "work in progress."

The LDAP APIs provide 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 is limited to the local codepage character set.

  In general, the connection-associated LDAP Version 3 APIs ( APIs that have ld as one of their parameters ) 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) accept and return UTF-8 encoded string data when the 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 their parameters), 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_init
  • ldap_ssl_init
  • ldap_explode_dn
  • ldap_explode_rdn
  • ldap_server_locate
  • ldap_server_conf_save
  • ldap_is_ldap_url
  • ldap_default_dn_set/get

  As a non-standard extension to the API set on i5/OS^(TM) only, two APIs have been added that allow input of string data in UTF8. These are:

  • ldap_explode_dn_utf8
  • ldap_explode_rdn_utf8
• The ability for an application to access schema information published by LDAP V3 servers (see Accessing Schema Information).
  
  
• The ability for certain LDAP Version 3 operations to 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

  The control type, represented as a string.

  ldctl_value

  The data associated with the control. The control may not include data.

  ldctl_iscritical

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

  If using any of the ber_xxx functions to set up the berval structure, you must specify QSYS/QGLDBRDR as one of the the bind service programs when creating the program.

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.

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.