1 /* 2 * TLS 1.3 key schedule 3 * 4 * Copyright The Mbed TLS Contributors 5 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 6 */ 7 #if !defined(MBEDTLS_SSL_TLS1_3_KEYS_H) 8 #define MBEDTLS_SSL_TLS1_3_KEYS_H 9 10 /* This requires MBEDTLS_SSL_TLS1_3_LABEL( idx, name, string ) to be defined at 11 * the point of use. See e.g. the definition of mbedtls_ssl_tls1_3_labels_union 12 * below. */ 13 #define MBEDTLS_SSL_TLS1_3_LABEL_LIST \ 14 MBEDTLS_SSL_TLS1_3_LABEL(finished, "finished") \ 15 MBEDTLS_SSL_TLS1_3_LABEL(resumption, "resumption") \ 16 MBEDTLS_SSL_TLS1_3_LABEL(traffic_upd, "traffic upd") \ 17 MBEDTLS_SSL_TLS1_3_LABEL(exporter, "exporter") \ 18 MBEDTLS_SSL_TLS1_3_LABEL(key, "key") \ 19 MBEDTLS_SSL_TLS1_3_LABEL(iv, "iv") \ 20 MBEDTLS_SSL_TLS1_3_LABEL(c_hs_traffic, "c hs traffic") \ 21 MBEDTLS_SSL_TLS1_3_LABEL(c_ap_traffic, "c ap traffic") \ 22 MBEDTLS_SSL_TLS1_3_LABEL(c_e_traffic, "c e traffic") \ 23 MBEDTLS_SSL_TLS1_3_LABEL(s_hs_traffic, "s hs traffic") \ 24 MBEDTLS_SSL_TLS1_3_LABEL(s_ap_traffic, "s ap traffic") \ 25 MBEDTLS_SSL_TLS1_3_LABEL(s_e_traffic, "s e traffic") \ 26 MBEDTLS_SSL_TLS1_3_LABEL(e_exp_master, "e exp master") \ 27 MBEDTLS_SSL_TLS1_3_LABEL(res_master, "res master") \ 28 MBEDTLS_SSL_TLS1_3_LABEL(exp_master, "exp master") \ 29 MBEDTLS_SSL_TLS1_3_LABEL(ext_binder, "ext binder") \ 30 MBEDTLS_SSL_TLS1_3_LABEL(res_binder, "res binder") \ 31 MBEDTLS_SSL_TLS1_3_LABEL(derived, "derived") 32 33 #define MBEDTLS_SSL_TLS1_3_LABEL(name, string) \ 34 const unsigned char name [sizeof(string) - 1]; 35 36 union mbedtls_ssl_tls1_3_labels_union { 37 MBEDTLS_SSL_TLS1_3_LABEL_LIST 38 }; 39 struct mbedtls_ssl_tls1_3_labels_struct { 40 MBEDTLS_SSL_TLS1_3_LABEL_LIST 41 }; 42 #undef MBEDTLS_SSL_TLS1_3_LABEL 43 44 extern const struct mbedtls_ssl_tls1_3_labels_struct mbedtls_ssl_tls1_3_labels; 45 46 #define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(LABEL) \ 47 mbedtls_ssl_tls1_3_labels.LABEL, \ 48 sizeof(mbedtls_ssl_tls1_3_labels.LABEL) 49 50 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN \ 51 sizeof(union mbedtls_ssl_tls1_3_labels_union) 52 53 /* The maximum length of HKDF contexts used in the TLS 1.3 standard. 54 * Since contexts are always hashes of message transcripts, this can 55 * be approximated from above by the maximum hash size. */ 56 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN \ 57 MBEDTLS_MD_MAX_SIZE 58 59 /* Maximum desired length for expanded key material generated 60 * by HKDF-Expand-Label. 61 * 62 * Warning: If this ever needs to be increased, the implementation 63 * ssl_tls1_3_hkdf_encode_label() in ssl_tls13_keys.c needs to be 64 * adjusted since it currently assumes that HKDF key expansion 65 * is never used with more than 255 Bytes of output. */ 66 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN 255 67 68 /** 69 * \brief The \c HKDF-Expand-Label function from 70 * the TLS 1.3 standard RFC 8446. 71 * 72 * <tt> 73 * HKDF-Expand-Label( Secret, Label, Context, Length ) = 74 * HKDF-Expand( Secret, HkdfLabel, Length ) 75 * </tt> 76 * 77 * \param hash_alg The identifier for the hash algorithm to use. 78 * \param secret The \c Secret argument to \c HKDF-Expand-Label. 79 * This must be a readable buffer of length \p slen Bytes. 80 * \param slen The length of \p secret in Bytes. 81 * \param label The \c Label argument to \c HKDF-Expand-Label. 82 * This must be a readable buffer of length \p llen Bytes. 83 * \param llen The length of \p label in Bytes. 84 * \param ctx The \c Context argument to \c HKDF-Expand-Label. 85 * This must be a readable buffer of length \p clen Bytes. 86 * \param clen The length of \p context in Bytes. 87 * \param buf The destination buffer to hold the expanded secret. 88 * This must be a writable buffer of length \p blen Bytes. 89 * \param blen The desired size of the expanded secret in Bytes. 90 * 91 * \returns \c 0 on success. 92 * \return A negative error code on failure. 93 */ 94 95 int mbedtls_ssl_tls1_3_hkdf_expand_label( 96 mbedtls_md_type_t hash_alg, 97 const unsigned char *secret, size_t slen, 98 const unsigned char *label, size_t llen, 99 const unsigned char *ctx, size_t clen, 100 unsigned char *buf, size_t blen); 101 102 /** 103 * \brief This function is part of the TLS 1.3 key schedule. 104 * It extracts key and IV for the actual client/server traffic 105 * from the client/server traffic secrets. 106 * 107 * From RFC 8446: 108 * 109 * <tt> 110 * [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) 111 * [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)* 112 * </tt> 113 * 114 * \param hash_alg The identifier for the hash algorithm to be used 115 * for the HKDF-based expansion of the secret. 116 * \param client_secret The client traffic secret. 117 * This must be a readable buffer of size \p slen Bytes 118 * \param server_secret The server traffic secret. 119 * This must be a readable buffer of size \p slen Bytes 120 * \param slen Length of the secrets \p client_secret and 121 * \p server_secret in Bytes. 122 * \param key_len The desired length of the key to be extracted in Bytes. 123 * \param iv_len The desired length of the IV to be extracted in Bytes. 124 * \param keys The address of the structure holding the generated 125 * keys and IVs. 126 * 127 * \returns \c 0 on success. 128 * \returns A negative error code on failure. 129 */ 130 131 int mbedtls_ssl_tls1_3_make_traffic_keys( 132 mbedtls_md_type_t hash_alg, 133 const unsigned char *client_secret, 134 const unsigned char *server_secret, 135 size_t slen, size_t key_len, size_t iv_len, 136 mbedtls_ssl_key_set *keys); 137 138 139 #define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED 0 140 #define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED 1 141 142 /** 143 * \brief The \c Derive-Secret function from the TLS 1.3 standard RFC 8446. 144 * 145 * <tt> 146 * Derive-Secret( Secret, Label, Messages ) = 147 * HKDF-Expand-Label( Secret, Label, 148 * Hash( Messages ), 149 * Hash.Length ) ) 150 * </tt> 151 * 152 * \param hash_alg The identifier for the hash function used for the 153 * applications of HKDF. 154 * \param secret The \c Secret argument to the \c Derive-Secret function. 155 * This must be a readable buffer of length \p slen Bytes. 156 * \param slen The length of \p secret in Bytes. 157 * \param label The \c Label argument to the \c Derive-Secret function. 158 * This must be a readable buffer of length \p llen Bytes. 159 * \param llen The length of \p label in Bytes. 160 * \param ctx The hash of the \c Messages argument to the 161 * \c Derive-Secret function, or the \c Messages argument 162 * itself, depending on \p context_already_hashed. 163 * \param clen The length of \p hash. 164 * \param ctx_hashed This indicates whether the \p ctx contains the hash of 165 * the \c Messages argument in the application of the 166 * \c Derive-Secret function 167 * (value MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED), or whether 168 * it is the content of \c Messages itself, in which case 169 * the function takes care of the hashing 170 * (value MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED). 171 * \param dstbuf The target buffer to write the output of 172 * \c Derive-Secret to. This must be a writable buffer of 173 * size \p buflen Bytes. 174 * \param buflen The length of \p dstbuf in Bytes. 175 * 176 * \returns \c 0 on success. 177 * \returns A negative error code on failure. 178 */ 179 int mbedtls_ssl_tls1_3_derive_secret( 180 mbedtls_md_type_t hash_alg, 181 const unsigned char *secret, size_t slen, 182 const unsigned char *label, size_t llen, 183 const unsigned char *ctx, size_t clen, 184 int ctx_hashed, 185 unsigned char *dstbuf, size_t buflen); 186 187 /** 188 * \brief Compute the next secret in the TLS 1.3 key schedule 189 * 190 * The TLS 1.3 key schedule proceeds as follows to compute 191 * the three main secrets during the handshake: The early 192 * secret for early data, the handshake secret for all 193 * other encrypted handshake messages, and the master 194 * secret for all application traffic. 195 * 196 * <tt> 197 * 0 198 * | 199 * v 200 * PSK -> HKDF-Extract = Early Secret 201 * | 202 * v 203 * Derive-Secret( ., "derived", "" ) 204 * | 205 * v 206 * (EC)DHE -> HKDF-Extract = Handshake Secret 207 * | 208 * v 209 * Derive-Secret( ., "derived", "" ) 210 * | 211 * v 212 * 0 -> HKDF-Extract = Master Secret 213 * </tt> 214 * 215 * Each of the three secrets in turn is the basis for further 216 * key derivations, such as the derivation of traffic keys and IVs; 217 * see e.g. mbedtls_ssl_tls1_3_make_traffic_keys(). 218 * 219 * This function implements one step in this evolution of secrets: 220 * 221 * <tt> 222 * old_secret 223 * | 224 * v 225 * Derive-Secret( ., "derived", "" ) 226 * | 227 * v 228 * input -> HKDF-Extract = new_secret 229 * </tt> 230 * 231 * \param hash_alg The identifier for the hash function used for the 232 * applications of HKDF. 233 * \param secret_old The address of the buffer holding the old secret 234 * on function entry. If not \c NULL, this must be a 235 * readable buffer whose size matches the output size 236 * of the hash function represented by \p hash_alg. 237 * If \c NULL, an all \c 0 array will be used instead. 238 * \param input The address of the buffer holding the additional 239 * input for the key derivation (e.g., the PSK or the 240 * ephemeral (EC)DH secret). If not \c NULL, this must be 241 * a readable buffer whose size \p input_len Bytes. 242 * If \c NULL, an all \c 0 array will be used instead. 243 * \param input_len The length of \p input in Bytes. 244 * \param secret_new The address of the buffer holding the new secret 245 * on function exit. This must be a writable buffer 246 * whose size matches the output size of the hash 247 * function represented by \p hash_alg. 248 * This may be the same as \p secret_old. 249 * 250 * \returns \c 0 on success. 251 * \returns A negative error code on failure. 252 */ 253 254 int mbedtls_ssl_tls1_3_evolve_secret( 255 mbedtls_md_type_t hash_alg, 256 const unsigned char *secret_old, 257 const unsigned char *input, size_t input_len, 258 unsigned char *secret_new); 259 260 #endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */ 261