Java Secure Socket Extension
API Overview
This document provides a short summary of the key features of
the API. It is
background for the more detailed API references provided through
the api guide. For an overview
of the currently implemented product feaures such as supported
SSL cipher suites see the JSSE reference implementation
fact sheet.
Sections of this Document
The functionality presented here includes the following:
What is SSL?
SSL and related secure socket protocols encapsulate an application
data stream over another stream protocol such as TCP. The
Java Secure Socket Extension provides a common, standard api
to access these protocols.
Secure sockets enhance TCP by providing three security services:
- Authentication, securely identifying the peer at
the other end of the connection by a set of X.509 public key
certificates or other means;
- Confidentiality, protecting data from eavesdroppers
by encrypting it.
- Integrity Protection, preventing undetected changes
to data as it is exchanged between clients and servers;
Integrity checking is always present, and by default so are
server authentication and data confidentiality.
Authentication can be mutual; see the sections on peer and self
authentication for more details.
This functionality is provided by the
javax.net.ssl.SSLSocket and
javax.net.ssl.SSLServerSocket
classes, which are for most purposes
treated just like their parent java.net.Socket
and
ServerSocket classes.
Instances of these classes may be used exactly like instances of the
java.net classes from which they derive, except when new
SSL-specific functionality is required. Such functionality includes
session creation, cipher suite negotiation, and authentication,
which are described in more detail later in these notes.
A few additional features which are briefly addressed here.
Typical Usage
Consult any reference on the use of Java's socket classes to see
how the basic socket API calls are used. The primary new feature
of this API is the use of socket factories for acquiring sockets,
rather than directly invoking constructors:
SocketFactory f = SSLSocketFactory.getDefault ();
Socket s = f.createSocket ("hostname", port);
That is, SSL sockets may be used exactly like other Java sockets,
and none of the special APIs described in this document are required
to achieve basic network connectivity.
Other Features
SSL's socket support has several features which are not
otherwise emphasized in these notes:
- SSL has the notion of a "server" and a "client" role in
connection setup. Some facilities to control these are provided.
You can implement the server side of FTP's normal DATA channel
as a TCP client, then make it act as an SSL server
to take advantage of the established SSL session for faster
initial connection setup.
- Any given SSL connection is a member of a "session". Sessions
may be used by multiple connections, concurrently or sequentially.
Sessions contexts are are used by servers to manage sessions and
associate sensitive data with them (for example, using a Hashtable).
- Any given SSL session has a single "cipher suite", which defines
the cryptographic algorithms used with that session.
The SSL protocol involves two basic operations: handshaking and
data transfer. Data transfer is performed by accessing the socket's
input and output streams, as usual; the data is protected using the
cipher suite which was negotiated.
Handshaking negotiates security parameters, and you may initiate
it at any time. It is initiated transparently before the first data
transfer on a connection, if it has not already completed. An api
to allow for delayed handshake initiation will be added in the near
future. Before any handshake, you might:
- Set security parameters used in this handshake, by
enabling specific cipher suites as described below.
- Ask to receive an event when the handshake completes, with
an event listener registered using the
SSLSocket.registerHandshakeCompletedListener method.
- Cause a new handshake to begin, using the
SSLSocket.startHandshake method. Servers may
specify that client authentication is required.
The outcome of handshaking is either creation of a new session
between the client and server, or resumption of an existing session.
In some applications (such as HTTPS) sessions are transparent. In
others, they can reflect significant events such as authenticating
to a firewall to set up a persistent tunnel.
The SSLSession
with which a connection is associated is exposed by the
getSession
method, and is included in the
event which signifies handshake completion.
From that session object, you may determine peer identity
and the particular cipher suite which has been negotiated.
Overview of Methods Affecting Cipher Negotiation
There are several methods which may be used to control the particular
cipher suites which are negotiated:
SSLSocketFactory.getSupportedCipherSuites
returns the list
of cipher suites supported by this implementation of SSL.
SSLSocket.setEnabledCipherSuites
enables
some or all of the
supported cipher suites, and may be applied both to server
and to connection sockets.
In addition, you may determine which cipher suites are normally
enabled by calling SSLSocketFactory.getDefaultCipherSuites
.
Not all cipher suites are enabled by default, and even if a suite
is enabled, it may not be usable. For example, both client and
server must enable some common cipher suite to communicate.
Initially, the enabled cipher suites are those which are
(a) supported (you can only use a fixed set
of cryptographic algorithms);
(b) provide server authentication, and
(c) provide confidentiality protection.
Handshaking will choose a cipher suite which is enabled by both
the server and the client, and which has appropriate support
in terms of certificates and keys available. For example, a
server could default to having a DHE_DSS based cipher suite
enabled (if it were supported) but might never choose that as
the outcome of handshaking, if it had no DSS certificate and
private key.
But what is a Cipher Suite?
A cipher suite combines four kinds of security option,
and is given a name:
- What kind of key exchange algorithm is used. SSL
defines many; the one that relies on RSA-certified server
identities is currently the most interoperable one.
- Whether it is exportable:
SSL supports the use of short public
keys for key exchange and symetric keys for encryption,
which are currently
subject to breaking in an afternoon by a motivated and moderately
well equipped (several hundred workstations) adversary.
This allows SSL implementations to receive export approval from the
U.S. government to most countries.
- What encryption algorithm is used. The fastest
option is the RC4 stream cipher; DES and variants (DES40, 3DES-EDE)
are also supported in "cipher block chaining" (CBC) mode,
as is (in some suites) null encryption. (Null
encryption does nothing; in such cases SSL is used to authenticate
and ensure integrity protection.)
- What digest algorithm is used for the Message
Authentication Code, either MD5 or SHA1.
So for example the cipher suite named
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
uses SSL, an authenticated Diffie-Hellman key exchange (DHE_DSS),
is export grade (EXPORT), uses an exportable variant of
the DES cipher (DES40_CBC), and uses the SHA1 digest
algorithm in its MAC (SHA).
Authentication is both a protocol feature of SSL, and an
action done before using SSL in order to support that protocol
feature in a secure manner. The goal is that nobody should be
able to authenticate themselves using SSL unless they've first
proven their identity outside the context of SSL.
Peer Authentication
This functionality is provided as a normal part of SSL
handshaking, as follows:
- Session.getPeerCertificateChain is used to acquire
the peer's certificate chain (by either client or server);
- SSLServerSocket.setNeedClientAuth requires client
authentication during initial handshaking.
- When a peer authenticates, its chain of X509
Certificates is verified.
- SSLSocket.startHandshake() may be used by servers
to request a client to start a new handshake or by clients
to start a new handshake.
Self Authentication and Login
All secure sockets are created through socket factories and
these factories are ultimately created by an
SSLContext.
The SSLContext must be initialized with authentication
related keys and certificates before it can be used
to create non-anonymous secure sockets. The JSSE reference
implemention provides a set of provider-based classes
for creating and initializing SSL context objects.
However, these APIs are not needed by code which is
run inside an "application container" such as a browser or web server
supporting servlets. In that case, the container itself provides the
authentication and trust decision support and the applet or servlet
need only use the public javax.net.ssl.* or java.net.URL apis.
In addition, the getDefault() static method on
SSLSocketFactory
provides access to a socket factory which can be used to
make secure sockets which authenticate the server but not the
client.
Encrypted Private Key Storage
Access to private key material is provided through the
standard Java 2 KeyStore API and keytool administration
utility. In addition, the Sun JSSE reference implementation
adds support for key store files in PKCS12 format which can
be used to exchange keys with other software which supports
SSL such as web browsers.
The SSLSessionContext
class
provides basic facilities to explicitly manage the cache of sessions.
In the JSSE reference implementation the cache is unlimited in
size but is cached with soft references so sessions not
currently in use may be automatically flushed when memory runs low.
The protocol "HTTPS" is HTTP (used for Web browsing and other
purposes), used in conjunction with a secure socket.
The JSSE reference implementation provides a basic client side HTTPS protocol
handler. This supports firewall tunneling, so that HTTPS
clients can access servers through firewalls which support
that tunneling (usually, only to port 443). This means that
you can write lines of Java code such as
URL url = new URL ("https://www.sun.com/");
java-security@java.sun.com