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.
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.
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.
SSL's socket support has several features which are not otherwise mentioned in these notes:
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.
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:
SSLSocket.getSupportedCipherSuites
SSLSocket.getDefaultCipherSuites
SSLSocket.setEnabledCipherSuites
SSLServerSocket.setEnabledCipherSuites
SSLSocket.getEnabledCipherSuites
SSLServerSocket.getEnabledCipherSuites
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:
This functionality is provided as follows:
TrustDecider
API. Such an object
should be placed into the AuthenticationContext.
In this release, no client authentication is possible; this restriction will be lifted in a later release.
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.
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.).
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.
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.
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.
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.)
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.