IBM Security Directory Server, Version 6.3.1

LDAP_INIT

Use the LDAP_INIT or LDAP routine to initialize the LDAP library and open a connection to an LDAP server, and get or set options for an LDAP connection.

ldap_init
ldap_open (deprecated)
ldap_set_option
ldap_get_option
ldap_version

Synopsis

#include ldap.h


LDAP *ldap_init(
         const char *host,
         int      port)

LDAP *ldap_open(
         const char *host,
         int      port)

int ldap_set_option(
         LDAP     *ld,
         int      optionToSet,
         void     *optionValue)

int ldap_get_option(
         LDAP     *ld,
         int      optionToGet,
         void     *optionValue)

int ldap_version(
         LDAPVersion  *version)

Input parameters

ld

Specifies the LDAP pointer that is returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

host

Several methods are supported for specifying one or more target LDAP servers, including the following methods:

Explicit Host List

Specifies the name of the host on which the LDAP server is running. The host parameter can contain a blank-separated list of hosts to try to connect to, and each host can optionally be of the form host:port. If present, the :port overrides the port parameter that is supplied on ldap_init(), ldap_ssl_init() or ldap_open(). The following are typical examples:

ld=ldap_init ("server1", ldap_port);
ld=ldap_init ("server2:1200", ldap_port);
ld=ldap_init ( "server1:800 server2:2000 server3", ldap_port);

Localhost

If the host parameter is NULL, the LDAP server is assumed to be running on the local host.

Default Hosts

If the host parameter is set to "ldap://" the LDAP library attempts to locate one or more default LDAP servers, with non-SSL ports, by using the ldap_server_locate() function. The port that is specified on the call is ignored because ldap_server_locate() returns the port. For example, the following are equivalent:

ld=ldap_init ("ldap://", ldap_port);

and

ld=ldap_init (LDAP_URL_PREFIX, LDAP_PORT);

If more than one default server is located, the list is processed in sequence until an active server is found.

The LDAP URL can include a distinguished name, which is used as a filter for selecting candidate LDAP servers that are based on the server suffixes. If the most significant DN portion is an exact match with a server suffix after normalizing for case, add the server to the candidate servers list. For example, the following example returns default LDAP servers that have a suffix that supports the specified DN only:

ld=ldap_init ("ldap:///cn=fred, dc=austin, 
        dc=ibm, dc=com", LDAP_PORT);

In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" matches. If more than one default server is located, the list is processed in sequence until an active server is found.

If the LDAP URL contains a host name and optional port, the host is used to create the connection. No attempt is made to locate the default servers, and the DN, if present, is ignored. For example, the following examples are equivalent:

ld=ldap_init ("ldap://myserver", LDAP_PORT);

and

ld=ldap_init ("myserver", LDAP_PORT);

For more information about the algorithm that is used to locate default LDAP servers, see Locating default LDAP servers.

Local Socket

If the host parameter is prefixed with a forward slash (/), the host parameter is assumed to be the name of a UNIX socket, that is, family is AF_UNIX, and port is ignored. Use of a UNIX socket requires the LDAP server to be running on the local host. In addition, the local operating system must support UNIX sockets and the LDAP server must be listening on the specified UNIX socket. UNIX variants of the IBM® Security Directory Server listen on the /tmp/s.slapd local socket, in addition to any configured TCP/IP ports. For example:

ld=ldap_init ("/tmp/s.slapd", ldap_port);

Host with Privileged Port

On platforms that support the rresvport function, typically UNIX platforms, if a specified host is prefixed with "privport://", then the LDAP library uses the rresvport function to attempt to obtain one of the reserved ports (512 through 1023), instead of an ephemeral port. The search for a reserved port starts at 1023 and stops at 512. If a reserved port cannot be obtained, the function call fails. For example:

ld=ldap_init ("privport://server1", ldap_port);
ld=ldap_init ("privport://server2:1200", ldap_port);
ld=ldap_init ("privport://server1:800 server2:2000 
  privport://server3", ldap_port);

port

Specifies the port number to connect to. If the default IANA-assigned port of 389 is wanted, LDAP_PORT must be specified. To use the default SSL port 636 for SSL connections, use LDAPS_PORT.

optionToSet

Identifies the option value that is to be set on the ldap_set_option() call. For the list of supported options, see the following section, Usage.

optionToGet

Identifies the option value that is to be queried on the ldap_get_option() call. For the list of supported options, see the following section, Usage.

optionValue

Specifies the address of the value to set by using ldap_set_option() or the address of the storage in which the queried value is returned by using ldap_get_option().

version

Specifies the address of an LDAPVersion structure that contains the following returned values:

sdk_version: SDK version, which is multiplied by 100.
protocol_version: Highest LDAP protocol that is supported, multiplied by 100.
SSL_version: SSL version that is supported, multiplied by 100.
security_level: Level of encryption that is supported in bits. Set to LDAP_SECURITY_NONE if SSL not enabled.
ssl_max_cipher: A string that contains the default ordered ciphers set that are supported by this installation. For more information about changing the set of ciphers that is used to negotiate the secure connection with the server, see LDAP_SET_OPTION syntax for LDAP V2 applications.
sdk_vendor: A pointer to a static string that identifies the supplier of the LDAP library. This string must not be freed by the application.
sdk_build_level: A pointer to a static string that identifies the build level, including the date when the library was built. This string must not be freed by the application.

Usage

The ldap_init() API initializes a session with an LDAP server. The server is not contacted until an operation is run that requires the server. It allows various options to be set after initialization, but before actually contacting the host. It allocates an LDAP structure that is used to identify the connection and maintain per-connection information.

Although still supported, ldap_open() is deprecated. The ldap_open() API allocates an LDAP structure and opens a connection to the LDAP server. Use ldap_init() instead of ldap_open().

The ldap_init() and ldap_open() APIs return a pointer to an LDAP structure, which must be passed to subsequent calls to ldap_set_option(), ldap_simple_bind(), ldap_search(), and others.

The LDAP structure is opaque to the application. Direct manipulation of the LDAP structure must be avoided. The ldap_version() API returns the toolkit version (multiplied by 100). It also sets information in the LDAPVersion structure. See the section Input Parameters.

Feedback