4
* Copyright The Mbed TLS Contributors
5
* SPDX-License-Identifier: Apache-2.0
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
11
* http://www.apache.org/licenses/LICENSE-2.0
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.
22
#if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL)
24
#include "mbedtls/hkdf.h"
25
#include "mbedtls/ssl_internal.h"
26
#include "ssl_tls13_keys.h"
31
#define MBEDTLS_SSL_TLS1_3_LABEL( name, string ) \
34
struct mbedtls_ssl_tls1_3_labels_struct const mbedtls_ssl_tls1_3_labels =
36
/* This seems to work in C, despite the string literal being one
37
* character too long due to the 0-termination. */
38
MBEDTLS_SSL_TLS1_3_LABEL_LIST
41
#undef MBEDTLS_SSL_TLS1_3_LABEL
44
* This function creates a HkdfLabel structure used in the TLS 1.3 key schedule.
46
* The HkdfLabel is specified in RFC 8446 as follows:
49
* uint16 length; // Length of expanded key material
50
* opaque label<7..255>; // Always prefixed by "tls13 "
51
* opaque context<0..255>; // Usually a communication transcript hash
55
* - desired_length: Length of expanded key material
56
* Even though the standard allows expansion to up to
57
* 2**16 Bytes, TLS 1.3 never uses expansion to more than
58
* 255 Bytes, so we require `desired_length` to be at most
59
* 255. This allows us to save a few Bytes of code by
60
* hardcoding the writing of the high bytes.
61
* - (label, llen): label + label length, without "tls13 " prefix
62
* The label length MUST be less than or equal to
63
* MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN
64
* It is the caller's responsibility to ensure this.
65
* All (label, label length) pairs used in TLS 1.3
66
* can be obtained via MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN().
67
* - (ctx, clen): context + context length
68
* The context length MUST be less than or equal to
69
* MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN
70
* It is the caller's responsibility to ensure this.
71
* - dst: Target buffer for HkdfLabel structure,
72
* This MUST be a writable buffer of size
73
* at least SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN Bytes.
74
* - dlen: Pointer at which to store the actual length of
75
* the HkdfLabel structure on success.
78
static const char tls1_3_label_prefix[6] = "tls13 ";
80
#define SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN( label_len, context_len ) \
81
( 2 /* expansion length */ \
82
+ 1 /* label length */ \
84
+ 1 /* context length */ \
87
#define SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN \
88
SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN( \
89
sizeof(tls1_3_label_prefix) + \
90
MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN, \
91
MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN )
93
static void ssl_tls1_3_hkdf_encode_label(
94
size_t desired_length,
95
const unsigned char *label, size_t llen,
96
const unsigned char *ctx, size_t clen,
97
unsigned char *dst, size_t *dlen )
99
size_t total_label_len =
100
sizeof(tls1_3_label_prefix) + llen;
101
size_t total_hkdf_lbl_len =
102
SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN( total_label_len, clen );
104
unsigned char *p = dst;
106
/* Add the size of the expanded key material.
107
* We're hardcoding the high byte to 0 here assuming that we never use
108
* TLS 1.3 HKDF key expansion to more than 255 Bytes. */
109
#if MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN > 255
110
#error "The implementation of ssl_tls1_3_hkdf_encode_label() is not fit for the \
111
value of MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN"
115
*p++ = (unsigned char)( ( desired_length >> 0 ) & 0xFF );
117
/* Add label incl. prefix */
118
*p++ = (unsigned char)( total_label_len & 0xFF );
119
memcpy( p, tls1_3_label_prefix, sizeof(tls1_3_label_prefix) );
120
p += sizeof(tls1_3_label_prefix);
121
memcpy( p, label, llen );
124
/* Add context value */
125
*p++ = (unsigned char)( clen & 0xFF );
127
memcpy( p, ctx, clen );
129
/* Return total length to the caller. */
130
*dlen = total_hkdf_lbl_len;
133
int mbedtls_ssl_tls1_3_hkdf_expand_label(
134
mbedtls_md_type_t hash_alg,
135
const unsigned char *secret, size_t slen,
136
const unsigned char *label, size_t llen,
137
const unsigned char *ctx, size_t clen,
138
unsigned char *buf, size_t blen )
140
const mbedtls_md_info_t *md;
141
unsigned char hkdf_label[ SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN ];
142
size_t hkdf_label_len;
144
if( llen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN )
146
/* Should never happen since this is an internal
147
* function, and we know statically which labels
149
return( MBEDTLS_ERR_SSL_INTERNAL_ERROR );
152
if( clen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN )
154
/* Should not happen, as above. */
155
return( MBEDTLS_ERR_SSL_INTERNAL_ERROR );
158
if( blen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN )
160
/* Should not happen, as above. */
161
return( MBEDTLS_ERR_SSL_INTERNAL_ERROR );
164
md = mbedtls_md_info_from_type( hash_alg );
166
return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
168
ssl_tls1_3_hkdf_encode_label( blen,
174
return( mbedtls_hkdf_expand( md,
176
hkdf_label, hkdf_label_len,
181
* The traffic keying material is generated from the following inputs:
183
* - One secret value per sender.
184
* - A purpose value indicating the specific value being generated
185
* - The desired lengths of key and IV.
187
* The expansion itself is based on HKDF:
189
* [sender]_write_key = HKDF-Expand-Label( Secret, "key", "", key_length )
190
* [sender]_write_iv = HKDF-Expand-Label( Secret, "iv" , "", iv_length )
192
* [sender] denotes the sending side and the Secret value is provided
193
* by the function caller. Note that we generate server and client side
194
* keys in a single function call.
196
int mbedtls_ssl_tls1_3_make_traffic_keys(
197
mbedtls_md_type_t hash_alg,
198
const unsigned char *client_secret,
199
const unsigned char *server_secret,
200
size_t slen, size_t key_len, size_t iv_len,
201
mbedtls_ssl_key_set *keys )
205
ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg,
207
MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( key ),
209
keys->client_write_key, key_len );
213
ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg,
215
MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( key ),
217
keys->server_write_key, key_len );
221
ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg,
223
MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( iv ),
225
keys->client_write_iv, iv_len );
229
ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg,
231
MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( iv ),
233
keys->server_write_iv, iv_len );
237
keys->key_len = key_len;
238
keys->iv_len = iv_len;
243
int mbedtls_ssl_tls1_3_derive_secret(
244
mbedtls_md_type_t hash_alg,
245
const unsigned char *secret, size_t slen,
246
const unsigned char *label, size_t llen,
247
const unsigned char *ctx, size_t clen,
249
unsigned char *dstbuf, size_t buflen )
252
unsigned char hashed_context[ MBEDTLS_MD_MAX_SIZE ];
254
const mbedtls_md_info_t *md;
255
md = mbedtls_md_info_from_type( hash_alg );
257
return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
259
if( ctx_hashed == MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED )
261
ret = mbedtls_md( md, ctx, clen, hashed_context );
264
clen = mbedtls_md_get_size( md );
268
if( clen > sizeof(hashed_context) )
270
/* This should never happen since this function is internal
271
* and the code sets `ctx_hashed` correctly.
272
* Let's double-check nonetheless to not run at the risk
273
* of getting a stack overflow. */
274
return( MBEDTLS_ERR_SSL_INTERNAL_ERROR );
277
memcpy( hashed_context, ctx, clen );
280
return( mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg,
283
hashed_context, clen,
287
int mbedtls_ssl_tls1_3_evolve_secret(
288
mbedtls_md_type_t hash_alg,
289
const unsigned char *secret_old,
290
const unsigned char *input, size_t input_len,
291
unsigned char *secret_new )
293
int ret = MBEDTLS_ERR_SSL_INTERNAL_ERROR;
295
unsigned char tmp_secret[ MBEDTLS_MD_MAX_SIZE ] = { 0 };
296
unsigned char tmp_input [ MBEDTLS_MD_MAX_SIZE ] = { 0 };
298
const mbedtls_md_info_t *md;
299
md = mbedtls_md_info_from_type( hash_alg );
301
return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
303
hlen = mbedtls_md_get_size( md );
305
/* For non-initial runs, call Derive-Secret( ., "derived", "")
306
* on the old secret. */
307
if( secret_old != NULL )
309
ret = mbedtls_ssl_tls1_3_derive_secret(
312
MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( derived ),
313
NULL, 0, /* context */
314
MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED,
322
memcpy( tmp_input, input, input_len );
330
/* HKDF-Extract takes a salt and input key material.
331
* The salt is the old secret, and the input key material
332
* is the input secret (PSK / ECDHE). */
333
ret = mbedtls_hkdf_extract( md,
344
mbedtls_platform_zeroize( tmp_secret, sizeof(tmp_secret) );
345
mbedtls_platform_zeroize( tmp_input, sizeof(tmp_input) );
349
#endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */
added
removed
mbedtls/ssl_tls13_keys.c
