Merge "Add PSKKeyManager to enable the use of TLS-PSK." (fd445e03) · Commits · e / os / android_frameworks_base

Android.mk

+4 −0

Original line number	Diff line number	Diff line
		@@ -610,8 +610,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 \

api/current.txt

+12 −0

Original line number	Diff line number	Diff line
		@@ -16374,6 +16374,18 @@ package android.net {
		method public android.net.NetworkRequest.Builder removeTransportType(int);
		}

		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;
		}

core/java/android/net/PSKKeyManager.java

0 → 100644

+186 −0

Original line number	Diff line number	Diff line
		/*
		* 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.
		*
		* <h3>Overview of TLS-PSK</h3>
		*
		* <p>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.</p>
		*
		* <p>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}.
		* </p>
		*
		* <h3>Supporting multiple keys</h3>
		*
		* <p>A peer may have multiple keys to choose from. To help choose the right key, during the handshake
		* the server can provide a <em>PSK identity hint</em> to the client, and the client can provide a
		* <em>PSK identity</em> to the server. The contents of these two pieces of information are specific
		* to application-level protocols.</p>
		*
		* <p><em>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.</em></p>
		*
		* <p>The high-level flow leading to peers choosing a key during TLS/SSL handshake is as follows:
		* <ol>
		* <li>Server receives a handshake request from client.
		* <li>Server replies, optionally providing a PSK identity hint to client.</li>
		* <li>Client chooses the key.</li>
		* <li>Client provides a PSK identity of the chosen key to server.</li>
		* <li>Server chooses the key.</li>
		* </ol></p>
		*
		* <p>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.</p>
		*
		* <h3>Maximum sizes</h3>
		*
		* <p>The maximum supported sizes are as follows:
		* <ul>
		* <li>256 bytes for keys (see {@link #MAX_KEY_LENGTH_BYTES}),</li>
		* <li>128 bytes for PSK identity and PSK identity hint (in modified UTF-8 representation) (see
		* {@link #MAX_IDENTITY_LENGTH_BYTES} and {@link #MAX_IDENTITY_HINT_LENGTH_BYTES}).</li>
		* </ul></p>
		*
		* <h3>Example</h3>
		* 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.
		* <pre> {@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();
		* }</pre>
		*/
		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);
		}