Botan 3.14.1
Crypto and TLS for C&
tls_cipher_state.cpp
Go to the documentation of this file.
1/*
2* TLS cipher state implementation for TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
5* 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10/**
11 * Cipher_State state machine adapted from RFC 8446 7.1.
12 *
13 * 0
14 * |
15 * v
16 * PSK -> HKDF-Extract = Early Secret
17 * |
18 * +-----> Derive-Secret(., "ext binder" | "res binder" | "imp binder", "")
19 * | = binder_key
20 * STATE PSK BINDER
21 * This state is reached by constructing the Cipher_State using init_with_psk().
22 * The state can then be further advanced using advance_with_client_hello() once
23 * the initial Client Hello is fully generated.
24 * |
25 * +-----> Derive-Secret(., "c e traffic", ClientHello)
26 * | = client_early_traffic_secret
27 * |
28 * +-----> Derive-Secret(., "e exp master", ClientHello)
29 * | = early_exporter_master_secret
30 * v
31 * Derive-Secret(., "derived", "")
32 * |
33 * *
34 * STATE EARLY TRAFFIC
35 * This state is reached by calling advance_with_client_hello().
36 * In this state the early data traffic secrets are available. TODO: implement early data.
37 * The state can then be further advanced using advance_with_server_hello().
38 * *
39 * |
40 * v
41 * (EC)DHE -> HKDF-Extract = Handshake Secret
42 * |
43 * +-----> Derive-Secret(., "c hs traffic",
44 * | ClientHello...ServerHello)
45 * | = client_handshake_traffic_secret
46 * |
47 * +-----> Derive-Secret(., "s hs traffic",
48 * | ClientHello...ServerHello)
49 * | = server_handshake_traffic_secret
50 * v
51 * Derive-Secret(., "derived", "")
52 * |
53 * *
54 * STATE HANDSHAKE TRAFFIC
55 * This state is reached by constructing Cipher_State using init_with_server_hello() or
56 * advance_with_server_hello(). In this state the handshake traffic secrets are available.
57 * The state can then be further advanced using advance_with_server_finished().
58 * *
59 * |
60 * v
61 * 0 -> HKDF-Extract = Master Secret
62 * |
63 * +-----> Derive-Secret(., "c ap traffic",
64 * | ClientHello...server Finished)
65 * | = client_application_traffic_secret_0
66 * |
67 * +-----> Derive-Secret(., "s ap traffic",
68 * | ClientHello...server Finished)
69 * | = server_application_traffic_secret_0
70 * |
71 * +-----> Derive-Secret(., "exp master",
72 * | ClientHello...server Finished)
73 * | = exporter_master_secret
74 * *
75 * STATE SERVER APPLICATION TRAFFIC
76 * This state is reached by calling advance_with_server_finished(). It allows the server
77 * to send application traffic and the client to receive it. The opposite direction is not
78 * yet possible in this state. The state can then be further advanced using
79 * advance_with_client_finished().
80 * *
81 * |
82 * +-----> Derive-Secret(., "res master",
83 * ClientHello...client Finished)
84 * = resumption_master_secret
85 * STATE COMPLETED
86 * Once this state is reached the handshake is finished, both client and server can exchange
87 * application data and no further cipher state advances are possible.
88 */
89
90#include <algorithm>
91#include <limits>
92#include <utility>
93
94#include <botan/internal/tls_cipher_state.h>
95
96#include <botan/aead.h>
97#include <botan/assert.h>
98#include <botan/hash.h>
99#include <botan/secmem.h>
100#include <botan/tls_ciphersuite.h>
101#include <botan/tls_exceptn.h>
102#include <botan/tls_magic.h>
103
104#include <botan/mem_ops.h>
105#include <botan/internal/concat_util.h>
106#include <botan/internal/fmt.h>
107#include <botan/internal/hkdf.h>
108#include <botan/internal/hmac.h>
109#include <botan/internal/int_utils.h>
110#include <botan/internal/loadstor.h>
111#include <botan/internal/mem_utils.h>
112#include <botan/internal/stl_util.h>
113#include <botan/internal/tls_channel_impl_13.h>
114
115namespace Botan::TLS {
116
117std::unique_ptr<Cipher_State> Cipher_State::create(Connection_Side side, TLS_Flavor flavor, std::string_view prf_algo) {
118 if(flavor == TLS_Flavor::DTLS) {
119 throw Not_Implemented("DTLS 1.3 is not yet supported");
120 } else {
121 return std::make_unique<TLS_Cipher_State>(side, prf_algo);
122 }
123}
124
125namespace {
126
127std::unique_ptr<MessageAuthenticationCode> create_hmac(std::string_view hash) {
128 return std::make_unique<HMAC>(HashFunction::create_or_throw(hash));
129}
130
131} // namespace
132
134 std::string_view hash_function,
135 ExpansionLabelPrefix expansion_label_prefix) :
136 m_state(State::Uninitialized),
137 m_connection_side(whoami),
138 m_extract(std::make_unique<HKDF_Extract>(create_hmac(hash_function))),
139 m_expand(std::make_unique<HKDF_Expand>(create_hmac(hash_function))),
140 m_hash(HashFunction::create_or_throw(hash_function)),
141 m_expansion_label_prefix(expansion_label_prefix),
142 m_salt(m_hash->output_length(), 0x00),
143 m_ticket_nonce(0) {}
144
146
147std::unique_ptr<Cipher_State> Cipher_State::init_with_server_hello(const Connection_Side side,
148 TLS_Flavor flavor,
149 secure_vector<uint8_t>&& shared_secret,
150 const Ciphersuite& cipher,
151 const Transcript_Hash& transcript_hash,
152 SecretLoggerFn secret_logger) {
153 auto cs = Cipher_State::create(side, flavor, cipher.prf_algo());
154 cs->set_secret_logger(std::move(secret_logger));
155 cs->advance_without_psk();
156 cs->advance_with_server_hello(cipher, std::move(shared_secret), transcript_hash);
157 return cs;
158}
159
160std::unique_ptr<Cipher_State> Cipher_State::init_with_psk(const Connection_Side side,
161 TLS_Flavor flavor,
162 const Cipher_State::PSK_Type type,
164 std::string_view prf_algo) {
165 auto cs = Cipher_State::create(side, flavor, prf_algo);
166 cs->advance_with_psk(type, std::move(psk));
167 return cs;
168}
169
171 BOTAN_ASSERT_NOMSG(m_state == State::PskBinder);
172
173 zap(m_binder_key);
174
175 // TODO: Currently 0-RTT is not yet implemented, hence we don't derive the
176 // early traffic secret for now.
177 //
178 // const auto client_early_traffic_secret = derive_secret(m_early_secret, "c e traffic", transcript_hash);
179 // derive_write_traffic_key(client_early_traffic_secret);
180
181 m_exporter_master_secret = derive_secret(m_early_secret, "e exp master", transcript_hash);
182
183 // draft-thomson-tls-keylogfile-00 Section 3.1
184 // An implementation of TLS 1.3 use the label
185 // "EARLY_EXPORTER_MASTER_SECRET" to identify the secret that is using for
186 // early exporters
187 maybe_log_secret("EARLY_EXPORTER_MASTER_SECRET", m_exporter_master_secret);
188
189 m_salt = derive_secret(m_early_secret, "derived", empty_hash());
190 zap(m_early_secret);
191
192 m_state = State::EarlyTraffic;
193}
194
196 BOTAN_ASSERT_NOMSG(m_state == State::HandshakeTraffic);
197 BOTAN_ASSERT_NONNULL(m_hash);
198
199 const auto master_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
200
201 // We have to stash the client traffic application secret until the client's
202 // Finished message is available. Only then can we update the respective
203 // encryption/decryption epoch. See `advance_with_client_finished()`.
204 m_client_application_traffic_secret_0 = derive_secret(master_secret, "c ap traffic", transcript_hash);
205 auto server_application_traffic_secret = derive_secret(master_secret, "s ap traffic", transcript_hash);
206
207 // draft-thomson-tls-keylogfile-00 Section 3.1
208 // An implementation of TLS 1.3 use the label "CLIENT_TRAFFIC_SECRET_0"
209 // and "SERVER_TRAFFIC_SECRET_0" to identify the secrets are using to
210 // protect the connection.
211 maybe_log_secret("CLIENT_TRAFFIC_SECRET_0", m_client_application_traffic_secret_0);
212 maybe_log_secret("SERVER_TRAFFIC_SECRET_0", server_application_traffic_secret);
213
214 // Note: the secrets for processing client's application data
215 // are not derived before the client's Finished message
216 // was seen and the handshake can be considered finished.
217 if(m_connection_side == Connection_Side::Server) {
218 advance_write_epoch(server_application_traffic_secret);
219 } else {
220 advance_read_epoch(server_application_traffic_secret);
221 }
222
223 m_exporter_master_secret = derive_secret(master_secret, "exp master", transcript_hash);
224
225 // draft-thomson-tls-keylogfile-00 Section 3.1
226 // An implementation of TLS 1.3 use the label "EXPORTER_SECRET" to
227 // identify the secret that is used in generating exporters(rfc8446
228 // Section 7.5).
229 maybe_log_secret("EXPORTER_SECRET", m_exporter_master_secret);
230
231 m_state = State::ServerApplicationTraffic;
232}
233
235 BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic);
236 BOTAN_ASSERT_NONNULL(m_hash);
237 BOTAN_ASSERT_NOMSG(!m_client_application_traffic_secret_0.empty());
238
239 // With the client's Finished message, the handshake is complete and
240 // we can process client application data.
241 if(m_connection_side == Connection_Side::Server) {
242 advance_read_epoch(m_client_application_traffic_secret_0);
243 } else {
244 advance_write_epoch(m_client_application_traffic_secret_0);
245 }
246
247 // The handshake is complete, we won't need the stashed client application
248 // traffic secret any longer.
249 zap(m_client_application_traffic_secret_0);
250
251 const auto master_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
252
253 m_resumption_master_secret = derive_secret(master_secret, "res master", transcript_hash);
254
255 // This was the final state change; the salt is no longer needed.
256 zap(m_salt);
257
258 m_state = State::Completed;
259}
260
261size_t Cipher_State::encrypt_output_length(const size_t input_length) const {
262 // This assumes that the AEAD cipher's output length does not change
263 // between epochs.
264 return latest_write_epoch().cipher->output_length(input_length);
265}
266
267size_t Cipher_State::decrypt_output_length(const size_t input_length) const {
268 // This assumes that the AEAD cipher's output length does not change
269 // between epochs.
270 return latest_read_epoch().cipher->output_length(input_length);
271}
272
274 // This assumes that the AEAD cipher's minimal final size does not change
275 // between epochs.
276 return latest_read_epoch().cipher->minimum_final_size();
277}
278
280 // Client side:
281 // After successfully receiving a Server Hello we expect servers to send
282 // alerts as protected records only, just like they start protecting their
283 // handshake data at this point.
284 if(m_connection_side == Connection_Side::Client && m_state == State::EarlyTraffic) {
285 return true;
286 }
287
288 // Server side:
289 // Servers must expect clients to send unprotected alerts during the hand-
290 // shake. In particular, in the response to the server's first protected
291 // flight. We don't expect the client to send alerts protected under the
292 // early traffic secret.
293 //
294 // TODO: when implementing PSK and/or early data for the server, we might
295 // need to reconsider this decision.
296 if(m_connection_side == Connection_Side::Server &&
297 (m_state == State::HandshakeTraffic || m_state == State::ServerApplicationTraffic)) {
298 return true;
299 }
300
301 return false;
302}
303
305 // TODO: when implementing early traffic (0-RTT) this will likely need
306 // to allow `State::EarlyTraffic`.
307
308 if(m_connection_side == Connection_Side::Client && m_state != State::Completed) {
309 return false;
310 }
311
312 if(m_connection_side == Connection_Side::Server && m_state != State::ServerApplicationTraffic &&
313 m_state != State::Completed) {
314 return false;
315 }
316
317 return has_write_epoch();
318}
319
321 // TODO: when implementing early traffic (0-RTT) this will likely need
322 // to allow `State::EarlyTraffic`.
323
324 if(m_connection_side == Connection_Side::Client && m_state != State::ServerApplicationTraffic &&
325 m_state != State::Completed) {
326 return false;
327 }
328
329 if(m_connection_side == Connection_Side::Server && m_state != State::Completed) {
330 return false;
331 }
332
333 return has_read_epoch();
334}
335
336std::string Cipher_State::hash_algorithm() const {
337 BOTAN_ASSERT_NONNULL(m_hash);
338 return m_hash->name();
339}
340
342 if(!cipher.usable_in_version(Protocol_Version::TLS_V13)) {
343 return false;
344 }
345
346 if(hash_algorithm() != cipher.prf_algo()) {
347 return false;
348 }
349
350 // Determine the canonical AEAD name utilized by the current cipher state.
351 // If the connection is half-closed in either direction, we use the AEAD from
352 // the still-active epoch. We assume that the AEAD of both directions is
353 // equal and does not change between epochs.
354 const auto our_aead_name = [&]() -> std::optional<std::string> {
355 if(has_write_epoch()) {
356 return latest_write_epoch().cipher->name();
357 } else if(has_read_epoch()) {
358 return latest_read_epoch().cipher->name();
359 } else {
360 return std::nullopt;
361 }
362 }();
363
364 // Compare canonical AEAD names rather than substring-matching cipher_algo
365 // against the AEAD's name(). starts_with() is both too permissive (an
366 // AES-128/CCM-8 instance starts with "AES-128/CCM" so it would accept the
367 // CCM-16 suite) and too restrictive (cipher_algo "AES-128/CCM(8)" does not
368 // prefix the canonical "AES-128/CCM(8,3)"). Re-instantiating the AEAD from
369 // cipher_algo yields the same canonical name() the suite would produce.
370 if(our_aead_name.has_value()) {
371 const auto ciphersuite_aead = AEAD_Mode::create(cipher.cipher_algo(), Cipher_Dir::Encryption);
372 if(!ciphersuite_aead || ciphersuite_aead->name() != *our_aead_name) {
373 return false;
374 }
375 }
376
377 return true;
378}
379
380std::vector<uint8_t> Cipher_State::psk_binder_mac(
381 const Transcript_Hash& transcript_hash_with_truncated_client_hello) const {
382 BOTAN_ASSERT_NOMSG(m_state == State::PskBinder);
383 BOTAN_ASSERT_NONNULL(m_hash);
384
385 auto hmac = HMAC(m_hash->new_object());
386 hmac.set_key(m_binder_key);
387 hmac.update(transcript_hash_with_truncated_client_hello);
388 return hmac.final_stdvec();
389}
390
391std::vector<uint8_t> Cipher_State::finished_mac(const Transcript_Hash& transcript_hash) const {
392 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Server || m_state == State::HandshakeTraffic);
393 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Client || m_state == State::ServerApplicationTraffic);
394 BOTAN_ASSERT_NONNULL(m_hash);
395
396 const auto& epoch = latest_write_epoch();
397 BOTAN_ASSERT_NOMSG(epoch.finished_key.has_value());
398
399 auto hmac = HMAC(m_hash->new_object());
400 hmac.set_key(*epoch.finished_key);
401 hmac.update(transcript_hash);
402 return hmac.final_stdvec();
403}
404
406 const std::vector<uint8_t>& peer_mac) const {
407 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Server || m_state == State::ServerApplicationTraffic);
408 BOTAN_ASSERT_NOMSG(m_connection_side != Connection_Side::Client || m_state == State::HandshakeTraffic);
409 BOTAN_ASSERT_NONNULL(m_hash);
410
411 const auto& epoch = latest_read_epoch();
412 BOTAN_ASSERT_NOMSG(epoch.finished_key.has_value());
413
414 auto hmac = HMAC(m_hash->new_object());
415 hmac.set_key(*epoch.finished_key);
416 hmac.update(transcript_hash);
417 return hmac.verify_mac(peer_mac);
418}
419
421 BOTAN_ASSERT_NOMSG(m_state == State::Completed);
422
423 return derive_secret(m_resumption_master_secret, "resumption", nonce.get());
424}
425
427 BOTAN_STATE_CHECK(m_state == State::Completed);
428 if(m_ticket_nonce_exhausted) {
429 throw Botan::Invalid_State("ticket nonce pool exhausted");
430 }
431
432 auto retval = store_be<Ticket_Nonce>(m_ticket_nonce);
433
434 if(m_ticket_nonce == std::numeric_limits<decltype(m_ticket_nonce)>::max()) {
435 m_ticket_nonce_exhausted = true;
436 } else {
437 ++m_ticket_nonce;
438 }
439
440 return retval;
441}
442
443secure_vector<uint8_t> Cipher_State::export_key(std::string_view label, std::string_view context, size_t length) const {
445 BOTAN_ASSERT_NONNULL(m_hash);
446
447 m_hash->update(context);
448 const auto context_hash = m_hash->final_stdvec();
449 return hkdf_expand_label(
450 derive_secret(m_exporter_master_secret, label, empty_hash()), "exporter", context_hash, length);
451}
452
453namespace {
454
455// RFC 8446 5.3
456// Each AEAD algorithm will specify a range of possible lengths for the
457// per-record nonce, from N_MIN bytes to N_MAX bytes of input [RFC5116].
458// The length of the TLS per-record nonce (iv_length) is set to the
459// larger of 8 bytes and N_MIN for the AEAD algorithm (see [RFC5116],
460// Section 4).
461//
462// N_MIN is 12 for AES_GCM and AES_CCM as per RFC 5116 and also 12 for ChaCha20 per RFC 8439.
463constexpr size_t NONCE_LENGTH = 12;
464
465std::array<uint8_t, NONCE_LENGTH> current_nonce(const uint64_t seq_no, std::span<const uint8_t> iv) {
466 // RFC 8446 5.3
467 // The per-record nonce for the AEAD construction is formed as follows:
468 //
469 // 1. The 64-bit record sequence number is encoded in network byte
470 // order and padded to the left with zeros to iv_length.
471 //
472 // 2. The padded sequence number is XORed with either the static
473 // client_write_iv or server_write_iv (depending on the role).
474 std::array<uint8_t, NONCE_LENGTH> nonce{};
475 store_be(std::span{nonce}.last<sizeof(seq_no)>(), seq_no);
476 xor_buf(nonce, iv);
477 return nonce;
478}
479
480} // namespace
481
482size_t Cipher_State::protected_record_length(Epoch& epoch, size_t payload_length, size_t padding_bytes) {
484
485 // RFC 8446 5.2
486 // type: The TLSPlaintext.type value containing the content type of the record.
487 constexpr size_t content_type_tag_length = 1;
488
489 const size_t plaintext_length = payload_length + content_type_tag_length + padding_bytes;
490 return epoch.cipher->output_length(plaintext_length);
491}
492
494 std::span<const uint8_t> header,
495 std::span<const uint8_t> payload,
496 Record_Type type,
497 size_t padding_bytes,
500
501 const size_t record_offset = out.size();
502 const size_t content_offset = record_offset + header.size();
503 const size_t record_length = header.size() + protected_record_length(epoch, payload.size(), padding_bytes);
504 out.reserve(record_offset + record_length);
505
506 // RFC 9846 5.2
507 // struct {
508 // opaque content[TLSPlaintext.length];
509 // ContentType type;
510 // uint8 zeros[length_of_padding];
511 // } TLSInnerPlaintext;
512 //
513 // RFC 9846 5.4
514 // Implementations MUST set the padding octets to all zeros before
515 // encrypting.
516 //
517 // resize() value-initializes the new bytes, so the padding is already
518 // zeroed. The header and content are then copied with copy_mem(): for a
519 // vector with a non-standard allocator, insert() falls back to an
520 // element-wise copy loop in libstdc++ that is several times slower than
521 // a memcpy() for a full-sized record.
522 out.resize(content_offset + payload.size() + 1 /* type */ + padding_bytes);
523 copy_mem(std::span{out}.subspan(record_offset, header.size()), header);
524 copy_mem(std::span{out}.subspan(content_offset, payload.size()), payload);
525 out[content_offset + payload.size()] = to_underlying(type);
526
527 // Protect the TLSInnerPlaintext in place (everything after the header,
528 // which is the tail of the buffer) and append the AEAD tag.
529 epoch.cipher->set_associated_data(header);
530 epoch.cipher->start(current_nonce(epoch.sequence_number, epoch.iv));
531 epoch.cipher->finish(out, content_offset);
532 BOTAN_DEBUG_ASSERT(out.size() == record_offset + record_length);
533}
534
536 std::span<const uint8_t> header,
537 Record_Content& protected_record,
538 size_t incoming_record_size_limit) const {
539 BOTAN_ASSERT_NOMSG(protected_record.sequence_number.has_value());
541 BOTAN_ASSERT_NOMSG(protected_record.payload.size() <= MAX_CIPHERTEXT_SIZE_TLS13);
542
543 epoch.cipher->set_associated_data(header);
544 epoch.cipher->start(current_nonce(*protected_record.sequence_number, epoch.iv));
545 epoch.cipher->finish(protected_record.payload);
546
547 // RFC 8449 Section 4
548 // A TLS endpoint that receives a record larger than its advertised limit
549 // MUST generate a fatal "record_overflow" alert; a DTLS endpoint that
550 // receives a record larger than its advertised limit MAY either generate
551 // a fatal "record_overflow" alert or discard the record.
552 //
553 // We choose to generate a fatal alert for DTLS as well, given that this
554 // error is detected after decryption only.
555 if(protected_record.payload.size() > incoming_record_size_limit) {
556 throw TLS_Exception(Alert::RecordOverflow, "Received an encrypted record that exceeds maximum plaintext size");
557 }
558
559 // Remove record padding (RFC 9846 5.4). The TLSInnerPlaintext layout is
560 // content || content_type || zero_padding
561 //
562 // This is intentionally not constant time. Checking it in constant time
563 // requires scanning the entire record which significantly impacts receive
564 // throughput, and in any case doing so seems pointless since the same
565 // information (namely the length of the unpadded record) still leaks to the
566 // same side channels later on during processing, when the application
567 // actually receives and looks at the record.
568 const auto end_of_content = std::find_if(
569 protected_record.payload.crbegin(), protected_record.payload.crend(), [](uint8_t b) { return b != 0x00; });
570
571 // RFC 9846 5.4
572 // If a receiving implementation does not find a non-zero octet in the
573 // cleartext, it MUST terminate the connection with an
574 // "unexpected_message" alert.
575 if(end_of_content == protected_record.payload.crend()) {
576 throw TLS_Exception(Alert::UnexpectedMessage, "No content type found in encrypted record");
577 }
578
579 // hydrate the actual content type from TLSInnerPlaintext
580 protected_record.type = static_cast<Record_Type>(*end_of_content);
581
582 // Truncate to drop the content_type byte and padding. resize() on a
583 // vector of trivially-destructible elements is bookkeeping-only and
584 // does not allocate or iterate over the dropped suffix.
585 protected_record.payload.resize(protected_record.payload.size() -
586 std::distance(protected_record.payload.crbegin(), end_of_content) -
587 1 /* content type byte */);
588
589 // RFC 9846 4.5.3
590 // Once a side has sent its Finished message and has received and
591 // validated the Finished message from its peer, it may begin to send and
592 // receive Application Data over the connection.
593 //
594 // See also:
595 // * https://github.com/randombit/botan/security/advisories/GHSA-pxcj-9ppx-g86g (CVE-2026-34582)
597 throw TLS_Exception(Alert::UnexpectedMessage, "Application data received before handshake completion");
598 }
599
600 // RFC 9846 5.4
601 // Implementations MUST NOT send Handshake and Alert records that have
602 // a zero-length TLSInnerPlaintext.content; if such a message is
603 // received, the receiving implementation MUST terminate the connection
604 // with an "unexpected_message" alert.
605 if(protected_record.payload.empty() && protected_record.type != Record_Type::ApplicationData) {
606 throw TLS_Exception(Alert::UnexpectedMessage, "Received a protected record with empty TLSInnerPlaintext content");
607 }
608}
609
610void Cipher_State::advance_without_psk() {
611 BOTAN_ASSERT_NOMSG(m_state == State::Uninitialized);
612 BOTAN_ASSERT_NONNULL(m_hash);
613
614 // We are not using `m_early_secret` here because the secret won't be needed
615 // in any further state advancement methods.
616 const auto early_secret = hkdf_extract(secure_vector<uint8_t>(m_hash->output_length(), 0x00));
617 m_salt = derive_secret(early_secret, "derived", empty_hash());
618
619 // Without PSK we skip the `PskBinder` state and go right to `EarlyTraffic`.
620 m_state = State::EarlyTraffic;
621}
622
623void Cipher_State::advance_with_psk(PSK_Type type, secure_vector<uint8_t>&& psk) {
624 BOTAN_ASSERT_NOMSG(m_state == State::Uninitialized);
625 BOTAN_ASSERT_NONNULL(m_hash);
626
627 m_early_secret = hkdf_extract(std::move(psk));
628
629 // RFC 8446 and RFC 9258 specify these strings
630 const char* binder_label = [type]() -> const char* {
631 switch(type) {
633 return "res binder";
635 return "ext binder";
637 return "imp binder";
638 }
640 }();
641
642 // RFC 8446 4.2.11.2
643 // The PskBinderEntry is computed in the same way as the Finished message
644 // [...] but with the BaseKey being the binder_key derived via the key
645 // schedule from the corresponding PSK which is being offered.
646 //
647 // Hence we are doing the binder key derivation and expansion in one go.
648 const auto binder_key = derive_secret(m_early_secret, binder_label, empty_hash());
649 m_binder_key = hkdf_expand_label(binder_key, "finished", {}, m_hash->output_length());
650
651 // TODO: Implement early data (0-RTT) and derive early traffic secrets here.
652
653 m_state = State::PskBinder;
654}
655
657 secure_vector<uint8_t>&& shared_secret,
658 const Transcript_Hash& transcript_hash) {
659 BOTAN_ASSERT_NOMSG(m_state == State::EarlyTraffic);
661 BOTAN_STATE_CHECK(!m_ciphersuite.has_value());
662
663 m_ciphersuite = cipher;
664
665 const auto handshake_secret = hkdf_extract(std::move(shared_secret));
666
667 const auto client_handshake_traffic_secret = derive_secret(handshake_secret, "c hs traffic", transcript_hash);
668 const auto server_handshake_traffic_secret = derive_secret(handshake_secret, "s hs traffic", transcript_hash);
669
670 // draft-thomson-tls-keylogfile-00 Section 3.1
671 // An implementation of TLS 1.3 use the label
672 // "CLIENT_HANDSHAKE_TRAFFIC_SECRET" and "SERVER_HANDSHAKE_TRAFFIC_SECRET"
673 // to identify the secrets are using to protect handshake messages.
674 maybe_log_secret("CLIENT_HANDSHAKE_TRAFFIC_SECRET", client_handshake_traffic_secret);
675 maybe_log_secret("SERVER_HANDSHAKE_TRAFFIC_SECRET", server_handshake_traffic_secret);
676
677 if(m_connection_side == Connection_Side::Server) {
678 advance_read_epoch(client_handshake_traffic_secret, true /* handshake epoch */);
679 advance_write_epoch(server_handshake_traffic_secret, true /* handshake epoch */);
680 } else {
681 advance_read_epoch(server_handshake_traffic_secret, true /* handshake epoch */);
682 advance_write_epoch(client_handshake_traffic_secret, true /* handshake epoch */);
683 }
684
685 m_salt = derive_secret(handshake_secret, "derived", empty_hash());
686
687 m_state = State::HandshakeTraffic;
688}
689
691 const secure_vector<uint8_t>& traffic_secret,
692 bool handshake_epoch) const {
693 BOTAN_ASSERT_NONNULL(m_hash);
694 BOTAN_ASSERT_NOMSG(m_ciphersuite.has_value());
695
696 return {
697 .cipher = [&]() -> std::unique_ptr<AEAD_Mode> {
698 auto cipher = AEAD_Mode::create_or_throw(m_ciphersuite->cipher_algo(), direction);
699 cipher->set_key(hkdf_expand_label(traffic_secret, "key", {}, cipher->minimum_keylength()));
700 return cipher;
701 }(),
702 .iv = hkdf_expand_label(traffic_secret, "iv", {}, NONCE_LENGTH),
703 .sequence_number = 0,
704 .traffic_secret = traffic_secret,
705 .finished_key = [&]() -> std::optional<secure_vector<uint8_t>> {
706 if(handshake_epoch) {
707 // Key derivation for the MAC in the "Finished" handshake message
708 // as described in RFC 8446 4.4.4
709 return hkdf_expand_label(traffic_secret, "finished", {}, m_hash->output_length());
710 }
711 return {};
712 }(),
713 };
714}
715
717 BOTAN_ASSERT_NOMSG(m_ciphersuite.has_value());
718 return *m_ciphersuite;
719}
720
721secure_vector<uint8_t> Cipher_State::hkdf_extract(std::span<const uint8_t> ikm) const {
722 BOTAN_ASSERT_NONNULL(m_extract);
723 BOTAN_ASSERT_NONNULL(m_hash);
724 return m_extract->derive_key(m_hash->output_length(), ikm, m_salt, std::vector<uint8_t>());
725}
726
728 std::string_view label,
729 const std::vector<uint8_t>& context,
730 const size_t length) const {
731 BOTAN_ASSERT_NONNULL(m_expand);
732 BOTAN_ARG_CHECK(length <= std::numeric_limits<uint16_t>::max(), "invalid length");
733 BOTAN_ARG_CHECK(context.size() <= 255, "context too large");
734 BOTAN_ARG_CHECK(m_expansion_label_prefix.size() + label.size() <= 255, "label too large");
735
736 const auto hkdf_label =
737 concat<secure_vector<uint8_t>>(store_be(static_cast<uint16_t>(length)),
738 store_be(static_cast<uint8_t>(m_expansion_label_prefix.size() + label.size())),
739 m_expansion_label_prefix,
740 as_span_of_bytes(label),
741 store_be(static_cast<uint8_t>(context.size())),
742 context);
743
744 // HKDF-Expand
745 return m_expand->derive_key(
746 length, secret, hkdf_label, std::vector<uint8_t>() /* just pleasing botan's interface */);
747}
748
749secure_vector<uint8_t> Cipher_State::derive_secret(const secure_vector<uint8_t>& secret,
750 std::string_view label,
751 const Transcript_Hash& messages_hash) const {
752 BOTAN_ASSERT_NONNULL(m_hash);
753 return hkdf_expand_label(secret, label, messages_hash, m_hash->output_length());
754}
755
756std::vector<uint8_t> Cipher_State::empty_hash() const {
757 BOTAN_ASSERT_NONNULL(m_hash);
758 m_hash->update("");
759 return m_hash->final_stdvec();
760}
761
763 BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic || m_state == State::Completed);
764 BOTAN_ASSERT_NONNULL(m_hash);
765
766 const auto& epoch = latest_read_epoch();
767
768 const auto new_read_application_traffic_secret =
769 hkdf_expand_label(epoch.traffic_secret, "traffic upd", {}, m_hash->output_length());
770
771 const auto secret_label = fmt("{}_TRAFFIC_SECRET_{}",
772 m_connection_side == Connection_Side::Server ? "CLIENT" : "SERVER",
773 ++m_read_key_update_count);
774
775 advance_read_epoch(new_read_application_traffic_secret);
776 maybe_log_secret(secret_label, new_read_application_traffic_secret);
777}
778
780 BOTAN_ASSERT_NOMSG(m_state == State::ServerApplicationTraffic || m_state == State::Completed);
781 BOTAN_ASSERT_NONNULL(m_hash);
782
783 const auto& epoch = latest_write_epoch();
784
785 const auto new_write_application_traffic_secret =
786 hkdf_expand_label(epoch.traffic_secret, "traffic upd", {}, m_hash->output_length());
787
788 const auto secret_label = fmt("{}_TRAFFIC_SECRET_{}",
789 m_connection_side == Connection_Side::Server ? "SERVER" : "CLIENT",
790 ++m_write_key_update_count);
791
792 // Our KeyUpdate was already sent, so install the new keys before a key log
793 // callback can throw; the application may continue using the channel
794 advance_write_epoch(new_write_application_traffic_secret);
795 maybe_log_secret(secret_label, new_write_application_traffic_secret);
796}
797
801
805
806TLS_Cipher_State::TLS_Cipher_State(Connection_Side side, std::string_view prf_algo) :
807 Cipher_State(side, prf_algo, {'t', 'l', 's', '1', '3', ' '} /* RFC 9846 7.1 */) {}
808
810
812 std::span<const uint8_t> plaintext,
813 size_t padding_bytes,
815 BOTAN_ASSERT_NOMSG(m_write_epoch.has_value());
817 "Application data must not be encrypted before handshake completion");
818
819 // RFC 8446 5.3
820 // Sequence numbers MUST NOT wrap.
821 if(m_write_epoch->sequence_number == std::numeric_limits<uint64_t>::max()) {
822 throw Invalid_State("TLS write sequence number overflow");
823 }
824
825 // RFC 9846 5.2
826 // opaque_type: The outer opaque_type field of a TLSCiphertext record is
827 // always set to the value 23 (application_data) [...]
828 // legacy_record_version: [...] is always 0x0303. TLS 1.3 TLSCiphertexts
829 // are not generated until after TLS 1.3 has been
830 // negotiated, so there are no historical
831 // compatibility concerns [...].
832 // length: [...] of the following TLSCiphertext.encrypted_record, which is
833 // the sum of the lengths of the content and the padding, plus one
834 // for the inner content type, plus any expansion added by the
835 // AEAD algorithm.
836 const auto header = Record_TLS::serialize_header(
838 Protocol_Version::TLS_V12 /* = 0x0303 */,
839 checked_cast_to<uint16_t>(protected_record_length(*m_write_epoch, plaintext.size(), padding_bytes)));
840
841 marshall_and_protect(*m_write_epoch, header, plaintext, type, padding_bytes, out);
842 ++m_write_epoch->sequence_number;
843}
844
845Record TLS_Cipher_State::deprotect_record(Record_TLS record, size_t incoming_record_size_limit) {
846 BOTAN_ASSERT_NOMSG(m_read_epoch.has_value());
847 BOTAN_ARG_CHECK(record.type() == Record_Type::ApplicationData, "Record type must be ApplicationData");
848
849 // RFC 9846 5.2
850 // length: The length (in bytes) [...], which is the sum of the lengths of
851 // the content and the padding, plus one for the inner content
852 // type, plus any expansion added by the AEAD algorithm.
853 // [...]
854 // If the decryption fails, the receiver MUST terminate the connection
855 // with a "bad_record_mac" alert.
856 //
857 // If the protected record contains less bytes than the expected AEAD tag we
858 // can already fail early because the decryption will fail anyway.
859 if(record.payload().size() < m_read_epoch->cipher->minimum_final_size()) {
860 throw TLS_Exception(Alert::BadRecordMac, "incomplete record mac received");
861 }
862
863 // RFC 9846 6.2
864 // record_overflow: A TLSCiphertext record was received that had a length
865 // more than 2^14 + 256 bytes, or a record decrypted to a TLSPlaintext
866 // record with more than 214 bytes (or some other negotiated limit).
867 //
868 // RFC 8449 4.
869 // A TLS endpoint that receives a record larger than its advertised limit
870 // MUST generate a fatal "record_overflow" alert [...].
871 if(decrypt_output_length(record.payload().size()) > incoming_record_size_limit) {
872 throw TLS_Exception(Alert::RecordOverflow, "Received an encrypted record that exceeds maximum plaintext size");
873 }
874
875 // RFC 8446 5.3
876 // Sequence numbers MUST NOT wrap.
877 if(m_read_epoch->sequence_number == std::numeric_limits<uint64_t>::max()) {
878 throw Invalid_State("TLS read sequence number overflow");
879 }
880
881 auto result = Record_Content{
882 .type = Record_Type::Invalid,
883 .sequence_number = m_read_epoch->sequence_number++,
884 .payload = record.take_payload(),
885 };
886
887 deprotect_and_hydrate_content_type(*m_read_epoch, record.header(), result, incoming_record_size_limit);
888
889 // RFC 9846 5.
890 // An implementation [...] which receives a protected change_cipher_spec
891 // record MUST abort the handshake with an "unexpected_message" alert.
892 // [....]
893 // If a TLS implementation receives an unexpected record type, it MUST
894 // terminate the connection with an "unexpected_message" alert.
895 //
896 // RFC 9846 5.1
897 // enum {
898 // invalid(0),
899 // change_cipher_spec(20),
900 // alert(21),
901 // handshake(22),
902 // application_data(23),
903 // (255)
904 // } ContentType;
905 if(result.type != Record_Type::ApplicationData && //
906 result.type != Record_Type::Handshake && //
907 result.type != Record_Type::Alert) {
908 throw TLS_Exception(Alert::UnexpectedMessage, "protected TLS record type had unexpected value");
909 }
910
911 return annotate_record_type(std::move(result));
912}
913
914void TLS_Cipher_State::advance_write_epoch(const secure_vector<uint8_t>& traffic_secret, bool handshake_epoch) {
915 m_write_epoch = create_epoch(Cipher_Dir::Encryption, traffic_secret, handshake_epoch);
916}
917
918void TLS_Cipher_State::advance_read_epoch(const secure_vector<uint8_t>& traffic_secret, bool handshake_epoch) {
919 m_read_epoch = create_epoch(Cipher_Dir::Decryption, traffic_secret, handshake_epoch);
920}
921
923 m_write_epoch.reset();
924}
925
927 m_read_epoch.reset();
928}
929
930} // namespace Botan::TLS
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:136
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
#define BOTAN_STATE_CHECK_MSG(expr, msg)
Definition assert.h:59
#define BOTAN_ASSERT_UNREACHABLE()
Definition assert.h:173
static std::unique_ptr< AEAD_Mode > create_or_throw(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
Definition aead.cpp:51
static std::unique_ptr< AEAD_Mode > create(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
Definition aead.cpp:61
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
bool can_decrypt_application_traffic() const
uint64_t records_encrypted_with_current_key() const
static size_t protected_record_length(Epoch &epoch, size_t payload_length, size_t padding_bytes)
static std::unique_ptr< Cipher_State > init_with_psk(Connection_Side side, TLS_Flavor flavor, PSK_Type type, secure_vector< uint8_t > &&psk, std::string_view prf_algo)
const Ciphersuite & ciphersuite() const
virtual Epoch & latest_write_epoch()=0
void advance_with_client_hello(const Transcript_Hash &transcript_hash)
size_t minimum_decryption_input_length() const
virtual bool has_read_epoch() const =0
void advance_with_server_finished(const Transcript_Hash &transcript_hash)
virtual void advance_read_epoch(const secure_vector< uint8_t > &traffic_secret, bool handshake_epoch=false)=0
secure_vector< uint8_t > hkdf_expand_label(const secure_vector< uint8_t > &secret, std::string_view label, const std::vector< uint8_t > &context, size_t length) const
bool must_expect_unprotected_alert_traffic() const
void advance_with_client_finished(const Transcript_Hash &transcript_hash)
bool verify_peer_finished_mac(const Transcript_Hash &transcript_hash, const std::vector< uint8_t > &peer_mac) const
std::string hash_algorithm() const
void deprotect_and_hydrate_content_type(Epoch &epoch, std::span< const uint8_t > header, Record_Content &protected_record, size_t incoming_record_size_limit) const
Cipher_State(const Cipher_State &other)=delete
secure_vector< uint8_t > psk(const Ticket_Nonce &nonce) const
void advance_with_server_hello(const Ciphersuite &cipher, secure_vector< uint8_t > &&shared_secret, const Transcript_Hash &transcript_hash)
bool is_compatible_with(const Ciphersuite &cipher) const
secure_vector< uint8_t > export_key(std::string_view label, std::string_view context, size_t length) const
virtual void advance_write_epoch(const secure_vector< uint8_t > &traffic_secret, bool handshake_epoch=false)=0
bool can_encrypt_application_traffic() const
size_t encrypt_output_length(size_t input_length) const
static std::unique_ptr< Cipher_State > init_with_server_hello(Connection_Side side, TLS_Flavor flavor, secure_vector< uint8_t > &&shared_secret, const Ciphersuite &cipher, const Transcript_Hash &transcript_hash, SecretLoggerFn secret_logger)
std::vector< uint8_t > psk_binder_mac(const Transcript_Hash &transcript_hash_with_truncated_client_hello) const
size_t decrypt_output_length(size_t input_length) const
static void marshall_and_protect(Epoch &epoch, std::span< const uint8_t > header, std::span< const uint8_t > payload, Record_Type type, size_t padding_bytes, secure_vector< uint8_t > &out)
Cipher_State::Epoch create_epoch(Cipher_Dir direction, const secure_vector< uint8_t > &traffic_secret, bool handshake_epoch) const
std::array< uint8_t, 6 > ExpansionLabelPrefix
uint64_t records_decrypted_with_current_key() const
virtual bool has_write_epoch() const =0
std::vector< uint8_t > finished_mac(const Transcript_Hash &transcript_hash) const
virtual Epoch & latest_read_epoch()=0
bool usable_in_version(Protocol_Version version) const
std::string prf_algo() const
std::string cipher_algo() const
secure_vector< uint8_t > take_payload()
std::span< uint8_t, TLS_HEADER_SIZE > header()
Record_Type type() const
static std::array< uint8_t, TLS_HEADER_SIZE > serialize_header(Record_Type type, Protocol_Version legacy_version, uint16_t payload_length)
std::span< const uint8_t > payload() const
Record deprotect_record(Record_TLS record, size_t incoming_record_size_limit)
TLS_Cipher_State(Connection_Side side, std::string_view prf_algo)
void protect_record(Record_Type type, std::span< const uint8_t > payload, size_t padding_bytes, secure_vector< uint8_t > &out)
constexpr T & get() &
Definition strong_type.h:81
std::variant< ChangeCipherSpec_Record, Alert_Record, Handshake_Record, ApplicationData_Record > Record
std::vector< uint8_t > Transcript_Hash
Definition tls_magic.h:105
@ MAX_CIPHERTEXT_SIZE_TLS13
Definition tls_magic.h:47
Strong< std::vector< uint8_t >, struct Ticket_Nonce_ > Ticket_Nonce
Used to derive the ticket's PSK from the resumption_master_secret.
Definition tls_magic.h:108
std::function< void(std::string_view label, std::span< const uint8_t > secret)> SecretLoggerFn
Record annotate_record_type(Record_Content &&record)
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:59
void zap(std::vector< T, Alloc > &vec)
Definition secmem.h:261
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
auto to_underlying(T e) noexcept
Definition stl_util.h:158
constexpr RT checked_cast_to(AT i)
Definition int_utils.h:104
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
constexpr void xor_buf(ranges::contiguous_output_range< uint8_t > auto &&out, ranges::contiguous_range< uint8_t > auto &&in)
Definition mem_ops.h:403
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745
std::unique_ptr< AEAD_Mode > cipher
secure_vector< uint8_t > iv
secure_vector< uint8_t > payload
std::optional< uint64_t > sequence_number