Chapter 3
Writing LDAP Clients

enerally, an application follows these steps when interacting with an LDAP server:

1. Initialize a session with the LDAP server, and set any session preferences.

2. Authenticate itself to the LDAP server.

3. Perform the LDAP operations.

4. Close the connection to the LDAP server.

This chapter explains how you can add functions to your application in order to interact with an LDAP server. The chapter also covers the differences between synchronous and asynchronous operations.

The chapter includes the following sections:

• Initializing an LDAP Session

• Authenticating the client to an LDAP Server

• Performing LDAP Operations

• Closing the Connection to the Server

• Freeing Memory

• Checking for Errors

• Synchronous and Asynchronous Functions

• A Simple Example

If the server is using the default port for the LDAP protocol (port 389), you can pass LDAP_PORT as the value of the port parameter.

If successful, the ldap_init() function returns a connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server. When you call API functions to interact with the LDAP server, you need to pass the connection handle as a parameter to the functions. (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.

The following section of code initializes sessions with two LDAP servers, ldap.netscape.com:389 and directory.mcom.com:20000:

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld1, *ld2;

/* Specify the host name of the LDAP server. */
char *ldap_host_1 = "ldap.netscape.com";
char *ldap_host_2 = "directory.mcom.com";

/* If the LDAP server is running on the standard LDAP port (port 389), you can use LDAP_PORT to identify the port number. */
int ldap_port_1 = LDAP_PORT;
int ldap_port_2 = 20000;
...
/* Initialize the session with ldap.netscape.com:389. */
if ( ( ld1 = ldap_init( ldap_host_1, ldap_port_1 ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}
/* Initialize the session with directory.mcom.com:20000 */
if ( ( ld2 = ldap_init( ldap_host_2, ldap_port_2 ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}
... 
/* Subsequent calls use ld1 and ld2 to connect to and authenticate the client with the LDAP servers and to perform LDAP operations. */
...

Getting and Setting Session Options

• the maximum number of entries returned in a search

• the maximum number of seconds spent on a search

• the way to handle aliases

• the way to handle referrals

• whether or not the client is threaded

• whether or not SSL is enabled on the default connection

To apply or change the setting for a session preference, call the ldap_set_option() function, which is described on page 252.

For both functions, the option parameter can have one of the following values:

LDAP_OPT_SIZELIMIT	Specifies the maximum number of entries to return in a search. See "Setting Time Limits and Size Limits for Searches" for details.
LDAP_OPT_TIMELIMIT	Specifies the maximum number of seconds to spend on a search. See "Setting Time Limits and Size Limits for Searches" for details.
LDAP_OPT_DEREF	Specifies how aliases are handled during a search. See "Handling Aliases" for details.
LDAP_OPT_REFERRALS	Specifies whether or not the client follows referrals from the LDAP server. See "Handling Referrals" for details.
LDAP_OPT_REFERRAL_HOP_LIMIT	Specifies the maximum number of referrals in a sequence that the client can follow. See "Handling Referrals" for details.
LDAP_OPT_IO_FN_PTRS	Allows you to use alternate communication stacks. See the description of the ldap_io_fns structure for details.
LDAP_OPT_THREAD_FN_PTRS	Allows you to use threads. See "Using Threads" for details.
LDAP_OPT_DESC (ldap_get_option() only)	Allows you to get the socket descriptor for the connection with the LDAP server. The data type of the *optdata parameter is LBER_SOCKET, which depends on the type of platform that you are using: In UNIX, a value of the type int is returned. In Windows, a value of the type SOCKET is returned. On the Macintosh, a void * is returned.
LDAP_OPT_SSL	Allows you to specify whether or not SSL is enabled. See "Alternative Method for Connecting Over SSL" for details.

The next sections describe these options in more detail.

Setting Time Limits and Size Limits for Searches

Note that the LDAP server may already have time and size constraints set up that you cannot override.

The following example sets these session preferences so that a search returns no more than 100 entries and takes no more than 30 seconds.

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
int max_ret, max_tim;
char *host = "ldap.netscape.com";
...
/* Initialize a session with the LDAP server ldap.netscape.com:389. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}

/* Set the maximum number of entries returned. */
max_ret = 100;
if (ldap_set_option(ld, LDAP_OPT_SIZELIMIT, 
      (void *)&max_ret) != LDAP_SUCCESS){
   ldap_perror( ld, "ldap_set_option" );
   return( 1 );
}

/* Set the maximum number of seconds to wait. */
max_tim = 30;
if (ldap_set_option( ld, LDAP_OPT_TIMELIMIT, 
         (void *)&max_tim) != LDAP_SUCCESS) {
   ldap_perror( ld, "ldap_set_option" );
   return( 1 );
}
...

You can pass one of the following values to the optdata parameter:

LDAP_DEREF_NEVER	Specifies that aliases are never dereferenced.
LDAP_DEREF_FINDING	Specifies that aliases are dereferenced when finding the starting point for the search (but not when searching under that starting entry).
LDAP_DEREF_SEARCHING	Specifies that aliases are dereferenced when searching the entries beneath the starting point of the search (but not when finding the starting entry).
LDAP_DEREF_ALWAYS	Specifies that aliases are always dereferenced (both when finding the starting point for the search and when searching under that starting entry).

This example sets up the session so that aliases are always dereferenced.

#include <stdio.h>
#include <ldap.h>
LDAP *ld;
int deref = LDAP_DEREF_ALWAYS;
char *host = "ldap.netscape.com";
/* Initialize a session with the LDAP server ldap.netscape.com:389. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}
/* Always dereference aliases. */
if (ldap_set_option(ld,LDAP_OPT_DEREF,(void *)&deref) != LDAP_SUCCESS){
   ldap_perror( ld, "ldap_set_option" );
   return( 1 );
}

To change the way referrals are handled, call the ldap_set_option() function and pass LDAP_OPT_REFERRALS as the value of the option parameter.

• To prevent the client from automatically following referrals, set the optdata parameter to LDAP_OPT_OFF.

• If you want the client to automatically follow referrals again, set the optdata parameter to LDAP_OPT_ON.

If you set up the client to automatically handle referrals, you can specify the maximum number of referral hops that should be followed in a sequence of referrals. (For example, suppose you set a limit of 1 referral hop. If your client is referred to another LDAP server which in turn refers you to yet another LDAP server, the client will not follow the second referral.)

To set this limit, pass LDAP_OPT_REFERRAL_HOP_LIMIT as the value of the option parameter and pass the maximum number of hops as value of the optdata parameter.

The following example prevents the client from automatically following referrals to other LDAP servers.

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
int refer;
char *host = "ldap.netscape.com";
...
/* Initialize a session with the LDAP server ldap.netscape.com:389. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}

/* Never follow referrals. */
if (ldap_set_option(ld,LDAP_OPT_REFERRALS,LDAP_OPT_OFF)!=LDAP_SUCCESS){
   ldap_perror( ld, "ldap_set_option" );
   return( 1 );
}
...

Use the ldap_thread_fns structure to specify pointers to the functions that need to be called. For details on setting up this structure, see the section "Writing Multithreaded Clients".

Initializing a Session Over SSL

SSL is only supported by some LDAP servers. The Netscape Enterprise server only supports SSL 3.0. In addition, this SDK only supports server authentication and encryption; client authentication is not currently supported.

For more information on SSL, see the following resources:

• "Securing Communications On The Intranet And Over The Internet" (http://home.netscape.com/newsref/ref/128bit.html)

• The SSL 3.0 Protocol Specification (http://home.netscape.com/eng/ssl3/ssl-toc.html)

Enabling Your Client to Connect Over SSL

1. initialize your client (call the ldapssl_client_init() function)

2. initialize an LDAP session with the secure server (call the ldapssl_init() function)

The following example prepares a client to connect to a secure LDAP server over SSL.

if ( ldapssl_client_init( "/u/mozilla/.netscape/cert5.db", NULL ) < 0) { 
   printf( "Failed to initialize SSL client...\n" ); 
   return( 1 ); 
} 
/* get a handle to an LDAP connection */ 
if ( (ld = ldapssl_init( "cert.netscape.com", LDAPS_PORT, 1 )) == NULL { 
   perror( "ldapssl_init" ); 
   return( 1 ); 
} 
...
/* Client can now perform LDAP operations on the secure LDAP server */
...

1. initialize an LDAP session with the server (call the standard ldap_init() function)

2. load the SSL I/O routines (call the ldapssl_install_routines() function)

3. set the option in the LDAP struct for using SSL (call the standard ldap_set_option() function)

Note that you need to initialize your client before initializing the LDAP session. The process of initializing the client opens the certificate database.

The following example prepares a client to connect to a secure LDAP server over SSL.

if ( ldapssl_client_init( "/u/mozilla/.netscape/cert5.db", NULL ) < 0) { 
   printf( "Failed to initialize SSL client...\n" ); 
   return( 1 ); 
} 
/* get a handle to an LDAP connection */ 
if ( (ld = ldapssl_init( "cert.netscape.com", LDAPS_PORT, 1 )) == NULL { 
   perror( "ldapssl_init" ); 
   return( 1 ); 
} 
/* Initialize LDAP session */
if ( (ld = ldap_init( MY_HOST, LDAPS_PORT )) == NULL ) { 
   perror( "ldap_init" ); 
   return( 1 ); 
} 

/* Load SSL routines */ 
if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) { 
   ldap_perror( ld, "ldapssl_install_routines" ); 
   return( 1 ); 
} 
/* Set up option in LDAP struct for using SSL */
if ( ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) { 
   ldap_perror( ld, "ldap_set_option" ); 
   return( 1 ); 
} 
/* Client can now perform LDAP operations on the secure LDAP server */
...

• To authenticate as a specific user, you must provide the distinguished name of the user and the password to the LDAP server.

• To provide anonymous authentication (in other words, to authenticate as an anonymous user), you can provide NULL values as the user's distinguished name and password.

• the synchronous ldap_simple_bind_s() function (see "Performing a Synchronous Authentication Operation")

• the asynchronous ldap_simple_bind() function (see "Performing an Asynchronous Authentication Operation")

Performing a Synchronous Authentication Operation

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 anonymous authentication, see "Authenticating as an Anonymous User".)

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *host = "ldap.netscape.com";
char *dn = "cn=Barbara Jensen, ou=New Department, o=Ace Industry, c=US";
char *pw = "23skidoo";
...
/* Initialize a session with the LDAP server ldap.netscape.com:389. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}
/* Attempt authentication. */
if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_simple_bind_s" );
   return( 1 );
}
...

After the operation is completed, call the ldap_result2error() function to determine if the operation was successful. The ldap_result2error() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

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 anonymous authentication, see "Authenticating as an Anonymous User".)

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *host = "ldap.netscape.com";
char *dn = "cn=Barbara Jensen, ou=New Department, o=Ace Industry, c=US";
char *pw = "23skidoo";
struct timeval zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Initialize a session with the LDAP server ldap.netscape.com:389. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}
/* Attempt authentication. */
msgid = ldap_simple_bind( ld, dn, pw ); 

/* Initialize the value returned by ldap_result(). */
rc = 0;

/* While the operation is still running, do this: */
while ( rc == 0 ) {
   ... /* Do other work while waiting. */...
   
   /* Check the status of the LDAP operation. */
   rc = ldap_result( ld, msgid, NULL, &zerotime, &result );
   switch( rc ) {

      /* If -1 was returned, an error occurred. */
      case -1:
         ldap_perror( ld, "ldap_result" );
         return( 1 );

      /* If 0 was returned, the operation is still in progress. */
      case 0:
         continue;

      /* If any other value is returned, assume we are done. */
      default:
         /* Check if the authentication operation was successful. */
         if ( ldap_result2error( result ) != LDAP_SUCCESS ) {
            ldap_perror( ld, "ldap_simple_bind" );
            return( 1 );
            }
   }
}

To provide anonymous authentication (in which the user does not specify a name and password), pass NULL values for the who and passwd parameters.

The following section of code uses the synchronous ldap_simple_bind_s() function to authenticate an anonymous user to the LDAP server. No user or password is specified, so NULL values are passed to the who and passwd parameters.

#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
char *host = "ldap.netscape.com";
...
/* Initialize a session with the LDAP server ldap.netscape.com:389. */
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) { 
   perror( "ldap_init" );
   return( 1 );
}
/* Attempt authentication. */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_simple_bind_s" );
   return( 1 );
}
...

By default, the reauthentication is done anonymously (the name and password are not sent to the new server for authentication). If you want to authenticate a specific user, you need to set up your own function for getting the name and password to use for authentication.

You need to write a function that has the following prototype:

int rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg );

Once you have a function that follows this prototype, you need to call the LDAP API function ldap_set_rebind_proc() so that your function is called during referrals.

Performing LDAP Operations

To perform LDAP operations, call these API functions:

• ldap_search() and ldap_search_s() search for matching entries in the directory (see "Searching the Directory" for details).

• ldap_compare() and ldap_compare_s() determine whether an attribute contains a certain value (see "Comparing the Value of an Attribute" for details).

• ldap_add() and ldap_add_s() add entries to the directory (see "Adding a New Entry" for details).

• ldap_modify() and ldap_modify_s() update entries in the directory (see "Modifying an Existing Entry" for details).

• ldap_delete() and ldap_delete_s() delete entries from the directory (see "Deleting an Entry" for details).

• ldap_modrdn2() and ldap_modrdn2_s() rename entries in the directory (see "Changing the Name of an Entry" for details).

Closing the Connection to the Server

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

• the ldap_unbind() function

• the ldap_unbind_s() function

After you close the connection, you can no longer use the LDAP structure. The LDAP structure is freed from memory.

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

#include <ldap.h>
...
LDAP *ld;
...
/* After completing your LDAP operations with the server, close the connection. */ 
if ( ldap_unbind( ld ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_unbind" );
   return( 1 );
...

Table 3.1 lists some of the API functions that allocate memory and the corresponding functions that you must call to free the memory.

Table 3.1: API functions that allocate and free memory

Function allocating memory	Type of data allocated	Function to free memory
ldap_result(), ldap_search_s(), ldap_search_st()	LDAPMessage	ldap_msgfree()
ldap_first_attribute()	BerElement	ldap_ber_free()
ldap_get_values()	char **	ldap_value_free()
ldap_get_values_len()	struct berval **	ldap_value_free_len()
ldap_friendly_name()	FriendlyMap	ldap_free_friendlymap()
ldap_url_parse()	LDAPURLDesc	ldap_free_urldesc()
ldap_init_getfilter(), ldap_init_getfilter_buf()	LDAPFiltDesc	ldap_getfilter_free()
malloc( )	LDAPMod **	ldap_mods_free()

To free memory allocated by other API functions, call the ldap_memfree() function.

This example frees the memory allocated by the ldap_get_dn() function.

#include <ldap.h>
LDAP *ld;
char *dn;
LDAPMessage *entry;
/* Get the distinguished name (DN) for an entry. */
dn = ldap_get_dn( ld, entry );
/* When you are done working with the DN, free the DN from memory. */
ldap_memfree( dn );

• the error code of the last error that occurred

• the error message of the last error that occurred

• the portion of the distinguished name that was successfully matched (If the function specified a non-existent distinguished name)

Printing Out Error Messages

This example prints a message if a function fails to delete an entry in the server.

#include <ldap.h>
LDAP *ld;
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
...
if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_delete_s" );
   return( 1 );
}
...

ldap_delete_s: Insufficient access

The following section of code attempts to add a new user to the directory. If components of the user's distinguished name do not exist (components other than the user's common name), matched is set to the portion of the distinguished name that matched. errmsg is set to the error message corresponding to the error code returned.

#include <ldap.h>
LDAP *ld;
char *dn = "cn=Barbara Jensen, ou=New Department, o=Ace Industry, c=US";
LDAPMod **list_of_attrs;
char *matched;
char *errmsg
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
   ldap_get_lderrno( ld, &matched, &errmsg );
   return( 1 );
}
...

