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.

Skip to main content

Mozilla LDAP C SDK Recent Changes

Last updated August 21, 2003
(but this file is not completely up-to-date)

Contents

Added features and enhancements

Miscellaneous Changes

  • The ldap.h file is now a small file that, for clarity, #includes several other files.
  • A new extended I/O function callback scheme was added to the SDK. The ldap_x_ext_io_fns struct has been added to hold extended I/O function pointers. The ldap-extension.h file outlines the new callbacks.
  • Netscape Portable Runtime library (NSPR) support was added. The library, libprldap was added to provide a simple way for an application that is using NSPR to tie libldap into their environment. The ldappr.h file outlines the new interface. The new example nsprio.c shows how to use the new interfaces.
  • The ldap_search*() line of functions was modified as follows:
    • The ldap_search*() line of functions now return LDAP_PARAM_ERROR if a sizelimit smaller than -1 is passed to the function call.
    • The ldap_search*() line of functions now set *result to NULL in all error situations.
  • The ldapmodify utility was modified as follows:
    • The -A option was added, which causes the tool to display non-ASCII values in conjunction with the -v option.
    • The -B and -q options were added, which provide support for the bulk import feature available in the Netscape Directory Server 6.0 and later.
    • Support for the version directive was added.
    • Support for changetype with moddn was added.
    • Improved the LDIF output to provide better support for file URLs.
  • The ldapsearch utility was modified as follows:
    • The -e option was added, which minimizes base-64 encoding of values. By default, ldapsearch will always produce ASCII values and any non-ASCII values (such as UTF-8 characters) as base-64 encoded characters. The new -e option causes ldapsearch to return as much real data as is possible. With -e, only values or DNs that contain an '\r', an '\n', or that start with ':', ' ', or '<' are base-64 encoded. Note that the -e option may cause ldapsearch to produce LDIF that does not conform to RFC 2849).
    • The -U option was added, which operates in conjunction with the -t option (which causes ldapsearch to produce file URLs).
    • To conform with RFC 2849, ldapsearch now outputs a "version: 1" line at the start of all LDIF. A new -1 (minus 1) option has been added to ldapsearch to suppress this line.
    • The ldapsearch utility has been modified to support a zero length filter, represented as either "" or NULL. The zero-length filter "" is now an alias for "(objectclass=*)".
  • The following new examples have been added to the SDK:
    • csearch -- search with ldap_memcache
    • ssnoauth -- search over SSL
    • ssearch -- search over SSL with cert based authentication
    • nsprio -- example usage of the extended IO callbacks
    • psearch -- uses persistent search
    • srvsort -- shows server-side sorting
    • ppolicy -- shows use of password policies
    • crtfilt -- demonstrates the use of ldap_create_filter()
  • The ldap.h header file was modified as follows:
    • Support was added for discovery of API version information at run-time with the LDAP_OPT_API_INFO option and LDAPAPIInfo structure.
    • Support was added for the discovery of API extensions at run-time with the LDAP_OPT_API_FEATURE_INFO and LDAPAPIFeatureInfo structures.
    • The following macros were added to support the discovery of API version information at compile-time: LDAP_VENDOR_VERSION, LDAP_VENDOR_NAME, and LDAP_API_VERSION.
    • A set pf LDAP_API_FEATURE_* macros were added to support the discovery of API extensions at compile-time.
    • The LDAP_OPT_PRIVATE_EXTENSION_BASE macro was added.
    • The ldap_unbind_ext() function was added.
    • The ldap_mods_u name was added to the mod_vals union.
    • A number of function parameters were modified to be declared with const.
  • The ldap_get_option() function was modified as follows:
    • Support for the LDAP_OPT_HOST_NAME option was added.
    • The function now returns a duplicate copy of data when LDAP_OPT_SERVER_CONTROLS, LDAP_OPT_CLIENT_CONTROLS, or LDAP_OPT_ERROR_STRING are retrieved.
    • The LDAP_OPT_MATCHED_DN option was added.
    • Support for LDAP_OPT_ERROR_NUMBER and LDAP_OPT_ERROR_STRING were added.
  • The lber.h header file was modified as follows:
    • Support was added for the LBER_USE_DER option.
    • Several internal datatypes were changed to provide support for liblber. In the header file, see the definition for _LP64 for details.
    • The typedef BerValue was added to the berval struct, as follows: 
      typedef struct berval {
  unsigned long bv_len;
  char          *bv_val;
} BerValue;
  • Support was added for receiving unsolicited LDAPv3 notification messages.
  • The header files disptmpl.h and srchpref.h are now shipped with the SDK.
  • When using SSL client authentication with the command-line utilities, you are no longer required to provide the Cert DB password with the -W option on the command line. If you do not specify the -W option, the command-line utility will prompt you for your Cert DB password.

    Alternatively, you can provide a path to a PIN file that contains your Cert DB password. The format of a PIN file is the same as the PIN file that you would use for Netscape Directory Server. That is, if your Cert DB password is secret12, then you would enter the following line into your PIN file: 

    Internal (Software) Token:secret12

    You would then point to this file using the -I option on the command line utility. For example: 

    -I /home/bjensen/.mozilla/bjensen/8vlmm76q.slt/my_pin_file

    The use of either the PIN file or interactive prompting for your password means that your Cert DB password is not exposed through process examination (that is, by using the ps command on Unix).

