NETSCAPE DIRECTORY SDK 3.0 FOR C RELEASE NOTES

• Changes in the 3.0 Release
• Changes Since the Beta 1 Release
• Installing the SDK
• Getting Started
• Changes in the LDAP API
• Reporting Problems
• Accessing the Directory Developer Newsgroup

Changes in the 3.0 Release
The following changes have been made in this release.

Support for the LDAP v3 protocol. The main new feature in this release is support for the LDAP v3 protocol. The LDAP v3 protocol is defined in the following RFCs and Internet Drafts:

• LDAP v3 Protocol (RFC 2551)
• LDAP v3 Attribute Syntax Definitions (RFC 2252)
• LDAP v3 UTF-8 String Representation of Distinguished Names (RFC 2253)
• LDAP v3 String Representation of LDAP Search Filters (RFC 2254)
• LDAP v3 URL Format (RFC 2255)
• The C LDAP Application Program Interface (Internet Draft)
• LDAP v3 Use of Language Codes (Internet Draft)
• Referrals and Knowledge References in LDAP Directories(Internet Draft)

The LDAP v3 protocol allows certain LDAP operations to be extended though the use of server controls. Your client can send a control with a request to the server. The server can send additional information to your client by including a control with the results it sends to your client. For example, using functions in the LDAP API, you can create, send, and receive controls that do the following:

• Sort search results on the server. You can include a server-sorting control with a search request that you send to the server. In the control, you specify the attribute that the server should use when sorting the results. When performing your requested search, the server sorts the results before sending the results back to your client.

• Receive notification of changes to data in the directory. You can include a persistent search control with a search request that you send to the server. In the control, you specify the kinds of changes that you want to track. When performing the requested search, the server does not end the search operation after sending your client the matching entries in the directory. Instead, if entries that match your search criteria are added, modified, renamed, or deleted and if the control specifies that you are tracking that type of change, the server sends the entry back your client.

  You can also specify that the server should return additional information about the change in an entry change notification control. (This control is included with each entry sent to your client.)

In addition, the Netscape Directory SDK for C now includes functions that you can use to request extended operations from the server. Extended operations are operations that can extend the LDAP protocol in arbitrary ways.

Note that LDAP controls and extended operations are part of the LDAP v3 protocol. In order to use these features, the LDAP server that you are working with must support the LDAP v3 protocol. The Netscape Directory Server 3.x and later versions supports LDAP v3 and its features (such as controls and extended operations).

In-memory cache for search results. A memory-based cache for search results has also been implemented in this release. See the Netscape Directory SDK 3.0 for C Programmer's Guide (provided in the docs directory) for information on the new ldap_memcache_* functions.

Change in SSL support. There are two changes to SSL support in the release of the Netscape Directory SDK 3.0 for C:

• Functions for client authentication are now provided. You can now authenticate to an LDAP server by sending a client certificate. Note that the LDAP server must support certificate-based client authentication. (See the chapter on SSL in the online documentation for details.)