o=Ace Industry, c=US

No such object

ldap_get_lderrno( ld, NULL, &errmsg );

The following section of code sets errmsg to the error message corresponding to the error code returned by the ldap_simple_bind_s() function.

#include <ldap.h>
...
LDAP *ld;
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
char *pw = "23skidoo";
char *errmsg;
...
errmsg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );
...

If you want to set error codes and error information in the LDAP structure, call the ldap_set_lderrno() function.

The following section of code attempts to perform an operation that you've defined. If the operation fails, the LDAP_PARAM_ERROR error code is placed in the LDAP structure.

#include <ldap.h>
LDAP *ld;
char *errmsg = "Invalid parameter";
if ( ldap_my_function() != LDAP_SUCCESS ) {
   ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg );
   return( 1 );
}

Calling Synchronous Functions

This example calls a synchronous function to delete an entry in the directory.

/ * Delete an entry and wait for the operation to complete. */
if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_delete_s" );
   return( 1 );
}

Calling Asynchronous Functions

An asynchronous function returns a unique message ID that identifies the operation being performed. You can pass this message ID to the ldap_result() function to check the status of the LDAP operation.

To see sample programs that call synchronous functions see the source files in the examples directory of the Netscape Enterprise server.

Checking the Status of the LDAP Operation

• -1 indicates that an error occurred.

