1/*
2 * TLS 1.3 key schedule
3 *
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0 ( the "License" ); you may
8 * not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19
20#include "common.h"
21
22#if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL)
23
24#include "mbedtls/hkdf.h"
25#include "mbedtls/ssl_internal.h"
26#include "ssl_tls13_keys.h"
27#include "psa/crypto_sizes.h"
28
29#include <stdint.h>
30#include <string.h>
31
32#define MBEDTLS_SSL_TLS1_3_LABEL(name, string) \
33 .name = string,
34
35#define TLS1_3_EVOLVE_INPUT_SIZE (PSA_HASH_MAX_SIZE > PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE) ? \
36 PSA_HASH_MAX_SIZE : PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE
37
38struct mbedtls_ssl_tls1_3_labels_struct const mbedtls_ssl_tls1_3_labels =
39{
40 /* This seems to work in C, despite the string literal being one
41 * character too long due to the 0-termination. */
42 MBEDTLS_SSL_TLS1_3_LABEL_LIST
43};
44
45#undef MBEDTLS_SSL_TLS1_3_LABEL
46
47/*
48 * This function creates a HkdfLabel structure used in the TLS 1.3 key schedule.
49 *
50 * The HkdfLabel is specified in RFC 8446 as follows:
51 *
52 * struct HkdfLabel {
53 * uint16 length; // Length of expanded key material
54 * opaque label<7..255>; // Always prefixed by "tls13 "
55 * opaque context<0..255>; // Usually a communication transcript hash
56 * };
57 *
58 * Parameters:
59 * - desired_length: Length of expanded key material
60 * Even though the standard allows expansion to up to
61 * 2**16 Bytes, TLS 1.3 never uses expansion to more than
62 * 255 Bytes, so we require `desired_length` to be at most
63 * 255. This allows us to save a few Bytes of code by
64 * hardcoding the writing of the high bytes.
65 * - (label, llen): label + label length, without "tls13 " prefix
66 * The label length MUST be less than or equal to
67 * MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN
68 * It is the caller's responsibility to ensure this.
69 * All (label, label length) pairs used in TLS 1.3
70 * can be obtained via MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN().
71 * - (ctx, clen): context + context length
72 * The context length MUST be less than or equal to
73 * MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN
74 * It is the caller's responsibility to ensure this.
75 * - dst: Target buffer for HkdfLabel structure,
76 * This MUST be a writable buffer of size
77 * at least SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN Bytes.
78 * - dlen: Pointer at which to store the actual length of
79 * the HkdfLabel structure on success.
80 */
81
82static const char tls1_3_label_prefix[6] = "tls13 ";
83
84#define SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN(label_len, context_len) \
85 (2 /* expansion length */ \
86 + 1 /* label length */ \
87 + label_len \
88 + 1 /* context length */ \
89 + context_len)
90
91#define SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN \
92 SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN( \
93 sizeof(tls1_3_label_prefix) + \
94 MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN, \
95 MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN)
96
97static void ssl_tls1_3_hkdf_encode_label(
98 size_t desired_length,
99 const unsigned char *label, size_t llen,
100 const unsigned char *ctx, size_t clen,
101 unsigned char *dst, size_t *dlen)
102{
103 size_t total_label_len =
104 sizeof(tls1_3_label_prefix) + llen;
105 size_t total_hkdf_lbl_len =
106 SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN(total_label_len, clen);
107
108 unsigned char *p = dst;
109
110 /* Add the size of the expanded key material.
111 * We're hardcoding the high byte to 0 here assuming that we never use
112 * TLS 1.3 HKDF key expansion to more than 255 Bytes. */
113#if MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN > 255
114#error "The implementation of ssl_tls1_3_hkdf_encode_label() is not fit for the \
115 value of MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN"
116#endif
117
118 *p++ = 0;
119 *p++ = MBEDTLS_BYTE_0(desired_length);
120
121 /* Add label incl. prefix */
122 *p++ = MBEDTLS_BYTE_0(total_label_len);
123 memcpy(p, tls1_3_label_prefix, sizeof(tls1_3_label_prefix));
124 p += sizeof(tls1_3_label_prefix);
125 memcpy(p, label, llen);
126 p += llen;
127
128 /* Add context value */
129 *p++ = MBEDTLS_BYTE_0(clen);
130 if (clen != 0) {
131 memcpy(p, ctx, clen);
132 }
133
134 /* Return total length to the caller. */
135 *dlen = total_hkdf_lbl_len;
136}
137
138int mbedtls_ssl_tls1_3_hkdf_expand_label(
139 mbedtls_md_type_t hash_alg,
140 const unsigned char *secret, size_t slen,
141 const unsigned char *label, size_t llen,
142 const unsigned char *ctx, size_t clen,
143 unsigned char *buf, size_t blen)
144{
145 const mbedtls_md_info_t *md;
146 unsigned char hkdf_label[SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN];
147 size_t hkdf_label_len;
148
149 if (llen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN) {
150 /* Should never happen since this is an internal
151 * function, and we know statically which labels
152 * are allowed. */
153 return MBEDTLS_ERR_SSL_INTERNAL_ERROR;
154 }
155
156 if (clen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN) {
157 /* Should not happen, as above. */
158 return MBEDTLS_ERR_SSL_INTERNAL_ERROR;
159 }
160
161 if (blen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN) {
162 /* Should not happen, as above. */
163 return MBEDTLS_ERR_SSL_INTERNAL_ERROR;
164 }
165
166 md = mbedtls_md_info_from_type(hash_alg);
167 if (md == NULL) {
168 return MBEDTLS_ERR_SSL_BAD_INPUT_DATA;
169 }
170
171 ssl_tls1_3_hkdf_encode_label(blen,
172 label, llen,
173 ctx, clen,
174 hkdf_label,
175 &hkdf_label_len);
176
177 return mbedtls_hkdf_expand(md,
178 secret, slen,
179 hkdf_label, hkdf_label_len,
180 buf, blen);
181}
182
183/*
184 * The traffic keying material is generated from the following inputs:
185 *
186 * - One secret value per sender.
187 * - A purpose value indicating the specific value being generated
188 * - The desired lengths of key and IV.
189 *
190 * The expansion itself is based on HKDF:
191 *
192 * [sender]_write_key = HKDF-Expand-Label( Secret, "key", "", key_length )
193 * [sender]_write_iv = HKDF-Expand-Label( Secret, "iv" , "", iv_length )
194 *
195 * [sender] denotes the sending side and the Secret value is provided
196 * by the function caller. Note that we generate server and client side
197 * keys in a single function call.
198 */
199int mbedtls_ssl_tls1_3_make_traffic_keys(
200 mbedtls_md_type_t hash_alg,
201 const unsigned char *client_secret,
202 const unsigned char *server_secret,
203 size_t slen, size_t key_len, size_t iv_len,
204 mbedtls_ssl_key_set *keys)
205{
206 int ret = 0;
207
208 ret = mbedtls_ssl_tls1_3_hkdf_expand_label(hash_alg,
209 client_secret, slen,
210 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(key),
211 NULL, 0,
212 keys->client_write_key, key_len);
213 if (ret != 0) {
214 return ret;
215 }
216
217 ret = mbedtls_ssl_tls1_3_hkdf_expand_label(hash_alg,
218 server_secret, slen,
219 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(key),
220 NULL, 0,
221 keys->server_write_key, key_len);
222 if (ret != 0) {
223 return ret;
224 }
225
226 ret = mbedtls_ssl_tls1_3_hkdf_expand_label(hash_alg,
227 client_secret, slen,
228 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(iv),
229 NULL, 0,
230 keys->client_write_iv, iv_len);
231 if (ret != 0) {
232 return ret;
233 }
234
235 ret = mbedtls_ssl_tls1_3_hkdf_expand_label(hash_alg,
236 server_secret, slen,
237 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(iv),
238 NULL, 0,
239 keys->server_write_iv, iv_len);
240 if (ret != 0) {
241 return ret;
242 }
243
244 keys->key_len = key_len;
245 keys->iv_len = iv_len;
246
247 return 0;
248}
249
250int mbedtls_ssl_tls1_3_derive_secret(
251 mbedtls_md_type_t hash_alg,
252 const unsigned char *secret, size_t slen,
253 const unsigned char *label, size_t llen,
254 const unsigned char *ctx, size_t clen,
255 int ctx_hashed,
256 unsigned char *dstbuf, size_t buflen)
257{
258 int ret;
259 unsigned char hashed_context[MBEDTLS_MD_MAX_SIZE];
260
261 const mbedtls_md_info_t *md;
262 md = mbedtls_md_info_from_type(hash_alg);
263 if (md == NULL) {
264 return MBEDTLS_ERR_SSL_BAD_INPUT_DATA;
265 }
266
267 if (ctx_hashed == MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED) {
268 ret = mbedtls_md(md, ctx, clen, hashed_context);
269 if (ret != 0) {
270 return ret;
271 }
272 clen = mbedtls_md_get_size(md);
273 } else {
274 if (clen > sizeof(hashed_context)) {
275 /* This should never happen since this function is internal
276 * and the code sets `ctx_hashed` correctly.
277 * Let's double-check nonetheless to not run at the risk
278 * of getting a stack overflow. */
279 return MBEDTLS_ERR_SSL_INTERNAL_ERROR;
280 }
281
282 memcpy(hashed_context, ctx, clen);
283 }
284
285 return mbedtls_ssl_tls1_3_hkdf_expand_label(hash_alg,
286 secret, slen,
287 label, llen,
288 hashed_context, clen,
289 dstbuf, buflen);
290}
291
292int mbedtls_ssl_tls1_3_evolve_secret(
293 mbedtls_md_type_t hash_alg,
294 const unsigned char *secret_old,
295 const unsigned char *input, size_t input_len,
296 unsigned char *secret_new)
297{
298 int ret = MBEDTLS_ERR_SSL_INTERNAL_ERROR;
299 size_t hlen, ilen;
300 unsigned char tmp_secret[PSA_MAC_MAX_SIZE] = { 0 };
301 unsigned char tmp_input[TLS1_3_EVOLVE_INPUT_SIZE] = { 0 };
302
303 const mbedtls_md_info_t *md;
304 md = mbedtls_md_info_from_type(hash_alg);
305 if (md == NULL) {
306 return MBEDTLS_ERR_SSL_BAD_INPUT_DATA;
307 }
308
309 hlen = mbedtls_md_get_size(md);
310
311 /* For non-initial runs, call Derive-Secret( ., "derived", "")
312 * on the old secret. */
313 if (secret_old != NULL) {
314 ret = mbedtls_ssl_tls1_3_derive_secret(
315 hash_alg,
316 secret_old, hlen,
317 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(derived),
318 NULL, 0, /* context */
319 MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED,
320 tmp_secret, hlen);
321 if (ret != 0) {
322 goto cleanup;
323 }
324 }
325
326 if (input != NULL) {
327 memcpy(tmp_input, input, input_len);
328 ilen = input_len;
329 } else {
330 ilen = hlen;
331 }
332
333 /* HKDF-Extract takes a salt and input key material.
334 * The salt is the old secret, and the input key material
335 * is the input secret (PSK / ECDHE). */
336 ret = mbedtls_hkdf_extract(md,
337 tmp_secret, hlen,
338 tmp_input, ilen,
339 secret_new);
340 if (ret != 0) {
341 goto cleanup;
342 }
343
344 ret = 0;
345
346cleanup:
347
348 mbedtls_platform_zeroize(tmp_secret, sizeof(tmp_secret));
349 mbedtls_platform_zeroize(tmp_input, sizeof(tmp_input));
350 return ret;
351}
352
353#endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */
354