From b0d1d914073256db05aa33feb6b2d6018802635e Mon Sep 17 00:00:00 2001 From: Alex Klyubin Date: Tue, 10 Jun 2014 10:28:08 -0700 Subject: [PATCH] Add PSKKeyManager to enable the use of TLS-PSK. TLS-PSK is supported by the underlying TLS/SSL stack (based on Conscrypt). This CL simply exposes this support in the Android framework. 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. Bug: 15073623 Change-Id: Idf2a773db3021de3d2ad144c5cc63d2415eb8e91 --- Android.mk | 4 + api/current.txt | 12 ++ core/java/android/net/PSKKeyManager.java | 186 +++++++++++++++++++++++ 3 files changed, 202 insertions(+) create mode 100644 core/java/android/net/PSKKeyManager.java diff --git a/Android.mk b/Android.mk index 4875cc560e18c..ada9173d570a2 100644 --- a/Android.mk +++ b/Android.mk @@ -605,8 +605,12 @@ framework_docs_LOCAL_MODULE_CLASS := JAVA_LIBRARIES framework_docs_LOCAL_DROIDDOC_HTML_DIR := docs/html # The since flag (-since N.xml API_LEVEL) is used to add API Level information # to the reference documentation. Must be in order of oldest to newest. +# +# Conscrypt (com.android.org.conscrypt) is an implementation detail and should +# not be referenced in the documentation. framework_docs_LOCAL_DROIDDOC_OPTIONS := \ -knowntags ./frameworks/base/docs/knowntags.txt \ + -hidePackage com.android.org.conscrypt \ -since $(SRC_API_DIR)/1.xml 1 \ -since $(SRC_API_DIR)/2.xml 2 \ -since $(SRC_API_DIR)/3.xml 3 \ diff --git a/api/current.txt b/api/current.txt index a091f1a459122..3c4c2353f7ea1 100644 --- a/api/current.txt +++ b/api/current.txt @@ -16518,6 +16518,18 @@ package android.net { field public final android.net.NetworkCapabilities networkCapabilities; } + public abstract interface PSKKeyManager { + method public abstract java.lang.String chooseClientKeyIdentity(java.lang.String, java.net.Socket); + method public abstract java.lang.String chooseClientKeyIdentity(java.lang.String, javax.net.ssl.SSLEngine); + method public abstract java.lang.String chooseServerKeyIdentityHint(java.net.Socket); + method public abstract java.lang.String chooseServerKeyIdentityHint(javax.net.ssl.SSLEngine); + method public abstract javax.crypto.SecretKey getKey(java.lang.String, java.lang.String, java.net.Socket); + method public abstract javax.crypto.SecretKey getKey(java.lang.String, java.lang.String, javax.net.ssl.SSLEngine); + field public static final int MAX_IDENTITY_HINT_LENGTH_BYTES = 128; // 0x80 + field public static final int MAX_IDENTITY_LENGTH_BYTES = 128; // 0x80 + field public static final int MAX_KEY_LENGTH_BYTES = 256; // 0x100 + } + public class ParseException extends java.lang.RuntimeException { field public java.lang.String response; } diff --git a/core/java/android/net/PSKKeyManager.java b/core/java/android/net/PSKKeyManager.java new file mode 100644 index 0000000000000..92dd1416d923c --- /dev/null +++ b/core/java/android/net/PSKKeyManager.java @@ -0,0 +1,186 @@ +/* + * Copyright 2014 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package android.net; + +import java.net.Socket; +import javax.crypto.SecretKey; +import javax.net.ssl.SSLEngine; + +/** + * 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 {@code TrustManager} in conjunction with this {@code 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.

+ * + *

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

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

+ * + *

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

+ * + *

Example

+ * The following example illustrates how to create an {@code SSLContext} which enables the use of + * TLS-PSK in {@code SSLSocket}, {@code SSLServerSocket} and {@code SSLEngine} instances obtained + * from it. + * 
 {@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); +}