• 0 indicates that the operation has not completed yet.

• Any other value indicates that the operation has completed. If ldap_result() returns such a value, you can check the result parameter to see if the operation completed successfully.

For an example of calling the ldap_result() function, see "Example of Calling an Asynchronous Function".

Determining Whether the Operation Was Successful

To get the error code, call the ldap_result2error() function. Most operations that complete successfully generate an LDAP_SUCCESS status code. You can check for this value to determine if the operation completed successfully.

For an example of calling the ldap_result2error() function, see "Example of Calling an Asynchronous Function".

Canceling an Operation in Progress

Example of Calling an Asynchronous Function

...
/* Delete an entry in the directory and wait for the operation to complete. */
msgid = ldap_delete( ld, dn ); 

/* Initialize the value returned by ldap_result(). */
rc = 0;

/* While the operation is still running, do this: */
while ( rc == 0 ) {
   ... 
   /* Do other work while waiting. */
   ...
   
   /* Check the status of the LDAP operation. */
   rc = ldap_result( ld, msgid, NULL, &zerotime, &result );
   switch( rc ) {

      /* If -1 is returned, an error occurred. */
      case -1:
         ldap_perror( ld, "ldap_result" );
         return( 1 );

      /* If 0 is returned, the operation is still in progress. */
      case 0:
         continue;

      /* If any other value is returned, assume you are done. */
      default:
         /* Check whether the delete operation was successful. */
         if ( ldap_result2error( result ) != LDAP_SUCCESS ) {
            ldap_perror( ld, "ldap_delete" );
            return( 1 );
         }
   }
}
...

