Chapter 11 Connecting Over SSL

The Sun™ Java System LDAP SDK for C includes functions to enable your application to connect to a Lightweight Directory Access Protocol (LDAP) server over a Secure Sockets Layer (SSL). This chapter covers the procedures for connecting and authenticating. It includes the following sections:

SSL and the LDAP SDK for C

The primary goal of the SSL protocol is to provide privacy and reliability between two communicating applications.



Note	SSL is not supported on all LDAP servers. The Sun Java System LDAP SDK for C only supports SSL 3.0 and does not support the Start Transport Layer Security (TLS) Operation. Also, SSL communication must take place on a separate TCP port. More information on SSL can be found in the Secure Sockets Layer (SSL) Protocol (v3), Internet-Draft Revision 3 (http://wp.netscape.com/eng/ssl3/).

When a LDAP client connects to a LDAP server over SSL, the server identifies itself by sending a certificate to the client. The client then needs to determine whether or not the certificate authority (CA) that issued the certificate is trusted so it searches a certificate database for the certificate of the CA. If the client cannot find the certificate or if the certificate is marked not trusted, the client refuses to connect to the server. The LDAP server may also request that the client send a certificate to authenticate itself. This part of the process is called certificate-based client authentication. If the client receives a request for a certificate from the server, the client retrieves its certificate from the certificate database and sends it to the server for authentication. After receiving the client’s certificate, the LDAP server would determine whether or not the CA that issued the certificate is trusted. 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. If the CA is trusted, the server then uses the subject name in the certificate to determine if the client has access rights to perform the requested operation.

The LDAP SDK for C includes functions that allow you to connect an LDAP client to an LDAP server over SSL. The functions assume the following:

Your client has access to a certificate database. The function call uses this certificate database to determine if it can trust the certificate sent from the server.



Caution	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 database that you are using contains any one of the following:

The certificate of the CA that issued the server’s certificate.

If the 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:

A client certificate (issued by a CA trusted by the LDAP server) in the certificate database.

A public/private key pair in a Netscape key file.

Set the session option for communicating with the server over SSL. For more information, see "Connecting to an LDAP Server 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".

Connecting to an LDAP Server Over SSL

Initialize your client by calling one of the following functions:

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. For an alternative way to accomplish this particular step, see "Alternative to ldapssl_init()".



Note	You need to initialize your client before initializing the LDAP session. The process of initializing the client opens the certificate database.

Code Example 11-1 initializes a client to connect to a secure LDAP server over SSL.

Code Example 11-1 Initializing a Client SSL Connection


if ( ldapssl_client_init( "/u/mozilla/.netscape/cert_file_name.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 */
...

Alternative to ldapssl_init()

As an alternative to calling the ldapssl_init() function (Step 2), you can do the following:

The effect of calling these three functions is the same as calling the ldapssl_init() function. Code Example 11-2 prepares a client to connect to a secure LDAP server over SSL using this alternate method.

Code Example 11-2 An Alternate Client SSL Initialization


if ( ldapssl_client_init( "/u/mozilla/.netscape/cert_file_name.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 */
...

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 session to use the standard SSL I/O functions provided with the LDAP SDK for C. If you want to use your own SSL I/O functions, use the ldap_io_fns structure. The procedure to specify your own SSL I/O functions is:

Code Example 11-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. In this case, the server requests that your client send a certificate to identify itself. This is the procedure to configure your client to use certificates for authentication:

You should call one of these functions to initialize your client instead of the ldapssl_client_init() function (Step a). Use ldapssl_advclientauth_init() 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.



Note	You can use these functions to initialize your client even if you do not plan to use certificate-based client authentication. They 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().

Perform a Simple Authentication and Security Layer (SASL) bind operation using the mechanism EXTERNAL. This indicates to the directory server that certificates should be used to authenticate clients.



Note	In all releases of Sun Java System Directory Server, 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.