Mozilla LDAP C SDK 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:

How SSL Works with the LDAP C SDK

The Mozilla LDAP C SDK 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.

The Mozilla LDAP C SDK 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. Refer to Where to Find Additional Information for information on SSL. 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 Mozilla LDAP C SDK includes API functions that allow you to connect over SSL to an LDAP server. The API functions allow you to do the following:

Set the session option for communicating with the server over SSL. For more information, see "Enabling Your Client to Connect Over SSL."
Replace the default I/O functions with your own I/O functions for communicating over SSL. For more information, see "Installing Your Own SSL I/O Functions."
Enable your client to send certificates to authenticate itself. For more information, see "Using Certificate-Based Client Authentication."

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 Mozilla LDAP C SDK that enable you to connect over SSL rely assume the following:

Your client has access to an NSS certificate database.
This must be the cert7.db database file used by the Mozilla and Netscape clients.x and above.
Note that previous and later versions of these applications use different file formats for the certificate database. Attempting to use a different version of the certificate database will result in database errors.
The LDAP API function call uses this certificate database to determine if it can trust the certificate sent from the server.
The database that you are using contains any one of the following:
- The certificate of the certificate authority (CA) that issued the server's certificate.
- If the certificate authorities (CAs) are organized in a hierarchy, the certificate of any of the CAs in the hierarchy.
- The certificate of the LDAP server.
The CA certificate is marked as "trusted" in the certificate database.
If you plan to use certificate-based client authentication, you also need the following:
- A client certificate (issued by a CA trusted by the LDAP server) in the certificate database.
- A public/private key pair in an NSS key file (this must be the key3.db file used by the Mozilla and Netscape clients.x and greater).

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:

Initialize your client by calling one of the following functions (note that these functions are not multithread safe):
- Call ldapssl_client_init() if you do not plan to use certificate-based client authentication.
- Call ldapssl_clientauth_init() if you plan to use certificate-based client authentication.
- Call ldapssl_clientauth_init() if you plan to use certificate-based client authentication and need to specify either the name and path of the security module database or the method of verifying the server's certificate.
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 initializes a client to connect to a secure LDAP server over SSL.

Code Example 12-1 - Initializing a client SSL connection

  printf( "Failed to initialize SSL client...\n" ); 
  return( 1 ); 
} 
/* get a handle to an LDAP connection */ 
if ( (ld = ldapssl_init( "cert.example.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:

Initialize an LDAP session with the server by calling the standard initialization function ldap_init().
Install the standard SSL I/O functions by calling ldapssl_install_routines().
Set the SSL option in the LDAP struct by calling ldap_set_option().

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.

Code Example 12-2 - An alternate client SSL initialization

  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 */
...

Handling Errors

The function ldapssl_err2string() provides support for special SSL error messages that are not handled by the normal error conversion routine ldap_err2string(). After calling any of the SSL initialization functions, you may convert SSL-specific errors codes to text strings by calling ldapssl_err2string().

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 Mozilla LDAP C SDK.

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:

Create an ldap_io_fns structure, and set the fields to point to your I/O functions.
Call ldap_set_option() to point to that structure.

For example:

Code Example 12-3 - Setting custom SSL I/O functions

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:

Initialize your client by calling one of the following functions (note that these functions are not multithread safe):
- ldapssl_clientauth_init()
- ldapssl_advclientauth_init()
  Use this function if you need to specify the name and path of a security module database or if you need to specify the method used to verify the server's certificate.
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().
Initialize an LDAP session with the secure server by calling ldapssl_init().
Enable your client to authenticate with the secure server by calling ldapssl_enable_clientauth().
(Optional) Perform a SASL bind operation using the mechanism "EXTERNAL". This indicates to the directory server that certificates should be used to authenticate clients.
In Netscape Directory Server 4.x and later, 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."