#define MY_HOST "localhost"
#define MY_PORT LDAP_PORT
#define ENTRYDN "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US"
int main( int argc, char **argv )
{
LDAP *ld;
LDAPMessage *result, *e;
char **vals, *attrs[ 5 ];
int i;

/* Get a handle to an LDAP connection. */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
   perror( "ldap_init" );
   return( 1 );
}

attrs[ 0 ] = "cn"; /* Get common name(s) (full name) */
attrs[ 1 ] = "sn"; /* Get surname(s) (last name) */
attrs[ 2 ] = "mail"; /* Get email address(es) */
attrs[ 3 ] = "telephonenumber"; /* Get telephone number(s) */
attrs[ 4 ] = NULL;
if ( ldap_search_s( ld, ENTRYDN, LDAP_SCOPE_BASE,
      "(objectclass=*)", attrs, 0, &result ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_search_s" );
   return( 1 );
}
/* Print out the entry. */
if (( e = ldap_first_entry( ld, result )) != NULL ) {
   if (( vals = ldap_get_values( ld, e, "cn" )) != NULL ) {
      printf( "Full name:\n" );
      for ( i = 0; vals[i] != NULL; i++ ) {
         printf( "\t%s\n", vals[i] );
      }
      ldap_value_free( vals );
   }
   if (( vals = ldap_get_values( ld, e, "sn" )) != NULL ) {
      printf( "Last name (surname):\n" );
      for ( i = 0; vals[i] != NULL; i++ ) {
         printf( "\t%s\n", vals[i] );
      }
      ldap_value_free( vals );
   }
   if (( vals = ldap_get_values( ld, e, "mail" )) != NULL ) {
      printf( "Email address:\n" );
      for ( i = 0; vals[i] != NULL; i++ ) {
         printf( "\t%s\n", vals[i] );
      }
      ldap_value_free( vals );
   }
   if ((vals = ldap_get_values( ld, e, "telephonenumber" )) != NULL) {
      printf( "Telephone number:\n" );
      for ( i = 0; vals[i] != NULL; i++ ) {
         printf( "\t%s\n", vals[i] );
      }
      ldap_value_free( vals );
   }
}
ldap_msgfree( result );
ldap_unbind( ld );
return( 0 );
}