210 lines
11 KiB
Plaintext
210 lines
11 KiB
Plaintext
<!--
|
|
|
|
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>
|