Botan 3.14.1
Crypto and TLS for C&
tls_flight_13.h
Go to the documentation of this file.
1/*
2* TLS 1.3 Flights
3* (C) 2026 Jack Lloyd
4* 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_FLIGHT_13_H_
10#define BOTAN_TLS_FLIGHT_13_H_
11
12#include <botan/tls_magic.h>
13#include <botan/tls_messages_13.h>
14#include <botan/internal/tls_types_13.h>
15#include <optional>
16#include <variant>
17#include <vector>
18
19namespace Botan::TLS {
20
21class Callbacks;
23
24/**
25 * Helper class to coalesce handshake messages into a TLS flight. The class
26 * keeps track of the serialized messages and updates the transcript hash
27 * accordingly.
28 *
29 * Once the flight is constructed, using code must commit() it and pass on the
30 * prepared list of serialized messages for sending. After commit() the flight
31 * object is invalid and must not be used anymore.
32 *
33 * Note that this class takes references to transcript hash and callbacks
34 * objects. The caller is responsible for ensuring that these objects remain
35 * valid for the lifetime of the Flight object. The flight object is meant to be
36 * used in a single stack frame and not stored for later use.
37 */
39 public:
41
47
48 using Message = std::variant<Dummy_ChangeCipherSpec, Message_Info>;
49
50 enum class PostHandshake : bool { No = false, Yes = true };
51
52 protected:
53 explicit Flight(Callbacks& callbacks) : m_callbacks(callbacks) { m_messages.emplace(); }
54
55 Flight(Flight&& other) = default;
56
57 public:
58 Flight(Transcript_Hash_State& transcript_hash, Callbacks& callbacks) :
59 m_transcript_hash(transcript_hash), m_callbacks(callbacks) {
60 m_messages.emplace();
61 }
62
63 Flight(const Flight& other) = delete;
64 Flight& operator=(const Flight& other) = delete;
65 Flight& operator=(Flight&& other) = delete;
66 ~Flight() = default;
67
68 /**
69 * Add a @p msg to this flight, updating the transcript hash associated
70 * with this flight and letting the user inspect the message first via the
71 * callbacks.
72 *
73 * TODO(C++23): deducing-this
74 *
75 * @param msg The handshake message to add to the flight
76 * @throws Invalid_State if the flight was already committed
77 */
79 std::visit([&](const auto m) { append(m.get(), PostHandshake::No); }, msg);
80 return *this;
81 }
82
83 /**
84 * Add a @p msg to this flight, updating the transcript hash associated
85 * with this flight and letting the user inspect the message first via the
86 * callbacks.
87 *
88 * TODO(C++23): deducing-this
89 *
90 * @param msg The handshake message to add to the flight
91 * @throws Invalid_State if the flight was already committed
92 */
94 std::visit([&](const auto m) { append(m.get(), PostHandshake::No); }, msg);
95 return std::move(*this);
96 }
97
98 /**
99 * Add a dummy ChangeCipherSpec message to the flight when following the
100 * compatibility mode for TLS 1.3. See RFC 9846 E.4 for details.
101 *
102 * TODO(C++23): deducing-this
103 *
104 * @throws Invalid_State if the flight was already committed
105 */
107 append_ccs();
108 return *this;
109 }
110
111 /**
112 * Add a dummy ChangeCipherSpec message to the flight when following the
113 * compatibility mode for TLS 1.3. See RFC 9846 E.4 for details.
114 *
115 * TODO(C++23): deducing-this
116 *
117 * @throws Invalid_State if the flight was already committed
118 */
120 append_ccs();
121 return std::move(*this);
122 }
123
124 /**
125 * Extract the messages from the flight for sending. This invalidates the
126 * flight object and it cannot be used anymore.
127 *
128 * @throws Invalid_State if the flight was already committed or if it
129 * is empty
130 */
131 std::vector<Message> commit();
132
133 protected:
134 void append(const Handshake_Message& message, PostHandshake post_handshake);
135 void append_ccs();
136
137 private:
138 std::optional<std::reference_wrapper<Transcript_Hash_State>> m_transcript_hash;
139 Callbacks& m_callbacks;
140
141 std::optional<std::vector<Message>> m_messages;
142};
143
144/**
145 * Helper class to coalesce post-handshake messages into a TLS flight.
146 */
148 public:
149 explicit PostHandshakeFlight(Callbacks& callbacks) : Flight(callbacks) {}
150
151 public:
152 /**
153 * Add a @p msg to this flight, letting the user inspect the message first
154 * via the callbacks. The transcript hash is unchanged for post-handshake
155 * messages.
156 *
157 * TODO(C++23): deducing-this
158 *
159 * @param msg The post-handshake message to add to the flight
160 * @throws Invalid_State if the flight was already committed
161 */
163 std::visit([&](const auto& m) { append(m, PostHandshake::Yes); }, msg);
164 return *this;
165 }
166
167 /**
168 * Add a @p msg to this flight, letting the user inspect the message first
169 * via the callbacks. The transcript hash is unchanged for post-handshake
170 * messages.
171 *
172 * TODO(C++23): deducing-this
173 *
174 * @param msg The post-handshake message to add to the flight
175 * @throws Invalid_State if the flight was already committed
176 */
178 std::visit([&](const auto& m) { append(m, PostHandshake::Yes); }, msg);
179 return std::move(*this);
180 }
181
182 using Flight::commit;
183};
184
185} // namespace Botan::TLS
186
187#endif
#define BOTAN_TEST_API
Definition api.h:41
Flight(Callbacks &callbacks)
Flight(Transcript_Hash_State &transcript_hash, Callbacks &callbacks)
Flight & operator=(const Flight &other)=delete
std::variant< Dummy_ChangeCipherSpec, Message_Info > Message
Flight & add(Handshake_Message_13_Ref msg) &
Flight add_dummy_change_cipher_spec() &&
void append(const Handshake_Message &message, PostHandshake post_handshake)
Flight & add_dummy_change_cipher_spec() &
Flight & operator=(Flight &&other)=delete
Flight add(Handshake_Message_13_Ref msg) &&
Flight(const Flight &other)=delete
Flight(Flight &&other)=default
std::vector< Message > commit()
PostHandshakeFlight(Callbacks &callbacks)
PostHandshakeFlight add(const Post_Handshake_Message_13 &msg) &&
PostHandshakeFlight & add(const Post_Handshake_Message_13 &msg) &
detail::as_wrapped_references_t< Handshake_Message_13 > Handshake_Message_13_Ref
Strong< std::array< uint8_t, 4 >, struct HandshakeProtocolHeader_ > HandshakeProtocolHeader
Holds the serialization of a TLS 1.3 handshake protocol header.
Strong< std::vector< uint8_t >, struct SerializedHandshakeMessage_ > SerializedHandshakeMessage
std::variant< New_Session_Ticket_13, Key_Update > Post_Handshake_Message_13
void append(std::vector< T, Alloc > &out, std::type_identity_t< std::span< const T > > in)
SerializedHandshakeMessage serialized
HandshakeProtocolHeader header