Provider of key material for pre-shared key (PSK) key exchange used in TLS-PSK cipher suites.

Overview of TLS-PSK

TLS-PSK is a set of TLS/SSL cipher suites which rely on a symmetric pre-shared key (PSK) to secure the TLS/SSL connection and mutually authenticate its peers. These cipher suites may be a more natural fit compared to conventional public key based cipher suites in some scenarios where communication between peers is bootstrapped via a separate step (for example, a pairing step) and requires both peers to authenticate each other. In such scenarios a symmetric key (PSK) can be exchanged during the bootstrapping step, removing the need to generate and exchange public key pairs and X.509 certificates.

When a TLS-PSK cipher suite is used, both peers have to use the same key for the TLS/SSL handshake to succeed. Thus, both peers are implicitly authenticated by a successful handshake. This removes the need to use a TrustManager in conjunction with this KeyManager.

Supporting multiple keys

A peer may have multiple keys to choose from. To help choose the right key, during the handshake the server can provide a PSK identity hint to the client, and the client can provide a PSK identity to the server. The contents of these two pieces of information are specific to application-level protocols.

The high-level flow leading to peers choosing a key during TLS/SSL handshake is as follows:

1. Server receives a handshake request from client.
2. Server replies, optionally providing a PSK identity hint to client.
3. Client chooses the key.
4. Client provides a PSK identity of the chosen key to server.
5. Server chooses the key.

In the flow above, either peer can signal that they do not have a suitable key, in which case the the handshake will be aborted immediately. This may enable a network attacker who does not know the key to learn which PSK identity hints or PSK identities are supported. If this is a concern then a randomly generated key should be used in the scenario where no key is available. This will lead to the handshake aborting later, due to key mismatch -- same as in the scenario where a key is available -- making it appear to the attacker that all PSK identity hints and PSK identities are supported.

Maximum sizes

The maximum supported sizes are as follows:

• 256 bytes for keys (see MAX_KEY_LENGTH_BYTES),
• 128 bytes for PSK identity and PSK identity hint (in modified UTF-8 representation) (see MAX_IDENTITY_LENGTH_BYTES and MAX_IDENTITY_HINT_LENGTH_BYTES).

Example

The following example illustrates how to create an SSLContext which enables the use of TLS-PSK in SSLSocket, SSLServerSocket and SSLEngine instances obtained from it.

 PSKKeyManager myPskKeyManager = ...;

SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(
        new KeyManager[] {myPskKeyManager},
        new TrustManager[0], // No TrustManagers needed for TLS-PSK
        null // Use the default source of entropy
        );

SSLSocket sslSocket = (SSLSocket) sslContext.getSocketFactory().createSocket(...);