NETSCAPE DIRECTORY SERVER

CONTENTS

These release notes include:

• Supported Platforms
• Installing the SDK
• New Features and Enhancements
  • LDAP_X_OPT_CONNECT_TIMEOUT
  • LDAP library/API Version Mismatch Error Messages
  • 64 Bit Safe Changes
  • ldap_url_parse() with Space-Separated Lists of Hosts
• Known Problems
• More Information

SUPPORTED PLATFORMS

The LDAP SDK for C, version 4.1 provides support for the following platforms:

• SunOS 5.6 (32-bit)
• SunOS 5.8 (64-bit)
• AIX 4.3.2
• Digital Tru64 (Digital Unix 4.0d)
• HP-UX 11.0 (both 32-bit and 64-bit)
• Linux 2.2 (for x86) (glibc 2.0)
• Windows NT 4.0 sp6
• Windows 95, Windows 98

INSTALLING THE SDK

Follow these instructions to install the Netscape LDAP SDK for C:

• For UNIX systems (Solaris, AIX, Digital Tru64, HP/UX, Linux)
  1. Save the appropriate UNIX file to disk.
  2. Uncompress the gzip file by typing:

         gunzip <filename>.tar.gz

  3. Unpack the resulting tar file by typing:

         tar xvof <filename>.tar

• For Win32 systems (Windows NT and Windows 95)
  1. Save the file named dk41x32s.exe to disk.
  2. Install the SDK by double-clicking the file in File Manager or Windows Explorer.

Note that you should install this version of the LDAP SDK for C into a different directory than any other installed version of this software.

NEW FEATURES AND ENHANCEMENTS

This section of enhancements details the changes that were made to both versions 4.0 and 4.1 of the LDAP SDK for C.

The following set of modifications were made to the LDAP SDK for C, version 4.1:

• The LDAP SDK for C library names were changed to indicate the new version of the SDK. For example, the new Solaris version of the SDK library is libldapssl41.so. For information on how to build and link applications that uses this SDK, see the make files for the SDK examples.

• Various changes were made to the LDAP SDK for C to align it with the LDAPv3, described in RFC 2251. You can find this RFC at the following URL:

  http://www.ietf.org/rfc/rfc2251.txt?number=2251

• Non-blocking connect functionality has been added. For more information, please see LDAP_X_OPT_CONNECT_TIMEOUT.

• 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.h file outlines the new callbacks.

• Netscape Portable Runtime library (NSPR) support was added. The library, libldappr 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 library libldapr is statically linked in the version of the SDK that is available from both Mozilla and iPlanet's web sites.

  The new example nsprio.c shows how to use the new interfaces. Note that before you can compile the example, you will need to rework the makefile to include NSPR v3.5.1. You can checkout the NSPR 3.5.1 source from http://www.mozilla.org with the following CVS command:

  cvs co -r NSPRPUB_RELEASE_3_5_1 mozilla/nsprpub
  

  Make sure to set your CVSROOT environment variable as described on http://www.mozilla.org/cvs.html before running the cvs checkout command. For information on NSPR and its API, see http://www.mozilla.org/docs/refList/refNSPR/.

• 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 iPlanet Directory Server, version 5.0.
  • 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, found at (ftp://ftp.isi.edu/in-notes/rfc2849.txt).
  • 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 following set of modifications were made to the LDAP SDK for C, version 4.0:

• 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 a 4.1 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 /h/bjensen/.netscape/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

The LDAP SDK for C, v4.1 provides 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 "mydirectory.siroe.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 "mydirectory.siroe.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

This feature was added to version 4.0 of the LDAP SDK for C.

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 Netscape Communications Corp.'s LDAP 
        library version 3.20 or greater; running with version 3.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

This feature was added to version 4.0 of the LDAP SDK for C.

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

This feature was added to version 4.0 of the LDAP SDK for C.

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.airius.com:2389 directory.airius.com:389/o=airius.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.airius.com phonebook2.airius.com phonebook3.airius.com:2389/o=airius.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

The following is a known bug in this release of the LDAP SDK for C:

• The IO Connect Timeout feature does not work on Windows NT with SSL. That is, the Windows NT connection always blocks for the Windows NT TCP/IP timeout value (approximately 50 seconds) in the event that the host is not reachable. This is because the PR_Connect() function in the Windows NT version of NSPR does not timeout, and so a timeout value cannot be set for it. This problem will be resolved in a future release when a fixed version of NSPR becomes available. (42900)

MORE INFORMATION

Netscape and iPlanet provide binary releases of this SDK. However, note that this SDK is also available in source code form as part of the Mozilla.org open source project. Refer to the following site for more information on how you can get the source code and contribute to the further development of this SDK:

http://www.mozilla.org/directory