2 * Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
4 * Licensed under the OpenSSL license (the "License"). You may not use
5 * this file except in compliance with the License. You can obtain a copy
6 * in the file LICENSE in the source distribution or at
7 * https://www.openssl.org/source/license.html
12 #include <openssl/evp.h>
13 #include <openssl/kdf.h>
15 #define TLS13_MAX_LABEL_LEN 246
17 /* Always filled with zeros */
18 static const unsigned char default_zeros
[EVP_MAX_MD_SIZE
];
21 * Given a |secret|; a |label| of length |labellen|; and a |hash| of the
22 * handshake messages, derive a new secret |outlen| bytes long and store it in
23 * the location pointed to be |out|. The |hash| value may be NULL. Returns 1 on
24 * success 0 on failure.
26 int tls13_hkdf_expand(SSL
*s
, const EVP_MD
*md
, const unsigned char *secret
,
27 const unsigned char *label
, size_t labellen
,
28 const unsigned char *hash
,
29 unsigned char *out
, size_t outlen
)
31 const unsigned char label_prefix
[] = "tls13 ";
32 EVP_PKEY_CTX
*pctx
= EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF
, NULL
);
37 * 2 bytes for length of whole HkdfLabel + 1 byte for length of combined
38 * prefix and label + bytes for the label itself + bytes for the hash
40 unsigned char hkdflabel
[sizeof(uint16_t) + sizeof(uint8_t) +
41 + sizeof(label_prefix
) + TLS13_MAX_LABEL_LEN
48 hashlen
= EVP_MD_size(md
);
50 if (!WPACKET_init_static_len(&pkt
, hkdflabel
, sizeof(hkdflabel
), 0)
51 || !WPACKET_put_bytes_u16(&pkt
, outlen
)
52 || !WPACKET_start_sub_packet_u8(&pkt
)
53 || !WPACKET_memcpy(&pkt
, label_prefix
, sizeof(label_prefix
) - 1)
54 || !WPACKET_memcpy(&pkt
, label
, labellen
)
55 || !WPACKET_close(&pkt
)
56 || !WPACKET_sub_memcpy_u8(&pkt
, hash
, (hash
== NULL
) ? 0 : hashlen
)
57 || !WPACKET_get_total_written(&pkt
, &hkdflabellen
)
58 || !WPACKET_finish(&pkt
)) {
59 EVP_PKEY_CTX_free(pctx
);
60 WPACKET_cleanup(&pkt
);
64 ret
= EVP_PKEY_derive_init(pctx
) <= 0
65 || EVP_PKEY_CTX_hkdf_mode(pctx
, EVP_PKEY_HKDEF_MODE_EXPAND_ONLY
)
67 || EVP_PKEY_CTX_set_hkdf_md(pctx
, md
) <= 0
68 || EVP_PKEY_CTX_set1_hkdf_key(pctx
, secret
, hashlen
) <= 0
69 || EVP_PKEY_CTX_add1_hkdf_info(pctx
, hkdflabel
, hkdflabellen
) <= 0
70 || EVP_PKEY_derive(pctx
, out
, &outlen
) <= 0;
72 EVP_PKEY_CTX_free(pctx
);
78 * Given a |secret| generate a |key| of length |keylen| bytes. Returns 1 on
79 * success 0 on failure.
81 int tls13_derive_key(SSL
*s
, const EVP_MD
*md
, const unsigned char *secret
,
82 unsigned char *key
, size_t keylen
)
84 static const unsigned char keylabel
[] = "key";
86 return tls13_hkdf_expand(s
, md
, secret
, keylabel
, sizeof(keylabel
) - 1,
91 * Given a |secret| generate an |iv| of length |ivlen| bytes. Returns 1 on
92 * success 0 on failure.
94 int tls13_derive_iv(SSL
*s
, const EVP_MD
*md
, const unsigned char *secret
,
95 unsigned char *iv
, size_t ivlen
)
97 static const unsigned char ivlabel
[] = "iv";
99 return tls13_hkdf_expand(s
, md
, secret
, ivlabel
, sizeof(ivlabel
) - 1,
103 int tls13_derive_finishedkey(SSL
*s
, const EVP_MD
*md
,
104 const unsigned char *secret
,
105 unsigned char *fin
, size_t finlen
)
107 static const unsigned char finishedlabel
[] = "finished";
109 return tls13_hkdf_expand(s
, md
, secret
, finishedlabel
,
110 sizeof(finishedlabel
) - 1, NULL
, fin
, finlen
);
114 * Given the previous secret |prevsecret| and a new input secret |insecret| of
115 * length |insecretlen|, generate a new secret and store it in the location
116 * pointed to by |outsecret|. Returns 1 on success 0 on failure.
118 int tls13_generate_secret(SSL
*s
, const EVP_MD
*md
,
119 const unsigned char *prevsecret
,
120 const unsigned char *insecret
,
122 unsigned char *outsecret
)
124 size_t mdlen
, prevsecretlen
;
126 EVP_PKEY_CTX
*pctx
= EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF
, NULL
);
127 static const char derived_secret_label
[] = "derived";
128 unsigned char preextractsec
[EVP_MAX_MD_SIZE
];
133 mdlen
= EVP_MD_size(md
);
135 if (insecret
== NULL
) {
136 insecret
= default_zeros
;
139 if (prevsecret
== NULL
) {
140 prevsecret
= default_zeros
;
143 EVP_MD_CTX
*mctx
= EVP_MD_CTX_new();
144 unsigned char hash
[EVP_MAX_MD_SIZE
];
146 /* The pre-extract derive step uses a hash of no messages */
148 || EVP_DigestInit_ex(mctx
, md
, NULL
) <= 0
149 || EVP_DigestFinal_ex(mctx
, hash
, NULL
) <= 0) {
150 EVP_MD_CTX_free(mctx
);
153 EVP_MD_CTX_free(mctx
);
155 /* Generate the pre-extract secret */
156 if (!tls13_hkdf_expand(s
, md
, prevsecret
,
157 (unsigned char *)derived_secret_label
,
158 sizeof(derived_secret_label
) - 1, hash
,
159 preextractsec
, mdlen
))
162 prevsecret
= preextractsec
;
163 prevsecretlen
= mdlen
;
166 ret
= EVP_PKEY_derive_init(pctx
) <= 0
167 || EVP_PKEY_CTX_hkdf_mode(pctx
, EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY
)
169 || EVP_PKEY_CTX_set_hkdf_md(pctx
, md
) <= 0
170 || EVP_PKEY_CTX_set1_hkdf_key(pctx
, insecret
, insecretlen
) <= 0
171 || EVP_PKEY_CTX_set1_hkdf_salt(pctx
, prevsecret
, prevsecretlen
)
173 || EVP_PKEY_derive(pctx
, outsecret
, &mdlen
)
176 EVP_PKEY_CTX_free(pctx
);
177 if (prevsecret
== preextractsec
)
178 OPENSSL_cleanse(preextractsec
, mdlen
);
183 * Given an input secret |insecret| of length |insecretlen| generate the
184 * handshake secret. This requires the early secret to already have been
185 * generated. Returns 1 on success 0 on failure.
187 int tls13_generate_handshake_secret(SSL
*s
, const unsigned char *insecret
,
190 return tls13_generate_secret(s
, ssl_handshake_md(s
), s
->early_secret
,
191 insecret
, insecretlen
,
192 (unsigned char *)&s
->handshake_secret
);
196 * Given the handshake secret |prev| of length |prevlen| generate the master
197 * secret and store its length in |*secret_size|. Returns 1 on success 0 on
200 int tls13_generate_master_secret(SSL
*s
, unsigned char *out
,
201 unsigned char *prev
, size_t prevlen
,
204 const EVP_MD
*md
= ssl_handshake_md(s
);
206 *secret_size
= EVP_MD_size(md
);
207 return tls13_generate_secret(s
, md
, prev
, NULL
, 0, out
);
211 * Generates the mac for the Finished message. Returns the length of the MAC or
214 size_t tls13_final_finish_mac(SSL
*s
, const char *str
, size_t slen
,
217 const EVP_MD
*md
= ssl_handshake_md(s
);
218 unsigned char hash
[EVP_MAX_MD_SIZE
];
219 size_t hashlen
, ret
= 0;
220 EVP_PKEY
*key
= NULL
;
221 EVP_MD_CTX
*ctx
= EVP_MD_CTX_new();
223 if (!ssl_handshake_hash(s
, hash
, sizeof(hash
), &hashlen
))
226 if (str
== s
->method
->ssl3_enc
->server_finished_label
)
227 key
= EVP_PKEY_new_mac_key(EVP_PKEY_HMAC
, NULL
,
228 s
->server_finished_secret
, hashlen
);
230 key
= EVP_PKEY_new_mac_key(EVP_PKEY_HMAC
, NULL
,
231 s
->client_finished_secret
, hashlen
);
235 || EVP_DigestSignInit(ctx
, NULL
, md
, NULL
, key
) <= 0
236 || EVP_DigestSignUpdate(ctx
, hash
, hashlen
) <= 0
237 || EVP_DigestSignFinal(ctx
, out
, &hashlen
) <= 0)
243 EVP_MD_CTX_free(ctx
);
248 * There isn't really a key block in TLSv1.3, but we still need this function
249 * for initialising the cipher and hash. Returns 1 on success or 0 on failure.
251 int tls13_setup_key_block(SSL
*s
)
255 int mac_type
= NID_undef
;
257 s
->session
->cipher
= s
->s3
->tmp
.new_cipher
;
258 if (!ssl_cipher_get_evp
259 (s
->session
, &c
, &hash
, &mac_type
, NULL
, NULL
, 0)) {
260 SSLerr(SSL_F_TLS13_SETUP_KEY_BLOCK
, SSL_R_CIPHER_OR_HASH_UNAVAILABLE
);
264 s
->s3
->tmp
.new_sym_enc
= c
;
265 s
->s3
->tmp
.new_hash
= hash
;
270 static int derive_secret_key_and_iv(SSL
*s
, int sending
, const EVP_MD
*md
,
271 const EVP_CIPHER
*ciph
,
272 const unsigned char *insecret
,
273 const unsigned char *hash
,
274 const unsigned char *label
,
275 size_t labellen
, unsigned char *secret
,
276 unsigned char *iv
, EVP_CIPHER_CTX
*ciph_ctx
)
278 unsigned char key
[EVP_MAX_KEY_LENGTH
];
279 size_t ivlen
, keylen
, taglen
;
280 size_t hashlen
= EVP_MD_size(md
);
282 if (!tls13_hkdf_expand(s
, md
, insecret
, label
, labellen
, hash
, secret
,
284 SSLerr(SSL_F_DERIVE_SECRET_KEY_AND_IV
, ERR_R_INTERNAL_ERROR
);
288 /* TODO(size_t): convert me */
289 keylen
= EVP_CIPHER_key_length(ciph
);
290 if (EVP_CIPHER_mode(ciph
) == EVP_CIPH_CCM_MODE
) {
293 ivlen
= EVP_CCM_TLS_IV_LEN
;
294 if (s
->s3
->tmp
.new_cipher
== NULL
) {
295 /* We've not selected a cipher yet - we must be doing early data */
296 algenc
= s
->session
->cipher
->algorithm_enc
;
298 algenc
= s
->s3
->tmp
.new_cipher
->algorithm_enc
;
300 if (algenc
& (SSL_AES128CCM8
| SSL_AES256CCM8
))
301 taglen
= EVP_CCM8_TLS_TAG_LEN
;
303 taglen
= EVP_CCM_TLS_TAG_LEN
;
305 ivlen
= EVP_CIPHER_iv_length(ciph
);
309 if (!tls13_derive_key(s
, md
, secret
, key
, keylen
)
310 || !tls13_derive_iv(s
, md
, secret
, iv
, ivlen
)) {
311 SSLerr(SSL_F_DERIVE_SECRET_KEY_AND_IV
, ERR_R_INTERNAL_ERROR
);
315 if (EVP_CipherInit_ex(ciph_ctx
, ciph
, NULL
, NULL
, NULL
, sending
) <= 0
316 || !EVP_CIPHER_CTX_ctrl(ciph_ctx
, EVP_CTRL_AEAD_SET_IVLEN
, ivlen
, NULL
)
317 || (taglen
!= 0 && !EVP_CIPHER_CTX_ctrl(ciph_ctx
, EVP_CTRL_AEAD_SET_TAG
,
319 || EVP_CipherInit_ex(ciph_ctx
, NULL
, NULL
, key
, NULL
, -1) <= 0) {
320 SSLerr(SSL_F_DERIVE_SECRET_KEY_AND_IV
, ERR_R_EVP_LIB
);
326 OPENSSL_cleanse(key
, sizeof(key
));
330 int tls13_change_cipher_state(SSL
*s
, int which
)
332 static const unsigned char client_early_traffic
[] = "c e traffic";
333 static const unsigned char client_handshake_traffic
[] = "c hs traffic";
334 static const unsigned char client_application_traffic
[] = "c ap traffic";
335 static const unsigned char server_handshake_traffic
[] = "s hs traffic";
336 static const unsigned char server_application_traffic
[] = "s ap traffic";
337 static const unsigned char resumption_master_secret
[] = "res master";
339 unsigned char secret
[EVP_MAX_MD_SIZE
];
340 unsigned char hashval
[EVP_MAX_MD_SIZE
];
341 unsigned char *hash
= hashval
;
342 unsigned char *insecret
;
343 unsigned char *finsecret
= NULL
;
344 const char *log_label
= NULL
;
345 EVP_CIPHER_CTX
*ciph_ctx
;
346 size_t finsecretlen
= 0;
347 const unsigned char *label
;
348 size_t labellen
, hashlen
= 0;
350 const EVP_MD
*md
= NULL
;
351 const EVP_CIPHER
*cipher
= NULL
;
353 if (which
& SSL3_CC_READ
) {
354 if (s
->enc_read_ctx
!= NULL
) {
355 EVP_CIPHER_CTX_reset(s
->enc_read_ctx
);
357 s
->enc_read_ctx
= EVP_CIPHER_CTX_new();
358 if (s
->enc_read_ctx
== NULL
) {
359 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_MALLOC_FAILURE
);
363 ciph_ctx
= s
->enc_read_ctx
;
366 RECORD_LAYER_reset_read_sequence(&s
->rlayer
);
368 if (s
->enc_write_ctx
!= NULL
) {
369 EVP_CIPHER_CTX_reset(s
->enc_write_ctx
);
371 s
->enc_write_ctx
= EVP_CIPHER_CTX_new();
372 if (s
->enc_write_ctx
== NULL
) {
373 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_MALLOC_FAILURE
);
377 ciph_ctx
= s
->enc_write_ctx
;
380 RECORD_LAYER_reset_write_sequence(&s
->rlayer
);
383 if (((which
& SSL3_CC_CLIENT
) && (which
& SSL3_CC_WRITE
))
384 || ((which
& SSL3_CC_SERVER
) && (which
& SSL3_CC_READ
))) {
385 if (which
& SSL3_CC_EARLY
) {
386 EVP_MD_CTX
*mdctx
= NULL
;
389 unsigned int hashlenui
;
390 const SSL_CIPHER
*sslcipher
= SSL_SESSION_get0_cipher(s
->session
);
392 insecret
= s
->early_secret
;
393 label
= client_early_traffic
;
394 labellen
= sizeof(client_early_traffic
) - 1;
395 log_label
= CLIENT_EARLY_LABEL
;
397 handlen
= BIO_get_mem_data(s
->s3
->handshake_buffer
, &hdata
);
399 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
,
400 SSL_R_BAD_HANDSHAKE_LENGTH
);
403 if (sslcipher
== NULL
) {
404 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_INTERNAL_ERROR
);
409 * We need to calculate the handshake digest using the digest from
410 * the session. We haven't yet selected our ciphersuite so we can't
411 * use ssl_handshake_md().
413 mdctx
= EVP_MD_CTX_new();
415 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_MALLOC_FAILURE
);
418 cipher
= EVP_get_cipherbynid(SSL_CIPHER_get_cipher_nid(sslcipher
));
419 md
= ssl_md(sslcipher
->algorithm2
);
420 if (md
== NULL
|| !EVP_DigestInit_ex(mdctx
, md
, NULL
)
421 || !EVP_DigestUpdate(mdctx
, hdata
, handlen
)
422 || !EVP_DigestFinal_ex(mdctx
, hashval
, &hashlenui
)) {
423 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_INTERNAL_ERROR
);
424 EVP_MD_CTX_free(mdctx
);
428 EVP_MD_CTX_free(mdctx
);
429 } else if (which
& SSL3_CC_HANDSHAKE
) {
430 insecret
= s
->handshake_secret
;
431 finsecret
= s
->client_finished_secret
;
432 finsecretlen
= EVP_MD_size(ssl_handshake_md(s
));
433 label
= client_handshake_traffic
;
434 labellen
= sizeof(client_handshake_traffic
) - 1;
435 log_label
= CLIENT_HANDSHAKE_LABEL
;
437 * The handshake hash used for the server read/client write handshake
438 * traffic secret is the same as the hash for the server
439 * write/client read handshake traffic secret. However, if we
440 * processed early data then we delay changing the server
441 * read/client write cipher state until later, and the handshake
442 * hashes have moved on. Therefore we use the value saved earlier
443 * when we did the server write/client read change cipher state.
445 hash
= s
->handshake_traffic_hash
;
447 insecret
= s
->master_secret
;
448 label
= client_application_traffic
;
449 labellen
= sizeof(client_application_traffic
) - 1;
450 log_label
= CLIENT_APPLICATION_LABEL
;
452 * For this we only use the handshake hashes up until the server
453 * Finished hash. We do not include the client's Finished, which is
454 * what ssl_handshake_hash() would give us. Instead we use the
455 * previously saved value.
457 hash
= s
->server_finished_hash
;
460 /* Early data never applies to client-read/server-write */
461 if (which
& SSL3_CC_HANDSHAKE
) {
462 insecret
= s
->handshake_secret
;
463 finsecret
= s
->server_finished_secret
;
464 finsecretlen
= EVP_MD_size(ssl_handshake_md(s
));
465 label
= server_handshake_traffic
;
466 labellen
= sizeof(server_handshake_traffic
) - 1;
467 log_label
= SERVER_HANDSHAKE_LABEL
;
469 insecret
= s
->master_secret
;
470 label
= server_application_traffic
;
471 labellen
= sizeof(server_application_traffic
) - 1;
472 log_label
= SERVER_APPLICATION_LABEL
;
476 if (!(which
& SSL3_CC_EARLY
)) {
477 md
= ssl_handshake_md(s
);
478 cipher
= s
->s3
->tmp
.new_sym_enc
;
479 if (!ssl3_digest_cached_records(s
, 1)
480 || !ssl_handshake_hash(s
, hashval
, sizeof(hashval
), &hashlen
)) {
481 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_INTERNAL_ERROR
);
487 * Save the hash of handshakes up to now for use when we calculate the
488 * client application traffic secret
490 if (label
== server_application_traffic
)
491 memcpy(s
->server_finished_hash
, hashval
, hashlen
);
493 if (label
== server_handshake_traffic
)
494 memcpy(s
->handshake_traffic_hash
, hashval
, hashlen
);
496 if (label
== client_application_traffic
) {
498 * We also create the resumption master secret, but this time use the
499 * hash for the whole handshake including the Client Finished
501 if (!tls13_hkdf_expand(s
, ssl_handshake_md(s
), insecret
,
502 resumption_master_secret
,
503 sizeof(resumption_master_secret
) - 1,
504 hashval
, s
->session
->master_key
, hashlen
)) {
505 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_INTERNAL_ERROR
);
508 s
->session
->master_key_length
= hashlen
;
511 if (!derive_secret_key_and_iv(s
, which
& SSL3_CC_WRITE
, md
, cipher
,
512 insecret
, hash
, label
, labellen
, secret
, iv
,
517 if (label
== server_application_traffic
)
518 memcpy(s
->server_app_traffic_secret
, secret
, hashlen
);
519 else if (label
== client_application_traffic
)
520 memcpy(s
->client_app_traffic_secret
, secret
, hashlen
);
522 if (!ssl_log_secret(s
, log_label
, secret
, hashlen
)) {
523 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_INTERNAL_ERROR
);
527 if (finsecret
!= NULL
528 && !tls13_derive_finishedkey(s
, ssl_handshake_md(s
), secret
,
529 finsecret
, finsecretlen
)) {
530 SSLerr(SSL_F_TLS13_CHANGE_CIPHER_STATE
, ERR_R_INTERNAL_ERROR
);
536 OPENSSL_cleanse(secret
, sizeof(secret
));
540 int tls13_update_key(SSL
*s
, int sending
)
542 static const unsigned char application_traffic
[] = "traffic upd";
543 const EVP_MD
*md
= ssl_handshake_md(s
);
544 size_t hashlen
= EVP_MD_size(md
);
545 unsigned char *insecret
, *iv
;
546 unsigned char secret
[EVP_MAX_MD_SIZE
];
547 EVP_CIPHER_CTX
*ciph_ctx
;
550 if (s
->server
== sending
)
551 insecret
= s
->server_app_traffic_secret
;
553 insecret
= s
->client_app_traffic_secret
;
557 ciph_ctx
= s
->enc_write_ctx
;
558 RECORD_LAYER_reset_write_sequence(&s
->rlayer
);
561 ciph_ctx
= s
->enc_read_ctx
;
562 RECORD_LAYER_reset_read_sequence(&s
->rlayer
);
565 if (!derive_secret_key_and_iv(s
, sending
, ssl_handshake_md(s
),
566 s
->s3
->tmp
.new_sym_enc
, insecret
, NULL
,
568 sizeof(application_traffic
) - 1, secret
, iv
,
572 memcpy(insecret
, secret
, hashlen
);
576 OPENSSL_cleanse(secret
, sizeof(secret
));
580 int tls13_alert_code(int code
)
582 if (code
== SSL_AD_MISSING_EXTENSION
)
585 return tls1_alert_code(code
);