• In order to use the SSL functions provided in the Netscape Directory SDK 3.0 for C, you must use a cert7.db certificate database, which is generated by Netscape Communicator. (Previous versions of the SDK used cert5.db databases, which are generated by Netscape Navigator 3.x browsers, and certificate databases generated by the Netscape Administration Server. Certificate databases that use these older formats are no longer supported with the LDAP SSL functions.)

  If the ldapssl_client_init() function returns an error, check to make sure that you are not using an older version of the certificate database. (The database should be named cert7.db .

  Also note that before you use the certificate database, you should make a copy of the database and use the copy. Do not use a cert7.db if it is currently being used by Netscape Communicator.

Changes Since the Beta 1 Release
The following changes have been made since the 3.0 Beta 1 release.

• The result code LDAP_INDEX_RANGE_ERROR has been added. This result code is returned by an LDAP server if a "virtual list view control" is used and the results of the search exceed the range provided by the offset value in the control.

• The ldap_controls_count() function has been removed from the API.

• Additional types of function pointers have been provided for specifying the threading functions that you want used when getting results from the server. The new LDAP_OPT_EXTRA_THREAD_FN_PTRS option allows you to specify a struct ldap_extra_thread_fns containing the additional function pointers that you want used.

• The new ldapssl_advclientauth_init function allows you to initialize your client for SSL while specifying the location of a security module database and specifying the level of verification of the server's certificate.

Installing the SDK

If you already have a 1.0 version of the SDK installed, install this SDK in a separate directory. Follow these instructions to install the Netscape Directory SDK for C:

• UNIX (Solaris, HP-UX, IRIX, AIX)
1. Save the file to a location on your hard drive where you want the SDK installed.
2. Unzip the file by entering the command:

gunzip <filename>.tar.gz
3. Untar the resulting tar file by entering the command:

tar xvof <filename>.tar.
• Win32 for Windows NT and Windows 95 (dk30e32s.exe)
1. Save the file named dk30e32s.exe to disk.
2. Install the SDK by double-clicking on the file in File Manager or Windows Explorer.

Getting Started

The Netscape Directory SDK for C includes the C libraries for the Lightweight Directory Access Protocol (LDAP) Application Programming Interface (API). You can use the functions in these libraries to enable your own application to connect to, search, and update LDAP servers on the Internet.

After installing the SDK, read the documentation in the docs directory and look at the samples in the examples directory.

Reading the Online Documentation
The Netscape Directory SDK for C includes the Netscape Directory SDK 3.0 for C Programmer's Guide in HTML format. To read this document:

1. Start Netscape Navigator.
2. Open the file named index.htm in the docs directory.

Compiling the Examples
The Netscape Directory SDK for C also includes the source code for sample LDAP clients that you can compile and run. The samples are in the examples directory.

Each client is an example of how you can use a set of API functions to search or update an LDAP server. For more information on these sample clients, see the README file in the examples directory.

Exploring the SDK
The Netscape Directory SDK for C contains the following directories:

• docs

This directory contains the Netscape Directory SDK 3.0 for C Programmer's Guide documentation. To view this online manual, start Netscape Navigator and open the file named index.htm in the docsdirectory.
• examples

This directory contains sample source code and makefiles for LDAP clients. See the README file in this directory for information about these clients.
• include

This directory contains the header files for the LDAP API. In the source files for your client applications, you need to include the ldap.h header file:

      #include "ldap.h"

You do not need to explicitly include the lber.h header file; lber.h is already included in ldap.h.

If you are calling the SSL functions (functions with the ldapssl_ prefix), you also need to include the ldapssl.h header file.

• lib

This directory contains the C library files for the LDAP API:
• For Solaris, HP-UX, IRIX and AIX, the library files consist of a shared library. The Netscape Directory SDK for C is available with or without SSL enabled, and the library names differ, depending on whether or not SSL is enabled.
  • If you have downloaded the SSL-enabled version of the Netscape Directory SDK for C, the shared library is named libldapssl30.so on Solaris, IRIX, and AIX, and libldapssl30.sl on HP-UX.

  • If you have downloaded the non-SSL version of the Netscape Directory SDK for C, the shared library is named libldap30.so on Solaris, IRIX, and AIX, and libldap30.sl on HP-UX.

  When running clients built with these libraries, make sure to set the appropriate environment variable that specifies the run-time path used to find libraries. For example, on Solaris and IRIX, set the LD_LIBRARY_PATH environment variable to the location of the shared library. On HP-UX, set SHLIB_PATH environment variable (if you've compiled with the -Wl,+s+b flag). On AIX, set the LIBPATH environment variable.

• For Windows, the library files include an import library and a dynamic link library. The Netscape Directory SDK for C is available with or without SSL enabled, and the library names differ, depending on whether or not SSL is enabled.
  • If you have downloaded the SSL-enabled version of the Netscape Directory SDK for C, the import library for Microsoft compilers is named nsldapssl32v30.lib and the dynamic link library is named nsldapssl32v30.dll.

  • If you have downloaded the non-SSL version of the Netscape Directory SDK for C, the import library for Microsoft compilers is named nsldap32v30.lib and the dynamic link library is named nsldap32v30.dll.

    The import library nsldap32v30bc.lib is intended for use with Borland compilers and is not officially supported at this time.

  When running clients built with these libraries, make sure to copy the dynamic link library to the directory containing your client or to a location where the DLL can be found. (For more information, see the section "Compiling Clients on Windows" in Chapter 2, "Using the Netscape Directory SDK for C", of the "Netscape Directory SDK 3.0 for C Programmer's Guide".)

  Note that this release of the SDK is intended for use with Intel architectures only.

• tools
  This directory contains the LDAP command-line tools. These are similar to the tools provided with the Netscape Directory Server (see the Netscape Directory Server Administrator's Guide for details). Note that in order to use these applications, you need to make sure that the application can find the LDAP API shared library or dynamic link library. See the notes on the lib directory above for details.

Changes in the LDAP API
This section is divided into two parts:

• Functions carried forward from 1.0/1.1 Release
• Functions that have been deprecated
• New Functions in 3.0 SDK

 The following functions have been have been carried forward from the 1.0/1.1 Release:

• ldap_simple_bind
• ldap_simple_bind_s
• ldap_unbind
• ldap_unbind_s
• ldap_search
• ldap_search_s
• ldap_search_st
• ldap_compare
• ldap_compare_s
• ldap_add
• ldap_add_s
• ldap_delete
• ldap_delete_s
• ldap_abandon
• ldap_first_message
• ldap_next_message
• ldap_first_entry
• ldap_next_entry
• ldap_first_attribute
• ldap_next_attribute
• ldap_init
• ldap_get_option
• ldap_set_option
• ldap_get_values
• ldap_get_values_len
• ldap_result
• ldap_msgfree
• ldap_msgtype
• ldap_err2string
• ldap_result2error
• ldap_perror
• ldap_memfree
• ldap_value_free
• ldap_value_free_len
• ldap_get_dn
• ldap_explode_dn
• ldap_explode_rdn

• ldap_bind
• ldap_bind_s
• ldap_kerberos_bind
• ldap_kerberos_bind_s
• ldap_modrdn
• ldap_modrdn_s
• ldap_open

• ldap_sasl_bind
• ldap_sasl_bind_s
• ldap_search_ext
• ldap_search_ext_s
• ldap_compare_ext
• ldap_compare_ext_s
• ldap_modify_ext
• ldap_modify_ext_s
• ldap_rename
• ldap_rename_s
• ldap_add_ext
• ldap_add_ext_s
• ldap_delete_ext
• ldap_delete_ext_s
• ldap_extended_operation
• ldap_extended_operation_s
• ldap_abandon_ext
• ldap_parse_result
• ldap_parse_sasl_bind_request
• ldap_parse_extended_result
• ldap_first_reference
• ldap_next_reference
• ldap_control_free
• ldap_controls_free
• ldap_count_messages
• ldap_count_entries
• ldap_count_references
• ldap_count_values
• ldap_count_values_len
• ldap_dn2ufn

Reporting Problems

Please submit your problem via the DevEdge Bug Report Form

Accessing the Directory Developer Newsgroup

If you have additional questions or need more information about the Netscape Directory SDK for C, see the directory developer newsgroup (snews://secnews.netscape.com/netscape.dev.directory).