Java Server

Secure Sockets Layer (SSL) Programming Notes (Beta)


This document provides a short summary of the key features of the Java API to the Secure Sockets Layer. It is in addition to the API reference documentation provided on the SSL and X.509 programming interfaces.

The functionality in the SSL API includes the following:

In addition, not strictly part of the SSL API, there is support for the HTTPS (HTTP over SSL) protocol.

These API notes are not intended to be tutorial; rather, they just summarize the functionality accessible through the API at a high level.

SSL is a transport (or often, session) level protocol which is used over a stream protocol such as TCP. It provides three services:

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.


Socket Functionality

This functionality is provided by the SSLSocket and SSLServerSocket 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 cipher suite negotiation and authentication, which are described in more detail later in these notes, and a few other 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:

    Socket            s = new SSLSocket ("hostname", port);

    ServerSocket      ss = new SSLServerSocket (port);

Note that "login" needs to be done before either end of a connection will authenticate itself. If "login" is not done, servers can only speak an "anonymous" flavors of SSL (which must be explicitly enabled; these are not enabled by default). After login, self-authentication is fully transparent.

Other Features

SSL's socket support has several features which are not otherwise mentioned in these notes:

Missing API Feature

At this time, the API does not support a particular feature of the SSL protocol: it does not provide a way to request a new handshake. This feature could be used to request that a client authenticate itself at some time other than the initial connection setup, or to switch cipher suites in use on a connection.


Cipher Suite Negotiation

This functionality is provided by the SSLSocket and SSLServerSocket classes.

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. If handshaking has not been performed before a data transfer is initiated, the data transfer will not begin until an initial handshake completes.

There are several methods which may be used to control the particular cipher suites which are used:

An application may call setEnabledCipherSuites to control which cipher suites may be chosen as part of the next handshake. So for example, if the application acquires a socket and then immediately sets the cipher suites enabled on that socket, all subsequent data transfers will use one of those cipher suites.

By default, the enabled cipher suites are those which are (a) supported (you can only use a 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.

As a point of information, a cipher suite basically lists four kinds of information:

  1. 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. We now support "anonymous Diffie-Hellman" key exchange, and have plans to support the an authenticated Diffie-Hellman "DHE_DSS" key exchange as a "pure Java" one.
  2. What encryption algorithm is used. The fastest option is the RC4 stream cipher; DES and variants (DES40, 3DES-EDE) are also supported, as is (in some suites) null encryption.
  3. Whether it is exportable according to the rules applicable in early 1996 (and also 1997): it uses short public keys for key exchange and for encryption, which are currently subject to breaking in an afternoon by a motivated and moderately well equipped (several hundred workstations) adversary.
  4. What digest algorithm is used for the Message Authentication Code, either MD5 or SHA1.


Peer Authentication

This functionality is provided as follows:

Missing Feature

In this release, no client authentication is possible; this restriction will be lifted in a later release.


Self Authentication

In SSL, servers normally authenticate themselves, and clients do not need to do so. However, there is a protocol feature which allows clients to authenticate themselves on request from the server.

Typical Usage

Authentication is always performed using "authentication context" which holds authentication information, including caches of active SSL sessions as well as X509 certificate chains and their associated private keys. It is intended to hold non-SSL information as well, when such information is used for authentication.

The API is designed to let authentication be transparent by default. This is achieved by providing a process-wide default authentication context. A "login" process -- involving a user presenting a passphrase -- is used to bootstrap an authentication context, as well as other parts of the user environment (such as home directory, default printer, etc.).

Other Features

There are applications where authentication must not be transparent. Specifically, processes which are trusted to authenticate on behalf of multiple principals ("delegation" scenarios) need to have control over what principal identity they use for each operation. This feature is supported by allowing multiple authentication contexts to be used, and allowing SSL sockets to be constructed with a non-default context.

Missing API Features

The self-authentication facilities are currently not exposed sufficiently so that SSL-enabled servers may be written, except when using the Java Server Toolkit. The consequence of this is that to write client/server programs with this current version of the API, both clients and servers must explicitly enable use of one or more of the "anonymous" (unauthenticated) cipher suites which are supported.


Encrypted Private Key Storage

In conjunction with the "login" facility noted above, some classes support secure storage of private keys. The most basic of these are KeyStore, which defines the format of the storage. The CertStore class provides a simple command-line user interface to that storage, and there is also an authstore graphical user interface to it. Both of these administrative interfaces support basic interoperation with certificate authorities, using PEM encoded certificates.

A given KeyStore will hold multiple identities/roles, each with a private key and certificate chain. For example, an SSL server may be able to authenticate using an RSA certificate chain, or (sometime later) a DSS one. SSL clients may have certificate chains issued by multiple certificate authorities, perhaps one for each service they are authorize to use.

A KeyStore is used to manage the in-memory storage of certificate chains and private keys. It may be saved via disk or network, and is in all external formats the private keys are securely encrypted.


Server Session Management

For SSL servers, the Session class provides basic facilities to explicitly manage the cache of sessions. Currently the cache is unlimited in size; it is not clear that this is an issue, since it uses the sun.misc.Cache class to facilitate memory management, and that class allows automatic collection of cache entries when memory is low.

Session caching is relevant to security discussions since clients will attempt use existing sessions in many cases. This can be a substantial performance improvement. Sessions hold authentication information for both servers and clients; and they define security parameters such as the kind of confidentiality protection being used between a given client and a server.

At this time, client side sessions are not reused, and hence are not cached. It is not clear whether clients would benefit from session visibility as much as servers; at this time, clients do not have access to session information.

(Some kinds of servers use SSL sessions to support fast access to information about clients. For example, they can look up data and store it in a cache keyed by session, so that common operations involving most currently active clients won't require expensive database accesses.)


HTTPS Support

The protocol "HTTPS" is HTTP (used for Web browsing and other purposes), used in conjunction with SSL. Accordingly, there are client and server side interfaces. The Java Web Server includes in particular the ability to serve data, such as HTML pages, using HTTPS.

At this time there is 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, through port 443). This means that you can write lines of Java code such as

    URL url = new URL ("https://www.verisign.com");

HTTPS clients, such as HotJava, should support callback interfaces for trust management (as described above). At this time there are no facilities to support connecting to websites whose certificates are invalid, or which do not provide certificates corresponding to their web sites.


Please send comments on this API to java-server-feedback@java.sun.com.