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 {@code TrustManager} in conjunction with this {@code KeyManager}. + *
+ * + *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: + *
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.
+ * + *The maximum supported sizes are as follows: + *
{@code
+ * PSKKeyManager myPskKeyManager = ...;
+ *
+ * SSLContext sslContext = SSLContext.getInstance("TLS");
+ * sslContext.init(
+ * new KeyManager[] {myPskKeyManager},
+ * new TrustManager[0], // No TrustManagers needed in TLS-PSK
+ * null // Use the default source of entropy
+ * );
+ *
+ * SSLSocket sslSocket = (SSLSocket) sslContext.getSocketFactory().createSocket(...);
+ * // Enable a TLS-PSK cipher suite (no TLS-PSK cipher suites are enabled by default)
+ * sslSocket.setEnabledCipherSuites(new String[] {"TLS_PSK_WITH_AES_128_CBC_SHA"});
+ * sslSocket.startHandshake();
+ * }
+ */
+public interface PSKKeyManager extends com.android.org.conscrypt.PSKKeyManager {
+ // IMPLEMENTATION DETAILS: This class exists only because the default implemenetation of the
+ // TLS/SSL JSSE provider (currently Conscrypt) cannot depend on Android framework classes.
+ // As a result, this framework class simply extends the PSKKeyManager interface from Conscrypt
+ // without adding any new methods or fields. Moreover, for technical reasons (Conscrypt classes
+ // are "hidden") this class replaces the Javadoc of Conscrypt's PSKKeyManager.
+
+ /**
+ * Maximum supported length (in bytes) for PSK identity hint (in modified UTF-8 representation).
+ */
+ int MAX_IDENTITY_HINT_LENGTH_BYTES =
+ com.android.org.conscrypt.PSKKeyManager.MAX_IDENTITY_HINT_LENGTH_BYTES;
+
+ /** Maximum supported length (in bytes) for PSK identity (in modified UTF-8 representation). */
+ int MAX_IDENTITY_LENGTH_BYTES =
+ com.android.org.conscrypt.PSKKeyManager.MAX_IDENTITY_LENGTH_BYTES;
+
+ /** Maximum supported length (in bytes) for PSK. */
+ int MAX_KEY_LENGTH_BYTES = com.android.org.conscrypt.PSKKeyManager.MAX_KEY_LENGTH_BYTES;
+
+ /**
+ * Gets the PSK identity hint to report to the client to help agree on the PSK for the provided
+ * socket.
+ *
+ * @return PSK identity hint to be provided to the client or {@code null} to provide no hint.
+ */
+ @Override
+ String chooseServerKeyIdentityHint(Socket socket);
+
+ /**
+ * Gets the PSK identity hint to report to the client to help agree on the PSK for the provided
+ * engine.
+ *
+ * @return PSK identity hint to be provided to the client or {@code null} to provide no hint.
+ */
+ @Override
+ String chooseServerKeyIdentityHint(SSLEngine engine);
+
+ /**
+ * Gets the PSK identity to report to the server to help agree on the PSK for the provided
+ * socket.
+ *
+ * @param identityHint identity hint provided by the server or {@code null} if none provided.
+ *
+ * @return PSK identity to provide to the server. {@code null} is permitted but will be
+ * converted into an empty string.
+ */
+ @Override
+ String chooseClientKeyIdentity(String identityHint, Socket socket);
+
+ /**
+ * Gets the PSK identity to report to the server to help agree on the PSK for the provided
+ * engine.
+ *
+ * @param identityHint identity hint provided by the server or {@code null} if none provided.
+ *
+ * @return PSK identity to provide to the server. {@code null} is permitted but will be
+ * converted into an empty string.
+ */
+ @Override
+ String chooseClientKeyIdentity(String identityHint, SSLEngine engine);
+
+ /**
+ * Gets the PSK to use for the provided socket.
+ *
+ * @param identityHint identity hint provided by the server to help select the key or
+ * {@code null} if none provided.
+ * @param identity identity provided by the client to help select the key.
+ *
+ * @return key or {@code null} to signal to peer that no suitable key is available and to abort
+ * the handshake.
+ */
+ @Override
+ SecretKey getKey(String identityHint, String identity, Socket socket);
+
+ /**
+ * Gets the PSK to use for the provided engine.
+ *
+ * @param identityHint identity hint provided by the server to help select the key or
+ * {@code null} if none provided.
+ * @param identity identity provided by the client to help select the key.
+ *
+ * @return key or {@code null} to signal to peer that no suitable key is available and to abort
+ * the handshake.
+ */
+ @Override
+ SecretKey getKey(String identityHint, String identity, SSLEngine engine);
+}