Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide

Chapter 12
Connecting Over SSL

This chapter describes the process of enabling an LDAP client to connect to an LDAP server over the Secure Sockets Layer (SSL) protocol. The chapter covers the procedures for connecting to an LDAP server and authenticating.

The chapter includes the following sections:

Overview: How SSL Works with the Netscape LDAP C SDK

The Netscape Directory SDK for C includes functions to enable your application to connect to an LDAP server over a Secure Sockets Layer (SSL).

The primary goal of the SSL Protocol is to provide privacy and reliability between two communicating applications. For more information on SSL, see the following resources:

The Netscape Directory SDK for C only supports SSL 3.0 and does not support the Start Transport Layer Security (TLS) Operation. SSL communication must take place on a separate TCP port.

Note that SSL is not supported by all LDAP servers.

When an LDAP client connects to an LDAP server over SSL, the LDAP server identifies itself by sending its certificate to the LDAP client. The LDAP client needs to determine whether or not the certificate authority (CA) who issued the certificate is trusted.

The LDAP server may also request that the client send a certificate to authenticate itself. (This process is called certificate-based client authentication.)

After receiving the client's certificate, the LDAP server determines whether or not the CA who issued the certificate is trusted. If the CA is trusted, the server uses the subject name in the certificate to determine if the client has access rights to perform the requested operation.

The Netscape Directory SDK for C includes API functions that allow you to connect over SSL to an LDAP server. The API functions allow you to do the following:

The API functions require a certificate database to hold the CA certificate and (if certificate-based client authentication is used) the client's certificate. For details, see "Prerequisites for Connecting Over SSL".

Prerequisites for Connecting Over SSL

The API functions in the Netscape Directory SDK for C that enable you to connect over SSL rely assume the following:

Essentially, when your client sends an initial request to the secure LDAP server, the server sends its certificate back to your client. Your client determines which CA issued the server's certificate and searches the certificate database for the certificate of that CA.

If your client cannot find the CA certificate or if the CA certificate is marked as "not trusted," your client refuses to connect to the server.

If you are using certificate-based client authentication, your client retrieves its certificate from the certificate database and sends it to the server for authentication. The server determines which CA issued the client's certificate and searches its certificate database for the certificate of that CA.

If the server cannot find the CA certificate or if the CA certificate is marked as "not trusted," the server refuses to authenticate your client.

Enabling Your Client to Connect Over SSL

To connect to an LDAP server using SSL, you need to:

  1. Initialize your client by calling one of the following functions:

  2. Initialize an LDAP session with the secure server by calling the ldapssl_init() 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/cert7.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 */
...
As an alternative to calling the ldapssl_init() function, you can do the following:

  1. Initialize an LDAP session with the server by calling the standard ldap_init() function.

  2. Install the standard SSL I/O functions by calling the ldapssl_install_routines() function.

  3. Set the SSL option in the LDAP struct by calling the ldap_set_option() function.
The effect of calling these three functions is the same as calling the ldapssl_init() 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/cert7.db", NULL ) < 0) { 
   printf( "Failed to initialize SSL client...\n" ); 
   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 ) != 0 ) { 
   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 ) != 0 ) { 
   ldap_perror( ld, "ldap_set_option" ); 
   return( 1 ); 
} 
/* Client can now perform LDAP operations on the secure LDAP server */
...

Installing Your Own SSL I/O Functions

The ldapssl_init() and ldapssl_install_routines() functions both set up the LDAP session to use the standard SSL I/O functions provided with the Netscape Directory SDK for C.

If you want to use your own SSL I/O functions, you can use the ldap_io_fns structure. If you plan to specify your own SSL I/O functions, follow these steps:

  1. Create an ldap_io_fns structure, and set the fields to point to your I/O functions.

  2. Call ldap_set_option() to point to that structure.

    3. For example: 

    ...
    if (ldap_set_option( ld, LDAP_OPT_IO_FN_PTRS, &my_io_struct) != 0 ) {
       ldap_perror( ld, "ldap_set_option" );
       return( 1 );
    }
    ...

Using Certificate-Based Client Authentication

Some LDAP servers may be configured to use certificate-based client authentication. A server may request that your client send a certificate to identify itself.

To configure your client to use certificates for authentication, follow these steps:

  1. Initialize your client by calling one of the following functions:

    2. You should call one of these functions instead of the ldapssl_client_init() function to initialize your client.

    (Note that you can also use these functions to initialize your client even if you do not plan to use certificate-based client authentication. These functions are equivalent to ldapssl_client_init().)

  2. Initialize an LDAP session with the secure server by calling the ldapssl_init() function.

  3. Enable your client to authenticate with the secure server by calling the ldapssl_enable_clientauth() function.

  4. (Optional) Perform a SASL bind operation using the mechanism "EXTERNAL". This indicates to the directory server that certificates should be used to authenticate clients.

    5. In the Netscape Directory Server 3.0 and more recent versions, this is done regardless of whether an explicit SASL bind operation with the "EXTERNAL" mechanism is done.

    In the Netscape Directory Server 4.0, if you perform a SASL bind operation and the server cannot find the corresponding directory entry for a client certificate, the server returns an LDAP_INVALID_CREDENTIALS result code with the error message "client certificate mapping failed."

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:04:55