101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin/* 201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * Copyright 2014 The Android Open Source Project 301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * Licensed under the Apache License, Version 2.0 (the "License"); 501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * you may not use this file except in compliance with the License. 601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * You may obtain a copy of the License at 701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * http://www.apache.org/licenses/LICENSE-2.0 901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 1001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * Unless required by applicable law or agreed to in writing, software 1101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * distributed under the License is distributed on an "AS IS" BASIS, 1201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * See the License for the specific language governing permissions and 1401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * limitations under the License. 1501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 1601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 1701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubinpackage org.conscrypt; 1801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 1901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubinimport java.net.Socket; 2001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubinimport javax.crypto.SecretKey; 2101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubinimport javax.net.ssl.KeyManager; 2201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubinimport javax.net.ssl.SSLEngine; 2301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 2401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin/** 250d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Provider of key material for pre-shared key (PSK) key exchange used in TLS-PSK cipher suites. 2601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 270d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <h3>Overview of TLS-PSK</h3> 2801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 290d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <p>TLS-PSK is a set of TLS/SSL cipher suites which rely on a symmetric pre-shared key (PSK) to 300d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * secure the TLS/SSL connection and mutually authenticate its peers. These cipher suites may be 310d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * a more natural fit compared to conventional public key based cipher suites in some scenarios 320d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * where communication between peers is bootstrapped via a separate step (for example, a pairing 330d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * step) and requires both peers to authenticate each other. In such scenarios a symmetric key (PSK) 340d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * can be exchanged during the bootstrapping step, removing the need to generate and exchange public 350d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * key pairs and X.509 certificates.</p> 360d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 370d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <p>When a TLS-PSK cipher suite is used, both peers have to use the same key for the TLS/SSL 380d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * handshake to succeed. Thus, both peers are implicitly authenticated by a successful handshake. 390d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * This removes the need to use a {@code TrustManager} in conjunction with this {@code KeyManager}. 400d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * </p> 410d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 420d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <h3>Supporting multiple keys</h3> 430d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 440d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <p>A peer may have multiple keys to choose from. To help choose the right key, during the 450d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * handshake the server can provide a <em>PSK identity hint</em> to the client, and the client can 460d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * provide a <em>PSK identity</em> to the server. The contents of these two pieces of information 470d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * are specific to application-level protocols.</p> 4801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 4901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * <p><em>NOTE: Both the PSK identity hint and the PSK identity are transmitted in cleartext. 5001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * Moreover, these data are received and processed prior to peer having been authenticated. Thus, 5101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * they must not contain or leak key material or other sensitive information, and should be 520d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * treated (e.g., parsed) with caution, as untrusted data.</em></p> 5301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 540d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <p>The high-level flow leading to peers choosing a key during TLS/SSL handshake is as follows: 5501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * <ol> 560d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <li>Server receives a handshake request from client. 570d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <li>Server replies, optionally providing a PSK identity hint to client.</li> 580d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <li>Client chooses the key.</li> 590d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <li>Client provides a PSK identity of the chosen key to server.</li> 600d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <li>Server chooses the key.</li> 610d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * </ol></p> 620d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 630d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <p>In the flow above, either peer can signal that they do not have a suitable key, in which case 640d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * the the handshake will be aborted immediately. This may enable a network attacker who does not 650d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * know the key to learn which PSK identity hints or PSK identities are supported. If this is a 660d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * concern then a randomly generated key should be used in the scenario where no key is available. 670d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * This will lead to the handshake aborting later, due to key mismatch -- same as in the scenario 680d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * where a key is available -- making it appear to the attacker that all PSK identity hints and PSK 690d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * identities are supported.</p> 700d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 710d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <h3>Maximum sizes</h3> 7201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 7301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * <p>The maximum supported sizes are as follows: 7401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * <ul> 7501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * <li>256 bytes for keys (see {@link #MAX_KEY_LENGTH_BYTES}),</li> 760d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <li>128 bytes for PSK identity and PSK identity hint (in modified UTF-8 representation) (see 7701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * {@link #MAX_IDENTITY_LENGTH_BYTES} and {@link #MAX_IDENTITY_HINT_LENGTH_BYTES}).</li> 780d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * </ul></p> 790d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 800d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <h3>Example</h3> 810d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * The following example illustrates how to create an {@code SSLContext} which enables the use of 820d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * TLS-PSK in {@code SSLSocket}, {@code SSLServerSocket} and {@code SSLEngine} instances obtained 830d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * from it. 840d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * <pre> {@code 850d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * PSKKeyManager myPskKeyManager = ...; 860d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * 870d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * SSLContext sslContext = SSLContext.getInstance("TLS"); 880d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * sslContext.init( 890d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * new KeyManager[] {myPskKeyManager}, 900d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * new TrustManager[0], // No TrustManagers needed for TLS-PSK 910d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * null // Use the default source of entropy 920d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * ); 9301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 940d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * SSLSocket sslSocket = (SSLSocket) sslContext.getSocketFactory().createSocket(...); 950d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * }</pre> 9601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 9701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubinpublic interface PSKKeyManager extends KeyManager { 9801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 9901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 10001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * Maximum supported length (in bytes) for PSK identity hint (in modified UTF-8 representation). 10101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 10201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin int MAX_IDENTITY_HINT_LENGTH_BYTES = 128; 10301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 10401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** Maximum supported length (in bytes) for PSK identity (in modified UTF-8 representation). */ 10501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin int MAX_IDENTITY_LENGTH_BYTES = 128; 10601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 10701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** Maximum supported length (in bytes) for PSK key. */ 10801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin int MAX_KEY_LENGTH_BYTES = 256; 10901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 11001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 1110d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Gets the PSK identity hint to report to the client to help agree on the PSK for the provided 1120d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * socket. 11301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 11401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @return PSK identity hint to be provided to the client or {@code null} to provide no hint. 11501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 11601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin String chooseServerKeyIdentityHint(Socket socket); 11701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 11801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 1190d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Gets the PSK identity hint to report to the client to help agree on the PSK for the provided 1200d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * engine. 12101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 12201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @return PSK identity hint to be provided to the client or {@code null} to provide no hint. 12301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 12401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin String chooseServerKeyIdentityHint(SSLEngine engine); 12501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 12601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 1270d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Gets the PSK identity to report to the server to help agree on the PSK for the provided 1280d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * socket. 12901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 13001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @param identityHint identity hint provided by the server or {@code null} if none provided. 13101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 13201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @return PSK identity to provide to the server. {@code null} is permitted but will be 13301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * converted into an empty string. 13401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 13501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin String chooseClientKeyIdentity(String identityHint, Socket socket); 13601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 13701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 1380d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Gets the PSK identity to report to the server to help agree on the PSK for the provided 1390d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * engine. 14001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 14101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @param identityHint identity hint provided by the server or {@code null} if none provided. 14201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 14301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @return PSK identity to provide to the server. {@code null} is permitted but will be 14401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * converted into an empty string. 14501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 14601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin String chooseClientKeyIdentity(String identityHint, SSLEngine engine); 14701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 14801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 1490d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Gets the PSK to use for the provided socket. 15001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 15101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @param identityHint identity hint provided by the server to help select the key or 15201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * {@code null} if none provided. 15301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @param identity identity provided by the client to help select the key. 15401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 15501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @return key or {@code null} to signal to peer that no suitable key is available and to abort 15601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * the handshake. 15701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 15801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin SecretKey getKey(String identityHint, String identity, Socket socket); 15901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin 16001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin /** 1610d62d5fd40d35048f27879b00ff716a503893735Alex Klyubin * Gets the PSK to use for the provided engine. 16201cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 16301cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @param identityHint identity hint provided by the server to help select the key or 16401cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * {@code null} if none provided. 16501cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @param identity identity provided by the client to help select the key. 16601cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * 16701cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * @return key or {@code null} to signal to peer that no suitable key is available and to abort 16801cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin * the handshake. 16901cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin */ 17001cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin SecretKey getKey(String identityHint, String identity, SSLEngine engine); 17101cce891dd313a0fb9d4694283f2a13fb5c43afeAlex Klyubin}