You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is
highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If
there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Mozilla LDAP C SDK Programmer's Guide

Chapter 4 - Writing an LDAP Client

This chapter describes the general process of writing an LDAP
client. The chapter covers the procedures for connecting to an LDAP
server, authenticating, requesting operations, and disconnecting
from the server.

Overview: Designing an LDAP Client

With the Mozilla LDAP C SDK, you can write a new application or
enable an existing application to interact with an LDAP server. The
following procedure outlines the typical process of communicating
with an LDAP server. Follow these steps when writing your LDAP client:

Set any preferences that you want applied to all LDAP sessions for
your client (see "Setting
Preferences" for details). If you intend to use any of the
LDAPv3 features (such as controls or operations), specify the LDAP
version of your client, as detailed in
"Specifying the LDAP Version of Your
Client" (the default LDAP version used by the Mozilla LDAP C
SDK is version 2).

The following is a simple example of an LDAP client that requests
an LDAP search operation from a server. The client connects to the
LDAP server running on the local machine at port 389, searches the
directory for entries with the last name "Jensen"
("sn=Jensen"), and prints out the DNs of any matching
entries.

The rest of this chapter explains how to initialize a session,
authenticate your client, perform LDAP operations, and disconnect
from the LDAP server.

Initializing an LDAP Session

Before you can connect to an LDAP server, you need to initialize
an LDAP session. As part of this process, you create an
LDAP structure, which
contains information about the LDAP server and the LDAP session. You
need to pass this LDAP
structure (usually as a pointer) to all subsequent LDAP API
functions to identify the LDAP server that you are working with.

The following sections explain how to initialize an LDAP session
with a server and how to specify session preferences:

If successful, the
ldap_init() function
returns a connection handle, which is a pointer to an
LDAP structure that
contains information about the connection to the LDAP server. You
need to pass this pointer to the LDAP API functions for connecting,
authenticating, and performing LDAP operations on a server.

For example, when you call a function to search the directory,
you need to pass the connection handle as a parameter. The
connection handle provides context for the connection.

Specifying a List of LDAP Servers

When initializing the LDAP session, you can specify a list of
LDAP servers that you want to attempt to connect to. If the first
LDAP server in the list does not respond, the client will attempt to
connect to the next server in the list.

To specify a list of LDAP servers, pass a space-delimited list of
the host names as the first argument to the
ldap_init() function.
For example:

In the example above, the LDAP client will attempt to connect to
the LDAP server on ld1.example.com, port 389. If that
server does not respond, the client will attempt to connect to the
LDAP server on ld2.iplaent.com, port 389. If that
server does not respond, the client will use the server on
ld3.example.com, port 389.

If any of the servers do not use the default port specified as
the second argument to
ldap_init(), use the
host:port format to
specify the server name. For example:

In the example above, the LDAP client will attempt to connect to
the LDAP server on ld1.example.com, port
389. If that server does not respond, the client will attempt to
connect to the LDAP server on ld2.example.com, port
38900.

Setting the Restart Preference

If communication with the LDAP server is interrupted, the result
code LDAP_SERVER_DOWN is returned by your client. If
you want your client to continue to attempt to communicate with the
server, you can set the LDAP_OPT_RECONNECT preference
for the session. If your connection is lost and this option is set,
the application will attempt another bind using the same
authentication to reestablish the connection.

Call the ldap_set_option() function and pass
LDAP_OPT_RECONNECT as the value of the
option parameter.

If you want the client to resume LDAP I/O operations automatically,
set the optdata parameter to LDAP_OPT_ON
(this specifies that the same connection handle can be used to
reconnect to the server).

If you do not want the client to resume I/O operations, set the
optdata parameter to LDAP_OPT_OFF
(specifies that you want to create a new connection handle to
connect to the server).

By default, this option is set to LDAP_OPT_OFF. Both
LDAP_OPT_OFF and LDAP_OPT_ON are cast to
(void *). You can pass these parameters directly to the
function. For example:

...
ldap_set_option( ld, LDAP_OPT_RECONNECT, LDAP_OPT_ON );
...

Specifying the LDAP Version of Your Client

If you plan to call API functions that make use of LDAPv3
features, you should set the protocol version of your client to
LDAPv3. (By default, clients built with the Mozilla LDAP C SDK
identify themselves to LDAP servers as LDAPv2 clients.)

To specify the LDAP version supported by your client, call the
ldap_set_option()
function and set the LDAP_OPT_PROTOCOL_VERSION option
to the value 3. For example:

