<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="ssl"><title>SSL Connections With &DirectorySDKForJava;</title>
<highlights>
<para>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
explains how to connect to an LDAP server with SSL. It also covers SSL authentication.
</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="ssl-overview">How SSL Works With Directory
SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="ssl-prerequisites">Prerequisites for Connecting
Over SSL With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="ssl-connecting">Connecting to a Server Over
SSL With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="ssl-cert-based-auth">Using Certificate-Based
Client Authentication With Directory SDK for Java</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="ssl-overview"><title>How SSL Works With &DirectorySDKForJava;</title>
<para>&DirectorySDKForJava; includes classes and methods to enable your
application to connect to an LDAP server over a <firstterm>Secure Sockets
Layer</firstterm> (SSL).</para>
<sect2 id="ssl-overview-overview"><title>Understanding SSL</title>
<para>The primary goal of the SSL Protocol is to provide privacy and reliability
between two communicating applications. For more information about SSL and <firstterm>
Transport Layer Security</firstterm>, refer to <ulink
url="http://www.ietf.org/rfc/rfc2246.txt" type="text">RFC 2246</ulink>, <emphasis>
The TLS Protocol</emphasis>.</para>
<para>The &DirectorySDKForJava; supports SSL 3.0.</para></sect2>
<sect2 id="ssl-ldap"><title>SSL and LDAP</title>
<para>When an LDAP client connects to an LDAP server over SSL, the LDAP server
identifies itself by sending its <firstterm>certificate</firstterm> to the
LDAP client. The LDAP client needs to determine whether or not the <firstterm>certificate
authority</firstterm> (CA) who issued the certificate is trusted.</para>
<para>The LDAP server can also request that the client send a certificate
to authenticate. This process is called <firstterm>certificate-based client
authentication</firstterm>.</para>
<para>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.</para>
<para>To use SSL, you need a <firstterm>certificate database</firstterm> to
hold the CA certificate. If certificate-based client authentication is used,
you need the client certificate.</para></sect2>
<sect2 id="ssl-interfaces-classes"><title>Interfaces and Classes for SSL</title>
<para>&DirectorySDKForJava; includes the <classname>LDAPSocketFactory</classname> interface.
This interface describes a single method, <literal>makeSocket</literal>, 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.</para>
<para>Classes that implement this interface rely on a separate class that
implements SSL sockets. In the constructors for objects that implement <classname>
LDAPSocketFactory</classname>, you typically need to specify the name of a
class that implements SSL sockets. The following classes implement this interface.
</para>
<variablelist>
<varlistentry><term><classname>LDAPSSLSocketFactory</classname></term>
<listitem><para>Use this class if you are using the <classname>netscape.net.SSLSocket
</classname> class to implement SSL sockets. You can also use this class if
the class that implements SSL sockets extends the <classname>Socket</classname> object.
</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>LDAPSSLSocketWrapFactory</classname></term>
<listitem><para>Use this class if the class that implements SSL sockets does
not extend the <classname>Socket</classname> object. The <classname>LDAPSSLSocketWrapFactory
</classname> class wraps your SSL socket implementation class in a class that
does extend the <classname>Socket</classname> object.</para>
</listitem>
</varlistentry>
<varlistentry><term><classname>JSSESocketFactory</classname></term>
<listitem><para>Use this class to rely on the standard SSL socket factory
code.</para>
</listitem>
</varlistentry>
</variablelist>
<para>You can construct an object for one of these factory classes. You can
pass the factory object to the constructor for the <classname>LDAPConnection</classname> object,
to identify the socket factory that is used for the connection.</para></sect2>
</sect1>
<sect1 id="ssl-prerequisites"><title>Prerequisites for Connecting Over SSL
With &DirectorySDKForJava;</title>
<itemizedlist>
<para>The LDAP Java classes that enable you to connect over SSL assume the
following:</para>
<listitem><para>Your client has access to a Netscape Security Services (NSS)
certificate database.</para><para>If your client runs in a Netscape or 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.</para></listitem>
<listitem><para>The database used contains one of the following certificates:</para>
<itemizedlist>
<listitem><para>The certificate of the CA who issued the server certificate</para>
</listitem>
<listitem><para>If the CAs are organized hierarchically, the certificate of
any CA in the hierarchy</para></listitem>
<listitem><para>The certificate of the server</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>The CA certificate is marked as <literal>trusted</literal> in
the database.</para></listitem>
<listitem><para>If you use certificate-based client authentication, you must
have the following data:</para>
<itemizedlist>
<listitem><para>A client certificate issued by a CA trusted by the LDAP server</para>
<para>This certificate must be in the client certificate database.</para>
</listitem>
<listitem><para>A public key, private key pair in an NSS key database on the
client side</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>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.</para>
<para>Your client might not find the CA certificate. Your client might also
find that the CA certificate is marked as <literal>not trusted</literal>.
If either condition occurs, your client refuses to connect to the server.</para>
<para>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.</para>
<para>The server might not find the CA certificate. The CA certificate might
be marked as <literal>not trusted</literal>. If either condition occurs, the
server refuses to authenticate your client.</para></sect1>
<sect1 id="ssl-connecting"><title>Connecting to a Server Over SSL With &DirectorySDKForJava;</title>
<orderedlist>
<para>To connect to an LDAP server with SSL, do the following:</para>
<listitem><para>Construct a new <classname>LDAPSSLSocketFactory</classname> object
or a new <classname>LDAPSSLSocketWrapFactory</classname> object.</para><para>This
object represents the SSL socket factory used to create the sockets for establishing
connections with the LDAP server.</para><para>The constructors for these classes
allow you to specify the name of the class used to create the actual sockets.</para>
<itemizedlist>
<listitem><para>For the <literal>LDAPSSLSocketFactory</literal> constructor,
you should specify a class that implements the <classname>javax.net.ssl.SSLSocket
</classname> interface. By default, if you do not specify a class, the <classname>
netscape.net.SSLSocket</classname> class is used.</para></listitem>
<listitem><para>If the SSL socket class does not extend the <classname>Socket</classname> class,
use the <classname>LDAPSSLSocketWrapFactory</classname> constructor.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>Pass the object that you constructed to the <literal>LDAPConnection
</literal> constructor.</para><para>When first you establish a connection
to the LDAP server, use the <literal>makeSocket</literal> method of the specified
object that you used to construct the socket.</para></listitem></orderedlist>
</sect1>
<sect1 id="ssl-cert-based-auth"><title>Using Certificate-Based Client Authentication
With &DirectorySDKForJava;</title>
<indexterm>
<primary>authentication</primary>
<secondary>certificate-based</secondary>
</indexterm><indexterm>
<primary>certificate-based client authentication</primary>
</indexterm>
<para>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.</para>
<itemizedlist>
<para>With &DirectorySDKForJava;, you can set up your client to perform
certificate-based authentication in either of the following situations:</para>
<listitem><para>Your client runs as an applet in a Netscape or Mozilla browser</para>
</listitem>
<listitem><para>Your client uses a class implementing the <classname>LDAPSocketFactory
</classname> interface and supporting client-based authentication</para>
</listitem>
</itemizedlist>
<itemizedlist>
<para>When using certificate-based client authentication, consider the following:
</para>
<listitem><para>The <classname>LDAPSSLSocketWrapFactory</classname> class
does not support certificate-based client authentication.</para></listitem>
<listitem><para>The <classname>LDAPSSLSocketFactory</classname> 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.</para></listitem>
</itemizedlist>
<orderedlist>
<para>To enable an applet to use certificate-based client authentication,
do the following:</para>
<listitem><para>Construct a new <classname>LDAPSSLSocketFactory</classname> object.
</para></listitem>
<listitem><para>Invoke the <literal>enableClientAuth</literal> method of the
object to enable certificate-based client authentication.</para></listitem>
<listitem><para>Pass the object that you constructed to the <literal>LDAPConnection
</literal> constructor.</para></listitem></orderedlist>
</sect1>
</chapter>