LDAP_X_OPT_CONNECT_TIMEOUT

There is a new option that allows you to control the TCP/IP timeout. Normally connection attempts will block for a period of time when the connection is for a host that is not reachable. LDAP_X_OPT_CONNECT_TIMEOUT allows you to control the amount of time for which a connection attempt will block in the event that the host is not reachable. You can tell the SDK to return immediately, return after an amount of time that you specify, or to block indefinitely.

The timeout value is set on a per-session handle basis and you can control the default timeout that is used by all session handles. Use ldap_set_option() to set the timeout value. Use ldap_get_option() to return the timeout value that is set for the current session handle.

Timeout Values

To support this option, the following special values are now available:

  • LDAP_X_IO_TIMEOUT_NO_WAIT -- The connection attempt returns immediately even if the server is reachable.
  • LDAP_X_IO_TIMEOUT_NO_TIMEOUT -- The connection attempt will block until the host responds, or for the duration of the platform's connection timeout. Depending on the platform, the default connection timeout can be anywhere from 20 seconds to 3 minutes or longer. This value is the default.

In addition, you can specify a timeout value in milliseconds.

Setting the Timeout Value

The following code fragment sets the timeout value for the session handle to 10 seconds.

#include <stdio.h>
#include "ldap.h"

#define HOST "ldap.example.com"
#define PORT 389

...

LDAP *ld;
LDAPMessage *result;
int rc, version;

/* timeout is specified in milliseconds. 10000 = 10 seconds. */
int timeout = 10000;

...

if ( ( ld = ldap_init( HOST, PORT ) ) == NULL ) {
	perror( "ldap_init" );
	return( -1 );
}

if ( ldap_set_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ) != LDAP_SUCCESS ) {
	rc = ldap_get_lderrno( ld, NULL, NULL);
	fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) );
	ldap_unbind( ld );
	return (rc);
}

...

You can also control the default timeout for all LDAP session handles by setting the LDAP * value to NULL using ldap_set_option(). For example:

int timeout = LDAP_X_IO_TIMEOUT_WAIT;

ldap_set_option( NULL, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout );

/* the default timeout is now set for all new ldap connections that 
    are created after this call to ldap_set_option. */

Retrieving the Timeout Value

The following code fragment retrieves the timeout value for the current session handle.

#include <stdio.h>
#include "ldap.h"

#define HOST "ldap.example.com"
#define PORT 389

...

LDAP *ld;
LDAPMessage *result;
int rc, version, timeout;

...

if ( ( ld = ldap_init( HOST, PORT ) ) == NULL ) {
  perror( "ldap_init" );
  return( -1 );
}

if ( ldap_get_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ) != LDAP_SUCCESS ) {
  rc = ldap_get_lderrno( ld, NULL, NULL);
  fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) );
  ldap_unbind( ld );
  return (rc);
}

