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 28 #include <stdint.h> 29 #include <string.h> 30 31 #define MBEDTLS_SSL_TLS1_3_LABEL( name, string ) \ 32 .name = string, 33 34 struct mbedtls_ssl_tls1_3_labels_struct const mbedtls_ssl_tls1_3_labels = 35 { 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 39 }; 40 41 #undef MBEDTLS_SSL_TLS1_3_LABEL 42 43 /* 44 * This function creates a HkdfLabel structure used in the TLS 1.3 key schedule. 45 * 46 * The HkdfLabel is specified in RFC 8446 as follows: 47 * 48 * struct HkdfLabel { 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 52 * }; 53 * 54 * Parameters: 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. 76 */ 77 78 static const char tls1_3_label_prefix[6] = "tls13 "; 79 80 #define SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN( label_len, context_len ) \ 81 ( 2 /* expansion length */ \ 82 + 1 /* label length */ \ 83 + label_len \ 84 + 1 /* context length */ \ 85 + context_len ) 86 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 ) 92 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 ) 98 { 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 ); 103 104 unsigned char *p = dst; 105 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" 112 #endif 113 114 *p++ = 0; 115 *p++ = MBEDTLS_BYTE_0( desired_length ); 116 117 /* Add label incl. prefix */ 118 *p++ = MBEDTLS_BYTE_0( total_label_len ); 119 memcpy( p, tls1_3_label_prefix, sizeof(tls1_3_label_prefix) ); 120 p += sizeof(tls1_3_label_prefix); 121 memcpy( p, label, llen ); 122 p += llen; 123 124 /* Add context value */ 125 *p++ = MBEDTLS_BYTE_0( clen ); 126 if( clen != 0 ) 127 memcpy( p, ctx, clen ); 128 129 /* Return total length to the caller. */ 130 *dlen = total_hkdf_lbl_len; 131 } 132 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 ) 139 { 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; 143 144 if( llen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN ) 145 { 146 /* Should never happen since this is an internal 147 * function, and we know statically which labels 148 * are allowed. */ 149 return( MBEDTLS_ERR_SSL_INTERNAL_ERROR ); 150 } 151 152 if( clen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN ) 153 { 154 /* Should not happen, as above. */ 155 return( MBEDTLS_ERR_SSL_INTERNAL_ERROR ); 156 } 157 158 if( blen > MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN ) 159 { 160 /* Should not happen, as above. */ 161 return( MBEDTLS_ERR_SSL_INTERNAL_ERROR ); 162 } 163 164 md = mbedtls_md_info_from_type( hash_alg ); 165 if( md == NULL ) 166 return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA ); 167 168 ssl_tls1_3_hkdf_encode_label( blen, 169 label, llen, 170 ctx, clen, 171 hkdf_label, 172 &hkdf_label_len ); 173 174 return( mbedtls_hkdf_expand( md, 175 secret, slen, 176 hkdf_label, hkdf_label_len, 177 buf, blen ) ); 178 } 179 180 /* 181 * The traffic keying material is generated from the following inputs: 182 * 183 * - One secret value per sender. 184 * - A purpose value indicating the specific value being generated 185 * - The desired lengths of key and IV. 186 * 187 * The expansion itself is based on HKDF: 188 * 189 * [sender]_write_key = HKDF-Expand-Label( Secret, "key", "", key_length ) 190 * [sender]_write_iv = HKDF-Expand-Label( Secret, "iv" , "", iv_length ) 191 * 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. 195 */ 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 ) 202 { 203 int ret = 0; 204 205 ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, 206 client_secret, slen, 207 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( key ), 208 NULL, 0, 209 keys->client_write_key, key_len ); 210 if( ret != 0 ) 211 return( ret ); 212 213 ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, 214 server_secret, slen, 215 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( key ), 216 NULL, 0, 217 keys->server_write_key, key_len ); 218 if( ret != 0 ) 219 return( ret ); 220 221 ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, 222 client_secret, slen, 223 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( iv ), 224 NULL, 0, 225 keys->client_write_iv, iv_len ); 226 if( ret != 0 ) 227 return( ret ); 228 229 ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, 230 server_secret, slen, 231 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( iv ), 232 NULL, 0, 233 keys->server_write_iv, iv_len ); 234 if( ret != 0 ) 235 return( ret ); 236 237 keys->key_len = key_len; 238 keys->iv_len = iv_len; 239 240 return( 0 ); 241 } 242 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, 248 int ctx_hashed, 249 unsigned char *dstbuf, size_t buflen ) 250 { 251 int ret; 252 unsigned char hashed_context[ MBEDTLS_MD_MAX_SIZE ]; 253 254 const mbedtls_md_info_t *md; 255 md = mbedtls_md_info_from_type( hash_alg ); 256 if( md == NULL ) 257 return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA ); 258 259 if( ctx_hashed == MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED ) 260 { 261 ret = mbedtls_md( md, ctx, clen, hashed_context ); 262 if( ret != 0 ) 263 return( ret ); 264 clen = mbedtls_md_get_size( md ); 265 } 266 else 267 { 268 if( clen > sizeof(hashed_context) ) 269 { 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 ); 275 } 276 277 memcpy( hashed_context, ctx, clen ); 278 } 279 280 return( mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, 281 secret, slen, 282 label, llen, 283 hashed_context, clen, 284 dstbuf, buflen ) ); 285 } 286 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 ) 292 { 293 int ret = MBEDTLS_ERR_SSL_INTERNAL_ERROR; 294 size_t hlen, ilen; 295 unsigned char tmp_secret[ MBEDTLS_MD_MAX_SIZE ] = { 0 }; 296 unsigned char tmp_input [ MBEDTLS_MD_MAX_SIZE ] = { 0 }; 297 298 const mbedtls_md_info_t *md; 299 md = mbedtls_md_info_from_type( hash_alg ); 300 if( md == NULL ) 301 return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA ); 302 303 hlen = mbedtls_md_get_size( md ); 304 305 /* For non-initial runs, call Derive-Secret( ., "derived", "") 306 * on the old secret. */ 307 if( secret_old != NULL ) 308 { 309 ret = mbedtls_ssl_tls1_3_derive_secret( 310 hash_alg, 311 secret_old, hlen, 312 MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( derived ), 313 NULL, 0, /* context */ 314 MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED, 315 tmp_secret, hlen ); 316 if( ret != 0 ) 317 goto cleanup; 318 } 319 320 if( input != NULL ) 321 { 322 memcpy( tmp_input, input, input_len ); 323 ilen = input_len; 324 } 325 else 326 { 327 ilen = hlen; 328 } 329 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, 334 tmp_secret, hlen, 335 tmp_input, ilen, 336 secret_new ); 337 if( ret != 0 ) 338 goto cleanup; 339 340 ret = 0; 341 342 cleanup: 343 344 mbedtls_platform_zeroize( tmp_secret, sizeof(tmp_secret) ); 345 mbedtls_platform_zeroize( tmp_input, sizeof(tmp_input) ); 346 return( ret ); 347 } 348 349 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 350