From 7a30d25c33f65b452b6d56ec27997dd0b9dd9118 Mon Sep 17 00:00:00 2001 From: Amos Treiber Date: Mon, 26 Oct 2026 13:21:26 +0000 Subject: [PATCH 1/2] Thread TLS Flavors through TLS 1.3 implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In preparation for DTLS 1.3 (#5000), introduce all flavor-dependent logic that will be in the TLS base files: every place where the base 1.3 implementation must behave differently for DTLS now branches on TLS_Flavor, and the polymorphic layer interfaces (Channel_IO, Handshake_Layer, Record_Layer, Cipher_State) expose the hooks that the DTLS 1.3 implementation will override. The DTLS 1.3 implementation itself is not part of this change: creating a DTLS 1.3 client still throws, and DTLS 1.3 remains disabled via Policy::allow_dtls13() defaulting to false. Concretely: * Channel_Impl_13 takes a Connection_Side and TLS_Flavor; Client and Server select the 1.3 implementation for is_tls_13_or_later() versions and pass the flavor down. Cipher_State::create() and Channel_IO::create() gain (still unreachable) DTLS branches that throw Not_Implemented until the DTLS 1.3 module lands. * Client/Server Hello 1.3 handle the DTLS legacy_version, ciphersuite lists and supported_versions, skip the middlebox compatibility mode and the session ID echo for DTLS; Hello_Retry_Request may carry a Cookie for the DTLS stateless cookie exchange; Encrypted_Extensions negotiates DTLS-SRTP (RFC 5764) and the negotiated SRTP profile is stored in the session. * Channel_IO grows no-op notification hooks for the DTLS ACK and retransmission logic (protocol version committed, complete/final flight received); Record_Layer and Handshake_Layer report ingestion outcomes and support epoch-specific record protection as needed for DTLS. * KeyUpdate handling: Channel_IO::handle_key_update() becomes virtual and subsumes the schedule_read_epoch_pruning() hook, which is removed. The DTLS implementation overrides it to reject KeyUpdates beyond the epoch limit (RFC 9147 8.) and to schedule pruning of superseded read epochs itself; TLS simply updates its read keys. * Downgrade handling: the client preserves epoch-0 sequence numbers for the 1.2 implementation; random_signals_downgrade() moves to the Server_Hello base class. Handling of Hello_Verify_Request as a downgrade trigger to DTLS 1.2 is factored out into a subsequent commit, as it belongs to the DTLS 1.3 implementation itself. * PSK binder calculation handles the DTLS legacy_cookie field and the PSK importer uses the "dtls13" label prefix for DTLS 1.3. * Policy gains allow_dtls13() (default: false). The handling of ACK records (RFC 9147 7.) together with the dtls_maximum_queued_acknowledgements() policy knob is likewise factored out into a subsequent commit, as the DTLS 1.3 implementation is their only consumer. Co-Authored-By: René Meusel --- src/fuzzer/tls_13_handshake_layer.cpp | 13 +- src/lib/tls/msg_client_hello.cpp | 5 +- src/lib/tls/msg_server_hello.cpp | 46 +++-- src/lib/tls/tls13/msg_client_hello_13.cpp | 51 +++-- .../tls/tls13/msg_encrypted_extensions.cpp | 28 ++- src/lib/tls/tls13/msg_server_hello_13.cpp | 184 ++++++++++++------ src/lib/tls/tls13/tls_channel_impl_13.cpp | 34 +++- src/lib/tls/tls13/tls_channel_impl_13.h | 70 ++++--- src/lib/tls/tls13/tls_channel_io.cpp | 26 +-- src/lib/tls/tls13/tls_channel_io.h | 68 ++++++- src/lib/tls/tls13/tls_cipher_state.cpp | 5 + src/lib/tls/tls13/tls_cipher_state.h | 6 + src/lib/tls/tls13/tls_client_impl_13.cpp | 120 +++++++++--- src/lib/tls/tls13/tls_client_impl_13.h | 7 +- src/lib/tls/tls13/tls_connection_state_13.cpp | 15 ++ src/lib/tls/tls13/tls_connection_state_13.h | 3 + src/lib/tls/tls13/tls_extensions_13.h | 6 +- src/lib/tls/tls13/tls_extensions_psk.cpp | 26 ++- src/lib/tls/tls13/tls_handshake_layer_13.cpp | 110 ++++++----- src/lib/tls/tls13/tls_handshake_layer_13.h | 56 ++++-- src/lib/tls/tls13/tls_messages_13.h | 43 ++-- src/lib/tls/tls13/tls_psk_importer_13.cpp | 20 +- src/lib/tls/tls13/tls_record_13.h | 2 + src/lib/tls/tls13/tls_record_layer_13.cpp | 27 ++- src/lib/tls/tls13/tls_record_layer_13.h | 48 +++-- src/lib/tls/tls13/tls_server_impl_13.cpp | 110 ++++++++--- src/lib/tls/tls13/tls_server_impl_13.h | 9 +- src/lib/tls/tls13/tls_transcript_hash_13.cpp | 16 +- src/lib/tls/tls13/tls_types_13.h | 4 + src/lib/tls/tls_channel.h | 10 +- src/lib/tls/tls_channel_impl.h | 5 + src/lib/tls/tls_client.cpp | 12 +- src/lib/tls/tls_messages.h | 10 +- src/lib/tls/tls_policy.cpp | 7 + src/lib/tls/tls_policy.h | 7 + src/lib/tls/tls_server.cpp | 4 +- src/lib/tls/tls_session.cpp | 7 +- src/lib/tls/tls_session.h | 1 + src/lib/tls/tls_text_policy.cpp | 4 + src/lib/tls/tls_version.cpp | 2 + src/tests/test_tls_flight_13.cpp | 2 +- src/tests/test_tls_handshake_layer_13.cpp | 31 +-- src/tests/test_tls_handshake_state_13.cpp | 4 +- src/tests/test_tls_messages.cpp | 2 +- src/tests/test_tls_protocol_version.cpp | 147 ++++++++++++++ src/tests/test_tls_record_layer_13.cpp | 76 ++++---- src/tests/test_tls_rfc8448.cpp | 1 + src/tests/test_tls_session_manager.cpp | 4 + src/tests/unit_tls.cpp | 10 +- 49 files changed, 1113 insertions(+), 391 deletions(-) create mode 100644 src/tests/test_tls_protocol_version.cpp diff --git a/src/fuzzer/tls_13_handshake_layer.cpp b/src/fuzzer/tls_13_handshake_layer.cpp index 2c1d9311b6d..4bf6191b720 100644 --- a/src/fuzzer/tls_13_handshake_layer.cpp +++ b/src/fuzzer/tls_13_handshake_layer.cpp @@ -16,21 +16,20 @@ void fuzz(std::span in) { static const Botan::TLS::Default_Policy policy; const auto in_record = Botan::TLS::Handshake_Record{ - { - .type = Botan::TLS::Record_Type::Handshake, - .sequence_number = std::nullopt, - .payload = {in.begin(), in.end()}, - }, + {.type = Botan::TLS::Record_Type::Handshake, + .sequence_number = std::nullopt, + .payload = {in.begin(), in.end()}, + .epoch = std::nullopt}, }; try { auto hl1 = Botan::TLS::TLS_Handshake_Layer(Botan::TLS::Connection_Side::Client); - hl1.copy_data(policy, in_record); + std::ignore = hl1.copy_data(policy, in_record); Botan::TLS::Transcript_Hash_State transcript_hash(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); while(hl1.next_message(policy, transcript_hash).has_value()) {}; auto hl2 = Botan::TLS::TLS_Handshake_Layer(Botan::TLS::Connection_Side::Client); - hl2.copy_data(policy, in_record); + std::ignore = hl2.copy_data(policy, in_record); while(hl2.next_post_handshake_message(policy).has_value()) {}; } catch(const Botan::Exception& e) {} } diff --git a/src/lib/tls/msg_client_hello.cpp b/src/lib/tls/msg_client_hello.cpp index 032cebe81c9..9ab87b4fe19 100644 --- a/src/lib/tls/msg_client_hello.cpp +++ b/src/lib/tls/msg_client_hello.cpp @@ -124,7 +124,8 @@ Protocol_Version Client_Hello_Internal::version() const { // 0x0303 and a supported_versions extension present with 0x0304 as // the highest version indicated therein. if(!extensions().has() || - !extensions().get()->supports(Protocol_Version::TLS_V13)) { + (!extensions().get()->supports(Protocol_Version::TLS_V13) && + !extensions().get()->supports(Protocol_Version::DTLS_V13))) { // The exact legacy_version is ignored we just inspect it to // distinguish TLS and DTLS. return (m_legacy_version.is_datagram_protocol()) ? Protocol_Version::DTLS_V12 : Protocol_Version::TLS_V12; @@ -132,7 +133,7 @@ Protocol_Version Client_Hello_Internal::version() const { // Note: The Client_Hello_13 class will make sure that legacy_version // is exactly 0x0303 (aka ossified TLS 1.2) - return Protocol_Version::TLS_V13; + return (m_legacy_version.is_datagram_protocol()) ? Protocol_Version::DTLS_V13 : Protocol_Version::TLS_V13; } Client_Hello::Client_Hello(Client_Hello&&) noexcept = default; diff --git a/src/lib/tls/msg_server_hello.cpp b/src/lib/tls/msg_server_hello.cpp index 9bbce00bccf..12215da8576 100644 --- a/src/lib/tls/msg_server_hello.cpp +++ b/src/lib/tls/msg_server_hello.cpp @@ -17,6 +17,7 @@ #include #include #include +#include #include namespace Botan::TLS { @@ -37,8 +38,9 @@ std::vector make_server_hello_random(RandomNumberGenerator& rng, // If negotiating TLS 1.2, TLS 1.3 servers MUST set the last 8 bytes of // their Random value to the bytes: [DOWNGRADE_TLS12] // - // DTLS 1.3 is not implemented, so a DTLS server never sets these. - if(flavor == TLS_Flavor::TLS && offered_version.is_pre_tls_13() && policy.allow_tls13()) { + // DTLS 1.3 servers signal downgrades just as TLS 1.3 servers do. + const bool server_supports_13 = flavor == TLS_Flavor::DTLS ? policy.allow_dtls13() : policy.allow_tls13(); + if(offered_version.is_pre_tls_13() && server_supports_13) { constexpr size_t downgrade_signal_length = sizeof(DOWNGRADE_TLS12); BOTAN_ASSERT_NOMSG(random.size() >= downgrade_signal_length); const auto lastbytes = std::span{random}.last(downgrade_signal_length); @@ -91,7 +93,21 @@ Protocol_Version Server_Hello_Internal::version() const { // // Note: Here we just take a message parsing decision, further validation of // the extension's contents is done later. - return (extensions().has()) ? Protocol_Version::TLS_V13 : m_legacy_version; + if(const auto* sv = extensions().get()) { + const auto versions = sv->versions(); + BOTAN_ASSERT_NOMSG(versions.size() == 1); + const auto v = versions.front(); // May be DTLS_V13 or TLS_V13 + if(!v.is_tls_13_or_later()) { + // RFC 8446 4.2.1 + // If the "supported_versions" extension in the ServerHello contains + // a version [...] prior to TLS 1.3, the client MUST abort the + // handshake with an "illegal_parameter" alert. + throw TLS_Exception(Alert::IllegalParameter, "supported_versions extension contains pre-TLS13 version"); + } + return v; + } + + return m_legacy_version; } Server_Hello::Server_Hello(std::unique_ptr data) : m_data(std::move(data)) {} @@ -156,6 +172,18 @@ const Extensions& Server_Hello::extensions() const { return m_data->extensions(); } +std::optional Server_Hello::random_signals_downgrade() const { + const uint64_t last8 = load_be(m_data->random().data(), 3); + if(last8 == DOWNGRADE_TLS11) { + return Protocol_Version::TLS_V11; + } + if(last8 == DOWNGRADE_TLS12) { + return Protocol_Version::TLS_V12; + } + + return std::nullopt; +} + Server_Hello_12_Shim::Server_Hello_12_Shim(std::span buf) : Server_Hello_12_Shim(std::make_unique(buf)) {} @@ -170,16 +198,4 @@ Protocol_Version Server_Hello_12_Shim::selected_version() const { return legacy_version(); } -std::optional Server_Hello_12_Shim::random_signals_downgrade() const { - const uint64_t last8 = load_be(m_data->random().data(), 3); - if(last8 == DOWNGRADE_TLS11) { - return Protocol_Version::TLS_V11; - } - if(last8 == DOWNGRADE_TLS12) { - return Protocol_Version::TLS_V12; - } - - return std::nullopt; -} - } // namespace Botan::TLS diff --git a/src/lib/tls/tls13/msg_client_hello_13.cpp b/src/lib/tls/tls13/msg_client_hello_13.cpp index 1b2689d7445..4d4afff9f65 100644 --- a/src/lib/tls/tls13/msg_client_hello_13.cpp +++ b/src/lib/tls/tls13/msg_client_hello_13.cpp @@ -164,24 +164,41 @@ Client_Hello_13::Client_Hello_13(const Policy& policy, // "supported_versions" extension (Section 4.2.1) and the // legacy_version field MUST be set to 0x0303, which is the version // number for TLS 1.2. - m_data->m_legacy_version = Protocol_Version::TLS_V12; + // RFC 9147 5.3 + // In DTLS 1.3, the client indicates its version preferences in the + // "supported_versions" extension (see Section 4.2.1 of [TLS13]) and + // the legacy_version field MUST be set to {254, 253} [...] + m_data->m_legacy_version = flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V12 : Protocol_Version::TLS_V12; m_data->m_random = make_hello_random(rng, cb, policy); m_data->m_suites = policy.ciphersuite_list(Protocol_Version::TLS_V13); - if(policy.allow_tls12()) { - // Note: DTLS 1.3 is NYI, hence dtls_12 is not checked + // When (D)TLS 1.2 is also allowed, advertise its ciphersuites so a legacy + // peer can select one and trigger a downgrade to Client_Impl_12. + if(flavor == TLS_Flavor::DTLS) { + if(policy.allow_dtls12()) { + const auto legacy_suites = policy.ciphersuite_list(Protocol_Version::DTLS_V12); + m_data->m_suites.insert(m_data->m_suites.end(), legacy_suites.cbegin(), legacy_suites.cend()); + } + } else if(policy.allow_tls12()) { const auto legacy_suites = policy.ciphersuite_list(Protocol_Version::TLS_V12); m_data->m_suites.insert(m_data->m_suites.end(), legacy_suites.cbegin(), legacy_suites.cend()); } - if(policy.tls_13_middlebox_compatibility_mode()) { + // RFC 9147 5. + // DTLS implementations do not use the TLS 1.3 "compatibility mode" [...]. + // + // RFC 9147 5.3 + // A client which has a cached session ID set by a pre-DTLS 1.3 server + // SHOULD set this field to that value. Otherwise, it MUST be set as a + // zero-length vector [...]. + // + // Note: we won't ever offer a (D)TLS 1.2 session. In such a case we would + // have instantiated a (D)TLS 1.2 client in the first place. + if(policy.tls_13_middlebox_compatibility_mode() && flavor != TLS_Flavor::DTLS) { // RFC 8446 4.1.2 // In compatibility mode (see Appendix D.4), this field MUST be non-empty, // so a client not offering a pre-TLS 1.3 session MUST generate a new // 32-byte value. - // - // Note: we won't ever offer a TLS 1.2 session. In such a case we would - // have instantiated a TLS 1.2 client in the first place. m_data->m_session_id = Session_ID(make_hello_random(rng, cb, policy)); } @@ -200,7 +217,8 @@ Client_Hello_13::Client_Hello_13(const Policy& policy, m_data->extensions().add(new Key_Share(policy, cb, rng)); - m_data->extensions().add(new Supported_Versions(Protocol_Version::TLS_V13, policy)); + m_data->extensions().add(new Supported_Versions( + flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V13 : Protocol_Version::TLS_V13, policy)); m_data->extensions().add(new Signature_Algorithms(policy.acceptable_signature_schemes())); if(auto cert_signing_prefs = policy.acceptable_certificate_signature_schemes()) { @@ -220,9 +238,10 @@ Client_Hello_13::Client_Hello_13(const Policy& policy, } // We currently support "record_size_limit" for TLS 1.3 exclusively. Hence, - // when TLS 1.2 is advertised as a supported protocol, we must not offer this + // when (D)TLS 1.2 is advertised as a supported protocol, we must not offer this // extension. - if(policy.record_size_limit().has_value() && !policy.allow_tls12()) { + const bool offers_pre_tls_13 = (flavor == TLS_Flavor::DTLS) ? policy.allow_dtls12() : policy.allow_tls12(); + if(policy.record_size_limit().has_value() && !offers_pre_tls_13) { m_data->extensions().add(new Record_Size_Limit(policy.record_size_limit().value())); } @@ -232,7 +251,7 @@ Client_Hello_13::Client_Hello_13(const Policy& policy, * support is disabled. Otherwise a peer might reply with a 1.2 server hello + a certificate_type * extension indicating it wishes to use RPK, which would lead to errors later. */ - if(!policy.allow_tls12()) { + if(!offers_pre_tls_13) { m_data->extensions().add(new Client_Certificate_Type(policy.accepted_client_certificate_types())); m_data->extensions().add(new Server_Certificate_Type(policy.accepted_server_certificate_types())); } @@ -241,12 +260,16 @@ Client_Hello_13::Client_Hello_13(const Policy& policy, m_data->extensions().add(new Application_Layer_Protocol_Notification(std::move(next_protocols))); } + if(flavor == TLS_Flavor::DTLS) { + m_data->extensions().add(new SRTP_Protection_Profiles(policy.srtp_profiles())); + } + #if defined(BOTAN_HAS_TLS_12) - if(policy.allow_tls12()) { + if(offers_pre_tls_13) { m_data->extensions().add(new Renegotiation_Extension()); m_data->extensions().add(new Session_Ticket_Extension()); - // EMS must always be used with TLS 1.2, regardless of the policy + // EMS must always be used with (D)TLS 1.2, regardless of the policy m_data->extensions().add(new Extended_Master_Secret); if(policy.negotiate_encrypt_then_mac()) { @@ -261,7 +284,7 @@ Client_Hello_13::Client_Hello_13(const Policy& policy, #endif if(session.has_value() || !psks.empty()) { - m_data->extensions().add(new PSK(session, std::move(psks), cb)); + m_data->extensions().add(new PSK(session, std::move(psks), cb, flavor)); } // NOLINTEND(*-owning-memory) diff --git a/src/lib/tls/tls13/msg_encrypted_extensions.cpp b/src/lib/tls/tls13/msg_encrypted_extensions.cpp index 33aab99ea0f..e5e1f50aced 100644 --- a/src/lib/tls/tls13/msg_encrypted_extensions.cpp +++ b/src/lib/tls/tls13/msg_encrypted_extensions.cpp @@ -21,7 +21,8 @@ Encrypted_Extensions::Encrypted_Extensions(const Client_Hello_13& client_hello, const Policy& policy, Callbacks& cb, bool is_resumption, - bool requesting_client_auth) { + bool requesting_client_auth, + TLS_Flavor flavor) { const auto& exts = client_hello.extensions(); // NOLINTBEGIN(*-owning-memory) @@ -109,10 +110,29 @@ Encrypted_Extensions::Encrypted_Extensions(const Client_Hello_13& client_hello, } } - // NOLINTEND(*-owning-memory) + // DTLS-SRTP is not defined for plain TLS, hence the "use_srtp" extension + // is only negotiated on datagram connections and silently ignored otherwise. + if(const auto* client_srtp = exts.get(); + client_srtp != nullptr && flavor == TLS_Flavor::DTLS) { + const auto& server_profiles = policy.srtp_profiles(); + const auto& client_profiles = client_srtp->profiles(); + + // RFC 5764 4.1.1 + // The extension_data field MUST contain a UseSRTPData value with a + // single SRTPProtectionProfile value that the server has chosen for + // use with this connection. [...] If there is no shared profile, + // the server SHOULD NOT return the use_srtp extension [...]. + // + // We're always using the server preference. + for(const auto profile : server_profiles) { + if(profile != 0 && value_exists(client_profiles, profile)) { + m_extensions.add(new SRTP_Protection_Profiles(profile)); + break; + } + } + } - // TODO: Implement handling for (at least) - // * SRTP + // NOLINTEND(*-owning-memory) cb.tls_modify_extensions(m_extensions, Connection_Side::Server, type()); diff --git a/src/lib/tls/tls13/msg_server_hello_13.cpp b/src/lib/tls/tls13/msg_server_hello_13.cpp index b0b54f7ecc5..932eaee7796 100644 --- a/src/lib/tls/tls13/msg_server_hello_13.cpp +++ b/src/lib/tls/tls13/msg_server_hello_13.cpp @@ -10,6 +10,7 @@ #include +#include #include #include #include @@ -31,7 +32,8 @@ std::variant Server_Hello_13::create(const Credentials_Manager& credentials_mgr, RandomNumberGenerator& rng, const Policy& policy, - Callbacks& cb) { + Callbacks& cb, + TLS_Flavor flavor) { const auto& exts = ch.extensions(); // RFC 8446 4.2.9 @@ -68,23 +70,32 @@ std::variant Server_Hello_13::create(const // ClientHello does not contain sufficient information to proceed with // the handshake. // - // In this case, the Client Hello did not contain a key share offer for - // the group selected by the application. - if(!value_exists(offered_by_client, selected_group)) { - // RFC 8446 4.1.4 - // If a client receives a second HelloRetryRequest in the same - // connection (i.e., where the ClientHello was itself in response to a - // HelloRetryRequest), it MUST abort the handshake with an - // "unexpected_message" alert. - BOTAN_STATE_CHECK(hello_retry_request_allowed); - return Hello_Retry_Request(ch, selected_group, policy, cb); + // Hence, we need a HelloRetryRequest if the client did not offer an + // acceptable key share. + const bool hrr_for_key_exchange = !value_exists(offered_by_client, selected_group); + + // RFC 9147 5.1 + // Datagram security protocols are extremely susceptible to a variety of + // DoS attacks [...]. In order to counter [two] of these attacks, DTLS + // borrows the stateless cookie technique used by Photuris and IKE. [...] + // The HelloRetryRequest message contains a stateless cookie [...]. This + // mechanism forces the attacker/client to be able to receive the cookie, + // which makes DoS attacks with spoofed IP addresses difficult. + // + // Hence, we enforce HelloRetryRequest if we're running DTLS and DoS + // protection is required by the policy. + const bool hrr_for_cookie = flavor == TLS_Flavor::DTLS && // + policy.dtls_server_require_cookie_exchange(); + + if(hello_retry_request_allowed && (hrr_for_cookie || hrr_for_key_exchange)) { + return Hello_Retry_Request(ch, selected_group, policy, credentials_mgr, cb, flavor); } else { - return Server_Hello_13(ch, selected_group, session_mgr, credentials_mgr, rng, cb, policy); + return Server_Hello_13(ch, selected_group, session_mgr, credentials_mgr, rng, cb, policy, flavor); } } std::variant Server_Hello_13::parse( - std::span buf) { + std::span buf, TLS_Flavor flavor) { auto data = std::make_unique(buf); // RFC 8446 4.1.3 @@ -94,7 +105,7 @@ std::variant Server_ // // Hello_Retry_Request validates that it selects TLS 1.3 if(data->is_hello_retry_request()) { - return Hello_Retry_Request(std::move(data)); + return Hello_Retry_Request(std::move(data), flavor); } const auto version = data->version(); @@ -103,8 +114,8 @@ std::variant Server_ return Server_Hello_12_Shim(std::move(data)); } - if(version == Protocol_Version::TLS_V13) { - return Server_Hello_13(std::move(data)); + if(version.is_tls_13_or_later()) { + return Server_Hello_13(std::move(data), flavor); } throw TLS_Exception(Alert::ProtocolVersion, "unexpected server hello version: " + version.to_string()); @@ -126,7 +137,7 @@ Alert::Type disallowed_extension_alert(const Extensions& exts, const std::set data, + TLS_Flavor flavor, Server_Hello_13::Server_Hello_Tag /*tag*/) : Server_Hello(std::move(data)) { BOTAN_ASSERT_NOMSG(!m_data->is_hello_retry_request()); - basic_validation(); + basic_validation(flavor); const auto& exts = extensions(); @@ -209,10 +230,11 @@ Server_Hello_13::Server_Hello_13(std::unique_ptr data, } Server_Hello_13::Server_Hello_13(std::unique_ptr data, + TLS_Flavor flavor, Server_Hello_13::Hello_Retry_Request_Tag /*tag*/) : Server_Hello(std::move(data)) { BOTAN_ASSERT_NOMSG(m_data->is_hello_retry_request()); - basic_validation(); + basic_validation(flavor); const auto& exts = extensions(); @@ -248,10 +270,10 @@ Server_Hello_13::Server_Hello_13(std::unique_ptr data, namespace { -uint16_t choose_ciphersuite(const Client_Hello_13& ch, const Policy& policy) { +uint16_t choose_ciphersuite(const Client_Hello_13& ch, const Policy& policy, TLS_Flavor flavor) { auto pref_list = ch.ciphersuites(); - // TODO: DTLS might need to make this version dynamic - auto other_list = policy.ciphersuite_list(Protocol_Version::TLS_V13); + const auto version = flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V13 : Protocol_Version::TLS_V13; + auto other_list = policy.ciphersuite_list(version); if(policy.server_uses_own_ciphersuite_preferences()) { std::swap(pref_list, other_list); @@ -298,12 +320,25 @@ Server_Hello_13::Server_Hello_13(const Client_Hello_13& ch, Credentials_Manager& credentials_mgr, RandomNumberGenerator& rng, Callbacks& cb, - const Policy& policy) : + const Policy& policy, + TLS_Flavor flavor) : Server_Hello(std::make_unique( - Protocol_Version::TLS_V12, - ch.session_id(), - make_server_hello_random(rng, Protocol_Version::TLS_V13, cb, policy, TLS_Flavor::TLS), - choose_ciphersuite(ch, policy), + flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V12 /* legacy version */ + : Protocol_Version::TLS_V12, + // RFC 9846 4.2.3 + // legacy_session_id_echo: The contents of the client's + // legacy_session_id field. + // + // RFC 9147 5. + // DTLS servers MUST NOT echo the "legacy_session_id" value from the + // client [...]. + flavor == TLS_Flavor::TLS ? ch.session_id() : Session_ID{}, + make_server_hello_random(rng, + flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V13 : Protocol_Version::TLS_V13, + cb, + policy, + flavor), + choose_ciphersuite(ch, policy, flavor), uint8_t(0) /* compression method */ )) { // RFC 8446 4.2.1 @@ -314,7 +349,8 @@ Server_Hello_13::Server_Hello_13(const Client_Hello_13& ch, // // Note that the legacy version (TLS 1.2) is set in this constructor's // initializer list, accordingly. - m_data->extensions().add(new Supported_Versions(Protocol_Version::TLS_V13)); // NOLINT(*-owning-memory) + const auto version = flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V13 : Protocol_Version::TLS_V13; + m_data->extensions().add(new Supported_Versions(version)); // NOLINT(*-owning-memory) if(key_exchange_group.has_value()) { BOTAN_ASSERT_NOMSG(ch.extensions().has()); @@ -361,18 +397,6 @@ void Server_Hello_13::decline_psk() { m_data->extensions().remove_extension(Extension_Code::PresharedKey); } -std::optional Server_Hello_13::random_signals_downgrade() const { - const uint64_t last8 = load_be(m_data->random().data(), 3); - if(last8 == DOWNGRADE_TLS11) { - return Protocol_Version::TLS_V11; - } - if(last8 == DOWNGRADE_TLS12) { - return Protocol_Version::TLS_V12; - } - - return std::nullopt; -} - Protocol_Version Server_Hello_13::selected_version() const { const auto* const versions_ext = m_data->extensions().get(); BOTAN_ASSERT_NOMSG(versions_ext); @@ -381,18 +405,24 @@ Protocol_Version Server_Hello_13::selected_version() const { return versions.front(); } -Hello_Retry_Request::Hello_Retry_Request(std::unique_ptr data) : - Server_Hello_13(std::move(data), Server_Hello_13::as_hello_retry_request) {} +Hello_Retry_Request::Hello_Retry_Request(std::unique_ptr data, TLS_Flavor flavor) : + Server_Hello_13(std::move(data), flavor, Server_Hello_13::as_hello_retry_request) {} Hello_Retry_Request::Hello_Retry_Request(const Client_Hello_13& ch, Named_Group selected_group, const Policy& policy, - Callbacks& cb) : + Credentials_Manager& credentials_manager, + Callbacks& cb, + TLS_Flavor flavor) : Server_Hello_13(std::make_unique( - Protocol_Version::TLS_V12 /* legacy_version */, - ch.session_id(), + flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V12 /* legacy_version */ + : Protocol_Version::TLS_V12, + // RFC 9147 5. + // DTLS servers MUST NOT echo the "legacy_session_id" value from the + // client [...]. + flavor == TLS_Flavor::DTLS ? Session_ID{} : ch.session_id(), std::vector(HELLO_RETRY_REQUEST_MARKER.begin(), HELLO_RETRY_REQUEST_MARKER.end()), - choose_ciphersuite(ch, policy), + choose_ciphersuite(ch, policy, flavor), uint8_t(0) /* compression method */, true /* is Hello Retry Request */ ), @@ -405,8 +435,6 @@ Hello_Retry_Request::Hello_Retry_Request(const Client_Hello_13& ch, BOTAN_STATE_CHECK(ch.extensions().has()); BOTAN_STATE_CHECK(ch.extensions().has()); - BOTAN_STATE_CHECK(!value_exists(ch.extensions().get()->offered_groups(), selected_group)); - // RFC 8446 4.1.4 // The server's extensions MUST contain "supported_versions". // @@ -416,19 +444,63 @@ Hello_Retry_Request::Hello_Retry_Request(const Client_Hello_13& ch, // value (0x0304). It MUST set the ServerHello.legacy_version field to // 0x0303 (TLS 1.2). // - // Note that the legacy version (TLS 1.2) is set in this constructor's + // Note that the legacy version ((D)TLS 1.2) is set in this constructor's // initializer list, accordingly. // NOLINTBEGIN(*-owning-memory) - m_data->extensions().add(new Supported_Versions(Protocol_Version::TLS_V13)); + const auto version = flavor == TLS_Flavor::DTLS ? Protocol_Version::DTLS_V13 : Protocol_Version::TLS_V13; + m_data->extensions().add(new Supported_Versions(version)); + + // RFC 9846 4.2.4 + // The server's [HelloRetryRequest] extensions SHOULD contain the minimal + // set of extensions necessary for the client to generate a correct + // ClientHello pair. + // + // I.e., if the client already offered a key share for our preferred group, + // we don't need to request a new key share for this particular group. + if(!value_exists(ch.extensions().get()->offered_groups(), selected_group)) { + m_data->extensions().add(new Key_Share(selected_group)); + } + + // RFC 9846 4.2.4 + // A HelloRetryRequest MUST NOT contain any extensions that were not first + // offered by the client in its ClientHello, with the exception of + // optionally the "cookie" [...] extension. + // + // RFC 9147 5.1 + // In order to counter [some DoS attacks], DTLS borrows the stateless + // cookie technique used by Photuris and IKE. [...] DTLS 1.3 reuses the + // HelloRetryRequest message and conveys the cookie to the client via an + // extension. + if(flavor == TLS_Flavor::DTLS && policy.dtls_server_require_cookie_exchange()) { + const std::string client_identity = cb.tls_peer_network_identity(); + if(client_identity.empty()) { + // RFC 9147 Section 11 + // Some key properties required of the cookie for the cookie-exchange + // mechanism to be functional [...]: + // - The cookie MUST depend on the client's address. + // + // Without an application-supplied identity the cookie is reusable from + // any source address, defeating the whole point of the cookie exchange. + // + // TODO(Botan4): Remove the version hint about the breaking change. + throw Invalid_State( + "Since Botan 3.13 DTLS server requires tls_peer_network_identity() return a non-empty value"); + } + + m_data->extensions().add(new Cookie( + calculate_cookie(ch.cookie_input_data(), client_identity, credentials_manager.dtls_cookie_secret()))); + } - m_data->extensions().add(new Key_Share(selected_group)); // NOLINTEND(*-owning-memory) cb.tls_modify_extensions(m_data->extensions(), Connection_Side::Server, type()); - if(!m_data->extensions().has()) { - throw TLS_Exception(Alert::InternalError, - "Application tls_modify_extensions callback removed Key_Share from the HelloRetryRequest"); + // Note: This error condition could also indicate some other internal + // issue, e.g., a faulty use of the Hello_Retry_Request constructor. + if(!m_data->extensions().has() && !m_data->extensions().has()) { + throw TLS_Exception( + Alert::InternalError, + "Application tls_modify_extensions callback removed Key_Share or Cookie from the HelloRetryRequest"); } } diff --git a/src/lib/tls/tls13/tls_channel_impl_13.cpp b/src/lib/tls/tls13/tls_channel_impl_13.cpp index c585d2c4362..3b5124a05cc 100644 --- a/src/lib/tls/tls13/tls_channel_impl_13.cpp +++ b/src/lib/tls/tls13/tls_channel_impl_13.cpp @@ -45,10 +45,12 @@ Channel_Impl_13::Channel_Impl_13(const std::shared_ptr& callbacks, const std::shared_ptr& credentials_manager, const std::shared_ptr& rng, const std::shared_ptr& policy, - bool is_server) : - m_side(is_server ? Connection_Side::Server : Connection_Side::Client), - m_transcript_hash(TLS_Flavor::TLS), - m_channel_io(Channel_IO::create(m_side, TLS_Flavor::TLS, policy, callbacks)), + Connection_Side connection_side, + TLS_Flavor flavor) : + m_side(connection_side), + m_flavor(flavor), + m_transcript_hash(flavor), + m_channel_io(Channel_IO::create(m_side, m_flavor, policy, callbacks)), m_callbacks(callbacks), m_session_manager(session_manager), m_credentials_manager(credentials_manager), @@ -212,6 +214,26 @@ void Channel_Impl_13::update_traffic_keys(bool request_peer_update) { m_channel_io->update_traffic_keys(request_peer_update); } +bool Channel_Impl_13::timeout_check() { + if(!is_datagram()) { + return false; + } + + throw Not_Implemented( + "timeout_check() is not implemented for DTLS 1.3, please implement " + "TLS::Callbacks::tls_register_deferred_operation() instead"); +} + +std::optional Channel_Impl_13::next_retransmission_timeout() const { + if(!is_datagram()) { + return std::nullopt; + } + + throw Not_Implemented( + "next_retransmission_timeout() is not implemented for DTLS 1.3, please " + "implement TLS::Callbacks::tls_register_deferred_operation() instead"); +} + SecretLoggerFn Channel_Impl_13::secret_logger() const { return [weak = weak_from_this()](std::string_view label, std::span secret) { if(const auto self = dynamic_pointer_cast(weak.lock())) { @@ -367,9 +389,9 @@ void Channel_Impl_13::expect_downgrade(const Server_Information& server_info, m_credentials_manager, m_rng, m_policy, - TLS_Flavor::TLS, + is_datagram() ? TLS_Flavor::DTLS : TLS_Flavor::TLS, false, // received_tls_13_error_alert - false // will_downgrade + false, // will_downgrade }; m_downgrade_info = std::make_unique(std::move(di)); } diff --git a/src/lib/tls/tls13/tls_channel_impl_13.h b/src/lib/tls/tls13/tls_channel_impl_13.h index abb41d6f159..6db52777b40 100644 --- a/src/lib/tls/tls13/tls_channel_impl_13.h +++ b/src/lib/tls/tls13/tls_channel_impl_13.h @@ -20,15 +20,16 @@ namespace Botan::TLS { class Cipher_State; +class Transcript_Hash_State; class Channel_IO; /** * Generic interface for TLS 1.3 endpoint */ class Channel_Impl_13 : public Channel_Impl { - public: + protected: /** - * Set up a new TLS 1.3 session + * Set up a new (D)TLS 1.3 session * * @param callbacks contains a set of callback function references * required by the TLS endpoint. @@ -36,15 +37,18 @@ class Channel_Impl_13 : public Channel_Impl { * @param credentials_manager manages application/user credentials * @param rng a random number generator * @param policy specifies other connection policy information - * @param is_server whether this is a server session or not + * @param connection_side whether this is a client or server session + * @param flavor whether TLS1.3 or DTLS1.3 is used */ explicit Channel_Impl_13(const std::shared_ptr& callbacks, const std::shared_ptr& session_manager, const std::shared_ptr& credentials_manager, const std::shared_ptr& rng, const std::shared_ptr& policy, - bool is_server); + Connection_Side connection_side, + TLS_Flavor flavor); + public: Channel_Impl_13(const Channel_Impl_13& other) = delete; Channel_Impl_13(Channel_Impl_13&& other) = delete; Channel_Impl_13& operator=(const Channel_Impl_13& other) = delete; @@ -115,23 +119,30 @@ class Channel_Impl_13 : public Channel_Impl { } /** - * Perform a handshake timeout check. This does nothing unless - * this is a DTLS channel with a pending handshake state, in - * which case we check for timeout and potentially retransmit - * handshake packets. - * - * In the TLS 1.3 implementation, this always returns false. + * Perform a handshake timeout check that the user can call. This is no + * longer relevant for DTLS 1.3. + * @throws for DTLS 1.3, since the callback mechanism + * tls_register_deferred_operation() shall be used instead of + * timeout_check. + * @returns false for TLS 1.3 */ - bool timeout_check() override { return false; } + bool timeout_check() override; - protected: /** - * Hands ownership of the channel's cipher state to this channel and its - * associated Channel_IO. Typically called once the handshake's key - * schedule produced the first traffic secrets. - * - * @return a reference to the handed-off cipher state for convenience - */ + * Tells the user when to call Channel::timeout_check() next. This is no + * longer relevant for DTLS 1.3. + * @throws for DTLS 1.3, since the callback mechanism + * tls_register_deferred_operation() shall be used instead of + * timeout_check. + * @returns std::nullopt for TLS 1.3 + */ + std::optional next_retransmission_timeout() const override; + + const Cipher_State* cipher_state() const { return m_cipher_state.get(); } + + Cipher_State* cipher_state() { return m_cipher_state.get(); } + + protected: Cipher_State& setup_cipher_state(std::unique_ptr cipher_state); virtual void process_handshake_msg(Handshake_Message_13 msg) = 0; @@ -155,6 +166,8 @@ class Channel_Impl_13 : public Channel_Impl { SecretLoggerFn secret_logger() const; + bool is_datagram() const { return m_flavor == TLS_Flavor::DTLS; } + void send_flight(std::vector flight); private: @@ -171,14 +184,6 @@ class Channel_Impl_13 : public Channel_Impl { void shutdown(); protected: - const Connection_Side m_side; // NOLINT(*non-private-member-variable*) - std::optional m_transcript_hash; // NOLINT(*non-private-member-variable*) - std::shared_ptr m_cipher_state; // NOLINT(*non-private-member-variable*) - std::optional m_active_state; // NOLINT(*non-private-member-variable*) - - /* I/O handling */ - std::shared_ptr m_channel_io; // NOLINT(*non-private-member-variable*) - #if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT) /** * Indicate that we have to expect a downgrade to TLS 1.2. In which case the current @@ -210,6 +215,18 @@ class Channel_Impl_13 : public Channel_Impl { */ void set_selected_certificate_type(Certificate_Type cert_type); + protected: + /* basic channel information */ + const Connection_Side m_side; // NOLINT(*non-private-member-variable*) + TLS_Flavor m_flavor; // NOLINT(*non-private-member-variable*) + + /* handshake state */ + std::optional m_transcript_hash; // NOLINT(*non-private-member-variable*) + std::optional m_active_state; // NOLINT(*non-private-member-variable*) + + /* I/O handling */ + std::shared_ptr m_channel_io; // NOLINT(*non-private-member-variable*) + private: /* callbacks */ std::shared_ptr m_callbacks; @@ -219,6 +236,7 @@ class Channel_Impl_13 : public Channel_Impl { std::shared_ptr m_credentials_manager; std::shared_ptr m_rng; std::shared_ptr m_policy; + std::shared_ptr m_cipher_state; bool m_can_read; bool m_can_write; diff --git a/src/lib/tls/tls13/tls_channel_io.cpp b/src/lib/tls/tls13/tls_channel_io.cpp index 1f69ef90925..42dd6732024 100644 --- a/src/lib/tls/tls13/tls_channel_io.cpp +++ b/src/lib/tls/tls13/tls_channel_io.cpp @@ -93,7 +93,10 @@ void Channel_IO::copy_data(std::span data) { return; } - record_layer().copy_data(data); + const auto cs = cipher_state(); + const auto has_cryptographic_association = (cs != nullptr) && cs->has_cryptographic_association(); + + record_layer().copy_data(data, has_cryptographic_association); } Channel_IO::ReceiveEvent Channel_IO::next_pending_event(std::optional& transcript_hash, @@ -241,7 +244,7 @@ void Channel_IO::handle_key_update(const Key_Update& key_update) { m_last_peer_key_update_ms = now; } - schedule_read_epoch_pruning(cs->update_read_keys()); + cs->update_read_keys(); if(key_update.expects_reciprocation() && cs->can_encrypt_application_traffic()) { // RFC 9846 4.7.3 @@ -340,6 +343,10 @@ void Channel_IO::set_selected_certificate_type(Certificate_Type cert_type) { handshake_layer().set_selected_certificate_type(cert_type); } +std::optional Channel_IO::epoch0_sequence_numbers() const { + return record_layer().epoch0_sequence_numbers(); +} + std::shared_ptr Channel_IO::cipher_state() const { return m_cipher_state.lock(); } @@ -483,7 +490,9 @@ class TLS_Channel_IO final : public Channel_IO { prepare_and_flush_current_prepared(protect_current_msgs); } - void process(const Handshake_Record& record) override { m_handshake_layer.copy_data(policy(), record); } + void process(const Handshake_Record& record) override { + std::ignore = m_handshake_layer.copy_data(policy(), record); + } Record_Layer& record_layer() override { return m_record_layer; } @@ -497,19 +506,10 @@ class TLS_Channel_IO final : public Channel_IO { void send_key_update(const Key_Update& msg) override { const auto cs = cipher_state(); BOTAN_ASSERT_NONNULL(cs); - - const auto serialized = Handshake_Layer::serialize(msg); - const auto header = TLS_Handshake_Layer::prepare_header(msg.wire_type(), serialized.size()); - - const auto payload = concat>(header, serialized); - - send_data(Record_Type::Handshake, payload, cs.get()); + send_data(Record_Type::Handshake, m_handshake_layer.marshal(msg), cs.get()); cs->update_write_keys(); } - void schedule_read_epoch_pruning(EpochNumber /* latest_epoch */) override { /* don't care */ - } - private: TLS_Record_Layer m_record_layer; TLS_Handshake_Layer m_handshake_layer; diff --git a/src/lib/tls/tls13/tls_channel_io.h b/src/lib/tls/tls13/tls_channel_io.h index 94e8a8ebcf8..b3308004ef0 100644 --- a/src/lib/tls/tls13/tls_channel_io.h +++ b/src/lib/tls/tls13/tls_channel_io.h @@ -1,5 +1,5 @@ /* -* TLS Channel IO +* (D)TLS Channel IO * (C) 2026 Jack Lloyd * 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH * @@ -19,6 +19,7 @@ class Alert; class Record_Layer; class Handshake_Layer; class Cipher_State; +struct RecordNumber; /** * Channel_IO owns the record layer and handshake layer of a (D)TLS 1.3 @@ -85,14 +86,14 @@ class BOTAN_TEST_API Channel_IO { /// @} - /// @name Traffic key updates (RFC 8446 4.6.3) + /// @name Traffic key updates (RFC 8446 4.6.3, RFC 9147 8.) /// @{ /** * Processes a KeyUpdate message received from the peer: updates the read * keys, and schedules a reciprocal KeyUpdate if the peer requested one. */ - void handle_key_update(const Key_Update& key_update); + virtual void handle_key_update(const Key_Update& key_update); /** * Sends a KeyUpdate message to the peer and updates the write keys once @@ -105,6 +106,63 @@ class BOTAN_TEST_API Channel_IO { /// @} + /// @name DTLS-specific state management + /// @{ + + /** + * Notifies that the TLS state machine is sure that we're talking to a + * peer using (D)TLS 1.3. Typically that is the case after receiving and + * processing a ServerHello or a ClientHello indicating support for (D)TLS + * 1.3. + * + * This is relevant for DTLS: before this point, lost records must be + * recovered by retransmitting entire flights (1.2-style); only afterwards + * may the ACK mechanism (RFC 9147 7.) be relied upon. + * + * For the case of receiving a HelloRetryRequest, use + * notify_protocol_version_committed_and_flight_superseded(). + */ + virtual void notify_protocol_version_committed() { /* don't care */ + } + + /** + * Like notify_protocol_version_committed(), but for the case where + * committing message additionally supersedes the flight currently held + * for retransmission. This is the case exactly for a HelloRetryRequest. + * + * This difference is only relevant for DTLS: Since the buffered flight + * (the initial ClientHello) is superseded by the response about to be + * sent, retransmitting it would be wrong. So in addition to committing the + * protocol version, this method also clears the resend buffer and + * retransmission timer. + */ + virtual void notify_protocol_version_committed_and_flight_superseded() { /* don't care */ + } + + /** + * Notifies that the last message completing a flight was received. + * + * This is relevant for DTLS: At that point, everything we need + * was received and the ACK mechanism is no longer needed. + */ + virtual void notify_received_complete_flight() { /* don't care */ + } + + /** + * Notifies that a complete flight was received that expects no response, + * i.e., the final flight of the peer (the client's Finished). + * + * This is relevant for DTLS: since there is no response flight + * that would implicitly acknowledge it, the flight must be acknowledged + * explicitly with an ACK message. + */ + virtual void notify_received_final_flight() { /* don't care */ + } + + std::optional epoch0_sequence_numbers() const; + + /// @} + /** * Notifies that the channel is closed for reading (close_notify received). * The IO can discard any read-side state; no further data will be processed. @@ -146,10 +204,6 @@ class BOTAN_TEST_API Channel_IO { /// write epoch. virtual void send_key_update(const Key_Update& msg) = 0; - /// Gives the IO the opportunity to schedule pruning of superseded read - /// epochs after a key update. Relevant for DTLS only; a no-op for TLS. - virtual void schedule_read_epoch_pruning(EpochNumber latest_epoch) = 0; - virtual Record_Layer& record_layer() = 0; virtual Handshake_Layer& handshake_layer() = 0; diff --git a/src/lib/tls/tls13/tls_cipher_state.cpp b/src/lib/tls/tls13/tls_cipher_state.cpp index 9eb5a5af721..526a0185013 100644 --- a/src/lib/tls/tls13/tls_cipher_state.cpp +++ b/src/lib/tls/tls13/tls_cipher_state.cpp @@ -276,6 +276,10 @@ size_t Cipher_State::minimum_decryption_input_length() const { return latest_read_epoch().cipher->minimum_final_size(); } +bool Cipher_State::has_cryptographic_association() const { + return current_write_epoch_number().is_protected() && current_read_epoch_number().is_protected(); +} + bool Cipher_State::must_expect_unprotected_alert_traffic() const { // Client side: // After successfully receiving a Server Hello we expect servers to send @@ -887,6 +891,7 @@ Record TLS_Cipher_State::deprotect_record(Record_TLS record, size_t incoming_rec .type = Record_Type::Invalid, .sequence_number = m_read_epoch->sequence_number++, .payload = record.take_payload(), + .epoch = std::nullopt, }; deprotect_and_hydrate_content_type(*m_read_epoch, record.header(), result, incoming_record_size_limit); diff --git a/src/lib/tls/tls13/tls_cipher_state.h b/src/lib/tls/tls13/tls_cipher_state.h index 017ee9db1a1..41cf2a1769d 100644 --- a/src/lib/tls/tls13/tls_cipher_state.h +++ b/src/lib/tls/tls13/tls_cipher_state.h @@ -226,6 +226,12 @@ class BOTAN_TEST_API Cipher_State { */ bool is_handshake_complete() const { return m_state == State::Completed; } + /** + * Indicates whether the cipher state has established cryptographic keys + * and is capable of sending/receiving protected records. + */ + bool has_cryptographic_association() const; + /** * Indicates whether unprotected Alert records are to be expected */ diff --git a/src/lib/tls/tls13/tls_client_impl_13.cpp b/src/lib/tls/tls13/tls_client_impl_13.cpp index 2fef10a27c5..bfd88df7f48 100644 --- a/src/lib/tls/tls13/tls_client_impl_13.cpp +++ b/src/lib/tls/tls13/tls_client_impl_13.cpp @@ -17,6 +17,7 @@ #include #include #include +#include #include #include @@ -28,24 +29,32 @@ std::shared_ptr Client_Impl_13::create(const std::shared_ptr& creds, const std::shared_ptr& policy, const std::shared_ptr& rng, + TLS_Flavor flavor, Server_Information server_info, const std::vector& next_protocols) { auto self = std::make_shared( - Private{}, callbacks, session_manager, creds, policy, rng, std::move(server_info)); + Private{}, callbacks, session_manager, creds, policy, rng, flavor, std::move(server_info)); #if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT) - if(policy->allow_tls12()) { + if(self->is_datagram() ? policy->allow_dtls12() : policy->allow_tls12()) { self->expect_downgrade(self->m_info, next_protocols); } #endif + if(!self->expects_downgrade()) { + // If we don't expect to downgrade, we can already enable all DTLS-only + // features (e.g. record ACKing), because we know that we won't ever + // talk to a legacy peer and succeed a handshake. + self->m_channel_io->notify_protocol_version_committed(); + } + if(auto session = self->find_session_for_resumption()) { if(session->session.version().is_tls_13_or_later()) { self->m_handshake->resumed_session = std::move(session); } #if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT) else if(self->expects_downgrade()) { - // If we found a session that was created with TLS 1.2, we downgrade + // If we found a session that was created with (D)TLS 1.2, we downgrade // the implementation right away, before even issuing a Client Hello. self->request_downgrade_for_resumption(std::move(session.value())); return self; @@ -64,7 +73,7 @@ std::shared_ptr Client_Impl_13::create(const std::shared_ptrm_handshake->resumed_session, creds->find_preshared_keys(self->m_info.hostname(), Connection_Side::Client), - TLS_Flavor::TLS))); + flavor))); // RFC 9846 E.4 // [...] If offering early data, the [dummy Change Cipher Spec record] @@ -75,7 +84,14 @@ std::shared_ptr Client_Impl_13::create(const std::shared_ptrsend_flight(flight.commit()); - self->m_handshake->transitions.set_expected_next({Handshake_Type::ServerHello, Handshake_Type::HelloRetryRequest}); + // on a pure TLS connection. + if(self->is_datagram()) { + self->m_handshake->transitions.set_expected_next( + {Handshake_Type::HelloVerifyRequest, Handshake_Type::ServerHello, Handshake_Type::HelloRetryRequest}); + } else { + self->m_handshake->transitions.set_expected_next( + {Handshake_Type::ServerHello, Handshake_Type::HelloRetryRequest}); + } return self; } @@ -232,7 +248,11 @@ void Client_Impl_13::handle(const Server_Hello_12_Shim& server_hello_msg) { throw TLS_Exception(Alert::ProtocolVersion, "Protocol version was not offered"); } - if(policy().tls_13_middlebox_compatibility_mode() && + // RFC 9147 5 + // DTLS implementations do not use the TLS 1.3 "compatibility mode" + // described in Appendix E.4 of [RFC 9846]. DTLS servers MUST NOT echo the + // "legacy_session_id" value from the client [...]. + if(policy().tls_13_middlebox_compatibility_mode() && !is_datagram() && m_handshake->state.client_hello().session_id() == server_hello_msg.session_id()) { // In compatibility mode, the server will reflect the session ID we sent in the client hello. // However, a TLS 1.2 server that wants to downgrade cannot have found the random session ID @@ -242,6 +262,7 @@ void Client_Impl_13::handle(const Server_Hello_12_Shim& server_hello_msg) { } preserve_client_hello(m_handshake->state.take_client_hello()); + preserve_sequence_numbers(m_channel_io->epoch0_sequence_numbers()); request_downgrade(); // After this, no further messages are expected here because this instance will be replaced @@ -252,12 +273,21 @@ void Client_Impl_13::handle(const Server_Hello_12_Shim& server_hello_msg) { namespace { // validate Server_Hello_13 and Hello_Retry_Request -void validate_server_hello_ish(const Client_Hello_13& ch, const Server_Hello_13& sh) { - // RFC 8446 4.1.3 - // A client which receives a legacy_session_id_echo field that does not match what - // it sent in the ClientHello MUST abort the handshake with an "illegal_parameter" alert. - if(ch.session_id() != sh.session_id()) { - throw TLS_Exception(Alert::IllegalParameter, "echoed session id did not match"); +void validate_server_hello_ish(const Client_Hello_13& ch, const Server_Hello_13& sh, TLS_Flavor flavor) { + if(flavor == TLS_Flavor::TLS) { + // RFC 8446 4.1.3 + // A client which receives a legacy_session_id_echo field that does not match what + // it sent in the ClientHello MUST abort the handshake with an "illegal_parameter" alert. + if(ch.session_id() != sh.session_id()) { + throw TLS_Exception(Alert::IllegalParameter, "echoed session id did not match"); + } + } else { + // RFC 9147 5 + // DTLS implementations do not use the TLS 1.3 "compatibility mode" + // [...]. DTLS servers MUST NOT echo the "legacy_session_id" value. + if(!sh.session_id().empty()) { + throw TLS_Exception(Alert::DecodeError, "Unexpected session ID in DTLS ServerHello"); + } } // RFC 8446 4.1.3 @@ -288,7 +318,7 @@ void Client_Impl_13::handle(const Server_Hello_13& sh) { const auto& ch = m_handshake->state.client_hello(); - validate_server_hello_ish(ch, sh); + validate_server_hello_ish(ch, sh, m_flavor); // RFC 8446 4.1.3: TLS 1.3 servers downgrading to TLS 1.2 or below set // the last 8 bytes of ServerHello.random to a magic value so the client @@ -327,6 +357,14 @@ void Client_Impl_13::handle(const Server_Hello_13& sh) { if(hrr.selected_version() != sh.selected_version()) { throw TLS_Exception(Alert::IllegalParameter, "server changed its chosen protocol version"); } + } else { + // We just received a TLS 1.3 ServerHello without ever receiving a + // HelloRetryRequest. Now, we can be sure that our peer uses TLS 1.3. + // + // This is a no-op for TLS; in DTLS this notification drives the + // retransmission state once the peer has committed to the protocol + // version (see Channel_IO::notify_protocol_version_committed()). + m_channel_io->notify_protocol_version_committed(); } auto cipher = Ciphersuite::by_id(sh.ciphersuite()); @@ -381,15 +419,13 @@ void Client_Impl_13::handle(const Server_Hello_13& sh) { new_cipher_state->advance_with_server_hello( cipher.value(), std::move(shared_secret), m_transcript_hash->current()); + // TODO: Early data + return new_cipher_state; } else { m_handshake->resumed_session.reset(); // might have been set if we attempted a resumption - return Cipher_State::init_with_server_hello(m_side, - TLS_Flavor::TLS, - std::move(shared_secret), - cipher.value(), - m_transcript_hash->current(), - secret_logger()); + return Cipher_State::init_with_server_hello( + m_side, m_flavor, std::move(shared_secret), cipher.value(), m_transcript_hash->current(), secret_logger()); } }()); @@ -405,9 +441,16 @@ void Client_Impl_13::handle(const Hello_Retry_Request& hrr) { BOTAN_ASSERT_NONNULL(m_handshake); BOTAN_ASSERT_NOMSG(m_transcript_hash.has_value()); + // We just received a TLS 1.3 HelloRetryRequest. Now, we can be sure that our + // peer uses TLS 1.3. The HRR also supersedes our previous flight. + m_channel_io->notify_protocol_version_committed_and_flight_superseded(); + + // by definition HRR is the "final" message of this flight. + m_channel_io->notify_received_complete_flight(); + auto& ch = m_handshake->state.client_hello(); - validate_server_hello_ish(ch, hrr); + validate_server_hello_ish(ch, hrr, m_flavor); // RFC 8446 4.1.4. // A HelloRetryRequest MUST NOT contain any @@ -494,6 +537,17 @@ void Client_Impl_13::handle(const Encrypted_Extensions& encrypted_extensions_msg } } + if(exts.has()) { + // RFC 5764 4.1.1 + // The server MUST NOT select a value that the client has not offered. + const auto* server_srtp = exts.get(); + const auto* client_srtp = m_handshake->state.client_hello().extensions().get(); + BOTAN_ASSERT_NONNULL(client_srtp); + if(!value_exists(client_srtp->profiles(), server_srtp->profiles().front())) { + throw TLS_Exception(Alert::HandshakeFailure, "Server replied with DTLS-SRTP profile we did not offer"); + } + } + if(exts.has() && m_handshake->state.client_hello().extensions().has()) { // RFC 8449 4. // The record size limit only applies to records sent toward the @@ -688,11 +742,17 @@ void Client_Impl_13::handle(const Finished_13& finished_msg) { BOTAN_ASSERT_NONNULL(m_handshake); BOTAN_ASSERT_NOMSG(m_transcript_hash.has_value()); + // The Server's Finished message is the last handshake message in the flight. + m_channel_io->notify_received_complete_flight(); + + auto* cs = cipher_state(); + BOTAN_ASSERT_NONNULL(cs); + // RFC 8446 4.4.4 // Recipients of Finished messages MUST verify that the contents are // correct and if incorrect MUST terminate the connection with a // "decrypt_error" alert. - if(!finished_msg.verify(*m_cipher_state, m_transcript_hash->previous())) { + if(!finished_msg.verify(*cs, m_transcript_hash->previous())) { throw TLS_Exception(Alert::DecryptError, "Finished message didn't verify"); } @@ -717,7 +777,7 @@ void Client_Impl_13::handle(const Finished_13& finished_msg) { // Derives the secrets for receiving application data but defers // the derivation of sending application data. - m_cipher_state->advance_with_server_finished(m_transcript_hash->current()); + cs->advance_with_server_finished(m_transcript_hash->current()); auto flight = Flight(*m_transcript_hash, callbacks()); @@ -742,12 +802,12 @@ void Client_Impl_13::handle(const Finished_13& finished_msg) { } // send client finished handshake message (still using handshake traffic secrets) - flight.add(m_handshake->state.sending(Finished_13(*m_cipher_state, m_transcript_hash->current()))); + flight.add(m_handshake->state.sending(Finished_13(*cs, m_transcript_hash->current()))); send_flight(flight.commit()); // derives the sending application traffic secrets - m_cipher_state->advance_with_client_finished(m_transcript_hash->current()); + cs->advance_with_client_finished(m_transcript_hash->current()); // TODO: Create a dummy session object and invoke tls_session_established. // Alternatively, consider changing the expectations described in the @@ -809,7 +869,10 @@ void TLS::Client_Impl_13::handle(const New_Session_Ticket_13& new_session_ticket callbacks().tls_examine_extensions( new_session_ticket.extensions(), Connection_Side::Server, Handshake_Type::NewSessionTicket); - const Session session(m_cipher_state->psk(new_session_ticket.nonce()), + auto* cs = cipher_state(); + BOTAN_ASSERT_NONNULL(cs); + + const Session session(cs->psk(new_session_ticket.nonce()), new_session_ticket.early_data_byte_limit(), new_session_ticket.ticket_age_add(), new_session_ticket.lifetime_hint(), @@ -819,6 +882,7 @@ void TLS::Client_Impl_13::handle(const New_Session_Ticket_13& new_session_ticket peer_cert_chain(), peer_raw_public_key(), m_info, + m_active_state->srtp_profile(), callbacks().tls_current_timestamp()); if(callbacks().tls_should_persist_resumption_information(session)) { @@ -877,6 +941,12 @@ std::optional Client_Impl_13::external_psk_identity() const { } bool Client_Impl_13::compat_mode_ccs_requested() const { + // RFC 9147 Section 5 + // DTLS implementations do not use the TLS 1.3 "compatibility mode" [...]. + if(is_datagram()) { + return false; + } + // RFC 9846 E.4 // This "compatibility mode" is partially negotiated: the client can opt // [in] or not [...]. diff --git a/src/lib/tls/tls13/tls_client_impl_13.h b/src/lib/tls/tls13/tls_client_impl_13.h index aba1bc33924..e97fbf8bc3d 100644 --- a/src/lib/tls/tls13/tls_client_impl_13.h +++ b/src/lib/tls/tls13/tls_client_impl_13.h @@ -12,6 +12,7 @@ #include #include +#include #include #include @@ -40,6 +41,8 @@ class Client_Impl_13 final : public Channel_Impl_13 { * * @param rng a random number generator * + * @param flavor Whether to use TLS or DTLS + * * @param server_info is identifying information about the TLS server * * @param next_protocols specifies protocols to advertise with ALPN @@ -49,6 +52,7 @@ class Client_Impl_13 final : public Channel_Impl_13 { const std::shared_ptr& creds, const std::shared_ptr& policy, const std::shared_ptr& rng, + TLS_Flavor flavor, Server_Information server_info = Server_Information(), const std::vector& next_protocols = {}); @@ -58,8 +62,9 @@ class Client_Impl_13 final : public Channel_Impl_13 { const std::shared_ptr& creds, const std::shared_ptr& policy, const std::shared_ptr& rng, + TLS_Flavor flavor, Server_Information server_info = Server_Information()) : - Channel_Impl_13(callbacks, session_manager, creds, rng, policy, false /* is_server */), + Channel_Impl_13(callbacks, session_manager, creds, rng, policy, Connection_Side::Client, flavor), m_info(std::move(server_info)), m_handshake(std::make_unique()) {} diff --git a/src/lib/tls/tls13/tls_connection_state_13.cpp b/src/lib/tls/tls13/tls_connection_state_13.cpp index b732dc23700..8a95dfc6c7a 100644 --- a/src/lib/tls/tls13/tls_connection_state_13.cpp +++ b/src/lib/tls/tls13/tls_connection_state_13.cpp @@ -1,5 +1,6 @@ /* * (C) 2026 Jack Lloyd +* 2026 René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH * * Botan is released under the Simplified BSD License (see license.txt) */ @@ -21,6 +22,19 @@ std::string extract_alpn(const Internal::Handshake_State_13_Base& state) { return {}; } +uint16_t extract_srtp_profile(const Internal::Handshake_State_13_Base& state) { + const auto& eee = state.encrypted_extensions().extensions(); + if(const auto* srtp = eee.get()) { + const auto& profiles = srtp->profiles(); + // The handshake logic guarantees that a negotiated "use_srtp" extension + // carries exactly one protection profile (RFC 5764 4.1.2): the server + // selects a single profile and the client validates the selection. + BOTAN_ASSERT_NOMSG(profiles.size() == 1); + return profiles.front(); + } + return 0; +} + } // namespace Active_Connection_State_13::~Active_Connection_State_13() = default; @@ -36,6 +50,7 @@ Active_Connection_State_13::Active_Connection_State_13(const Internal::Handshake m_version(state.server_hello().selected_version()), m_ciphersuite_code(state.server_hello().ciphersuite()), m_application_protocol(extract_alpn(state)), + m_srtp_profile(extract_srtp_profile(state)), m_peer_certs(std::move(peer_certs)), m_client_random(state.client_hello().random()), m_psk_identity(std::move(psk_identity)), diff --git a/src/lib/tls/tls13/tls_connection_state_13.h b/src/lib/tls/tls13/tls_connection_state_13.h index 6819aaeab10..ed38bd56b3f 100644 --- a/src/lib/tls/tls13/tls_connection_state_13.h +++ b/src/lib/tls/tls13/tls_connection_state_13.h @@ -53,6 +53,8 @@ class Active_Connection_State_13 final { const std::string& application_protocol() const { return m_application_protocol; } + uint16_t srtp_profile() const { return m_srtp_profile; } + const std::vector& peer_certs() const { return m_peer_certs; } const std::vector& client_random() const { return m_client_random; } @@ -69,6 +71,7 @@ class Active_Connection_State_13 final { Protocol_Version m_version; uint16_t m_ciphersuite_code = 0; std::string m_application_protocol; + uint16_t m_srtp_profile = 0; std::vector m_peer_certs; std::vector m_client_random; std::optional m_psk_identity; diff --git a/src/lib/tls/tls13/tls_extensions_13.h b/src/lib/tls/tls13/tls_extensions_13.h index 78a803ac3cc..cc56affb872 100644 --- a/src/lib/tls/tls13/tls_extensions_13.h +++ b/src/lib/tls/tls13/tls_extensions_13.h @@ -179,8 +179,12 @@ class BOTAN_UNSTABLE_API PSK final : public Extension /* NOLINT(*-special-member * @param psks a list of non-resumption PSKs that should be * offered to the server * @param callbacks the application's callbacks + * @param flavor whether TLS or DTLS is used (default: TLS) */ - PSK(std::optional& session_to_resume, std::vector psks, Callbacks& callbacks); + PSK(std::optional& session_to_resume, + std::vector psks, + Callbacks& callbacks, + TLS_Flavor flavor = TLS_Flavor::TLS); ~PSK() override; diff --git a/src/lib/tls/tls13/tls_extensions_psk.cpp b/src/lib/tls/tls13/tls_extensions_psk.cpp index b65055dcc40..98f6dea3400 100644 --- a/src/lib/tls/tls13/tls_extensions_psk.cpp +++ b/src/lib/tls/tls13/tls_extensions_psk.cpp @@ -38,20 +38,24 @@ decltype(auto) calculate_age(std::chrono::system_clock::time_point then, std::ch class Client_PSK { public: - Client_PSK(Session_with_Handle& session_to_resume, std::chrono::system_clock::time_point timestamp) : + Client_PSK(Session_with_Handle& session_to_resume, + std::chrono::system_clock::time_point timestamp, + TLS_Flavor flavor) : Client_PSK(PskIdentity(session_to_resume.handle.opaque_handle(), calculate_age(session_to_resume.session.start_time(), timestamp), session_to_resume.session.session_age_add()), session_to_resume.session.ciphersuite().prf_algo(), session_to_resume.session.extract_master_secret(), - Cipher_State::PSK_Type::Resumption) {} + Cipher_State::PSK_Type::Resumption, + flavor) {} // NOLINTNEXTLINE(*-rvalue-reference-param-not-moved) - explicit Client_PSK(ExternalPSK&& psk) : + explicit Client_PSK(ExternalPSK&& psk, TLS_Flavor flavor) : Client_PSK(PskIdentity(PresharedKeyID(psk.identity())), psk.prf_algo(), psk.extract_master_secret(), - psk.is_imported() ? Cipher_State::PSK_Type::Imported : Cipher_State::PSK_Type::External) {} + psk.is_imported() ? Cipher_State::PSK_Type::Imported : Cipher_State::PSK_Type::External, + flavor) {} Client_PSK(PskIdentity id, std::vector bndr) : m_identity(std::move(id)), m_binder(std::move(bndr)), m_is_resumption(false) {} @@ -59,7 +63,8 @@ class Client_PSK { Client_PSK(PskIdentity id, std::string_view prf_algo, secure_vector&& master_secret, - Cipher_State::PSK_Type psk_type) : + Cipher_State::PSK_Type psk_type, + TLS_Flavor flavor) : m_identity(std::move(id)), // RFC 8446 4.2.11.2 @@ -78,7 +83,7 @@ class Client_PSK { m_binder(HashFunction::create_or_throw(prf_algo)->output_length()), m_is_resumption(psk_type == Cipher_State::PSK_Type::Resumption), m_cipher_state(Cipher_State::init_with_psk( - Connection_Side::Client, TLS_Flavor::TLS, psk_type, std::move(master_secret), prf_algo)) {} + Connection_Side::Client, flavor, psk_type, std::move(master_secret), prf_algo)) {} const PskIdentity& identity() const { return m_identity; } @@ -206,15 +211,18 @@ PSK::PSK(TLS_Data_Reader& reader, uint16_t extension_size, Handshake_Type messag } } -PSK::PSK(std::optional& session_to_resume, std::vector psks, Callbacks& callbacks) { +PSK::PSK(std::optional& session_to_resume, + std::vector psks, + Callbacks& callbacks, + TLS_Flavor flavor) { std::vector cpsk; if(session_to_resume.has_value()) { - cpsk.emplace_back(session_to_resume.value(), callbacks.tls_current_timestamp()); + cpsk.emplace_back(session_to_resume.value(), callbacks.tls_current_timestamp(), flavor); } for(auto&& psk : psks) { - cpsk.emplace_back(std::move(psk)); + cpsk.emplace_back(std::move(psk), flavor); } m_impl = std::make_unique(std::move(cpsk)); diff --git a/src/lib/tls/tls13/tls_handshake_layer_13.cpp b/src/lib/tls/tls13/tls_handshake_layer_13.cpp index 1682c015f14..5d03b994460 100644 --- a/src/lib/tls/tls13/tls_handshake_layer_13.cpp +++ b/src/lib/tls/tls13/tls_handshake_layer_13.cpp @@ -11,7 +11,6 @@ #include #include #include -#include #include #include #include @@ -25,6 +24,13 @@ namespace { constexpr size_t HEADER_LENGTH = 4; +void verify_handshake_message_size(size_t msg_len, size_t max_size) { + if(max_size > 0 && msg_len > max_size) { + throw TLS_Exception(Alert::HandshakeFailure, + Botan::fmt("Handshake message is {} bytes, policy maximum is {}", msg_len, max_size)); + } +} + } // namespace Handshake_Message_13 Handshake_Layer::parse_handshake_message(Handshake_Type type, @@ -39,7 +45,7 @@ Handshake_Message_13 Handshake_Layer::parse_handshake_message(Handshake_Type typ case Handshake_Type::ServerHello: // ... might be TLS 1.2 Server Hello or TLS 1.3 Server Hello or // a TLS 1.3 Hello Retry Request disguising as a Server Hello - return generalize_to(Server_Hello_13::parse(msg)); + return generalize_to(Server_Hello_13::parse(msg, tls_flavor())); // case Handshake_Type::EndOfEarlyData: // return End_Of_Early_Data(msg); case Handshake_Type::EncryptedExtensions: @@ -75,7 +81,7 @@ void Handshake_Layer::update_transcript_for_psk_binder_calc(const Client_Hello_1 transcript_hash.update(TLS_Handshake_Layer::prepare_header(message.wire_type(), msg_bytes.size()), msg_bytes); } -Handshake_Type Handshake_Layer::read_handshake_message_type(uint8_t value, Handshake_Phase phase) { +Handshake_Type Handshake_Layer::read_handshake_message_type(uint8_t value, Handshake_Phase phase) const { const auto type = static_cast(value); switch(type) { @@ -134,7 +140,13 @@ HandshakeProtocolHeader TLS_Handshake_Layer::prepare_header(Handshake_Type type, return header; } -void TLS_Handshake_Layer::copy_data(const Policy& policy, const Handshake_Record& data_from_peer) { +MarshalledHandshakeMessage TLS_Handshake_Layer::marshal(const Handshake_Message& message) { + const auto bytes = serialize(message); + return concat(prepare_header(message.wire_type(), bytes.size()), bytes); +} + +TLS_Handshake_Layer::CopyDataResult TLS_Handshake_Layer::copy_data(const Policy& policy, + const Handshake_Record& data_from_peer) { BOTAN_UNUSED(policy); // Compact consumed data before appending new data @@ -145,72 +157,78 @@ void TLS_Handshake_Layer::copy_data(const Policy& policy, const Handshake_Record } m_read_buffer.insert(m_read_buffer.end(), data_from_peer.payload.begin(), data_from_peer.payload.end()); + return CopyDataResult::Consumed; } -std::optional TLS_Handshake_Layer::next_incoming_message(const Policy& policy, - Handshake_Phase phase) { - BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); - - // prepare reading from the current read offset - auto bs = BufferSlicer(std::span{m_read_buffer}.subspan(m_read_offset)); - +std::optional TLS_Handshake_Layer::next_message_buffer( + std::span bytes, const Policy& policy, Handshake_Phase phase) { // read the message header - if(bs.remaining() < HEADER_LENGTH) { + if(bytes.size() < HEADER_LENGTH) { return std::nullopt; } - HandshakeProtocolHeader header; - bs.copy_into(header); - const auto type = read_handshake_message_type(header[0], phase); - const auto msg_length = make_uint32(0, header[1], header[2], header[3]); + const auto type = read_handshake_message_type(bytes[0], phase); + const auto msg_len = make_uint32(0, bytes[1], bytes[2], bytes[3]); - const auto max_msg_length = policy.maximum_handshake_message_size(); - if(max_msg_length > 0 && msg_length > max_msg_length) { - throw TLS_Exception( - Alert::HandshakeFailure, - Botan::fmt("Handshake message is {} bytes, policy maximum is {}", msg_length, max_msg_length)); - } + // TODO(Botan4) this is split out due to a GCC 11 ICE, can be inlined + verify_handshake_message_size(msg_len, policy.maximum_handshake_message_size()); - // read the message body - if(bs.remaining() < msg_length) { + if(bytes.size() < HEADER_LENGTH + msg_len) { return std::nullopt; } - auto incoming_msg = IncomingMessage{ + return NextMessageResult{ .type = type, - .header = header, - .message = bs.copy(msg_length), + .tls_header_bytes = HandshakeProtocolHeader(std::array{bytes[0], bytes[1], bytes[2], bytes[3]}), + .message_bytes = StrongSpan(bytes.subspan(HEADER_LENGTH, msg_len)), + .bytes_consumed = HEADER_LENGTH + msg_len, }; - - // update the read buffer and offset after consuming the message - if(bs.empty()) { - m_read_buffer.clear(); - m_read_offset = 0; - } else { - m_read_offset = m_read_buffer.size() - bs.remaining(); - BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); - } - - return incoming_msg; } std::optional TLS_Handshake_Layer::next_message(const Policy& policy, Transcript_Hash_State& transcript_hash) { - if(auto msg = next_incoming_message(policy, Handshake_Phase::Handshake)) { - auto parsed = parse_handshake_message(msg->type, msg->message, policy); - transcript_hash.update(msg->header, msg->message); - return parsed; - } else { + BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + const auto pending = std::span{m_read_buffer}.subspan(m_read_offset); + + const auto header_and_msg = next_message_buffer(pending, policy, Handshake_Phase::Handshake); + if(!header_and_msg.has_value()) { return std::nullopt; } + + auto msg = parse_handshake_message(header_and_msg->type, header_and_msg->message_bytes, policy); + + transcript_hash.update(header_and_msg->tls_header_bytes, header_and_msg->message_bytes); + m_read_offset += header_and_msg->bytes_consumed; + BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + + if(m_read_offset == m_read_buffer.size()) { + m_read_buffer.clear(); + m_read_offset = 0; + } + + return msg; } std::optional TLS_Handshake_Layer::next_post_handshake_message(const Policy& policy) { - if(auto msg = next_incoming_message(policy, Handshake_Phase::PostHandshake)) { - return parse_post_handshake_message(msg->type, msg->message); - } else { + BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + const auto pending = std::span{m_read_buffer}.subspan(m_read_offset); + + const auto header_and_msg = next_message_buffer(pending, policy, Handshake_Phase::PostHandshake); + if(!header_and_msg.has_value()) { return std::nullopt; } + + auto msg = parse_post_handshake_message(header_and_msg->type, header_and_msg->message_bytes); + + m_read_offset += header_and_msg->bytes_consumed; + BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + + if(m_read_offset == m_read_buffer.size()) { + m_read_buffer.clear(); + m_read_offset = 0; + } + + return msg; } } // namespace Botan::TLS diff --git a/src/lib/tls/tls13/tls_handshake_layer_13.h b/src/lib/tls/tls13/tls_handshake_layer_13.h index b88ba3a8809..e1b212f115a 100644 --- a/src/lib/tls/tls13/tls_handshake_layer_13.h +++ b/src/lib/tls/tls13/tls_handshake_layer_13.h @@ -43,6 +43,26 @@ class BOTAN_TEST_API Handshake_Layer { m_certificate_type(Certificate_Type::X509) {} public: + /** + * The outcome of ingesting handshake data via copy_data(). This + * information is relevant for DTLS, where handshake messages can be + * fragmented and fragments may be maliciously forged or arrive + * out of order. + */ + enum class [[nodiscard]] CopyDataResult : uint8_t { + /// The passed-in data was discarded without being processed or buffered + Discarded, + + /// The passed-in data consisted solely of retransmitted fragments + DiscardedDuplicate, + + /// Some of the passed-in data was discarded, but some was buffered + ConsumedPartially, + + /// All of the passed-in data was successfully consumed + Consumed, + }; + static SerializedHandshakeMessage serialize(const Handshake_Message& message) { return SerializedHandshakeMessage(message.serialize()); } @@ -60,10 +80,15 @@ class BOTAN_TEST_API Handshake_Layer { * processing during the invocation of `next_message()`. * * @param policy The TLS policy - * @param data_from_peer The data to be parsed; typically the payload - * of one handshake record + * @param data_from_peer The data to be parsed. In DTLS this is assumed to be one or + * more full handshake message fragments. In TLS it might be a + * an in-order portion of any size + * + * @returns a CopyDataResult indicating whether the data contained new + * handshake information and/or fragments that had to be + * discarded (relevant for DTLS only). */ - virtual void copy_data(const Policy& policy, const Handshake_Record& data_from_peer) = 0; + virtual CopyDataResult copy_data(const Policy& policy, const Handshake_Record& data_from_peer) = 0; /** * Parses one handshake message off the internal buffer that is being filled using `copy_data`. @@ -121,7 +146,9 @@ class BOTAN_TEST_API Handshake_Layer { protected: enum class Handshake_Phase : bool { Handshake, PostHandshake }; - static Handshake_Type read_handshake_message_type(uint8_t value, Handshake_Phase phase); + Handshake_Type read_handshake_message_type(uint8_t value, Handshake_Phase phase) const; + + virtual TLS_Flavor tls_flavor() const = 0; Connection_Side peer() const { return m_peer; } @@ -149,21 +176,28 @@ class BOTAN_TEST_API TLS_Handshake_Layer final : public Handshake_Layer { bool has_pending_data() const override { return m_read_offset < m_read_buffer.size(); } - void copy_data(const Policy& policy, const Handshake_Record& data_from_peer) override; + CopyDataResult copy_data(const Policy& policy, const Handshake_Record& data_from_peer) override; std::optional next_message(const Policy& policy, Transcript_Hash_State& transcript_hash) override; std::optional next_post_handshake_message(const Policy& policy) override; - private: - struct IncomingMessage { - Handshake_Type type = Handshake_Type::None; - HandshakeProtocolHeader header = {}; - SerializedHandshakeMessage message; + static MarshalledHandshakeMessage marshal(const Handshake_Message& message); + + protected: + struct NextMessageResult { + Handshake_Type type; + HandshakeProtocolHeader tls_header_bytes; + StrongSpan message_bytes; + size_t bytes_consumed; }; - std::optional next_incoming_message(const Policy& policy, Handshake_Phase phase); + std::optional next_message_buffer(std::span bytes, + const Policy& policy, + Handshake_Phase phase); + + TLS_Flavor tls_flavor() const override { return TLS_Flavor::TLS; } private: std::vector m_read_buffer; diff --git a/src/lib/tls/tls13/tls_messages_13.h b/src/lib/tls/tls13/tls_messages_13.h index 03e3ccdc852..90d2979a7c4 100644 --- a/src/lib/tls/tls13/tls_messages_13.h +++ b/src/lib/tls/tls13/tls_messages_13.h @@ -100,9 +100,13 @@ class BOTAN_UNSTABLE_API Server_Hello_13 : public Server_Hello { // after parsing a peer's message. They perform basic validation // and are therefore not suitable for constructing a message to // be sent to a client. - explicit Server_Hello_13(std::unique_ptr data, Server_Hello_Tag tag = as_server_hello); - explicit Server_Hello_13(std::unique_ptr data, Hello_Retry_Request_Tag tag); - void basic_validation() const; + explicit Server_Hello_13(std::unique_ptr data, + TLS_Flavor flavor, + Server_Hello_Tag tag = as_server_hello); + explicit Server_Hello_13(std::unique_ptr data, + TLS_Flavor flavor, + Hello_Retry_Request_Tag tag); + void basic_validation(TLS_Flavor flavor) const; // Instantiate a Server Hello as response to a client's Client Hello // (called from Server_Hello_13::create()) @@ -112,7 +116,8 @@ class BOTAN_UNSTABLE_API Server_Hello_13 : public Server_Hello { Credentials_Manager& credentials_mgr, RandomNumberGenerator& rng, Callbacks& cb, - const Policy& policy); + const Policy& policy, + TLS_Flavor flavor); explicit Server_Hello_13(std::unique_ptr data, Hello_Retry_Request_Creation_Tag tag); @@ -123,10 +128,11 @@ class BOTAN_UNSTABLE_API Server_Hello_13 : public Server_Hello { Credentials_Manager& credentials_mgr, RandomNumberGenerator& rng, const Policy& policy, - Callbacks& cb); + Callbacks& cb, + TLS_Flavor flavor); static std::variant parse( - std::span buf); + std::span buf, TLS_Flavor flavor); /** * Decline the PSK selected in this (not yet sent) Server Hello, so that @@ -134,11 +140,6 @@ class BOTAN_UNSTABLE_API Server_Hello_13 : public Server_Hello { */ void decline_psk(); - /** - * Return desired downgrade version indicated by hello random, if any. - */ - std::optional random_signals_downgrade() const; - /** * @returns the selected version as indicated by the supported_versions extension */ @@ -148,8 +149,13 @@ class BOTAN_UNSTABLE_API Server_Hello_13 : public Server_Hello { class BOTAN_UNSTABLE_API Hello_Retry_Request final : public Server_Hello_13 { protected: friend class Server_Hello_13; // to allow construction by Server_Hello_13::parse() and ::create() - explicit Hello_Retry_Request(std::unique_ptr data); - Hello_Retry_Request(const Client_Hello_13& ch, Named_Group selected_group, const Policy& policy, Callbacks& cb); + Hello_Retry_Request(std::unique_ptr data, TLS_Flavor flavor); + Hello_Retry_Request(const Client_Hello_13& ch, + Named_Group selected_group, + const Policy& policy, + Credentials_Manager& credentials_manager, + Callbacks& cb, + TLS_Flavor flavor); public: Handshake_Type type() const override { return Handshake_Type::HelloRetryRequest; } @@ -164,7 +170,8 @@ class BOTAN_UNSTABLE_API Encrypted_Extensions final : public Handshake_Message { const Policy& policy, Callbacks& cb, bool is_resumption, - bool requesting_client_auth); + bool requesting_client_auth, + TLS_Flavor flavor); Handshake_Type type() const override { return Handshake_Type::EncryptedExtensions; } @@ -446,9 +453,9 @@ using as_wrapped_references_t = typename as_wrapped_references::type; // Handshake message types from RFC 8446 4. using Handshake_Message_13 = std::variant; using Server_Handshake_13_Message = std::variant; diff --git a/src/lib/tls/tls13/tls_psk_importer_13.cpp b/src/lib/tls/tls13/tls_psk_importer_13.cpp index 277182f8a97..7cf60c9a2d8 100644 --- a/src/lib/tls/tls13/tls_psk_importer_13.cpp +++ b/src/lib/tls/tls13/tls_psk_importer_13.cpp @@ -43,7 +43,8 @@ PSKImporter::PSKImporter(std::span key, } ExternalPSK PSKImporter::derive_imported_psk(Protocol_Version version, std::string_view target_hash) const { - BOTAN_ARG_CHECK(version == Protocol_Version::TLS_V13, "PSK importer is only defined for TLS 1.3"); + BOTAN_ARG_CHECK(version == Protocol_Version::TLS_V13 || version == Protocol_Version::DTLS_V13, + "PSK importer is only defined for (D)TLS 1.3"); BOTAN_ARG_CHECK(target_hash == "SHA-256" || target_hash == "SHA-384", "PSK importer target hash must be SHA-256 or SHA-384"); @@ -104,9 +105,20 @@ ExternalPSK PSKImporter::derive_imported_psk(Protocol_Version version, std::stri const auto expand_out_len = static_cast(target_hash_len); auto hkdf_expand = KDF::create_or_throw("HKDF-Expand(" + m_hash + ")"); - // "tls13 derived psk" as bytes - const std::array prefixed_label = { - 't', 'l', 's', '1', '3', ' ', 'd', 'e', 'r', 'i', 'v', 'e', 'd', ' ', 'p', 's', 'k'}; + + // RFC 9147 5.9 + // Section 7.1 of RFC 9846 specifies that HKDF-Expand-Label uses a label + // prefix of "tls13 ". For DTLS 1.3, that label SHALL be "dtls13". [...] + // Note that there is no trailing space; this is necessary in order to + // keep the overall label size inside of one hash iteration because "DTLS" + // is one letter longer than "TLS". + const auto prefixed_label = [&]() -> std::array { + if(!version.is_datagram_protocol()) { + return {'t', 'l', 's', '1', '3', ' ', 'd', 'e', 'r', 'i', 'v', 'e', 'd', ' ', 'p', 's', 'k'}; + } else { + return {'d', 't', 'l', 's', '1', '3', 'd', 'e', 'r', 'i', 'v', 'e', 'd', ' ', 'p', 's', 'k'}; + } + }(); // TLS 1.3 HkdfLabel: length (2) || label length (1) || label || context length (1) || context diff --git a/src/lib/tls/tls13/tls_record_13.h b/src/lib/tls/tls13/tls_record_13.h index e068154d568..c1a9e7bbed7 100644 --- a/src/lib/tls/tls13/tls_record_13.h +++ b/src/lib/tls/tls13/tls_record_13.h @@ -27,6 +27,8 @@ struct Record_Content { Record_Type type; std::optional sequence_number; secure_vector payload; + + std::optional epoch; // only set for DTLS }; struct ChangeCipherSpec_Record final : public Record_Content {}; diff --git a/src/lib/tls/tls13/tls_record_layer_13.cpp b/src/lib/tls/tls13/tls_record_layer_13.cpp index a84b6d3a2c1..8609001324e 100644 --- a/src/lib/tls/tls13/tls_record_layer_13.cpp +++ b/src/lib/tls/tls13/tls_record_layer_13.cpp @@ -92,8 +92,10 @@ TLS_Record_Layer::TLS_Record_Layer(Connection_Side side) : // is disabled at initialization for servers. m_sending_compat_mode(side == Connection_Side::Client) {} -void TLS_Record_Layer::copy_data(std::span data) { - while(!data.empty()) { +bool TLS_Record_Layer::copy_data(std::span data_from_peer, bool has_cryptographic_association) { + BOTAN_UNUSED(has_cryptographic_association); + + while(!data_from_peer.empty()) { auto& record = [&]() -> Record_TLS& { if(m_incoming_records.empty() || m_incoming_records.back().complete()) { return m_incoming_records.emplace_back(); @@ -103,20 +105,24 @@ void TLS_Record_Layer::copy_data(std::span data) { }(); BOTAN_DEBUG_ASSERT(!record.complete()); - const size_t consumed = record.append(data); - BOTAN_ASSERT_NOMSG(consumed <= data.size()); - data = data.subspan(consumed); + const size_t consumed = record.append(data_from_peer); + BOTAN_ASSERT_NOMSG(consumed <= data_from_peer.size()); + data_from_peer = data_from_peer.subspan(consumed); } + + // We don't ever drop data in TLS, we do that in DTLS only. + return true; } RecordNumber TLS_Record_Layer::prepare_record(Record_Type type, std::span payload, const Policy& policy, Cipher_State* cipher_state, - secure_vector& out) { + secure_vector& out, + std::optional epoch) { auto* cs = as_tls_cipher_state(cipher_state); - BOTAN_ARG_CHECK(payload.size() <= record_payload_size_limit(policy, cs), + BOTAN_ARG_CHECK(payload.size() <= record_payload_size_limit(policy, cs, epoch), "data size exceeds record payload size limit"); // RFC 9846 5. @@ -196,8 +202,10 @@ RecordNumber TLS_Record_Layer::prepare_record(Record_Type type, } } -uint16_t TLS_Record_Layer::record_payload_size_limit(const Policy& policy, Cipher_State* cipher_state) const { - BOTAN_UNUSED(policy); // not relevant for TLS +uint16_t TLS_Record_Layer::record_payload_size_limit(const Policy& policy, + Cipher_State* cipher_state, + std::optional epoch) const { + BOTAN_UNUSED(policy, epoch); // not relevant for TLS // RFC 8449 4. // When the "record_size_limit" extension is negotiated, an endpoint @@ -275,6 +283,7 @@ Record_Layer::ReadResult TLS_Record_Layer::next_record(Cipher_State* cipher_stat .type = record.type(), .sequence_number = std::nullopt, .payload = record.take_payload(), + .epoch = std::nullopt, })); } else { if(cs == nullptr) { diff --git a/src/lib/tls/tls13/tls_record_layer_13.h b/src/lib/tls/tls13/tls_record_layer_13.h index f9488bd9ce2..dd254af5a67 100644 --- a/src/lib/tls/tls13/tls_record_layer_13.h +++ b/src/lib/tls/tls13/tls_record_layer_13.h @@ -38,8 +38,8 @@ class BOTAN_TEST_API Record_Layer { virtual ~Record_Layer() = default; Record_Layer(const Record_Layer&) = delete; Record_Layer& operator=(const Record_Layer&) = delete; - Record_Layer(Record_Layer&&) = delete; - Record_Layer& operator=(Record_Layer&&) = delete; + Record_Layer(Record_Layer&&) = default; + Record_Layer& operator=(Record_Layer&&) = default; using ReadResult = variant_append_t; @@ -51,11 +51,18 @@ class BOTAN_TEST_API Record_Layer { * processing during the invocation of `next_record()`. * * @param data_from_peer The data to be parsed. + * @param has_cryptographic_association Indicates whether there is already an + * established cryptographic association + * with the peer (i.e. a shared secret). + * + * @returns true if the data was successfully ingested, false if something + * went wrong. Typically DTLS record layers will return false if + * the passed-in datagram was somehow invalid and got discarded. */ - virtual void copy_data(std::span data_from_peer) = 0; + virtual bool copy_data(std::span data_from_peer, bool has_cryptographic_association) = 0; /** - * Parses one record off the internal buffer that is being filled using `copy_data`. + * Parses one record off the internal buffer that is being filled using `ingest`. * * Return value contains either the number of bytes (`size_t`) needed to proceed * with processing TLS records or a single plaintext TLS record content containing @@ -85,6 +92,8 @@ class BOTAN_TEST_API Record_Layer { * this cipher state. Pass nullptr to prepare a * plaintext record. * @param out The container the marshalled record is written to + * @param epoch Optionally, the epoch number that shall be used to + * protect the record (relevant for DTLS only) * * @returns The record number (epoch and sequence number) of the * prepared record @@ -93,7 +102,8 @@ class BOTAN_TEST_API Record_Layer { std::span payload, const Policy& policy, Cipher_State* cipher_state, - secure_vector& out) = 0; + secure_vector& out, + std::optional epoch = std::nullopt) = 0; /// @} @@ -101,10 +111,13 @@ class BOTAN_TEST_API Record_Layer { * Returns the maximum number of bytes that can be put into a record. * * Both the specified and negotiated record size limit is taken into - * account. Depending on the @p cipher_state, the size of the record - * overhead (e.g. MAC, padding, record header, etc.) is also considered. + * account. As well as the user-specified MTU for DTLS. Depending on the + * @p cipher_state, the size of the record overhead (e.g. MAC, padding, + * record header, etc.) is also considered. */ - virtual uint16_t record_payload_size_limit(const Policy& policy, Cipher_State* cipher_state = nullptr) const = 0; + virtual uint16_t record_payload_size_limit(const Policy& policy, + Cipher_State* cipher_state = nullptr, + std::optional epoch = std::nullopt) const = 0; /** * Clears any data currently stored in the read buffer. This is typically @@ -132,6 +145,13 @@ class BOTAN_TEST_API Record_Layer { uint16_t incoming_record_size_limit() const noexcept { return m_incoming_record_size_limit; } + /** + * Extracts the current sequence numbers (before rolling over into any + * protected epoch). This is used to downgrade a DTLS 1.3 handshake to a + * DTLS 1.2 handshake. + */ + virtual std::optional epoch0_sequence_numbers() const noexcept { return std::nullopt; } + void disable_receiving_compat_mode() noexcept { m_receiving_compat_mode = false; } bool receiving_compat_mode() const noexcept { return m_receiving_compat_mode; } @@ -152,18 +172,24 @@ class BOTAN_TEST_API TLS_Record_Layer final : public Record_Layer { public: explicit TLS_Record_Layer(Connection_Side side); - void copy_data(std::span data) override; + bool copy_data(std::span data_from_peer, bool has_cryptographic_association) override; ReadResult next_record(Cipher_State* cipher_state = nullptr) override; RecordNumber prepare_record(Record_Type type, std::span payload, const Policy& policy, Cipher_State* cipher_state, - secure_vector& out) override; + secure_vector& out, + std::optional epoch = std::nullopt) override; void clear_read_buffer() override; - uint16_t record_payload_size_limit(const Policy& policy, Cipher_State* cipher_state = nullptr) const override; + uint16_t record_payload_size_limit(const Policy& policy, + Cipher_State* cipher_state = nullptr, + std::optional epoch = std::nullopt) const override; + /// Disables the sending compatibility mode that uses legacy record + /// version 0x0301 for the initial (unprotected) flight. Must be called + /// once the first flight's unprotected messages have been sent. void disable_sending_compat_mode() noexcept { m_sending_compat_mode = false; } private: diff --git a/src/lib/tls/tls13/tls_server_impl_13.cpp b/src/lib/tls/tls13/tls_server_impl_13.cpp index ed999e0a875..ac8025a7e9e 100644 --- a/src/lib/tls/tls13/tls_server_impl_13.cpp +++ b/src/lib/tls/tls13/tls_server_impl_13.cpp @@ -14,8 +14,10 @@ #include #include #include +#include #include #include +#include #include namespace Botan::TLS { @@ -24,16 +26,24 @@ std::shared_ptr Server_Impl_13::create(const std::shared_ptr& session_manager, const std::shared_ptr& credentials_manager, const std::shared_ptr& policy, - const std::shared_ptr& rng) { + const std::shared_ptr& rng, + TLS_Flavor flavor) { auto self = - std::make_shared(Private{}, callbacks, session_manager, credentials_manager, policy, rng); + std::make_shared(Private{}, callbacks, session_manager, credentials_manager, policy, rng, flavor); #if defined(BOTAN_HAS_TLS_12) - if(policy->allow_tls12()) { + if((flavor == TLS_Flavor::TLS) ? policy->allow_tls12() : policy->allow_dtls12()) { self->expect_downgrade({}, {}); } #endif + if(!self->expects_downgrade()) { + // If we don't expect to downgrade, we can already enable all DTLS-only + // features (e.g. record ACKing), because we know that we won't ever + // talk to a legacy peer and succeed a handshake. + self->m_channel_io->notify_protocol_version_committed(); + } + self->m_handshake->transitions.set_expected_next(Handshake_Type::ClientHello); return self; @@ -111,7 +121,6 @@ bool Server_Impl_13::new_session_ticket_supported() const { size_t Server_Impl_13::send_new_session_tickets(const size_t tickets) { BOTAN_STATE_CHECK(is_handshake_complete()); - BOTAN_STATE_CHECK(m_cipher_state != nullptr); if(tickets == 0) { return 0; @@ -121,6 +130,8 @@ size_t Server_Impl_13::send_new_session_tickets(const size_t tickets) { size_t tickets_created = 0; BOTAN_STATE_CHECK(m_active_state.has_value()); + auto* cs = cipher_state(); + BOTAN_ASSERT_NONNULL(cs); // RFC 8446 4.6.1 // Servers MUST NOT use any value greater than 604800 seconds (7 days). @@ -132,9 +143,9 @@ size_t Server_Impl_13::send_new_session_tickets(const size_t tickets) { (policy_lifetime.count() <= 0 || policy_lifetime > max_ticket_lifetime) ? max_ticket_lifetime : policy_lifetime; for(size_t i = 0; i < tickets; ++i) { - auto nonce = m_cipher_state->next_ticket_nonce(); + auto nonce = cs->next_ticket_nonce(); const uint32_t ticket_age_add = load_be(rng().random_array<4>()); - const Session session(m_cipher_state->psk(nonce), + const Session session(cs->psk(nonce), std::nullopt, // early data not yet implemented ticket_age_add, ticket_lifetime, @@ -144,6 +155,7 @@ size_t Server_Impl_13::send_new_session_tickets(const size_t tickets) { peer_cert_chain(), peer_raw_public_key(), Server_Information(m_active_state->sni_hostname()), + m_active_state->srtp_profile(), callbacks().tls_current_timestamp()); if(callbacks().tls_should_persist_resumption_information(session)) { @@ -244,6 +256,12 @@ void Server_Impl_13::downgrade() { #endif bool Server_Impl_13::compat_mode_ccs_requested() const { + // RFC 9147 Section 5 + // DTLS implementations do not use the TLS 1.3 "compatibility mode" [...]. + if(is_datagram()) { + return false; + } + // RFC 9846 E.4 // This "compatibility mode" is partially negotiated: the client can opt // to provide a session ID or not, [...]. @@ -292,7 +310,7 @@ void Server_Impl_13::handle_reply_to_client_hello(Server_Hello_13 server_hello) [&, this](Session session) { m_handshake->resumed_session = std::move(session); return Cipher_State::init_with_psk(Connection_Side::Server, - TLS_Flavor::TLS, + m_flavor, Cipher_State::PSK_Type::Resumption, m_handshake->resumed_session->extract_master_secret(), cipher.prf_algo()); @@ -302,7 +320,7 @@ void Server_Impl_13::handle_reply_to_client_hello(Server_Hello_13 server_hello) const auto psk_type = psk.is_imported() ? Cipher_State::PSK_Type::Imported : Cipher_State::PSK_Type::External; return Cipher_State::init_with_psk( - Connection_Side::Server, TLS_Flavor::TLS, psk_type, psk.extract_master_secret(), cipher.prf_algo()); + Connection_Side::Server, m_flavor, psk_type, psk.extract_master_secret(), cipher.prf_algo()); }, }, psk_extension->take_session_to_resume_or_psk()); @@ -392,12 +410,8 @@ void Server_Impl_13::handle_reply_to_client_hello(Server_Hello_13 server_hello) return std::move(psk_cipher_state); } else { - return Cipher_State::init_with_server_hello(m_side, - TLS_Flavor::TLS, - my_keyshare->take_shared_secret(), - cipher, - m_transcript_hash->current(), - secret_logger()); + return Cipher_State::init_with_server_hello( + m_side, m_flavor, my_keyshare->take_shared_secret(), cipher, m_transcript_hash->current(), secret_logger()); } }(); @@ -412,7 +426,7 @@ void Server_Impl_13::handle_reply_to_client_hello(Server_Hello_13 server_hello) const bool requesting_client_auth = certificate_request.has_value(); flight.add(m_handshake->state.sending( - Encrypted_Extensions(client_hello, policy(), callbacks(), is_resumption, requesting_client_auth))); + Encrypted_Extensions(client_hello, policy(), callbacks(), is_resumption, requesting_client_auth, m_flavor))); if(!uses_psk) { // RFC 8446 4.3.2 @@ -573,6 +587,15 @@ void Server_Impl_13::handle(const Client_Hello_13& client_hello) { const bool is_initial_client_hello = !m_handshake->state.has_hello_retry_request(); + // We received a TLS 1.3 ClientHello. Now, we can be sure that our peer uses + // TLS 1.3. Note that for DTLS, we don't have to explicitly clear our resend + // buffer like on the client side, because the server never sends any flights + // before committing the protocol version anyway. + m_channel_io->notify_protocol_version_committed(); + + // By definition, SH is the "final" message of this flight. + m_channel_io->notify_received_complete_flight(); + if(is_initial_client_hello) { const auto preferred_version = client_hello.highest_supported_version(policy()); if(!preferred_version) { @@ -609,24 +632,51 @@ void Server_Impl_13::handle(const Client_Hello_13& client_hello) { BOTAN_ASSERT_NOMSG(exts.has()); if(!is_initial_client_hello) { + // RFC 9846 4.2.2 + // The client will also send a ClientHello when the server has + // responded to its ClientHello with a HelloRetryRequest. In that case, + // the client MUST send the same ClientHello without modification, + // except as follows: ... const auto& hrr_exts = m_handshake->state.hello_retry_request().extensions(); const auto offered_groups = exts.get()->offered_groups(); const auto* hrr_key_share = hrr_exts.get(); - BOTAN_ASSERT_NONNULL(hrr_key_share); - const auto selected_group = hrr_key_share->selected_group(); - if(offered_groups.size() != 1 || offered_groups.at(0) != selected_group) { - throw TLS_Exception(Alert::IllegalParameter, "Client did not comply with the requested key exchange group"); + + // RFC 9846 4.2.2 + // ... If a "key_share" extension was supplied in the HelloRetryRequest, + // replacing the list of shares with a list containing a single + // KeyShareEntry from the indicated group. + if(hrr_key_share != nullptr) { + const auto selected_group = hrr_key_share->selected_group(); + if(offered_groups.size() != 1 || offered_groups.at(0) != selected_group) { + throw TLS_Exception(Alert::IllegalParameter, "Client did not comply with the requested key exchange group"); + } + } + + const auto* ch_cookie = exts.get(); + const auto* hrr_cookie = hrr_exts.get(); + + // RFC 9846 4.2.2 + // ... Including a "cookie" extension if one was provided in the + // HelloRetryRequest. + if(hrr_cookie == nullptr && ch_cookie != nullptr) { + throw TLS_Exception(Alert::IllegalParameter, + "Received a Cookie in a second ClientHello, but we did not send one in HelloRetryRequest"); } // RFC 9846 4.3.2 // When sending the new ClientHello, the client MUST copy the contents // of the extension received in the HelloRetryRequest into a "cookie" // extension in the new ClientHello. - const auto* hrr_cookie = hrr_exts.get(); - const auto* client_cookie = exts.get(); - if((hrr_cookie == nullptr) != (client_cookie == nullptr) || - (hrr_cookie != nullptr && hrr_cookie->get_cookie() != client_cookie->get_cookie())) { - throw TLS_Exception(Alert::IllegalParameter, "Client did not echo the cookie of the HelloRetryRequest"); + if(hrr_cookie != nullptr) { + if(ch_cookie == nullptr) { + throw TLS_Exception(Alert::IllegalParameter, + "Received a second ClientHello without a Cookie, but we sent one in HelloRetryRequest"); + } + + if(!CT::is_equal(hrr_cookie->get_cookie(), ch_cookie->get_cookie()).as_bool()) { + throw TLS_Exception(Alert::IllegalParameter, + "The second ClientHello did not contain the matching cookie from HelloRetryRequest"); + } } } @@ -638,7 +688,8 @@ void Server_Impl_13::handle(const Client_Hello_13& client_hello) { credentials_manager(), rng(), policy(), - callbacks())); + callbacks(), + m_flavor)); } void Server_Impl_13::handle(const Certificate_13& certificate_msg) { @@ -730,11 +781,14 @@ void Server_Impl_13::handle(const Finished_13& finished_msg) { BOTAN_ASSERT_NONNULL(m_handshake); BOTAN_ASSERT_NOMSG(m_transcript_hash.has_value()); + auto* cs = cipher_state(); + BOTAN_ASSERT_NONNULL(cs); + // RFC 8446 4.4.4 // Recipients of Finished messages MUST verify that the contents are // correct and if incorrect MUST terminate the connection with a // "decrypt_error" alert. - if(!finished_msg.verify(*m_cipher_state, m_transcript_hash->previous())) { + if(!finished_msg.verify(*cs, m_transcript_hash->previous())) { throw TLS_Exception(Alert::DecryptError, "Finished message didn't verify"); } @@ -752,7 +806,9 @@ void Server_Impl_13::handle(const Finished_13& finished_msg) { Server_Information(m_handshake->state.client_hello().sni_hostname()), callbacks().tls_current_timestamp())); - m_cipher_state->advance_with_client_finished(m_transcript_hash->current()); + cs->advance_with_client_finished(m_transcript_hash->current()); + + m_channel_io->notify_received_final_flight(); // no more handshake messages expected m_handshake->transitions.set_expected_next({}); diff --git a/src/lib/tls/tls13/tls_server_impl_13.h b/src/lib/tls/tls13/tls_server_impl_13.h index 6434a092159..fad0ad2135a 100644 --- a/src/lib/tls/tls13/tls_server_impl_13.h +++ b/src/lib/tls/tls13/tls_server_impl_13.h @@ -24,15 +24,18 @@ class Server_Impl_13 final : public Channel_Impl_13 { const std::shared_ptr& session_manager, const std::shared_ptr& credentials_manager, const std::shared_ptr& policy, - const std::shared_ptr& rng); + const std::shared_ptr& rng, + TLS_Flavor flavor); Server_Impl_13([[maybe_unused]] Private dont_call_me, const std::shared_ptr& callbacks, const std::shared_ptr& session_manager, const std::shared_ptr& credentials_manager, const std::shared_ptr& policy, - const std::shared_ptr& rng) : - Channel_Impl_13(callbacks, session_manager, credentials_manager, rng, policy, true /* is_server */), + const std::shared_ptr& rng, + TLS_Flavor flavor) : + Channel_Impl_13( + callbacks, session_manager, credentials_manager, rng, policy, Connection_Side::Server, flavor), m_handshake(std::make_unique()) {} std::string application_protocol() const override; diff --git a/src/lib/tls/tls13/tls_transcript_hash_13.cpp b/src/lib/tls/tls13/tls_transcript_hash_13.cpp index 5ebd465c52b..fb9641a2ea9 100644 --- a/src/lib/tls/tls13/tls_transcript_hash_13.cpp +++ b/src/lib/tls/tls13/tls_transcript_hash_13.cpp @@ -83,10 +83,7 @@ namespace { // // Finds the truncation offset in a serialization of Client Hello as defined in // RFC 8446 4.2.11.2 used for the calculation of PSK binder MACs. -// Returns std::nullopt if the Client Hello does not contain a PSK extension. std::optional find_client_hello_truncation_mark(std::span client_hello, TLS_Flavor flavor) { - BOTAN_UNUSED(flavor); - TLS_Data_Reader reader("Client Hello Truncation", client_hello); // legacy version @@ -99,6 +96,19 @@ std::optional find_client_hello_truncation_mark(std::span const auto session_id_length = reader.get_byte(); reader.discard_next(session_id_length); + // Cookie (only for DTLS) + if(flavor == TLS_Flavor::DTLS) { + // RFC 9147 5.3 + // A DTLS 1.3-only client MUST set the legacy_cookie field to zero + // length. If a DTLS 1.3 ClientHello is received with any other value + // in this field, the server MUST abort the handshake with an + // "illegal_parameter" alert. + const auto cookie_length = reader.get_byte(); + if(cookie_length != 0) { + throw TLS_Exception(Alert::IllegalParameter, "DTLS 1.3 Client Hello has non-empty cookie"); + } + } + // cipher suites const auto ciphersuites_length = reader.get_uint16_t(); reader.discard_next(ciphersuites_length); diff --git a/src/lib/tls/tls13/tls_types_13.h b/src/lib/tls/tls13/tls_types_13.h index 52abaaf2a1a..97dc229ac3c 100644 --- a/src/lib/tls/tls13/tls_types_13.h +++ b/src/lib/tls/tls13/tls_types_13.h @@ -107,6 +107,10 @@ using SerializedHandshakeMessage = Strong, struct Serialize /// Holds the serialization of a TLS 1.3 handshake protocol header. using HandshakeProtocolHeader = Strong, struct HandshakeProtocolHeader_>; +/// Holds the serialization of a single TLS 1.3 handshake message along with +/// the handshake protocol header. +using MarshalledHandshakeMessage = Strong, struct MarshalledHandshakeMessage_>; + /// Holds the serialization of a TLS 1.3 handshake message flight containing /// multiple handshake messages along with their handshake protocol headers. using MarshalledHandshakeMessageFlight = Strong, struct MarshalledHandshakeMessageFlight_>; diff --git a/src/lib/tls/tls_channel.h b/src/lib/tls/tls_channel.h index 36ac5fa4ddf..b24ba4457b7 100644 --- a/src/lib/tls/tls_channel.h +++ b/src/lib/tls/tls_channel.h @@ -188,7 +188,15 @@ class BOTAN_PUBLIC_API(2, 0) Channel { /** * Attempt to update the session's traffic key material - * Note that this is possible with a TLS 1.3 channel, only. + * Note that this is possible with a (D)TLS 1.3 channel, only. + * + * @throws Invalid_Argument if called on a (D)TLS 1.2 channel + * @throws Invalid_State if called on a DTLS 1.3 channel and another + * KeyUpdate is already pending (see RFC 9147 quote below). + * + * RFC 9147 (DTLS 1.3) Section 8 "Key Updates": + * [...] implementations MUST NOT send [...] a new KeyUpdate until the + * previous KeyUpdate has been acknowledged [...]. * * @param request_peer_update if true, require a reciprocal key update */ diff --git a/src/lib/tls/tls_channel_impl.h b/src/lib/tls/tls_channel_impl.h index 3416cbcecfd..0d02683c601 100644 --- a/src/lib/tls/tls_channel_impl.h +++ b/src/lib/tls/tls_channel_impl.h @@ -261,6 +261,11 @@ class Channel_Impl : public std::enable_shared_from_this { m_downgrade_info->client_hello.emplace(std::move(client_hello)); } + void preserve_sequence_numbers(std::optional epoch0_sec_nums) { + BOTAN_STATE_CHECK(m_downgrade_info); + m_downgrade_info->epoch0_sequence_numbers = epoch0_sec_nums; + } + friend class Client; friend class Server; diff --git a/src/lib/tls/tls_client.cpp b/src/lib/tls/tls_client.cpp index 169d1ea6759..2e2bc66a28d 100644 --- a/src/lib/tls/tls_client.cpp +++ b/src/lib/tls/tls_client.cpp @@ -41,8 +41,16 @@ Client::Client(const std::shared_ptr& callbacks, "Policy does not allow to offer requested protocol version"); #if defined(BOTAN_HAS_TLS_13) - if(offer_version == Protocol_Version::TLS_V13) { - m_impl = Client_Impl_13::create(callbacks, session_manager, creds, policy, rng, std::move(info), next_protocols); + if(offer_version.is_tls_13_or_later()) { + const auto flavor = offer_version.is_datagram_protocol() ? TLS_Flavor::DTLS : TLS_Flavor::TLS; + + if(flavor == TLS_Flavor::DTLS) { + // DTLS 1.3 is not yet supported. + throw Not_Implemented("DTLS 1.3 is not yet supported"); + } + + m_impl = Client_Impl_13::create( + callbacks, session_manager, creds, policy, rng, flavor, std::move(info), next_protocols); #if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT) if(m_impl->expects_downgrade()) { diff --git a/src/lib/tls/tls_messages.h b/src/lib/tls/tls_messages.h index 63d77cc0145..ee19263bc39 100644 --- a/src/lib/tls/tls_messages.h +++ b/src/lib/tls/tls_messages.h @@ -186,6 +186,11 @@ class BOTAN_UNSTABLE_API Server_Hello : public Handshake_Message { const Extensions& extensions() const; const Session_ID& session_id() const; + /** + * Return desired downgrade version indicated by hello random, if any. + */ + std::optional random_signals_downgrade() const; + virtual Protocol_Version selected_version() const = 0; protected: @@ -219,11 +224,6 @@ class BOTAN_UNSTABLE_API Server_Hello_12_Shim : public Server_Hello { * @returns the selected version as indicated in the legacy_version field */ Protocol_Version selected_version() const final; - - /** - * Return desired downgrade version indicated by hello random, if any. - */ - std::optional random_signals_downgrade() const; }; /** diff --git a/src/lib/tls/tls_policy.cpp b/src/lib/tls/tls_policy.cpp index 20fb9c5cb28..6ef44478cc9 100644 --- a/src/lib/tls/tls_policy.cpp +++ b/src/lib/tls/tls_policy.cpp @@ -333,6 +333,9 @@ bool Policy::acceptable_protocol_version(Protocol_Version version) const { Protocol_Version Policy::latest_supported_version(bool datagram) const { if(datagram) { + if(acceptable_protocol_version(Protocol_Version::DTLS_V13)) { + return Protocol_Version::DTLS_V13; + } if(acceptable_protocol_version(Protocol_Version::DTLS_V12)) { return Protocol_Version::DTLS_V12; } @@ -389,6 +392,10 @@ bool Policy::allow_dtls12() const { #endif } +bool Policy::allow_dtls13() const { + return false; // DTLS 1.3 is not yet supported +} + bool Policy::include_time_in_hello_random() const { return true; } diff --git a/src/lib/tls/tls_policy.h b/src/lib/tls/tls_policy.h index 392bef1f941..7c6faa03580 100644 --- a/src/lib/tls/tls_policy.h +++ b/src/lib/tls/tls_policy.h @@ -263,6 +263,11 @@ class BOTAN_PUBLIC_API(2, 0) Policy /* NOLINT(*-special-member-functions) */ { */ virtual bool allow_dtls12() const; + /** + * Allow DTLS v1.3 + */ + virtual bool allow_dtls13() const; + /** * For ephemeral Diffie-Hellman key exchange, the server sends a group * parameter. Return the 2 Byte TLS group identifier specifying the group @@ -919,6 +924,8 @@ class BOTAN_PUBLIC_API(2, 0) Text_Policy : public Policy { bool allow_dtls12() const override; + bool allow_dtls13() const override; + bool allow_insecure_renegotiation() const override; bool include_time_in_hello_random() const override; diff --git a/src/lib/tls/tls_server.cpp b/src/lib/tls/tls_server.cpp index 6a1af7b9ba2..845bfdee510 100644 --- a/src/lib/tls/tls_server.cpp +++ b/src/lib/tls/tls_server.cpp @@ -39,8 +39,8 @@ Server::Server(const std::shared_ptr& callbacks, const auto flavor = is_datagram ? TLS_Flavor::DTLS : TLS_Flavor::TLS; #if defined(BOTAN_HAS_TLS_13) - if(!max_version.is_pre_tls_13()) { - m_impl = Server_Impl_13::create(callbacks, session_manager, creds, policy, rng); + if(max_version.is_tls_13_or_later()) { + m_impl = Server_Impl_13::create(callbacks, session_manager, creds, policy, rng, flavor); #if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT) if(m_impl->expects_downgrade()) { diff --git a/src/lib/tls/tls_session.cpp b/src/lib/tls/tls_session.cpp index 4bbf72b7723..cf3f4ce77a9 100644 --- a/src/lib/tls/tls_session.cpp +++ b/src/lib/tls/tls_session.cpp @@ -277,14 +277,13 @@ Session::Session(const secure_vector& session_psk, const std::vector& peer_certs, std::shared_ptr peer_raw_public_key, const Server_Information& server_info, + uint16_t srtp_profile, std::chrono::system_clock::time_point current_timestamp) : Session_Base(current_timestamp, version, ciphersuite, side, - - // TODO: SRTP might become necessary when DTLS 1.3 is being implemented - 0, + srtp_profile, // RFC 8446 Appendix D // Because TLS 1.3 always hashes in the transcript up to the server @@ -362,7 +361,7 @@ Session::Session(std::span ber_data) /* NOLINT(*-member-init) */ m_version = Protocol_Version(major_version, minor_version); // A session for a version that is disabled in this build is still well formed if(m_version != Protocol_Version::TLS_V12 && m_version != Protocol_Version::DTLS_V12 && - m_version != Protocol_Version::TLS_V13) { + m_version != Protocol_Version::TLS_V13 && m_version != Protocol_Version::DTLS_V13) { throw Decoding_Error("Serialized TLS session contains unknown protocol version " + m_version.to_string()); } diff --git a/src/lib/tls/tls_session.h b/src/lib/tls/tls_session.h index 45c1b892bc1..28586f72d2a 100644 --- a/src/lib/tls/tls_session.h +++ b/src/lib/tls/tls_session.h @@ -283,6 +283,7 @@ class BOTAN_PUBLIC_API(3, 0) Session final : public Session_Base { const std::vector& peer_certs, std::shared_ptr peer_raw_public_key, const Server_Information& server_info, + uint16_t srtp_profile, std::chrono::system_clock::time_point current_timestamp); #endif diff --git a/src/lib/tls/tls_text_policy.cpp b/src/lib/tls/tls_text_policy.cpp index cdc4ae2a5e7..d5e0a6dffbd 100644 --- a/src/lib/tls/tls_text_policy.cpp +++ b/src/lib/tls/tls_text_policy.cpp @@ -68,6 +68,10 @@ bool Text_Policy::allow_dtls12() const { return get_bool("allow_dtls12", Policy::allow_dtls12()); } +bool Text_Policy::allow_dtls13() const { + return get_bool("allow_dtls13", Policy::allow_dtls13()); +} + bool Text_Policy::allow_insecure_renegotiation() const { return get_bool("allow_insecure_renegotiation", Policy::allow_insecure_renegotiation()); } diff --git a/src/lib/tls/tls_version.cpp b/src/lib/tls/tls_version.cpp index c6e581152b3..f8ee48c4fca 100644 --- a/src/lib/tls/tls_version.cpp +++ b/src/lib/tls/tls_version.cpp @@ -24,6 +24,8 @@ Protocol_Version Protocol_Version::latest_tls_version() { } Protocol_Version Protocol_Version::latest_dtls_version() { + // Note: DTLS 1.3 is not yet supported, so DTLS 1.2 remains the latest + // DTLS version for the time being. #if defined(BOTAN_HAS_TLS_12) return Protocol_Version::DTLS_V12; #else diff --git a/src/tests/test_tls_flight_13.cpp b/src/tests/test_tls_flight_13.cpp index 888c50e216e..52f8969f989 100644 --- a/src/tests/test_tls_flight_13.cpp +++ b/src/tests/test_tls_flight_13.cpp @@ -58,7 +58,7 @@ Client_Hello_13 make_client_hello() { } Server_Hello_13 make_server_hello() { - return std::get(Server_Hello_13::parse(Botan::hex_decode(server_hello_body))); + return std::get(Server_Hello_13::parse(Botan::hex_decode(server_hello_body), TLS_Flavor::TLS)); } Certificate_13 make_certificate() { diff --git a/src/tests/test_tls_handshake_layer_13.cpp b/src/tests/test_tls_handshake_layer_13.cpp index a9e92d88c7b..a1fe6a2b792 100644 --- a/src/tests/test_tls_handshake_layer_13.cpp +++ b/src/tests/test_tls_handshake_layer_13.cpp @@ -16,6 +16,7 @@ #include #include #include + #include using namespace Botan::TLS; @@ -150,6 +151,7 @@ Botan::TLS::Handshake_Record as_hs_record(std::span payload) { .type = Botan::TLS::Record_Type::Handshake, .sequence_number = std::nullopt, .payload = {payload.begin(), payload.end()}, + .epoch = std::nullopt, }, }; } @@ -175,7 +177,7 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(std::array{0x00, 0x01, 0x02})); + std::ignore = hl.copy_data(Policy(), as_hs_record(std::array{0x00, 0x01, 0x02})); result.test_is_true("needs more bytes", !hl.next_message(Policy(), th)); check_transcript_hash_empty(result, th); }), @@ -184,7 +186,7 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(client_hello_message)); + std::ignore = hl.copy_data(Policy(), as_hs_record(client_hello_message)); result.test_is_true("is a client hello", has_message(result, hl.next_message(Policy(), th))); check_transcript_hash_filled(result, th); @@ -194,7 +196,7 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(server_hello_message)); + std::ignore = hl.copy_data(Policy(), as_hs_record(server_hello_message)); result.test_is_true("is a server hello", has_message(result, hl.next_message(Policy(), th))); check_transcript_hash_filled(result, th); @@ -204,7 +206,7 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(server_hello_12_message)); + std::ignore = hl.copy_data(Policy(), as_hs_record(server_hello_12_message)); result.test_is_true("is a legacy server hello", has_message(result, hl.next_message(Policy(), th))); check_transcript_hash_filled(result, th); @@ -217,13 +219,13 @@ std::vector read_handshake_messages() { const Botan::secure_vector partial_client_hello_message(client_hello_message.cbegin(), client_hello_message.cend() - 15); - hl.copy_data(Policy(), as_hs_record(partial_client_hello_message)); + std::ignore = hl.copy_data(Policy(), as_hs_record(partial_client_hello_message)); result.test_is_true("needs more bytes", !hl.next_message(Policy(), th)); result.test_is_true("holds pending message data", hl.has_pending_data()); const Botan::secure_vector remaining_client_hello_message(client_hello_message.cend() - 15, client_hello_message.cend()); - hl.copy_data(Policy(), as_hs_record(remaining_client_hello_message)); + std::ignore = hl.copy_data(Policy(), as_hs_record(remaining_client_hello_message)); result.test_is_true("is a client hello", has_message(result, hl.next_message(Policy(), th))); @@ -234,7 +236,8 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(Botan::concat(server_hello_message, encrypted_extensions))); + std::ignore = + hl.copy_data(Policy(), as_hs_record(Botan::concat(server_hello_message, encrypted_extensions))); result.test_is_true("is a server hello", has_message(result, hl.next_message(Policy(), th))); result.test_is_true("is encrypted extensions", @@ -248,7 +251,7 @@ std::vector read_handshake_messages() { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(msg)); + std::ignore = hl.copy_data(Policy(), as_hs_record(msg)); result.template test_throws("message is rejected", [&] { hl.next_message(Policy(), th); }); @@ -268,7 +271,7 @@ std::vector read_handshake_messages() { // ~~ <- bogus message type auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - hl.copy_data(Policy(), as_hs_record(data)); + std::ignore = hl.copy_data(Policy(), as_hs_record(data)); result.template test_throws( "message is rejected", "Unknown handshake message received", [&] { hl.next_message(Policy(), th); }); }), @@ -289,8 +292,8 @@ std::vector test_prepare_message() { CHECK("prepare server hello", [&](auto& result) { - auto hello = std::get( - Server_Hello_13::parse({server_hello_message.cbegin() + 4, server_hello_message.cend()})); + auto hello = std::get(Server_Hello_13::parse( + {server_hello_message.cbegin() + 4, server_hello_message.cend()}, TLS_Flavor::TLS)); const auto hl = TLS_Handshake_Layer(Connection_Side::Server); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); result.test_bin_eq("produces the same message", prepare_message(hello, th), server_hello_message); @@ -316,7 +319,7 @@ std::vector full_client_handshake() { CHECK("server hello", [&](auto& result) { - hl.copy_data(Policy(), as_hs_record(server_hello_message)); + std::ignore = hl.copy_data(Policy(), as_hs_record(server_hello_message)); const auto server_hello = hl.next_message(policy, th); result.test_is_true("is a Server Hello", has_message(result, server_hello)); @@ -336,7 +339,7 @@ std::vector full_client_handshake() { CHECK( "server handshake messages", [&](auto& result) { - hl.copy_data(Policy(), as_hs_record(server_handshake_messages)); + std::ignore = hl.copy_data(Policy(), as_hs_record(server_handshake_messages)); const auto enc_exts = hl.next_message(policy, th); result.test_is_true("is Encrypted Extensions", has_message(result, enc_exts)); @@ -390,7 +393,7 @@ std::vector hello_retry_request_handshake() { CHECK("hello retry request", [&](auto& result) { - hl.copy_data(Policy(), as_hs_record(hrr_hello_retry_request_msg)); + std::ignore = hl.copy_data(Policy(), as_hs_record(hrr_hello_retry_request_msg)); const auto hrr = hl.next_message(policy, th); result.test_is_true("is a Hello Retry Request", has_message(result, hrr)); diff --git a/src/tests/test_tls_handshake_state_13.cpp b/src/tests/test_tls_handshake_state_13.cpp index 25b5b44aeb4..2a6d6fcdf62 100644 --- a/src/tests/test_tls_handshake_state_13.cpp +++ b/src/tests/test_tls_handshake_state_13.cpp @@ -110,8 +110,8 @@ std::vector handshake_message_filtering() { const auto server_hello_message = Botan::hex_decode(server_hello_message_hex); - auto server_hello = - std::get(Botan::TLS::Server_Hello_13::parse(server_hello_message)); + auto server_hello = std::get( + Botan::TLS::Server_Hello_13::parse(server_hello_message, Botan::TLS::TLS_Flavor::TLS)); const auto filtered = state.received(std::move(server_hello)); result.test_is_true("client can receive server hello", diff --git a/src/tests/test_tls_messages.cpp b/src/tests/test_tls_messages.cpp index 5f60c218c93..4a52ad4faa1 100644 --- a/src/tests/test_tls_messages.cpp +++ b/src/tests/test_tls_messages.cpp @@ -653,7 +653,7 @@ class TLS_13_Message_Parsing_Test final : public Text_Based_Test { } result.test_bin_eq("Hello extensions", buf, extensions); }, - Botan::TLS::Server_Hello_13::parse(buffer)); + Botan::TLS::Server_Hello_13::parse(buffer, Botan::TLS::TLS_Flavor::TLS)); } catch(const std::exception& ex) { result.test_str_eq("correct error produced", ex.what(), exception); result.test_is_true("negative test", !is_positive_test); diff --git a/src/tests/test_tls_protocol_version.cpp b/src/tests/test_tls_protocol_version.cpp new file mode 100644 index 00000000000..9d184f55e37 --- /dev/null +++ b/src/tests/test_tls_protocol_version.cpp @@ -0,0 +1,147 @@ +/* +* (C) 2026 Jack Lloyd +* 2026 René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH +* +* Botan is released under the Simplified BSD License (see license.txt) +*/ + +#include "tests.h" + +#if defined(BOTAN_HAS_TLS) + + #include + #include + +namespace Botan_Tests { + + #if defined(BOTAN_HAS_TLS_13) || defined(BOTAN_HAS_TLS_12) + #define BOTAN_PROVIDES_SOME_TLS_VERSION + #endif + + #if defined(BOTAN_HAS_DTLS_13) || defined(BOTAN_HAS_TLS_12) /* DTLS 1.2 is not split off from TLS 1.2 */ + #define BOTAN_PROVIDES_SOME_DTLS_VERSION + #endif + +namespace { + +namespace TLS = Botan::TLS; + +[[maybe_unused]] TLS::Protocol_Version latest_tls_version_in_this_build() { + #if defined(BOTAN_HAS_TLS_13) + return TLS::Protocol_Version::TLS_V13; + #elif defined(BOTAN_HAS_TLS_12) + return TLS::Protocol_Version::TLS_V12; + #else + throw Test_Error("No TLS in this build, some #ifdef issue in the test code?"); + #endif +} + +[[maybe_unused]] TLS::Protocol_Version latest_dtls_version_in_this_build() { + #if defined(BOTAN_HAS_DTLS_13) + return TLS::Protocol_Version::DTLS_V13; + #elif defined(BOTAN_HAS_TLS_12) + return TLS::Protocol_Version::DTLS_V12; + #else + throw Test_Error("No DTLS in this build, some #ifdef issue in the test code?"); + #endif +} + +std::vector tls_protocol_version_wrapper() { + return { + CHECK("protocol version factories", + [&](Test::Result& result) { + #if defined(BOTAN_PROVIDES_SOME_TLS_VERSION) + result.test_is_true("latest_tls_version() returns correct version", + TLS::Protocol_Version::latest_tls_version() == latest_tls_version_in_this_build()); + #else + result.test_throws( + "latest_tls_version() not available in this build", + []{ TLS::Protocol_Version::latest_tls_version(); }); + #endif + + #if defined(BOTAN_PROVIDES_SOME_DTLS_VERSION) + result.test_is_true("latest_dtls_version() returns correct version", + TLS::Protocol_Version::latest_dtls_version() == latest_dtls_version_in_this_build()); + #else + result.test_throws( + "latest_dtls_version() not available in this build", + []{ TLS::Protocol_Version::latest_dtls_version(); }); + #endif + }), + + CHECK("default constructor", + [&](Test::Result& result) { + const TLS::Protocol_Version v; + result.test_is_true("returns invalid version", !v.valid()); + result.test_is_true("returns unknown version", !v.known_version()); + }), + + CHECK("concrete constructors", + [&](Test::Result& result) { + using PV = TLS::Protocol_Version; + + auto check = [&](const PV& pv, std::string_view expected) { + result.test_str_eq("to_string() for " + std::string(expected), pv.to_string(), expected); + }; + + check(PV(0x0301), "TLS v1.0"); + check(PV(0x0302), "TLS v1.1"); + check(PV(0x0303), "TLS v1.2"); + check(PV(0x0304), "TLS v1.3"); + + check(PV(0xFEFF), "DTLS v1.0"); + check(PV(0xFEFD), "DTLS v1.2"); + check(PV(0xFEFC), "DTLS v1.3"); + + check(PV(PV::TLS_V11), "TLS v1.1"); + check(PV(PV::TLS_V12), "TLS v1.2"); + check(PV(PV::TLS_V13), "TLS v1.3"); + + check(PV(PV::DTLS_V10), "DTLS v1.0"); + check(PV(PV::DTLS_V12), "DTLS v1.2"); + check(PV(PV::DTLS_V13), "DTLS v1.3"); + + check(PV(3, 0), "SSL v3"); + check(PV(2, 0), "Unknown 2.0"); + }), + + CHECK("detect pre-TLS 1.3", + [](Test::Result& result) { + using PV = TLS::Protocol_Version; + + result.test_is_true("TLS v1.1 is pre-TLS 1.3", PV(PV::TLS_V11).is_pre_tls_13()); + result.test_is_true("TLS v1.2 is pre-TLS 1.3", PV(PV::TLS_V12).is_pre_tls_13()); + result.test_is_true("TLS v1.3 is not pre-TLS 1.3", !PV(PV::TLS_V13).is_pre_tls_13()); + result.test_is_true("(hypothetical) TLS v1.4 is not pre-TLS 1.3", !PV(0x0305).is_pre_tls_13()); + + result.test_is_true("DTLS v1.0 is pre-TLS 1.3", PV(PV::DTLS_V10).is_pre_tls_13()); + result.test_is_true("DTLS v1.2 is pre-TLS 1.3", PV(PV::DTLS_V12).is_pre_tls_13()); + result.test_is_true("DTLS v1.2 is pre-TLS 1.3", PV(PV::DTLS_V12).is_pre_tls_13()); + result.test_is_true("DTLS v1.3 is not pre-TLS 1.3", !PV(PV::DTLS_V13).is_pre_tls_13()); + result.test_is_true("(hypothetical) DTLS v1.4 is not pre-TLS 1.3", !PV(0xFEFB).is_pre_tls_13()); + }), + + CHECK("detect TLS 1.3 or later", + [](Test::Result& result) { + using PV = TLS::Protocol_Version; + + result.test_is_true("TLS v1.1 is not TLS 1.3 or later", !PV(PV::TLS_V11).is_tls_13_or_later()); + result.test_is_true("TLS v1.2 is not TLS 1.3 or later", !PV(PV::TLS_V12).is_tls_13_or_later()); + result.test_is_true("TLS v1.3 is TLS 1.3 or later", PV(PV::TLS_V13).is_tls_13_or_later()); + result.test_is_true("(hypothetical) TLS v1.4 is TLS 1.3 or later", PV(0x0305).is_tls_13_or_later()); + + result.test_is_true("DTLS v1.0 is not TLS 1.3 or later", !PV(PV::DTLS_V10).is_tls_13_or_later()); + result.test_is_true("DTLS v1.2 is not TLS 1.3 or later", !PV(PV::DTLS_V12).is_tls_13_or_later()); + result.test_is_true("DTLS v1.3 is TLS 1.3 or later", PV(PV::DTLS_V13).is_tls_13_or_later()); + result.test_is_true("(hypothetical) DTLS v1.4 is TLS 1.3 or later", PV(0xFEFB).is_tls_13_or_later()); + }), + }; +} + +} // namespace + +BOTAN_REGISTER_TEST_FN("tls", "tls_protocol_version", tls_protocol_version_wrapper); + +} // namespace Botan_Tests + +#endif diff --git a/src/tests/test_tls_record_layer_13.cpp b/src/tests/test_tls_record_layer_13.cpp index 4f0da93b7c8..f02157b872b 100644 --- a/src/tests/test_tls_record_layer_13.cpp +++ b/src/tests/test_tls_record_layer_13.cpp @@ -116,7 +116,7 @@ std::vector read_full_records() { [&](auto& result) { auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Server); - rl.copy_data(ccs_record); + rl.copy_data(ccs_record, true); auto read = rl.next_record(); result.require("received something", !std::holds_alternative(read)); @@ -132,7 +132,7 @@ std::vector read_full_records() { auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Server); - rl.copy_data(two_ccs_records); + rl.copy_data(two_ccs_records, true); auto read = rl.next_record(); result.require("received something", !std::holds_alternative(read)); @@ -150,7 +150,7 @@ std::vector read_full_records() { CHECK("read full handshake message", [&](auto& result) { auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Server); - rl.copy_data(client_hello_record); + rl.copy_data(client_hello_record, true); auto read = rl.next_record(); result.test_is_true("received something", !std::holds_alternative(read)); @@ -167,7 +167,7 @@ std::vector read_full_records() { const auto payload = Botan::concat(client_hello_record, ccs_record); auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Server); - rl.copy_data(payload); + rl.copy_data(payload, true); auto read = rl.next_record(); result.require("received something", !std::holds_alternative(read)); @@ -193,7 +193,7 @@ std::vector basic_sanitization_parse_records() { // influences the sending compat mode. Hence, a single run of this suite is // sufficient (arbitrarily hardcoded to server). auto rl = Botan::TLS::TLS_Record_Layer(TLS::Connection_Side::Server); - rl.copy_data(data); + rl.copy_data(data, true); return rl.next_record(cs); }; @@ -290,24 +290,24 @@ std::vector basic_sanitization_parse_records() { CHECK("initial received record versions might be 0x03XX ", [&](auto& result) { auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - rl.copy_data(std::vector{0x16, 0x03, 0x00, 0x00, 0x01, 0x42}); + rl.copy_data(std::vector{0x16, 0x03, 0x00, 0x00, 0x01, 0x42}, true); result.test_no_throw("0x03 0x00 should be fine for first records", [&] { rl.next_record(); }); - rl.copy_data(std::vector{0x16, 0x03, 0x01, 0x00, 0x01, 0x42}); + rl.copy_data(std::vector{0x16, 0x03, 0x01, 0x00, 0x01, 0x42}, true); result.test_no_throw("0x03 0x01 should be fine for first records", [&] { rl.next_record(); }); - rl.copy_data(std::vector{0x16, 0x03, 0x02, 0x00, 0x01, 0x42}); + rl.copy_data(std::vector{0x16, 0x03, 0x02, 0x00, 0x01, 0x42}, true); result.test_no_throw("0x03 0x02 should be fine for first records", [&] { rl.next_record(); }); - rl.copy_data(std::vector{0x16, 0x03, 0x03, 0x00, 0x01, 0x42}); + rl.copy_data(std::vector{0x16, 0x03, 0x03, 0x00, 0x01, 0x42}, true); result.test_no_throw("0x03 0x03 should be fine for first records", [&] { rl.next_record(); }); rl.disable_receiving_compat_mode(); - rl.copy_data(std::vector{0x16, 0x03, 0x03, 0x00, 0x01, 0x42}); + rl.copy_data(std::vector{0x16, 0x03, 0x03, 0x00, 0x01, 0x42}, true); result.test_no_throw("0x03 0x03 is okay regardless", [&] { rl.next_record(); }); - rl.copy_data(std::vector{0x16, 0x03, 0x01, 0x00, 0x01, 0x42}); + rl.copy_data(std::vector{0x16, 0x03, 0x01, 0x00, 0x01, 0x42}, true); result.test_throws("0x03 0x01 not okay once client hello was received", [&] { rl.next_record(); }); }), @@ -327,7 +327,7 @@ std::vector read_fragmented_records() { auto wait_for_more_bytes = [](Botan::TLS::BytesNeeded bytes_needed, auto& record_layer, std::vector bytes, auto& result) { - record_layer.copy_data(bytes); + record_layer.copy_data(bytes, true); const auto rlr = record_layer.next_record(); if(result.test_is_true("waiting for bytes", std::holds_alternative(rlr))) { result.test_sz_eq("right amount", std::get(rlr), bytes_needed); @@ -344,7 +344,7 @@ std::vector read_fragmented_records() { wait_for_more_bytes(1, rl, {'\x00'}, result); wait_for_more_bytes(1, rl, {'\x01'}, result); - rl.copy_data(std::vector{'\x01'}); + rl.copy_data(std::vector{'\x01'}, true); auto res1 = rl.next_record(); result.require("received something 1", !std::holds_alternative(res1)); @@ -357,7 +357,7 @@ std::vector read_fragmented_records() { CHECK("two change cipher specs in several pieces", [&](auto& result) { wait_for_more_bytes(1, rl, {'\x14', '\x03', '\x03', '\x00'}, result); - rl.copy_data(std::vector{'\x01', '\x01', /* second CCS starts here */ '\x14', '\x03'}); + rl.copy_data(std::vector{'\x01', '\x01', /* second CCS starts here */ '\x14', '\x03'}, true); auto res2 = rl.next_record(); result.require("received something 2", !std::holds_alternative(res2)); @@ -367,7 +367,7 @@ std::vector read_fragmented_records() { wait_for_more_bytes(2, rl, {'\x03'}, result); - rl.copy_data(std::vector{'\x00', '\x01', '\x01'}); + rl.copy_data(std::vector{'\x00', '\x01', '\x01'}, true); auto res3 = rl.next_record(); result.require("received something 3", !std::holds_alternative(res3)); @@ -519,7 +519,7 @@ std::vector read_encrypted_records() { auto parse_records = [](const std::vector& data, TLS::Cipher_State* cs) { auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - rl.copy_data(data); + rl.copy_data(data, true); return rl.next_record(cs); }; @@ -528,7 +528,7 @@ std::vector read_encrypted_records() { [&](Test::Result& result) { const auto cs = rfc8448_rtt1_handshake_traffic(); auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - rl.copy_data(encrypted_record); + rl.copy_data(encrypted_record, true); auto res = rl.next_record(cs.get()); result.require("some records decrypted", !std::holds_alternative(res)); @@ -541,7 +541,7 @@ std::vector read_encrypted_records() { CHECK("premature application data", [&](Test::Result& result) { auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - rl.copy_data(encrypted_record); + rl.copy_data(encrypted_record, true); result.test_throws( "cannot process encrypted data with uninitialized cipher state", @@ -676,7 +676,7 @@ std::vector read_encrypted_records() { Botan::hex_decode("305e4a0a7cee581b282c571b251b20138a1a6a21918937a6bb95b1e9ba1b5cac")); auto rl = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - rl.copy_data(encrypted); + rl.copy_data(encrypted, true); auto res = rl.next_record(cs.get()); result.require("decrypted a record", std::holds_alternative(res)); auto records = std::get(res); @@ -702,7 +702,7 @@ std::vector read_encrypted_records() { coalesced.insert(coalesced.end(), encrypted_record.cbegin(), encrypted_record.cend()); auto client = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - client.copy_data(coalesced); + client.copy_data(coalesced, true); const auto srv_hello = client.next_record(nullptr); result.test_is_true("is handshake record", std::holds_alternative(srv_hello)); @@ -715,7 +715,7 @@ std::vector read_encrypted_records() { CHECK("read a padded record", [&](Test::Result& result) { auto client = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - client.copy_data(encrypted_record_with_padding); + client.copy_data(encrypted_record_with_padding, true); auto cs = rfc8448_rtt1_handshake_traffic(); const auto record = client.next_record(cs.get()); @@ -724,7 +724,7 @@ std::vector read_encrypted_records() { CHECK("read an empty encrypted record", [&](Test::Result& result) { auto client = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Client); - client.copy_data(Botan::hex_decode("1703030011292e9d47d3beec9aec58466d05f7718a2c")); + client.copy_data(Botan::hex_decode("1703030011292e9d47d3beec9aec58466d05f7718a2c"), true); const auto cs = rfc8448_rtt1_appdata_traffic(); const auto record = client.next_record(cs.get()); @@ -806,7 +806,7 @@ std::vector legacy_version_handling() { }; auto parse_record = [](auto& record_layer, std::span data) { - record_layer.copy_data(data); + record_layer.copy_data(data, true); return record_layer.next_record(); }; @@ -905,7 +905,7 @@ std::vector record_size_limits() { const auto css = rfc8448_rtt1_appdata_traffic(Botan::TLS::Connection_Side::Server); auto rls = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Server); - rls.copy_data(rec1); + rls.copy_data(rec1, true); result.test_sz_eq("correct length record", record_length(result, rls.next_record(css.get())), @@ -1007,7 +1007,7 @@ std::vector record_size_limits() { rlc.set_record_size_limits(Botan::TLS::MAX_PLAINTEXT_SIZE + 1, 95 + 1); - rlc.copy_data(Botan::concat(Botan::hex_decode("16 03 03 00 80"), std::vector(128))); + rlc.copy_data(Botan::concat(Botan::hex_decode("16 03 03 00 80"), std::vector(128)), true); result.test_sz_eq("correct length record", record_length(result, rlc.next_record()), 128); }), @@ -1019,23 +1019,23 @@ std::vector record_size_limits() { auto rls = Botan::TLS::TLS_Record_Layer(Botan::TLS::Connection_Side::Server); rls.set_record_size_limits(Botan::TLS::MAX_PLAINTEXT_SIZE + 1, message_length + 1); - rls.copy_data( - Botan::hex_decode("170303007a7b18af30323eb7a60629f6364a69807a966207008d04809355" - "4e5b37c28b8595e493bc95dedae341d7cbddbe469ac2f92b513dc244a8df" - "f73587f0a879345c2966189820edc5a58873188a4de5f6e98d0b180725f9" - "2beec3b27a30c395ce53653f6278c30dc2a7379ed78be6d0362924a2cb8d" - "c9b3daf435ae6e")); + rls.copy_data(Botan::hex_decode("170303007a7b18af30323eb7a60629f6364a69807a966207008d04809355" + "4e5b37c28b8595e493bc95dedae341d7cbddbe469ac2f92b513dc244a8df" + "f73587f0a879345c2966189820edc5a58873188a4de5f6e98d0b180725f9" + "2beec3b27a30c395ce53653f6278c30dc2a7379ed78be6d0362924a2cb8d" + "c9b3daf435ae6e"), + true); result.test_sz_eq( "correct length record", record_length(result, rls.next_record(css.get())), message_length); - rls.copy_data( - Botan::hex_decode("17030300987b18af30323eb7a60629f6364a69807a966207008d04809355" - "4e5b37c28b8595e493bc95dedae341d7cbddbe469ac2f92b513dc244a8df" - "f73587f0a879345c2966189820edc5a58873188a4de5f6e98d0b180725f9" - "2beec3b27a30c395ce53653f6278c30dc2a7379ee00af947d947e1dccf47" - "165c507c6c70682342aefce4cc9330b9808613f45cf792d31a16e2533c58" - "795473aea6c700")); + rls.copy_data(Botan::hex_decode("17030300987b18af30323eb7a60629f6364a69807a966207008d04809355" + "4e5b37c28b8595e493bc95dedae341d7cbddbe469ac2f92b513dc244a8df" + "f73587f0a879345c2966189820edc5a58873188a4de5f6e98d0b180725f9" + "2beec3b27a30c395ce53653f6278c30dc2a7379ee00af947d947e1dccf47" + "165c507c6c70682342aefce4cc9330b9808613f45cf792d31a16e2533c58" + "795473aea6c700"), + true); result.test_throws("overflow detected", "Received an encrypted record that exceeds maximum plaintext size", diff --git a/src/tests/test_tls_rfc8448.cpp b/src/tests/test_tls_rfc8448.cpp index 37b648e09ca..94a2866c008 100644 --- a/src/tests/test_tls_rfc8448.cpp +++ b/src/tests/test_tls_rfc8448.cpp @@ -832,6 +832,7 @@ Botan::TLS::Session as_server_session(const Botan::TLS::Session& session) { {}, nullptr, session.server_info(), + 0, session.start_time()); } diff --git a/src/tests/test_tls_session_manager.cpp b/src/tests/test_tls_session_manager.cpp index 248304bb1a6..ac1ebfee792 100644 --- a/src/tests/test_tls_session_manager.cpp +++ b/src/tests/test_tls_session_manager.cpp @@ -173,6 +173,7 @@ decltype(auto) default_session(Botan::TLS::Connection_Side side, {}, nullptr, server_info(), + 0, start_time); #else throw Test_Error("TLS 1.3 is not available in this build"); @@ -536,6 +537,7 @@ std::vector test_session_manager_choose_ticket() { {}, nullptr, server_info(), + 0, mycbs.tls_current_timestamp()); }; @@ -1534,6 +1536,7 @@ std::vector tls_session_manager_lifetime_edge_cases() { {}, nullptr, server_info(), + 0, start), random_id(*rng)); @@ -1583,6 +1586,7 @@ std::vector tls_session_manager_lifetime_edge_cases() { {}, nullptr, Botan::TLS::Server_Information(host), + 0, start); }; diff --git a/src/tests/unit_tls.cpp b/src/tests/unit_tls.cpp index 1edf7808847..bd0e5b1ca3a 100644 --- a/src/tests/unit_tls.cpp +++ b/src/tests/unit_tls.cpp @@ -1041,8 +1041,11 @@ class TLS_Unit_Tests final : public Test { policy->set("allow_dtls12", "true"); } else if(version == Botan::TLS::Protocol_Version::TLS_V13) { policy->set("allow_tls13", "true"); + } else if(version == Botan::TLS::Protocol_Version::DTLS_V13) { + policy->set("allow_dtls13", "true"); + } else { + throw Test_Error("Unknown version " + version.to_string()); } - // TODO(DTLS13): once implemented, map DTLS_V13 -> allow_dtls13 here. } } @@ -1054,7 +1057,7 @@ class TLS_Unit_Tests final : public Test { policy->set("allow_tls12", "false"); policy->set("allow_tls13", "false"); policy->set("allow_dtls12", "false"); - // TODO(DTLS13): once implemented, also set allow_dtls13=false here. + policy->set("allow_dtls13", "false"); enable_versions(policy, versions); } @@ -1633,6 +1636,7 @@ class TLS_Unit_Tests final : public Test { .offer_version = PV::TLS_V12, .expected_version = std::nullopt, }, + }; const auto make_policy = [&](std::span versions) { @@ -3075,7 +3079,7 @@ class TLS_Unit_Tests final : public Test { // TLS version negotiation / downgrade (and mismatch failures) - #if defined(BOTAN_HAS_TLS_12) && defined(BOTAN_HAS_TLS_13) + #if defined(BOTAN_HAS_TLS_DOWNGRADE_SUPPORT) test_version_negotiation(results, creds, rng); #endif From 3cc60b39b8999aeb09aa843102f6f9d5eb118273 Mon Sep 17 00:00:00 2001 From: Amos Treiber Date: Fri, 30 Oct 2026 14:04:42 +0000 Subject: [PATCH 2/2] Unify Handshake_Layer and rework Channel_IO post-handshake handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prepares the shared TLS 1.3 base layers for the DTLS 1.3 implementation module. All changes are in TLS base files and behave identically for TLS, with one exception noted below. * Handshake_Layer: replace the per-flavor virtual next_message() and next_post_handshake_message() by non-virtual implementations that are built on a single hook, fetch_next_message_buffer_view(). The flavors merely provide the next message (including its epoch, if any) and the base class does the policy size check, parsing, transcript update and the RFC 9846 5.1 "no key change within a record" validation. The handshake message type validation no longer distinguishes handshake and post-handshake phases; the parsers reject unexpected types as before. The validation of excess handshake data moves from Channel_IO into the handshake layer, hence the BoGo error mapping is adapted. * Channel_IO: introduce can_send_post_handshake_messages() in place of can_send_key_update(); Channel_Impl_13 and Server_Impl_13 refuse to send KeyUpdates and NewSessionTickets when it is false (DTLS may have to wait for the acknowledgement of a pending KeyUpdate). The opportunistic KeyUpdate logic in send() is folded into maybe_send_opportunistic_key_update(). Add the validate() hook for records that Channel_IO merely passes through, so TLS can reject the interleaving of handshake and other records while DTLS may tolerate it. * Generalize variant_append_t to append multiple alternatives. * Channel_IO: restructure maybe_send_opportunistic_key_update() so that it decides once whether to send a single KeyUpdate and whether to request a peer update. As a side effect, a peer update is no longer requested when the peer has already half-closed its side of the connection. * Channel_IO: make notify_closed_for_reading() virtual, add the virtual notify_closed_for_writing() (called by Channel_Impl_13 once close_notify was sent) and let notify_shutdown() invoke both. validate() is no longer const so that implementations may keep state while inspecting passed-through records. Co-Authored-By: René Meusel --- src/bogo_shim/bogo_shim.cpp | 4 +- src/fuzzer/tls_13_handshake_layer.cpp | 3 +- src/lib/tls/tls13/tls_channel_impl_13.cpp | 18 + src/lib/tls/tls13/tls_channel_io.cpp | 201 +++++------ src/lib/tls/tls13/tls_channel_io.h | 70 ++-- src/lib/tls/tls13/tls_handshake_layer_13.cpp | 356 +++++++++++-------- src/lib/tls/tls13/tls_handshake_layer_13.h | 95 +++-- src/lib/tls/tls13/tls_server_impl_13.cpp | 17 +- src/lib/tls/tls_channel_impl.h | 10 + src/lib/utils/stl_util.h | 12 +- src/tests/test_tls_channel_io.cpp | 2 +- src/tests/test_tls_handshake_layer_13.cpp | 116 +++++- src/tests/test_tls_protocol_version.cpp | 4 +- src/tests/unit_tls.cpp | 23 ++ 14 files changed, 600 insertions(+), 331 deletions(-) diff --git a/src/bogo_shim/bogo_shim.cpp b/src/bogo_shim/bogo_shim.cpp index f45ac80dc47..ea5478d8fc7 100644 --- a/src/bogo_shim/bogo_shim.cpp +++ b/src/bogo_shim/bogo_shim.cpp @@ -204,7 +204,8 @@ std::string map_to_bogo_error(const std::string& e, std::string_view test_name) {"Have data remaining in buffer after Finished", ":EXCESS_HANDSHAKE_DATA:"}, {"Have data remaining in buffer after ServerHelloDone", ":EXCESS_HANDSHAKE_DATA:"}, {"Hello Retry Request does not request any changes to Client Hello", ":EMPTY_HELLO_RETRY_REQUEST:"}, - {"Unexpected additional handshake message data found in record", ":EXCESS_HANDSHAKE_DATA:"}, + {"Unexpected additional handshake data at epoch boundary", ":EXCESS_HANDSHAKE_DATA:"}, + {"Unexpected additional post-handshake data at epoch boundary", ":EXCESS_HANDSHAKE_DATA:"}, {"Inconsistent length in certificate request", ":DECODE_ERROR:"}, {"Inconsistent length in certificate_authorities extension", ":DECODE_ERROR:"}, {"unexpected key_update parameter", ":DECODE_ERROR:"}, @@ -243,6 +244,7 @@ std::string map_to_bogo_error(const std::string& e, std::string_view test_name) {"PSK binder does not check out", ":DIGEST_CHECK_FAILED:"}, {"PSK identity selected by server is out of bounds", ":PSK_IDENTITY_NOT_FOUND:"}, {"PSK and ciphersuite selected by server are not compatible", ":OLD_SESSION_PRF_HASH_MISMATCH:"}, + {"Received a new post-handshake message under an outdated epoch", ":EXCESS_HANDSHAKE_DATA:"}, {"Received an unexpectedly non-empty Certificate_Status_Request", ":DECODE_ERROR:"}, {"Received a record that exceeds maximum size", ":ENCRYPTED_LENGTH_TOO_LONG:"}, {"Received a protected record that exceeds maximum size", ":ENCRYPTED_LENGTH_TOO_LONG:"}, diff --git a/src/fuzzer/tls_13_handshake_layer.cpp b/src/fuzzer/tls_13_handshake_layer.cpp index 4bf6191b720..9c4cfd73cfd 100644 --- a/src/fuzzer/tls_13_handshake_layer.cpp +++ b/src/fuzzer/tls_13_handshake_layer.cpp @@ -14,6 +14,7 @@ void fuzz(std::span in) { static const Botan::TLS::Default_Policy policy; + constexpr auto epoch_appdata_0 = Botan::TLS::EpochNumber::create(3); const auto in_record = Botan::TLS::Handshake_Record{ {.type = Botan::TLS::Record_Type::Handshake, @@ -30,6 +31,6 @@ void fuzz(std::span in) { auto hl2 = Botan::TLS::TLS_Handshake_Layer(Botan::TLS::Connection_Side::Client); std::ignore = hl2.copy_data(policy, in_record); - while(hl2.next_post_handshake_message(policy).has_value()) {}; + while(hl2.next_post_handshake_message(policy, epoch_appdata_0).has_value()) {}; } catch(const Botan::Exception& e) {} } diff --git a/src/lib/tls/tls13/tls_channel_impl_13.cpp b/src/lib/tls/tls13/tls_channel_impl_13.cpp index 3b5124a05cc..ca0442760a9 100644 --- a/src/lib/tls/tls13/tls_channel_impl_13.cpp +++ b/src/lib/tls/tls13/tls_channel_impl_13.cpp @@ -189,6 +189,7 @@ void Channel_Impl_13::send_alert(const Alert& alert) { if(m_cipher_state) { m_cipher_state->clear_write_keys(); } + m_channel_io->notify_closed_for_writing(); } if(is_error_alert(alert)) { @@ -211,6 +212,23 @@ SymmetricKey Channel_Impl_13::key_material_export(std::string_view label, void Channel_Impl_13::update_traffic_keys(bool request_peer_update) { BOTAN_STATE_CHECK(!is_downgrading() && is_handshake_complete() && is_active()); + + // RFC 9147 8. + // In order to facilitate epoch reconstruction, implementations MUST NOT + // send records with the new keys or send a new KeyUpdate until the + // previous KeyUpdate has been acknowledged (this avoids having too many + // epochs in active use). + // + // For DTLS this will prevent sending a KeyUpdate while a previous one is not + // yet acknowledged. For TLS this will always be true once the handshake has + // completed and the connection is active. + if(!m_channel_io->can_send_post_handshake_messages()) { + throw Invalid_State( + "Cannot send KeyUpdate messages right now. " + "Probably you're using DTLS and another KeyUpdate is currently pending. " + "Please try again later."); + } + m_channel_io->update_traffic_keys(request_peer_update); } diff --git a/src/lib/tls/tls13/tls_channel_io.cpp b/src/lib/tls/tls13/tls_channel_io.cpp index 42dd6732024..b307af80aaa 100644 --- a/src/lib/tls/tls13/tls_channel_io.cpp +++ b/src/lib/tls/tls13/tls_channel_io.cpp @@ -29,58 +29,34 @@ std::optional Channel_IO::next_pending_handshake_messa if(!handshake_complete) { BOTAN_ASSERT_NOMSG(transcript_hash.has_value()); + + // TODO(C++23): use std::optional::transform() here auto handshake_msg = hs_layer.next_message(policy(), *transcript_hash); if(!handshake_msg.has_value()) { return std::nullopt; } - // RFC 9846 5.1 - // Handshake messages MUST NOT span key changes. Implementations - // MUST verify that all messages immediately preceding a key change - // align with a record boundary; if not, then they MUST terminate the - // connection with an "unexpected_message" alert. Because the - // ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate - // messages can immediately precede a key change, implementations - // MUST send these messages in alignment with a record boundary. - // - // Note: Hello_Retry_Request was added to the list below although it - // cannot immediately precede a key change. However, there cannot be - // any further sensible messages in the record after HRR. - // - // Note: Server_Hello_12 was deliberately not included in the check below - // because in TLS 1.2 Server Hello and other handshake messages can - // be legally coalesced in a single record. - // - if(holds_any_of(handshake_msg.value()) && - hs_layer.has_pending_data()) { - throw Unexpected_Message("Unexpected additional handshake message data found in record"); - } - // After the initial handshake message is received, the record // layer must be more restrictive. // See RFC 9846 5.1 regarding "legacy_record_version" if(!m_first_message_delivered) { + // TODO: Consider always calling disable_receiving_compat_mode + // to get rid of m_first_message_delivered rec_layer.disable_receiving_compat_mode(); m_first_message_delivered = true; } return std::move(handshake_msg).value(); } else { - auto post_handshake_msg = hs_layer.next_post_handshake_message(policy()); + auto cs = cipher_state(); + BOTAN_ASSERT_NONNULL(cs); + + // TODO(C++23): use std::optional::transform() here + auto post_handshake_msg = hs_layer.next_post_handshake_message(policy(), cs->current_read_epoch_number()); if(!post_handshake_msg.has_value()) { return std::nullopt; } - // make sure Key_Update appears only at the end of a record; see RFC - // 9846 5.1 description above - if(std::holds_alternative(post_handshake_msg.value()) && hs_layer.has_pending_data()) { - throw Unexpected_Message("Unexpected additional post-handshake message data found in record"); - } - return std::move(post_handshake_msg).value(); } } @@ -124,13 +100,9 @@ Channel_IO::ReceiveEvent Channel_IO::next_pending_event(std::optional std::optional { - // RFC 8446 5.1 - // Handshake messages MUST NOT be interleaved with other record types. - if(handshake_layer().has_pending_data()) { - throw Unexpected_Message("Expected remainder of a handshake message"); - } - return anything_else; + [&](TransparentRecord anything_else) -> std::optional { + validate(anything_else); + return generalize_to(std::move(anything_else)); }, }, record_layer().next_record(cs.get())); @@ -146,43 +118,23 @@ void Channel_IO::send(std::vector flight) { } void Channel_IO::send(std::span payload) { - // RFC 9846 4.7.3 - // If the request_update field [of a received KeyUpdate] is set to - // "update_requested", then the receiver MUST send a KeyUpdate of its own - // with request_update set to "update_not_requested" prior to sending its - // next Application Data record. This mechanism allows either side to - // force an update to the entire connection, but causes an implementation - // which receives multiple KeyUpdates while it is silent to respond with - // a single update. - if(m_key_update_reciprocation_pending) { - update_traffic_keys(false /* update_requested */); - } else if(needs_traffic_based_key_update()) { - // If approaching traffic limits request the peer update their own keys - // as well, unless an earlier request is still unanswered: - // - // RFC 9846 4.7.3 - // Until receiving a subsequent KeyUpdate from the peer, the sender - // MUST NOT send another KeyUpdate with request_update set to - // "update_requested". - update_traffic_keys(!m_key_update_requested); - } - const auto cs = cipher_state(); BOTAN_ASSERT_NONNULL(cs); + maybe_send_opportunistic_key_update(); send_data(Record_Type::ApplicationData, payload, cs.get()); } -/** - * RFC 9846 Section 5.5 - * Implementations MUST either close the connection or do a key update as - * described in Section 4.7.3 prior to reaching these limits. - * - * [This is a SHOULD in RFC 8446] - * - * The ChaCha-based suites don't have any practical usage limit but we - * apply the limit for all suites for simplicity. - */ -bool Channel_IO::needs_traffic_based_key_update() const { +void Channel_IO::maybe_send_opportunistic_key_update() { + // In DTLS we cannot send KeyUpdates while a previous one is not yet + // acknowledged. In that case, we skip the opportunistic update silently and + // try again whenever the application sends more data. + if(!can_send_post_handshake_messages()) { + return; + } + + const auto cs = cipher_state(); + BOTAN_ASSERT_NONNULL(cs); + // RFC 9846 5.5 // There are cryptographic limits on the amount of plaintext which can be // safely encrypted under a given set of keys. [...] Implementations MUST @@ -190,37 +142,47 @@ bool Channel_IO::needs_traffic_based_key_update() const { // 4.7.3 prior to reaching these limits. // // The ChaCha-based suites don't have any practical usage limit but we apply - // the limit for all suites for simplicity. - const uint64_t limit = policy().records_per_traffic_key(); - const auto cs = cipher_state(); - BOTAN_ASSERT_NONNULL(cs); + // the limit for all suites for simplicity. A limit of 0 means that the + // policy disabled traffic-based key updates altogether. + const uint64_t write_limit = policy().records_per_traffic_key(); - // Have to skip this if the handshake is not yet completed since we can't - // send a KeyUpdate in the (unlikely) case that the limit is hit with - // half-RTT data. If it is we just defer until the handshake completes. - if(limit == 0 || !cs->is_handshake_complete()) { - return false; - } + const bool write_limit_reached = write_limit > 0 && cs->current_write_sequence_number() >= write_limit; - // If we half-closed the connection for writing, i.e. we cannot encrypt - // application traffic any longer, naturally, we won't need to update our - // traffic keys. - if(cs->can_encrypt_application_traffic() && cs->current_write_sequence_number() >= limit) { - return true; - } + const auto read_limit_reached = [&] { + // The read threshold is set above the write-side limit so that a peer + // which tracks its own write limit will normally have rotated its keys + // already, avoiding a redundant key update crossing ours in flight. + const uint64_t read_limit = write_limit + write_limit / 2; + return write_limit > 0 && cs->current_read_sequence_number() >= read_limit; + }; - // For the read side all we can do is ask the peer to update its keys, - // and only if no earlier request is still outstanding. The threshold is - // set above the write-side limit so that a peer which tracks its own - // write limit will normally have rotated its keys already, avoiding a - // redundant key update crossing ours in flight. + // RFC 9846 4.7.3 + // If the request_update field [of a received KeyUpdate] is set to + // "update_requested", then the receiver MUST send a KeyUpdate of its own + // with request_update set to "update_not_requested" prior to sending its + // next Application Data record. This mechanism allows either side to + // force an update to the entire connection, but causes an implementation + // which receives multiple KeyUpdates while it is silent to respond with + // a single update. + // + // Until receiving a subsequent KeyUpdate from the peer, the sender MUST + // NOT send another KeyUpdate with [...] "update_requested". // - // Note: if the peer half-closed their connection for writing, i.e we - // destroyed the receive traffic keys, there's no point in requesting a key - // update from them. - const uint64_t read_limit = limit + limit / 2; - return !m_key_update_requested && cs->can_decrypt_application_traffic() && - cs->current_read_sequence_number() >= read_limit; + // Requesting an update is also pointless if the peer half-closed its + // connection already, as it won't send any more records anyway. + const bool may_request_peer_update = + !m_key_update_reciprocation_pending && !m_key_update_requested && cs->can_decrypt_application_traffic(); + + // We cannot update the read keys ourselves, all we can do is request the + // peer to update its write keys. We do that alongside any update of our own + // write keys, provided that we are allowed to request one. + const bool request_peer_update = may_request_peer_update && // + (write_limit_reached || // + read_limit_reached()); + + if(m_key_update_reciprocation_pending || write_limit_reached || request_peer_update) { + update_traffic_keys(request_peer_update); + } } void Channel_IO::handle_key_update(const Key_Update& key_update) { @@ -266,18 +228,11 @@ void Channel_IO::handle_key_update(const Key_Update& key_update) { } void Channel_IO::update_traffic_keys(bool request_peer_update) { + BOTAN_ASSERT_NOMSG(can_send_post_handshake_messages()); + const auto cs = cipher_state(); BOTAN_ASSERT_NONNULL(cs); - // In DTLS we cannot send a KeyUpdate while a previous one is not yet - // acknowledged. In that case, we just skip the update silently. Note that if - // called in `Channel_IO::send` because m_key_update_reciprocation_pending is - // true, this flag will remain true and a reciprocation will be tried again - // during the next call to `Channel_IO::send`. - if(!can_send_key_update()) { - return; - } - const auto key_update = Key_Update(request_peer_update); callbacks().tls_inspect_handshake_msg(key_update); send_key_update(key_update); @@ -291,6 +246,15 @@ void Channel_IO::update_traffic_keys(bool request_peer_update) { } } +bool Channel_IO::can_send_post_handshake_messages() const { + // RFC 9846 4.7 + // TLS also allows other messages to be sent after the main handshake. + // These messages use a handshake content type and are encrypted under the + // appropriate application traffic key. + auto cs = cipher_state(); + return cs != nullptr && cs->is_handshake_complete() && cs->can_encrypt_application_traffic(); +} + void Channel_IO::send(const Alert& alert, bool handle_compat_mode) { const auto cs = cipher_state(); @@ -331,9 +295,7 @@ void Channel_IO::notify_closed_for_reading() { m_closed_for_reading = true; } -void Channel_IO::notify_shutdown() { - notify_closed_for_reading(); -} +void Channel_IO::notify_closed_for_writing() {} void Channel_IO::set_record_size_limits(uint16_t out, uint16_t in) { record_layer().set_record_size_limits(out, in); @@ -494,6 +456,23 @@ class TLS_Channel_IO final : public Channel_IO { std::ignore = m_handshake_layer.copy_data(policy(), record); } + void validate(const TransparentRecord& record) override { + BOTAN_UNUSED(record); + + // RFC 9846 5.1 + // Handshake messages MUST NOT be interleaved with other record types. + // That is, if a handshake message is split over two or more records, + // there MUST NOT be any other records between them. + // + // If there is any pending data currently stored in the handshake layer + // it must be an incomplete handshake message. The event loop in + // Channel_IO::next_pending_event() ensures that all completed messages + // are drained to the channel before any other records are processed. + if(handshake_layer().has_pending_data()) { + throw Unexpected_Message("Expected remainder of a handshake message"); + } + } + Record_Layer& record_layer() override { return m_record_layer; } const Record_Layer& record_layer() const override { return m_record_layer; } diff --git a/src/lib/tls/tls13/tls_channel_io.h b/src/lib/tls/tls13/tls_channel_io.h index b3308004ef0..539895bccdf 100644 --- a/src/lib/tls/tls13/tls_channel_io.h +++ b/src/lib/tls/tls13/tls_channel_io.h @@ -9,6 +9,7 @@ #ifndef BOTAN_TLS_CHANNEL_IO_BASE_H_ #define BOTAN_TLS_CHANNEL_IO_BASE_H_ +#include #include #include #include @@ -29,13 +30,19 @@ struct RecordNumber; * send() overloads. */ class BOTAN_TEST_API Channel_IO { + protected: + /// Records that the I/O object just passes out to the channel for further + /// processing. These records are not processed by the I/O object itself, + /// they may be used for validation of protocol invariants, though. + using TransparentRecord = std::variant; + public: - using ReceiveEvent = std::variant; + using ReceiveEvent = variant_append_t; static std::shared_ptr create(Connection_Side side, TLS_Flavor flavor, @@ -97,8 +104,8 @@ class BOTAN_TEST_API Channel_IO { /** * Sends a KeyUpdate message to the peer and updates the write keys once - * the transport allows it. Silently does nothing if no KeyUpdate may be - * sent right now (see can_send_key_update()). + * the transport allows it. Note that this assumes that post-handshake + * messages are allowed to be sent when this is invoked. * * @param request_peer_update whether to request a reciprocal KeyUpdate */ @@ -109,6 +116,15 @@ class BOTAN_TEST_API Channel_IO { /// @name DTLS-specific state management /// @{ + /** + * Whether it is currently possible to send post-handshake messages like + * KeyUpdate or NewSessionTicket. Note that DTLS might intermittently deny + * sending such messages while a recent KeyUpdate is not yet acknowledged. + * + * @returns true if post-handshake messages may be sent, false otherwise + */ + virtual bool can_send_post_handshake_messages() const; + /** * Notifies that the TLS state machine is sure that we're talking to a * peer using (D)TLS 1.3. Typically that is the case after receiving and @@ -122,8 +138,7 @@ class BOTAN_TEST_API Channel_IO { * For the case of receiving a HelloRetryRequest, use * notify_protocol_version_committed_and_flight_superseded(). */ - virtual void notify_protocol_version_committed() { /* don't care */ - } + virtual void notify_protocol_version_committed() {} /** * Like notify_protocol_version_committed(), but for the case where @@ -136,8 +151,7 @@ class BOTAN_TEST_API Channel_IO { * protocol version, this method also clears the resend buffer and * retransmission timer. */ - virtual void notify_protocol_version_committed_and_flight_superseded() { /* don't care */ - } + virtual void notify_protocol_version_committed_and_flight_superseded() {} /** * Notifies that the last message completing a flight was received. @@ -145,8 +159,7 @@ class BOTAN_TEST_API Channel_IO { * This is relevant for DTLS: At that point, everything we need * was received and the ACK mechanism is no longer needed. */ - virtual void notify_received_complete_flight() { /* don't care */ - } + virtual void notify_received_complete_flight() {} /** * Notifies that a complete flight was received that expects no response, @@ -156,8 +169,7 @@ class BOTAN_TEST_API Channel_IO { * that would implicitly acknowledge it, the flight must be acknowledged * explicitly with an ACK message. */ - virtual void notify_received_final_flight() { /* don't care */ - } + virtual void notify_received_final_flight() {} std::optional epoch0_sequence_numbers() const; @@ -167,13 +179,23 @@ class BOTAN_TEST_API Channel_IO { * Notifies that the channel is closed for reading (close_notify received). * The IO can discard any read-side state; no further data will be processed. */ - void notify_closed_for_reading(); + virtual void notify_closed_for_reading(); + + /** + * Notifies that the channel is closed for writing (close_notify sent). + * The IO can discard any write-side state; no further data will be sent. + */ + virtual void notify_closed_for_writing(); /** * Notifies that the channel was shut down in both directions. The IO - * discards any read-side state; no further data will be processed. + * discards any read-side and write-side state; no further data will be + * processed or sent. */ - void notify_shutdown(); + void notify_shutdown() { + notify_closed_for_reading(); + notify_closed_for_writing(); + } void set_cipher_state(std::weak_ptr cipher_state) { m_cipher_state = std::move(cipher_state); } @@ -188,16 +210,10 @@ class BOTAN_TEST_API Channel_IO { void send_dummy_change_cipher_spec(); virtual void process(const Handshake_Record& record) = 0; + virtual void validate(const TransparentRecord& record) = 0; virtual void send_data(Record_Type record_type, std::span payload, Cipher_State* cipher_state) = 0; - /** - * Whether a KeyUpdate may be sent right now. Relevant for DTLS only - * (RFC 9147 8. disallows a new KeyUpdate while a previous one is not - * yet acknowledged); always true for TLS. - */ - virtual bool can_send_key_update() const { return true; } - virtual void send_flight(std::vector flight) = 0; /// Marshalls and sends the given KeyUpdate message, then advances the @@ -222,7 +238,7 @@ class BOTAN_TEST_API Channel_IO { Callbacks& callbacks() { return *m_callbacks; } private: - bool needs_traffic_based_key_update() const; + void maybe_send_opportunistic_key_update(); private: bool m_first_message_delivered = false; diff --git a/src/lib/tls/tls13/tls_handshake_layer_13.cpp b/src/lib/tls/tls13/tls_handshake_layer_13.cpp index 5d03b994460..edf4d43b58a 100644 --- a/src/lib/tls/tls13/tls_handshake_layer_13.cpp +++ b/src/lib/tls/tls13/tls_handshake_layer_13.cpp @@ -11,10 +11,11 @@ #include #include #include +#include #include #include -#include #include +#include #include #include @@ -33,118 +34,29 @@ void verify_handshake_message_size(size_t msg_len, size_t max_size) { } // namespace -Handshake_Message_13 Handshake_Layer::parse_handshake_message(Handshake_Type type, - std::span msg, - const Policy& policy) const { - switch(type) { - // Client Hello and Server Hello messages are ambiguous. Both may come - // from non-TLS 1.3 peers. Hence, their parsing is somewhat different. - case Handshake_Type::ClientHello: - // ... might be TLS 1.2 Client Hello or TLS 1.3 Client Hello - return generalize_to(Client_Hello_13::parse(msg)); - case Handshake_Type::ServerHello: - // ... might be TLS 1.2 Server Hello or TLS 1.3 Server Hello or - // a TLS 1.3 Hello Retry Request disguising as a Server Hello - return generalize_to(Server_Hello_13::parse(msg, tls_flavor())); - // case Handshake_Type::EndOfEarlyData: - // return End_Of_Early_Data(msg); - case Handshake_Type::EncryptedExtensions: - return Encrypted_Extensions(msg); - case Handshake_Type::Certificate: - return Certificate_13(msg, policy, peer(), certificate_type()); - case Handshake_Type::CertificateRequest: - return Certificate_Request_13(msg, peer()); - case Handshake_Type::CertificateVerify: - return Certificate_Verify_13(msg, peer()); - case Handshake_Type::Finished: - return Finished_13({msg.begin(), msg.end()}); - default: - throw TLS_Exception(AlertType::UnexpectedMessage, "Unexpected handshake message received"); - } -} - -Post_Handshake_Message_13 Handshake_Layer::parse_post_handshake_message(Handshake_Type type, - std::span msg) const { - switch(type) { - case Handshake_Type::NewSessionTicket: - return New_Session_Ticket_13(msg, peer()); - case Handshake_Type::KeyUpdate: - return Key_Update(msg); - default: - throw TLS_Exception(AlertType::UnexpectedMessage, "Unexpected post-handshake message received"); - } -} - -void Handshake_Layer::update_transcript_for_psk_binder_calc(const Client_Hello_13& message, - Transcript_Hash_State& transcript_hash) { - const auto msg_bytes = serialize(message); - transcript_hash.update(TLS_Handshake_Layer::prepare_header(message.wire_type(), msg_bytes.size()), msg_bytes); -} - -Handshake_Type Handshake_Layer::read_handshake_message_type(uint8_t value, Handshake_Phase phase) const { +std::optional Handshake_Layer::read_handshake_message_type(uint8_t value) { const auto type = static_cast(value); - switch(type) { - // Handshake message types - case Handshake_Type::ClientHello: - case Handshake_Type::ServerHello: - case Handshake_Type::EncryptedExtensions: - case Handshake_Type::Certificate: - case Handshake_Type::CertificateRequest: - case Handshake_Type::CertificateVerify: - case Handshake_Type::Finished: - if(phase == Handshake_Phase::Handshake) { - return type; - } - break; - - // Post-handshake message types - case Handshake_Type::NewSessionTicket: - case Handshake_Type::KeyUpdate: - if(phase == Handshake_Phase::PostHandshake) { - return type; - } - break; - - // TODO(0-RTT): implement handling for EndOfEarlyData - case Handshake_Type::EndOfEarlyData: - - // TLS 1.2 specific handshake messages - case Handshake_Type::HelloRequest: - case Handshake_Type::HelloVerifyRequest: - case Handshake_Type::ServerKeyExchange: - case Handshake_Type::ClientKeyExchange: - case Handshake_Type::ServerHelloDone: - case Handshake_Type::CertificateUrl: - case Handshake_Type::CertificateStatus: - - // Pseudo handshake messages that aren't actually expected on the wire - case Handshake_Type::HandshakeCCS: - case Handshake_Type::HelloRetryRequest: - case Handshake_Type::MessageHash: - case Handshake_Type::None: - break; - }; - - if(phase == Handshake_Phase::Handshake) { - throw TLS_Exception(AlertType::UnexpectedMessage, "Unknown handshake message received"); - } else { - throw TLS_Exception(AlertType::UnexpectedMessage, "Unknown post-handshake message received"); + using enum Handshake_Type; + + case ClientHello: + case ServerHello: + case HelloVerifyRequest: + // NYI: needs PSK/resumption support -- won't be offered in Client Hello for now + // case EndOfEarlyData: + case EncryptedExtensions: + case Certificate: + case CertificateRequest: + case CertificateVerify: + case Finished: + case NewSessionTicket: + case KeyUpdate: + return type; + default: + return std::nullopt; } } -HandshakeProtocolHeader TLS_Handshake_Layer::prepare_header(Handshake_Type type, size_t payload_length) { - BOTAN_ASSERT_NOMSG(payload_length <= 0xFFFFFF); - auto header = HandshakeProtocolHeader(store_be(static_cast(payload_length))); - header[0] = static_cast(type); - return header; -} - -MarshalledHandshakeMessage TLS_Handshake_Layer::marshal(const Handshake_Message& message) { - const auto bytes = serialize(message); - return concat(prepare_header(message.wire_type(), bytes.size()), bytes); -} - TLS_Handshake_Layer::CopyDataResult TLS_Handshake_Layer::copy_data(const Policy& policy, const Handshake_Record& data_from_peer) { BOTAN_UNUSED(policy); @@ -160,75 +72,221 @@ TLS_Handshake_Layer::CopyDataResult TLS_Handshake_Layer::copy_data(const Policy& return CopyDataResult::Consumed; } -std::optional TLS_Handshake_Layer::next_message_buffer( - std::span bytes, const Policy& policy, Handshake_Phase phase) { - // read the message header - if(bytes.size() < HEADER_LENGTH) { +std::optional Handshake_Layer::next_message_buffer_view(const Policy& policy) { + auto buffer_view = fetch_next_message_buffer_view(); + if(!buffer_view.has_value()) { return std::nullopt; } - const auto type = read_handshake_message_type(bytes[0], phase); - const auto msg_len = make_uint32(0, bytes[1], bytes[2], bytes[3]); - // TODO(Botan4) this is split out due to a GCC 11 ICE, can be inlined - verify_handshake_message_size(msg_len, policy.maximum_handshake_message_size()); + verify_handshake_message_size(buffer_view->payload_size(), policy.maximum_handshake_message_size()); - if(bytes.size() < HEADER_LENGTH + msg_len) { + return buffer_view; +} + +std::optional Handshake_Layer::next_message(const Policy& policy, + Transcript_Hash_State& transcript_hash) { + const auto buffer_view = next_message_buffer_view(policy); + if(!buffer_view.has_value()) { return std::nullopt; } - return NextMessageResult{ - .type = type, - .tls_header_bytes = HandshakeProtocolHeader(std::array{bytes[0], bytes[1], bytes[2], bytes[3]}), - .message_bytes = StrongSpan(bytes.subspan(HEADER_LENGTH, msg_len)), - .bytes_consumed = HEADER_LENGTH + msg_len, - }; -} + auto msg = parse_handshake_message(buffer_view->type(), buffer_view->payload(), policy); + + // RFC 9846 5.1 + // Handshake messages MUST NOT span key changes. Implementations + // MUST verify that all messages immediately preceding a key change + // align with a record boundary; if not, then they MUST terminate the + // connection with an "unexpected_message" alert. Because the + // ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate + // messages can immediately precede a key change, implementations + // MUST send these messages in alignment with a record boundary. + // + // Note: Hello_Retry_Request and Hello_Verify_Request were added to the list + // below although they cannot immediately precede a key change. + // However, there cannot be any further sensible messages in the record + // after them. + // + // Note: Server_Hello_12 was deliberately not included in the check below + // because in TLS 1.2 Server Hello and other handshake messages can be + // legally coalesced in a single record. + // + // These messages don't only "precede" a key change, they are the only + // mechanism that can cause the key change to happen once the TLS state + // machine processes them downstream from here. Therefore, any such message + // must always be the last available handshake message in the queue of + // available handshake messages. (Any legal follow-up handshake message + // cannot be present in the queue yet, because we can successfully deprotect + // it only after said key change.) + if(holds_any_of(msg) && + !buffer_view->was_final_message_in_queue()) { + throw TLS_Exception(Alert::UnexpectedMessage, "Unexpected additional handshake data at epoch boundary"); + } -std::optional TLS_Handshake_Layer::next_message(const Policy& policy, - Transcript_Hash_State& transcript_hash) { - BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); - const auto pending = std::span{m_read_buffer}.subspan(m_read_offset); + transcript_hash.update(buffer_view->header(), buffer_view->payload()); + return msg; +} - const auto header_and_msg = next_message_buffer(pending, policy, Handshake_Phase::Handshake); - if(!header_and_msg.has_value()) { +std::optional Handshake_Layer::next_post_handshake_message( + const Policy& policy, EpochNumber latest_read_epoch_number) { + const auto buffer_view = next_message_buffer_view(policy); + if(!buffer_view.has_value()) { return std::nullopt; } - auto msg = parse_handshake_message(header_and_msg->type, header_and_msg->message_bytes, policy); - - transcript_hash.update(header_and_msg->tls_header_bytes, header_and_msg->message_bytes); - m_read_offset += header_and_msg->bytes_consumed; - BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + // RFC 9147 8. + // As with other handshake messages with no built-in response, KeyUpdates + // MUST be acknowledged. In order to facilitate epoch reconstruction, + // implementations MUST NOT send records with the new keys or send a new + // KeyUpdate until the previous KeyUpdate has been acknowledged [...]. + // + // Note that this is only relevant for DTLS, where the KeyUpdate becomes + // effective only after receiving its acknowledgment. For TLS, the check is + // trivially true because the sender switches its write keys immediately + // after sending a KeyUpdate. + // + // Technically, the check below could be scoped to KeyUpdate messages only. + // However, by enforcing it for all post-handshake messages, we harmonize the + // strong epoch ordering semantics of post-handshake messages across TLS and + // DTLS. The same restriction is applied by BoringSSL, making us compatible + // to them. + // + // Note that we currently enforce this by throwing Invalid_State when the + // user explicitly requests sending any post-handshake message while a + // KeyUpdate is pending in DTLS. + if(buffer_view->epoch_number().has_value() && buffer_view->epoch_number().value() != latest_read_epoch_number) { + throw TLS_Exception(Alert::UnexpectedMessage, "Received a new post-handshake message under an outdated epoch"); + } - if(m_read_offset == m_read_buffer.size()) { - m_read_buffer.clear(); - m_read_offset = 0; + auto msg = parse_post_handshake_message(buffer_view->type(), buffer_view->payload()); + + // RFC 9846 5.1 + // Handshake messages MUST NOT span key changes. Implementations + // MUST verify that all messages immediately preceding a key change + // align with a record boundary; if not, then they MUST terminate the + // connection with an "unexpected_message" alert. Because the + // ClientHello, EndOfEarlyData, ServerHello, Finished, and KeyUpdate + // messages can immediately precede a key change, implementations + // MUST send these messages in alignment with a record boundary. + // + // See above (Handshake_Layer::next_handshake_message) for a rationale. Note + // that in DTLS this rationale only holds because of the strong epoch + // ordering enforced by the check above. RFC 9147 does not strictly prohibit + // protecting post-handshake messages with an epoch that is about to be + // retired by a pending KeyUpdate. + if(std::holds_alternative(msg) && !buffer_view->was_final_message_in_queue()) { + throw TLS_Exception(Alert::UnexpectedMessage, "Unexpected additional post-handshake data at epoch boundary"); } return msg; } -std::optional TLS_Handshake_Layer::next_post_handshake_message(const Policy& policy) { +std::optional TLS_Handshake_Layer::fetch_next_message_buffer_view() { BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); - const auto pending = std::span{m_read_buffer}.subspan(m_read_offset); - const auto header_and_msg = next_message_buffer(pending, policy, Handshake_Phase::PostHandshake); - if(!header_and_msg.has_value()) { + BufferSlicer bs(m_read_buffer); + bs.skip(m_read_offset); + + if(bs.empty()) { return std::nullopt; } - auto msg = parse_post_handshake_message(header_and_msg->type, header_and_msg->message_bytes); + // Validate the message type early, before committing to wait for a + // potentially bogus and huge message body. + if(!read_handshake_message_type(bs.peek_byte()).has_value()) { + throw TLS_Exception(AlertType::UnexpectedMessage, "Unknown handshake message received"); + } + + if(bs.remaining() < HEADER_LENGTH) { + return std::nullopt; + } - m_read_offset += header_and_msg->bytes_consumed; - BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + const auto header = typecast_copy(bs.take()); + const auto msg_len = load_be(header) & 0x00FFFFFF; - if(m_read_offset == m_read_buffer.size()) { - m_read_buffer.clear(); - m_read_offset = 0; + if(bs.remaining() < msg_len) { + return std::nullopt; } - return msg; + const bool is_final_message = bs.remaining() == msg_len; + return MessageBufferView(std::nullopt, // TLS 1.3 does not have epochs + is_final_message, + header, + bs.take(msg_len), + [this, msg_len]() { + m_read_offset += HEADER_LENGTH + msg_len; + BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size()); + + if(m_read_offset == m_read_buffer.size()) { + m_read_buffer.clear(); + m_read_offset = 0; + } + }); +} + +Handshake_Layer::MessageBufferView::MessageBufferView(std::optional epoch_number, + bool final_message, + HandshakeProtocolHeader header, + StrongSpan payload, + CleanupFunction cleanup) : + m_epoch_number(epoch_number), + m_final_message(final_message), + m_header(header), + m_payload(payload), + m_cleanup(std::move(cleanup)) { + if(auto type = read_handshake_message_type(header[0])) { + m_type = *type; + } else { + throw TLS_Exception(AlertType::UnexpectedMessage, "Unknown handshake message received"); + } +} + +Handshake_Message_13 Handshake_Layer::parse_handshake_message(Handshake_Type type, + std::span msg, + const Policy& policy) const { + switch(type) { + // Client Hello and Server Hello messages are ambiguous. Both may come + // from non-TLS 1.3 peers. Hence, their parsing is somewhat different. + case Handshake_Type::ClientHello: + // ... might be TLS 1.2 Client Hello or TLS 1.3 Client Hello + return generalize_to(Client_Hello_13::parse(msg)); + case Handshake_Type::ServerHello: + // ... might be TLS 1.2 Server Hello or TLS 1.3 Server Hello or + // a TLS 1.3 Hello Retry Request disguising as a Server Hello + return generalize_to(Server_Hello_13::parse(msg, tls_flavor())); + // case Handshake_Type::EndOfEarlyData: + // return End_Of_Early_Data(msg); + case Handshake_Type::EncryptedExtensions: + return Encrypted_Extensions(msg); + case Handshake_Type::Certificate: + return Certificate_13(msg, policy, peer(), certificate_type()); + case Handshake_Type::CertificateRequest: + return Certificate_Request_13(msg, peer()); + case Handshake_Type::CertificateVerify: + return Certificate_Verify_13(msg, peer()); + case Handshake_Type::Finished: + return Finished_13({msg.begin(), msg.end()}); + default: + throw TLS_Exception(AlertType::UnexpectedMessage, "Unexpected handshake message received"); + } +} + +Post_Handshake_Message_13 Handshake_Layer::parse_post_handshake_message(Handshake_Type type, + std::span msg) const { + switch(type) { + case Handshake_Type::NewSessionTicket: + return New_Session_Ticket_13(msg, peer()); + case Handshake_Type::KeyUpdate: + return Key_Update(msg); + default: + throw TLS_Exception(AlertType::UnexpectedMessage, "Unexpected post-handshake message received"); + } +} + +void Handshake_Layer::update_transcript_for_psk_binder_calc(const Client_Hello_13& message, + Transcript_Hash_State& transcript_hash) { + const auto msg_bytes = serialize(message); + transcript_hash.update(TLS_Handshake_Layer::prepare_header(message.wire_type(), msg_bytes.size()), msg_bytes); } } // namespace Botan::TLS diff --git a/src/lib/tls/tls13/tls_handshake_layer_13.h b/src/lib/tls/tls13/tls_handshake_layer_13.h index e1b212f115a..8b61f104f73 100644 --- a/src/lib/tls/tls13/tls_handshake_layer_13.h +++ b/src/lib/tls/tls13/tls_handshake_layer_13.h @@ -15,6 +15,9 @@ #include #include +#include +#include +#include #include namespace Botan::TLS { @@ -67,6 +70,12 @@ class BOTAN_TEST_API Handshake_Layer { return SerializedHandshakeMessage(message.serialize()); } + /** + * Reads and verifies the handshake message type byte. If the byte does + * not represent a valid handshake message type, std::nullopt is returned. + */ + [[nodiscard]] static std::optional read_handshake_message_type(uint8_t byte_value); + public: Handshake_Layer(const Handshake_Layer&) = delete; Handshake_Layer(Handshake_Layer&&) = delete; @@ -93,22 +102,26 @@ class BOTAN_TEST_API Handshake_Layer { /** * Parses one handshake message off the internal buffer that is being filled using `copy_data`. * + * TODO: remove the std::optional> shenanigan + * when integrating the re-vamped DTLS-enabled data influx routine. + * * @param policy the TLS policy * @param transcript_hash the transcript hash state to be updated * * @return the parsed handshake message, or nullopt if more data is needed to complete the message */ - virtual std::optional next_message(const Policy& policy, - Transcript_Hash_State& transcript_hash) = 0; + std::optional next_message(const Policy& policy, Transcript_Hash_State& transcript_hash); /** * Parses one post-handshake message off the internal buffer that is being filled using `copy_data`. * - * @param policy the TLS policy + * @param policy the TLS policy + * @param latest_read_epoch_number the number of the latest available read epoch * * @return the parsed post-handshake message, or nullopt if more data is needed to complete the message */ - virtual std::optional next_post_handshake_message(const Policy& policy) = 0; + std::optional next_post_handshake_message(const Policy& policy, + EpochNumber latest_read_epoch_number); /** * Marshals a ClientHello prematurely for a truncated transcript hash @@ -144,9 +157,51 @@ class BOTAN_TEST_API Handshake_Layer { void set_selected_certificate_type(Certificate_Type cert_type) { m_certificate_type = cert_type; } protected: - enum class Handshake_Phase : bool { Handshake, PostHandshake }; + /** + * This helper class represents a view into the handshake message buffer, + * along with meta information and a cleanup function that is called when + * the view goes out of scope. That way, we avoid copying the unparsed + * message from the read buffer for processing. + * + * Note that this is tightly coupled within the Handshake_Layer and its + * subclasses, so that potential life-time issues of the underlying buffer + * are manageable within this scope. + */ + class MessageBufferView final { + public: + using CleanupFunction = std::function; + + public: + MessageBufferView(std::optional epoch_number, + bool final_message, + HandshakeProtocolHeader header, + StrongSpan payload, + CleanupFunction cleanup); + + bool was_final_message_in_queue() const { return m_final_message; } + + Handshake_Type type() const { return m_type; } + + std::optional epoch_number() const { return m_epoch_number; } - Handshake_Type read_handshake_message_type(uint8_t value, Handshake_Phase phase) const; + HandshakeProtocolHeader header() const { return m_header; } + + StrongSpan payload() const { return m_payload; } + + size_t payload_size() const { return m_payload.size(); } + + private: + Handshake_Type m_type; + std::optional m_epoch_number; + bool m_final_message; + HandshakeProtocolHeader m_header; + StrongSpan m_payload; + scoped_cleanup m_cleanup; + }; + + std::optional next_message_buffer_view(const Policy& policy); + + virtual std::optional fetch_next_message_buffer_view() = 0; virtual TLS_Flavor tls_flavor() const = 0; @@ -172,30 +227,24 @@ class BOTAN_TEST_API TLS_Handshake_Layer final : public Handshake_Layer { /** * Prepare the TLS message header according to RFC9846 Section 4 */ - static HandshakeProtocolHeader prepare_header(Handshake_Type type, size_t payload_length); + static HandshakeProtocolHeader prepare_header(Handshake_Type type, size_t payload_length) { + BOTAN_ASSERT_NOMSG(payload_length <= 0xFFFFFF); + auto header = HandshakeProtocolHeader(store_be(static_cast(payload_length))); + header[0] = static_cast(type); + return header; + } bool has_pending_data() const override { return m_read_offset < m_read_buffer.size(); } CopyDataResult copy_data(const Policy& policy, const Handshake_Record& data_from_peer) override; - std::optional next_message(const Policy& policy, - Transcript_Hash_State& transcript_hash) override; - - std::optional next_post_handshake_message(const Policy& policy) override; - - static MarshalledHandshakeMessage marshal(const Handshake_Message& message); + static auto marshal(const Handshake_Message& message) { + const auto bytes = serialize(message); + return concat(prepare_header(message.wire_type(), bytes.size()), bytes); + } protected: - struct NextMessageResult { - Handshake_Type type; - HandshakeProtocolHeader tls_header_bytes; - StrongSpan message_bytes; - size_t bytes_consumed; - }; - - std::optional next_message_buffer(std::span bytes, - const Policy& policy, - Handshake_Phase phase); + std::optional fetch_next_message_buffer_view() override; TLS_Flavor tls_flavor() const override { return TLS_Flavor::TLS; } diff --git a/src/lib/tls/tls13/tls_server_impl_13.cpp b/src/lib/tls/tls13/tls_server_impl_13.cpp index ac8025a7e9e..9ab376712f2 100644 --- a/src/lib/tls/tls13/tls_server_impl_13.cpp +++ b/src/lib/tls/tls13/tls_server_impl_13.cpp @@ -126,6 +126,17 @@ size_t Server_Impl_13::send_new_session_tickets(const size_t tickets) { return 0; } + if(!m_channel_io->can_send_post_handshake_messages()) { + // In DTLS 1.3 KeyUpdate messages must be acknowledged by the peer. Before + // that, we don't allow any other post-handshake messages to be sent for + // compatibility with BoringSSL which enforces this restriction even + // though the RFC does not require it explicitly. + throw Invalid_State( + "Cannot send NewSessionTicket messages right now. " + "Probably you're using DTLS and a KeyUpdate is currently pending. " + "Please try again later."); + } + auto flight = PostHandshakeFlight(callbacks()); size_t tickets_created = 0; @@ -854,8 +865,10 @@ void Server_Impl_13::handle(const Finished_13& finished_msg) { m_transcript_hash.reset(); callbacks().tls_session_activated(); - if(new_session_ticket_supported()) { - send_new_session_tickets(policy().new_session_tickets_upon_handshake_success()); + const auto session_tickets_after_handshake = policy().new_session_tickets_upon_handshake_success(); + if(new_session_ticket_supported() && session_tickets_after_handshake > 0) { + BOTAN_ASSERT_NOMSG(m_channel_io->can_send_post_handshake_messages()); + send_new_session_tickets(session_tickets_after_handshake); } } diff --git a/src/lib/tls/tls_channel_impl.h b/src/lib/tls/tls_channel_impl.h index 0d02683c601..c4285a3d6a9 100644 --- a/src/lib/tls/tls_channel_impl.h +++ b/src/lib/tls/tls_channel_impl.h @@ -164,6 +164,11 @@ class Channel_Impl : public std::enable_shared_from_this { * Additionally, anything but TLS 1.3 servers will return 0 (because they * don't support sending such session tickets). * + * @throws Invalid_State when the channel cannot send post-handshake + * messages either because the handshake is not yet + * complete or if a DTLS association is waiting on + * an acknowledgement for a pending KeyUpdate. + * * @returns the number of session tickets successfully sent to the client */ virtual size_t send_new_session_tickets(const size_t /* tickets */) { return 0; } @@ -172,6 +177,11 @@ class Channel_Impl : public std::enable_shared_from_this { * Attempt to update the session's traffic key material * Note that this is possible with a TLS 1.3 channel, only. * + * @throws Invalid_State when the channel cannot send post-handshake + * messages either because the handshake is not yet + * complete or if a DTLS association is waiting on + * an acknowledgement for a previous KeyUpdate. + * * @param request_peer_update if true, require a reciprocal key update */ virtual void update_traffic_keys(bool request_peer_update = false) = 0; diff --git a/src/lib/utils/stl_util.h b/src/lib/utils/stl_util.h index 59d75d5d960..0fad7abc874 100644 --- a/src/lib/utils/stl_util.h +++ b/src/lib/utils/stl_util.h @@ -127,20 +127,20 @@ constexpr std::optional specialize_to(GeneralVariantT&& v) { std::forward(v)); } -template +template struct variant_append; -template -struct variant_append, T> { - using type = std::variant; +template +struct variant_append, NewTs...> { + using type = std::variant; }; /** * @brief Converts a given variant into another variant with all its alternative * types and an additional alternative type T. */ -template -using variant_append_t = typename variant_append::type; +template +using variant_append_t = typename variant_append::type; // This is a helper utility to emulate pattern matching with std::visit. // See https://en.cppreference.com/w/cpp/utility/variant/visit for more info. diff --git a/src/tests/test_tls_channel_io.cpp b/src/tests/test_tls_channel_io.cpp index 2d616447897..b299a870ae8 100644 --- a/src/tests/test_tls_channel_io.cpp +++ b/src/tests/test_tls_channel_io.cpp @@ -672,7 +672,7 @@ std::vector receive_error_cases() { io->copy_data(record); result.test_throws("server hello must not be followed by more data in the same record", - "Unexpected additional handshake message data found in record", + "Unexpected additional handshake data at epoch boundary", [&] { drain_events(*io, th, false); }); }), diff --git a/src/tests/test_tls_handshake_layer_13.cpp b/src/tests/test_tls_handshake_layer_13.cpp index a1fe6a2b792..7bf25d778a2 100644 --- a/src/tests/test_tls_handshake_layer_13.cpp +++ b/src/tests/test_tls_handshake_layer_13.cpp @@ -30,6 +30,12 @@ bool has_message(Test::Result& test_result, const std::optional(read_result.value()); } +template +bool has_message(Test::Result& test_result, const std::optional& read_result) { + test_result.require("has a message", read_result.has_value()); + return std::holds_alternative(read_result.value()); +} + // NOLINTBEGIN(cert-err58-cpp,bugprone-throwing-static-initialization) const auto client_hello_message = Botan::hex_decode_locked( // from RFC 8448 "01 00 00 c0 03 03 cb" @@ -100,6 +106,11 @@ const auto client_finished_message = Botan::hex_decode_locked( "14 00 00 20 a8 ec 43 6d 67 76 34 ae 52 5a c1" "fc eb e1 1a 03 9e c1 76 94 fa c6 e9 85 27 b6 42 f2 ed d5 ce 61"); +const auto key_update_not_requested = Botan::hex_decode_locked("18 00 00 01 00"); + +const auto new_session_ticket = // ticket lifetime: 86400, nonce: 0xaa, ticket: 0xdeadbeef, no extensions + Botan::hex_decode_locked("04 00 00 12 00 01 51 80 00 00 00 00 01 aa 00 04 de ad be ef 00 00"); + // // ################################################################### // @@ -177,11 +188,24 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - std::ignore = hl.copy_data(Policy(), as_hs_record(std::array{0x00, 0x01, 0x02})); + std::ignore = hl.copy_data(Policy(), as_hs_record(std::array{0x01, 0x02, 0x03})); result.test_is_true("needs more bytes", !hl.next_message(Policy(), th)); check_transcript_hash_empty(result, th); }), + CHECK("reject incomplete header with invalid type", + [&](auto& result) { + auto hl = TLS_Handshake_Layer(Connection_Side::Client); + Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); + + // The type tag is validated as soon as its first byte arrived, + // without waiting for the rest of the header. + std::ignore = hl.copy_data(Policy(), as_hs_record(std::array{0xD4, 0x00, 0x00})); + result.template test_throws( + "message is rejected", "Unknown handshake message received", [&] { hl.next_message(Policy(), th); }); + check_transcript_hash_empty(result, th); + }), + CHECK("read client hello", [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); @@ -236,15 +260,93 @@ std::vector read_handshake_messages() { [&](auto& result) { auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); - std::ignore = - hl.copy_data(Policy(), as_hs_record(Botan::concat(server_hello_message, encrypted_extensions))); + const Text_Policy policy("minimum_rsa_bits = 1024"); // for the RFC 8448 certificate + + // After the ServerHello, a key change is expected. Handshake_Layer + // validates that no additional messages are pending when emitting a + // ServerHello. We have to read it independently (just like in a real + // handshake). + std::ignore = hl.copy_data(policy, as_hs_record(server_hello_message)); result.test_is_true("is a server hello", - has_message(result, hl.next_message(Policy(), th))); + has_message(result, hl.next_message(policy, th))); + + // ... the remaining server handshake messages may legally be + // coalesced in a single record, as long as any message that can + // precede a key change (like Finished) is the last one in it. + std::ignore = hl.copy_data(policy, as_hs_record(server_handshake_messages)); result.test_is_true("is encrypted extensions", - has_message(result, hl.next_message(Policy(), th))); + has_message(result, hl.next_message(policy, th))); + result.test_is_true("is certificate", has_message(result, hl.next_message(policy, th))); + result.test_is_true("is certificate verify", + has_message(result, hl.next_message(policy, th))); + result.test_is_true("is finished", has_message(result, hl.next_message(policy, th))); check_transcript_hash_filled(result, th); }), + CHECK("reject server hello coalesced with other messages", + [&](auto& result) { + auto hl = TLS_Handshake_Layer(Connection_Side::Client); + Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); + + std::ignore = + hl.copy_data(Policy(), as_hs_record(Botan::concat(server_hello_message, encrypted_extensions))); + result.template test_throws("coalesced ServerHello is rejected", + "Unexpected additional handshake data at epoch boundary", + [&] { hl.next_message(Policy(), th); }); + check_transcript_hash_empty(result, th); + }), + + CHECK("reject client hello coalesced with other messages", + [&](auto& result) { + auto hl = TLS_Handshake_Layer(Connection_Side::Server); + Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); + + std::ignore = + hl.copy_data(Policy(), as_hs_record(Botan::concat(client_hello_message, client_hello_message))); + result.template test_throws("coalesced ClientHello is rejected", + "Unexpected additional handshake data at epoch boundary", + [&] { hl.next_message(Policy(), th); }); + check_transcript_hash_empty(result, th); + }), + + CHECK("reject finished coalesced with other messages", + [&](auto& result) { + auto hl = TLS_Handshake_Layer(Connection_Side::Server); + Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); + + std::ignore = + hl.copy_data(Policy(), as_hs_record(Botan::concat(client_finished_message, encrypted_extensions))); + result.template test_throws("coalesced Finished is rejected", + "Unexpected additional handshake data at epoch boundary", + [&] { hl.next_message(Policy(), th); }); + check_transcript_hash_empty(result, th); + }), + + CHECK("read post-handshake messages", + [&](auto& result) { + auto hl = TLS_Handshake_Layer(Connection_Side::Client); + + std::ignore = hl.copy_data(Policy(), as_hs_record(key_update_not_requested)); + const auto ku = hl.next_post_handshake_message(Policy(), EpochNumber::create(3)); + result.test_is_true("is a key update", has_message(result, ku)); + + std::ignore = hl.copy_data(Policy(), as_hs_record(new_session_ticket)); + const auto nst = hl.next_post_handshake_message(Policy(), EpochNumber::create(3)); + result.test_is_true("is a new session ticket", has_message(result, nst)); + }), + + CHECK("reject key update coalesced with other messages", + [&](auto& result) { + auto hl = TLS_Handshake_Layer(Connection_Side::Client); + + std::ignore = + hl.copy_data(Policy(), as_hs_record(Botan::concat(key_update_not_requested, new_session_ticket))); + result.template test_throws( + "coalesced KeyUpdate is rejected", + "Unexpected additional post-handshake data at epoch boundary", + [&] { hl.next_post_handshake_message(Policy(), EpochNumber::create(3)); }); + }), + CHECK("reject TLS 1.2 messages", [&](auto& result) { for(const auto& msg : tls_12_only_messages) { @@ -267,8 +369,8 @@ std::vector read_handshake_messages() { // This caused a deadlock as we waited to receive the complete message, rather than validating the type // tag to exit early. const auto data = Botan::hex_decode_locked("D4B028717D0FA310FF8664127B9448D7952E06A4F9EA23"); - // data from the bogo test -- ~~~~~~ <- length - // ~~ <- bogus message type + // data from the bogo test -- ~~~~~~ <- length + // ~~ <- bogus message type auto hl = TLS_Handshake_Layer(Connection_Side::Client); Transcript_Hash_State th(Botan::TLS::TLS_Flavor::TLS, "SHA-256"); std::ignore = hl.copy_data(Policy(), as_hs_record(data)); diff --git a/src/tests/test_tls_protocol_version.cpp b/src/tests/test_tls_protocol_version.cpp index 9d184f55e37..7168552815c 100644 --- a/src/tests/test_tls_protocol_version.cpp +++ b/src/tests/test_tls_protocol_version.cpp @@ -37,9 +37,7 @@ namespace TLS = Botan::TLS; } [[maybe_unused]] TLS::Protocol_Version latest_dtls_version_in_this_build() { - #if defined(BOTAN_HAS_DTLS_13) - return TLS::Protocol_Version::DTLS_V13; - #elif defined(BOTAN_HAS_TLS_12) + #if defined(BOTAN_HAS_TLS_12) return TLS::Protocol_Version::DTLS_V12; #else throw Test_Error("No DTLS in this build, some #ifdef issue in the test code?"); diff --git a/src/tests/unit_tls.cpp b/src/tests/unit_tls.cpp index bd0e5b1ca3a..1c9e2ac9ca8 100644 --- a/src/tests/unit_tls.cpp +++ b/src/tests/unit_tls.cpp @@ -2877,6 +2877,29 @@ class TLS_Unit_Tests final : public Test { half_closed_result.test_is_true("server is still active", server.is_active()); half_closed_result.test_bin_eq("client received server data intact", client_cb->received(), server_msg); + half_closed_result.test_sz_eq("no key update below the write limit", server_cb->key_updates_sent(), 0); + + // Three more records bring the server to its write limit of 4; + // the next send must rekey. As the peer will never send again, + // the server must not request a reciprocal KeyUpdate. + const std::vector more_msg{'1', '2', '3'}; + for(const uint8_t byte : more_msg) { + server.send(&byte, 1); + } + pump(); + half_closed_result.test_sz_eq("no key update before the write limit", server_cb->key_updates_sent(), 0); + + const uint8_t limit_byte = '4'; + server.send(&limit_byte, 1); + pump(); + + half_closed_result.test_sz_eq("write limit triggered a key update", server_cb->key_updates_sent(), 1); + half_closed_result.test_sz_eq( + "no reciprocal update requested from half-closed peer", server_cb->key_updates_requested(), 0); + half_closed_result.test_is_true("server is still active after key update", server.is_active()); + + const std::vector expected_msg{'b', 'y', 'e', '1', '2', '3', '4'}; + half_closed_result.test_bin_eq("client received all server data", client_cb->received(), expected_msg); server.close(); pump();