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:

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 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:


Session Creation, Cipher Suite Negotiation

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:

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:

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:
  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.
  2. 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.
  3. 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.)
  4. 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

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:

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.


Server Session Management

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.


HTTPS Support

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