Interface PSKKeyManager
-
- All Superinterfaces:
javax.net.ssl.KeyManager
- All Known Implementing Classes:
DuckTypedPSKKeyManager
@Deprecated @Internal public interface PSKKeyManager extends javax.net.ssl.KeyManager
Deprecated.This abstraction is deprecated because it does not work with TLS 1.3.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 thisKeyManager
.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.
NOTE: Both the PSK identity hint and the PSK identity are transmitted in cleartext. Moreover, these data are received and processed prior to peer having been authenticated. Thus, they must not contain or leak key material or other sensitive information, and should be treated (e.g., parsed) with caution, as untrusted data.
The high-level flow leading to peers choosing a key during TLS/SSL handshake is as follows:
- Server receives a handshake request from client.
- Server replies, optionally providing a PSK identity hint to client.
- Client chooses the key.
- Client provides a PSK identity of the chosen key to server.
- 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
andMAX_IDENTITY_HINT_LENGTH_BYTES
).
Example
The following example illustrates how to create anSSLContext
which enables the use of TLS-PSK inSSLSocket
,SSLServerSocket
andSSLEngine
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(...);
-
-
Field Summary
Fields Modifier and Type Field Description static int
MAX_IDENTITY_HINT_LENGTH_BYTES
Deprecated.Maximum supported length (in bytes) for PSK identity hint (in modified UTF-8 representation).static int
MAX_IDENTITY_LENGTH_BYTES
Deprecated.Maximum supported length (in bytes) for PSK identity (in modified UTF-8 representation).static int
MAX_KEY_LENGTH_BYTES
Deprecated.Maximum supported length (in bytes) for PSK key.
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description java.lang.String
chooseClientKeyIdentity(java.lang.String identityHint, java.net.Socket socket)
Deprecated.Gets the PSK identity to report to the server to help agree on the PSK for the provided socket.java.lang.String
chooseClientKeyIdentity(java.lang.String identityHint, javax.net.ssl.SSLEngine engine)
Deprecated.Gets the PSK identity to report to the server to help agree on the PSK for the provided engine.java.lang.String
chooseServerKeyIdentityHint(java.net.Socket socket)
Deprecated.Gets the PSK identity hint to report to the client to help agree on the PSK for the provided socket.java.lang.String
chooseServerKeyIdentityHint(javax.net.ssl.SSLEngine engine)
Deprecated.Gets the PSK identity hint to report to the client to help agree on the PSK for the provided engine.javax.crypto.SecretKey
getKey(java.lang.String identityHint, java.lang.String identity, java.net.Socket socket)
Deprecated.Gets the PSK to use for the provided socket.javax.crypto.SecretKey
getKey(java.lang.String identityHint, java.lang.String identity, javax.net.ssl.SSLEngine engine)
Deprecated.Gets the PSK to use for the provided engine.
-
-
-
Field Detail
-
MAX_IDENTITY_HINT_LENGTH_BYTES
static final int MAX_IDENTITY_HINT_LENGTH_BYTES
Deprecated.Maximum supported length (in bytes) for PSK identity hint (in modified UTF-8 representation).- See Also:
- Constant Field Values
-
MAX_IDENTITY_LENGTH_BYTES
static final int MAX_IDENTITY_LENGTH_BYTES
Deprecated.Maximum supported length (in bytes) for PSK identity (in modified UTF-8 representation).- See Also:
- Constant Field Values
-
MAX_KEY_LENGTH_BYTES
static final int MAX_KEY_LENGTH_BYTES
Deprecated.Maximum supported length (in bytes) for PSK key.- See Also:
- Constant Field Values
-
-
Method Detail
-
chooseServerKeyIdentityHint
java.lang.String chooseServerKeyIdentityHint(java.net.Socket socket)
Deprecated.Gets the PSK identity hint to report to the client to help agree on the PSK for the provided socket.- Returns:
- PSK identity hint to be provided to the client or
null
to provide no hint.
-
chooseServerKeyIdentityHint
java.lang.String chooseServerKeyIdentityHint(javax.net.ssl.SSLEngine engine)
Deprecated.Gets the PSK identity hint to report to the client to help agree on the PSK for the provided engine.- Returns:
- PSK identity hint to be provided to the client or
null
to provide no hint.
-
chooseClientKeyIdentity
java.lang.String chooseClientKeyIdentity(java.lang.String identityHint, java.net.Socket socket)
Deprecated.Gets the PSK identity to report to the server to help agree on the PSK for the provided socket.- Parameters:
identityHint
- identity hint provided by the server ornull
if none provided.- Returns:
- PSK identity to provide to the server.
null
is permitted but will be converted into an empty string.
-
chooseClientKeyIdentity
java.lang.String chooseClientKeyIdentity(java.lang.String identityHint, javax.net.ssl.SSLEngine engine)
Deprecated.Gets the PSK identity to report to the server to help agree on the PSK for the provided engine.- Parameters:
identityHint
- identity hint provided by the server ornull
if none provided.- Returns:
- PSK identity to provide to the server.
null
is permitted but will be converted into an empty string.
-
getKey
javax.crypto.SecretKey getKey(java.lang.String identityHint, java.lang.String identity, java.net.Socket socket)
Deprecated.Gets the PSK to use for the provided socket.- Parameters:
identityHint
- identity hint provided by the server to help select the key ornull
if none provided.identity
- identity provided by the client to help select the key.- Returns:
- key or
null
to signal to peer that no suitable key is available and to abort the handshake.
-
getKey
javax.crypto.SecretKey getKey(java.lang.String identityHint, java.lang.String identity, javax.net.ssl.SSLEngine engine)
Deprecated.Gets the PSK to use for the provided engine.- Parameters:
identityHint
- identity hint provided by the server to help select the key ornull
if none provided.identity
- identity provided by the client to help select the key.- Returns:
- key or
null
to signal to peer that no suitable key is available and to abort the handshake.
-
-