switch( timeout ) {
  case LDAP_X_IO_TIMEOUT_NO_WAIT:
    printf("The connection is set to not block\n");
    break;

  case LDAP_X_IO_TIMEOUT_NO_TIMEOUT:
    printf("The connection is set to block indefinitely\n");
    break;

  default:
    printf("The connection timeout is set to %d seconds", (timeout/1000) );
    break;
}

...

LDAP library/API Version Mismatch Error Messages

Various macros and structures have been added to the SDK to allow for compile-time and run-time discovery of the API version. Their intended use is to allow you to ensure that you are compiling and running with the correct version of the LDAP SDK for C. These features are in line with the latest LDAP SDK for C API Internet Draft.

As a result of these changes, the command line tools bundled with the LDAP SDK for C now check to ensure that they are running with the correct version of the library. If your library path variable (LD_LIBRARY_PATH on most Unix systems and the PATH variable on Windows NT) is set so that an old version of the LDAP SDK for C library is in use, then the command line tools can return one of the following error messages:

ldapsearch: unable to retrieve LDAP library version information; 
            this program requires an LDAP library that implements 
            revision 2003 or greater of the LDAP API. 

ldapsearch: this program requires an LDAP library that implements revision 
            2003 or greater of the LDAP API; running with revision 2002. 

ldapsearch: this program requires Mozilla's LDAP 
            library version 5.05 or greater; running with version 5.00.

By default, the tools will exit if they see a mismatch in versions. To override the version mismatch, you can use -0 option (zero, not 'o') with the tools, but results may vary.

64-Bit Safe Changes

Internal data types for liblber have been upgraded so that the data types are 64-bit safe. This is done in the following section of code in lber.h:

/*
 * Implementation-specific integer data types.  If living in an LP64
 * environment (where sizeof(long) is 64 bits), we use unsigned ints;
 * otherwise we use unsigned longs.  The goal is to always use 32-bit
 * quantities and to also be backwards compatible with previous SDK
 * versions which used unsigned longs.
 */

#if defined(_LP64)
       typedef unsigned int ber_len_t;
       typedef          int ber_signed_len_t;
       typedef unsigned int ber_tag_t;
       typedef          int ber_int_t;
#else
       typedef unsigned long ber_len_t;
       typedef          long ber_signed_len_t;
       typedef unsigned long ber_tag_t;
       typedef          long ber_int_t;
#endif

This change makes liblber consistent between environments where int data types are 32 bits and those where they are 64 bits. However, this change may cause some compilers, especially c++ compilers where strong type checking is enforced, to emit warnings or errors when you recompile old code.

ldap_url_parse() with Space-Separated Lists of Hosts

You can now pass ldap_url_parse() a string that uses the following format:

ldap://host1:port1 host2:port2 host2:port3 ... hostn:portn/<basedn>

Using this formatting, ldap_url_parse() will return results that are acceptable to ldap_init(). For example:

LDAP *ld;
LDAPURLDesc *ludpp;
int res;

char *url = "ldap://phonebook.example.com:2389 directory.example.com:389/dc=example,dc=com";

res = ldap_url_parse(url, &ludpp);
ld = ldap_init(ludpp->host, ludpp->port);

This input causes ldap_init() to try to connect to each host and port in the URL string until it finds a host with which it can connect.

Note that ludpp->port is set to the port identified on the last host in the URL string. If ludpp->port is used as shown here, then the last port identified on the URL string becomes the default port for any hosts for which a port is not explicitly set. Using the example above, suppose the URL string contained the following:

ldap://phonebook.example.com phonebook2.example.com phonebook3.example.com:2389/dc=example,dc=com

Here, ldap_init() would use port 2389 for all the hosts that it tries. If the last host in the string does not identify a port, then ludpp->port is set to zero (0). Setting the port to 0 tells ldap_init() to use the default port, which is 389 for ldap:// urls and 636 for ldaps:// urls.

Known problems

Please use Bugzilla to find out about known problems and recent fixes. List All Open LDAP C SDK bugs.