1/*
2 * Copyright 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.net;
18
19import com.android.org.conscrypt.PSKKeyManager;
20import java.net.Socket;
21import javax.crypto.SecretKey;
22import javax.net.ssl.SSLEngine;
23
24/**
25 * Provider of key material for pre-shared key (PSK) key exchange used in TLS-PSK cipher suites.
26 *
27 * <h3>Overview of TLS-PSK</h3>
28 *
29 * <p>TLS-PSK is a set of TLS/SSL cipher suites which rely on a symmetric pre-shared key (PSK) to
30 * secure the TLS/SSL connection and mutually authenticate its peers. These cipher suites may be
31 * a more natural fit compared to conventional public key based cipher suites in some scenarios
32 * where communication between peers is bootstrapped via a separate step (for example, a pairing
33 * step) and requires both peers to authenticate each other. In such scenarios a symmetric key (PSK)
34 * can be exchanged during the bootstrapping step, removing the need to generate and exchange public
35 * key pairs and X.509 certificates.</p>
36 *
37 * <p>When a TLS-PSK cipher suite is used, both peers have to use the same key for the TLS/SSL
38 * handshake to succeed. Thus, both peers are implicitly authenticated by a successful handshake.
39 * This removes the need to use a {@code TrustManager} in conjunction with this {@code KeyManager}.
40 * </p>
41 *
42 * <h3>Supporting multiple keys</h3>
43 *
44 * <p>A peer may have multiple keys to choose from. To help choose the right key, during the
45 * handshake the server can provide a <em>PSK identity hint</em> to the client, and the client can
46 * provide a <em>PSK identity</em> to the server. The contents of these two pieces of information
47 * are specific to application-level protocols.</p>
48 *
49 * <p><em>NOTE: Both the PSK identity hint and the PSK identity are transmitted in cleartext.
50 * Moreover, these data are received and processed prior to peer having been authenticated. Thus,
51 * they must not contain or leak key material or other sensitive information, and should be
52 * treated (e.g., parsed) with caution, as untrusted data.</em></p>
53 *
54 * <p>The high-level flow leading to peers choosing a key during TLS/SSL handshake is as follows:
55 * <ol>
56 * <li>Server receives a handshake request from client.
57 * <li>Server replies, optionally providing a PSK identity hint to client.</li>
58 * <li>Client chooses the key.</li>
59 * <li>Client provides a PSK identity of the chosen key to server.</li>
60 * <li>Server chooses the key.</li>
61 * </ol></p>
62 *
63 * <p>In the flow above, either peer can signal that they do not have a suitable key, in which case
64 * the the handshake will be aborted immediately. This may enable a network attacker who does not
65 * know the key to learn which PSK identity hints or PSK identities are supported. If this is a
66 * concern then a randomly generated key should be used in the scenario where no key is available.
67 * This will lead to the handshake aborting later, due to key mismatch -- same as in the scenario
68 * where a key is available -- making it appear to the attacker that all PSK identity hints and PSK
69 * identities are supported.</p>
70 *
71 * <h3>Maximum sizes</h3>
72 *
73 * <p>The maximum supported sizes are as follows:
74 * <ul>
75 * <li>256 bytes for keys (see {@link #MAX_KEY_LENGTH_BYTES}),</li>
76 * <li>128 bytes for PSK identity and PSK identity hint (in modified UTF-8 representation) (see
77 * {@link #MAX_IDENTITY_LENGTH_BYTES} and {@link #MAX_IDENTITY_HINT_LENGTH_BYTES}).</li>
78 * </ul></p>
79 *
80 * <h3>Subclassing</h3>
81 * Subclasses should normally provide their own implementation of {@code getKey} because the default
82 * implementation returns no key, which aborts the handshake.
83 *
84 * <h3>Known issues</h3>
85 * The implementation of {@code ECDHE_PSK} cipher suites in API Level 21 contains a bug which breaks
86 * compatibility with other implementations. {@code ECDHE_PSK} cipher suites are enabled by default
87 * on platforms with API Level 21 when an {@code SSLContext} is initialized with a
88 * {@code PskKeyManager}. A workaround is to disable {@code ECDHE_PSK} cipher suites on platforms
89 * with API Level 21.
90 *
91 * <h3>Example</h3>
92 * The following example illustrates how to create an {@code SSLContext} which enables the use of
93 * TLS-PSK in {@code SSLSocket}, {@code SSLServerSocket} and {@code SSLEngine} instances obtained
94 * from it.
95 * <pre> {@code
96 * PskKeyManager pskKeyManager = ...;
97 *
98 * SSLContext sslContext = SSLContext.getInstance("TLS");
99 * sslContext.init(
100 *         new KeyManager[] &#123;pskKeyManager&#125;,
101 *         new TrustManager[0], // No TrustManagers needed for TLS-PSK
102 *         null // Use the default source of entropy
103 *         );
104 *
105 * SSLSocket sslSocket = (SSLSocket) sslContext.getSocketFactory().createSocket(...);
106 * }</pre>
107 */
108public abstract class PskKeyManager implements PSKKeyManager {
109    // IMPLEMENTATION DETAILS: This class exists only because the default implemenetation of the
110    // TLS/SSL JSSE provider (currently Conscrypt) cannot depend on Android framework classes.
111    // As a result, this framework class simply extends the PSKKeyManager interface from Conscrypt
112    // without adding any new methods or fields. Moreover, for technical reasons (Conscrypt classes
113    // are "hidden") this class replaces the Javadoc of Conscrypt's PSKKeyManager.
114
115    /**
116     * Maximum supported length (in bytes) for PSK identity hint (in modified UTF-8 representation).
117     */
118    public static final int MAX_IDENTITY_HINT_LENGTH_BYTES =
119            PSKKeyManager.MAX_IDENTITY_HINT_LENGTH_BYTES;
120
121    /** Maximum supported length (in bytes) for PSK identity (in modified UTF-8 representation). */
122    public static final int MAX_IDENTITY_LENGTH_BYTES = PSKKeyManager.MAX_IDENTITY_LENGTH_BYTES;
123
124    /** Maximum supported length (in bytes) for PSK. */
125    public static final int MAX_KEY_LENGTH_BYTES = PSKKeyManager.MAX_KEY_LENGTH_BYTES;
126
127    /**
128     * Gets the PSK identity hint to report to the client to help agree on the PSK for the provided
129     * socket.
130     *
131     * <p>
132     * The default implementation returns {@code null}.
133     *
134     * @return PSK identity hint to be provided to the client or {@code null} to provide no hint.
135     */
136    @Override
137    public String chooseServerKeyIdentityHint(Socket socket) {
138        return null;
139    }
140
141    /**
142     * Gets the PSK identity hint to report to the client to help agree on the PSK for the provided
143     * engine.
144     *
145     * <p>
146     * The default implementation returns {@code null}.
147     *
148     * @return PSK identity hint to be provided to the client or {@code null} to provide no hint.
149     */
150    @Override
151    public String chooseServerKeyIdentityHint(SSLEngine engine) {
152        return null;
153    }
154
155    /**
156     * Gets the PSK identity to report to the server to help agree on the PSK for the provided
157     * socket.
158     *
159     * <p>
160     * The default implementation returns an empty string.
161     *
162     * @param identityHint identity hint provided by the server or {@code null} if none provided.
163     *
164     * @return PSK identity to provide to the server. {@code null} is permitted but will be
165     *         converted into an empty string.
166     */
167    @Override
168    public String chooseClientKeyIdentity(String identityHint, Socket socket) {
169        return "";
170    }
171
172    /**
173     * Gets the PSK identity to report to the server to help agree on the PSK for the provided
174     * engine.
175     *
176     * <p>
177     * The default implementation returns an empty string.
178     *
179     * @param identityHint identity hint provided by the server or {@code null} if none provided.
180     *
181     * @return PSK identity to provide to the server. {@code null} is permitted but will be
182     *         converted into an empty string.
183     */
184    @Override
185    public String chooseClientKeyIdentity(String identityHint, SSLEngine engine) {
186        return "";
187    }
188
189    /**
190     * Gets the PSK to use for the provided socket.
191     *
192     * <p>
193     * The default implementation returns {@code null}.
194     *
195     * @param identityHint identity hint provided by the server to help select the key or
196     *        {@code null} if none provided.
197     * @param identity identity provided by the client to help select the key.
198     *
199     * @return key or {@code null} to signal to peer that no suitable key is available and to abort
200     *         the handshake.
201     */
202    @Override
203    public SecretKey getKey(String identityHint, String identity, Socket socket) {
204        return null;
205    }
206
207    /**
208     * Gets the PSK to use for the provided engine.
209     *
210     * <p>
211     * The default implementation returns {@code null}.
212     *
213     * @param identityHint identity hint provided by the server to help select the key or
214     *        {@code null} if none provided.
215     * @param identity identity provided by the client to help select the key.
216     *
217     * @return key or {@code null} to signal to peer that no suitable key is available and to abort
218     *         the handshake.
219     */
220    @Override
221    public SecretKey getKey(String identityHint, String identity, SSLEngine engine) {
222        return null;
223    }
224}
225