After setting this option, your client can authenticate or
bind to the server (see
"Binding and Authenticating to an LDAP
Server" for details). As part of the process of binding to the
server, your client sends the supported LDAP version number to the
server. This allows the server to determine whether or not to enable
use of LDAPv3 features.

Note that the LDAPv3 protocol allows you to perform LDAP
operations without first binding to the server. An LDAPv3 server
will assume that the client is LDAPv3 compliant if the client issues
non-bind operations before is issues a bind.

Examples of Initializing an LDAP Session

The following section of code initializes a session with an LDAP
server. The example specifies a list of LDAP servers to try:
ldap.example.com:389 and
directory.example.com:3890. The example
also sets a session preference that identifies the client as an
LDAPv3 client.

After you initialize a session with an LDAP server, you can set
session options and connect and authenticate to the LDAP server.
(Note that the
ldap_init() function
does not connect to the LDAP server right away.)

Binding and Authenticating to an LDAP Server

When connecting to the LDAP server, your client may need to send
a bind operation request to the server. This is also called
binding to the server.

An LDAP bind request contains the following information:

The LDAP version of the client.

The DN that the client is attempting to authenticate as.

The method of authentication that should be used.

The credentials to be used for authentication.

Your client should send a bind request to the server in the
following situations:

You want to authenticate to the server.

For example, you may want to add or modify entries in the
directory, which requires you to authenticate as a user with
certain access privileges.

You are connecting to an LDAPv2 server.

LDAPv2 servers typically require clients to bind before any
operations can be performed.

LDAP clients can also bind as an anonymous clients to the server
(for example, the LDAP server may not require authentication if your
client is just searching the directory).

This chapter explains how to set up your client to bind to an
LDAP server. Topics covered here include:

Simple Authentication and Security Layer (SASL).
SASL is described in Simple Authentication and Security Layer
(SASL), RFC 2222. For more information, refer to
Where to Find Additional
Information. Some LDAPv3 servers (including the Netscape
Directory Server 6.0 and later) support authentication through SASL.

Note that if you specify a DN but no password, your client will
bind to the server anonymously. If you want a NULL
password to be rejected as an incorrect password, you need to write
code to perform the check before you call the
ldap_simple_bind() or
the ldap_simple_bind_s()
functions.

If you are binding to the Netscape Directory Server, the server
may send back special controls to indicate that your password has
expired or will expire in the near future. For more information on
these controls, see "Using Password
Policy Controls."

Performing a Synchronous Authentication Operation

If you want to wait for the bind operation to complete before
continuing, call the
ldap_simple_bind_s()
function. This function returns LDAP_SUCCESS if the
operation successfully completed or an LDAP result code if a problem
occurred. (See the documentation for this function for a list of
possible result codes returned.)

If you specify a DN but no password, your client will bind to the
server anonymously. If you want a NULL password to be
rejected as an incorrect password, you need to write code to perform
the check before you call the
ldap_simple_bind_s()
function.

The following section of code uses the synchronous
ldap_simple_bind_s() function to authenticate the user
Barbara Jensen to the LDAP server. (For an example of binding anonymously,
see "Binding Anonymously.")

Performing an Asynchronous Authentication Operation

If you want to perform other work (in parallel) while waiting for
the bind operation to complete, call the
ldap_simple_bind()
function. This function sends an LDAP bind request to the server and
returns a message ID identifying the bind operation.

If you specify a DN but no password, your client will bind to the
server anonymously. If you want a NULL password to be
rejected as an incorrect password, you need to write code to perform
the check before you call the
ldap_simple_bind()
function.

You can check to see if your client has received the results of
the bind operation from the server by calling the
ldap_result() function
and passing it the message ID.

If your client has received the results, the
ldap_result() function passes back the results of the
bind operation in an
LDAPMessage structure.
To get error information from this structure, you can pass it to the
ldap_parse_result()
function.

The ldap_parse_result() function gets the LDAP
result code of the operation and any error messages sent back from
the server. This function also retrieves any controls sent back from
the server.

(Netscape Directory Server may return a control if the user's
password has expired or will expire in the near future. For more
information, see "Using Password Policy
Controls.")

The following section of code uses the asynchronous
ldap_simple_bind() function to authenticate the user
Barbara Jensen to the LDAP server. (For an example of binding
anonymously, see "Binding
Anonymously.")

Binding Anonymously

In some cases, you may not need to authenticate to the LDAP
server. For example, if you are writing a client to search the
directory (and if users don't need special access permissions to
search), you might not need to authenticate before performing the
search operation.

With LDAPv2, the client is required to send a bind request, even
when binding anonymously (binding without specifying a name or
password). With LDAPv3, the client is no longer required to bind to
the server if the client does not need to authenticate.

Performing LDAP Operations

Once you initialize a session with an LDAP server and complete
the authentication process, you can perform LDAP operations, such as
searching the directory, adding new entries, updating existing
entries, and removing entries (provided the server's access control
allows these operations).

Most LDAP operations can be performed synchronously or
asynchronously. The functions with names ending in _s
are synchronous functions, and the remaining functions are
asynchronous functions. (For more information on the distinction
between calling synchronous and asynchronous functions, see
"Calling Synchronous and Asynchronous
Functions.")

Closing the Connection to the Server

When you have finished performing all necessary LDAP operations,
you need to close the connection to the LDAP server.

To close a connection to an LDAP server, call one of the
following functions:

Both ldap_unbind() and ldap_unbind_s()
are synchronous functions. These functions are identical; they use
different names so that each authentication function
(ldap_simple_bind() and ldap_simple_bind_s())
has a corresponding function for closing the server connection.

After you close the connection, you can no longer use the
LDAP structure. Calling any of the
unbind functions frees the LDAP structure from memory.

The following code closes the current connection with the LDAP
server:

The ldap_unbind_ext() function allows you to
explicitly include both server and client controls in your unbind
request. However, note that since there is no server response to an
unbind request, there is no way to receive a response from a server
control that is included with your unbind request.