Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Add PSKKeyManager to enable the use of TLS-PSK."

Browse Source
This commit is contained in:
Alex Klyubin
2014-06-17 17:32:12 +00:00
committed by Android (Google) Code Review
parent f8f8bdaeba b0d1d91407
commit fd445e0336
3 changed files with 202 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Android.mk
View File

@@ -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 \

12
api/current.txt
View File

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

186
core/java/android/net/PSKKeyManager.java Normal file
View File

@@ -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.
*
* <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[] &#123;myPskKeyManager&#125;,
* 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[] &#123;"TLS_PSK_WITH_AES_128_CBC_SHA"&#125;);
* 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);
}