Mozilla LDAP SDK Programmer's Guide/SSL Connections With LDAP Java SDK

This section describes the process of enabling an LDAP client to connect to an LDAP server over the Secure Sockets Layer (SSL) protocol. The chapter explains how to connect to an LDAP server with SSL. It also covers SSL authentication.

How SSL Works With LDAP Java SDK

LDAP Java SDK includes classes and methods to enable your application to connect to an LDAP server over a Secure Sockets Layer (SSL).

Understanding SSL

The primary goal of the SSL Protocol is to provide privacy and reliability between two communicating applications. For more information about SSL and Transport Layer Security, refer to RFC 2246, The TLS Protocol.

The LDAP Java SDK supports SSL 3.0.

SSL and LDAP

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 can also request that the client send a certificate to authenticate. 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. With the subject name, the server determines if the client has access rights to perform the requested operation.

To use SSL, you need a certificate database to hold the CA certificate. If certificate-based client authentication is used, you need the client certificate.

Interfaces and Classes for SSL

LDAP Java SDK includes the LDAPSocketFactory interface.

This interface describes a single method, makeSocket, that returns a socket to a given server specified by a host name and port number.

To establish an SSL connection, you need to create an object of a class that implements this interface.

Classes that implement this interface rely on a separate class that implements SSL sockets. In the constructors for objects that implement LDAPSocketFactory, you typically need to specify the name of a class that implements SSL sockets. The following classes implement this interface.

• LDAPSSLSocketFactory: Use this class if you are using the netscape.net.SSLSocket class to implement SSL sockets. You can also use this class if the class that implements SSL sockets extends the Socket object.
• LDAPSSLSocketWrapFactory: Use this class if the class that implements SSL sockets does not extend the Socket object. The LDAPSSLSocketWrapFactory class wraps your SSL socket implementation class in a class that does extend the Socket object.
• JSSESocketFactory: Use this class to rely on the standard SSL socket factory code.

You can construct an object for one of these factory classes. You can pass the factory object to the constructor for the LDAPConnection object, to identify the socket factory that is used for the connection.

Prerequisites for Connecting Over SSL With LDAP Java SDK

The LDAP Java classes that enable you to connect over SSL assume the following:

• Your client has access to a Netscape Security Services (NSS) certificate database.
  If your client runs in a Mozilla browser, you can use the browser certificate database. With the browser certificate database, you can determine if you trust the certificate that is sent from the server.
• The database used contains one of the following certificates:
  • The certificate of the CA who issued the server certificate
  • If the CAs are organized hierarchically, the certificate of any CA in the hierarchy
  • The certificate of the server
  • The CA certificate is marked as trusted in the database.
• If you use certificate-based client authentication, you must have the following data:
• A client certificate issued by a CA trusted by the LDAP server
  This certificate must be in the client certificate database.
• A public key, private key pair in an NSS key database on the client side

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. Your client then searches the certificate database for the certificate of the issuing CA.

Your client might not find the CA certificate. Your client might also find that the CA certificate is marked as not trusted.

If either condition occurs, 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. Your client sends the certificate to the server for authentication. The server determines which CA issued the client certificate. The server then searches its certificate database for the certificate of the issuing CA.

The server might not find the CA certificate. The CA certificate might be marked as not trusted. If either condition occurs, the server refuses to authenticate your client.

Connecting to a Server Over SSL With LDAP Java SDK

To connect to an LDAP server with SSL, do the following:

1. Construct a new LDAPSSLSocketFactory object or a new LDAPSSLSocketWrapFactory object.
   This object represents the SSL socket factory used to create the sockets for establishing connections with the LDAP server.
   The constructors for these classes allow you to specify the name of the class used to create the actual sockets.
2. For the LDAPSSLSocketFactory constructor, you should specify a class that implements the javax.net.ssl.SSLSocket interface.
   By default, if you do not specify a class, the netscape.net.SSLSocket class is used.
3. If the SSL socket class does not extend the Socket class, use the LDAPSSLSocketWrapFactory constructor.
4. Pass the object that you constructed to the LDAPConnection constructor.

When first you establish a connection to the LDAP server, use the makeSocket method of the specified object that you used to construct the socket.

Using Certificate-Based Client Authentication With LDAP Java SDK

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

With LDAP Java SDK, you can set up your client to perform certificate-based authentication in either of the following situations:

• Your client runs as an applet in a Mozilla browser
• Your client uses a class implementing the LDAPSocketFactory interface and supporting client-based authentication

When using certificate-based client authentication, consider the following:

• The LDAPSSLSocketWrapFactory class does not support certificate-based client authentication.
• The LDAPSSLSocketFactory class relies on the browser to support certificate-based client authentication. The class does not support the use of certificates for authentication outside the browser, in stand-alone Java applications.

To enable an applet to use certificate-based client authentication, do the following:

1. Construct a new LDAPSSLSocketFactory object.
2. Invoke the enableClientAuth method of the object to enable certificate-based client authentication.
3. Pass the object that you constructed to the LDAPConnection constructor.