Botan 3.9.0
Crypto and TLS for C&
tls_cipher_state.h
Go to the documentation of this file.
1/*
2* TLS cipher state implementation for TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_CIPHER_STATE_H_
10#define BOTAN_TLS_CIPHER_STATE_H_
11
12#include <botan/secmem.h>
13#include <botan/tls_magic.h>
14#include <botan/tls_messages.h>
15
16#include <botan/internal/tls_transcript_hash_13.h>
17
18namespace Botan {
19
20class AEAD_Mode;
21class HashFunction;
22class HKDF_Extract;
23class HKDF_Expand;
24
25} // namespace Botan
26
27namespace Botan::TLS {
28
29class Ciphersuite;
30class Secret_Logger;
31
32/**
33 * This class implements the key schedule for TLS 1.3 as described in RFC 8446 7.1.
34 *
35 * Internally, it reflects the state machine pictured in the same RFC section.
36 * It provides the following entry points and state advancement methods that
37 * each facilitate certain cryptographic functionality:
38 *
39 * * init_with_psk()
40 * sets up the cipher state with a pre-shared key (out of band or via session
41 * ticket). will allow sending early data in the future
42 *
43 * * init_with_server_hello() / advance_with_server_hello()
44 * allows encrypting and decrypting handshake traffic, as well as producing
45 * and validating the client/server handshake finished MACs
46 *
47 * * advance_with_server_finished()
48 * allows encrypting and decrypting application traffic
49 *
50 * * advance_with_client_finished()
51 * allows negotiation of resumption PSKs
52 *
53 * While encrypting and decrypting records (RFC 8446 5.2) Cipher_State
54 * internally keeps track of the current sequence numbers (RFC 8446 5.3) to
55 * calculate the correct Per-Record Nonce. Sequence numbers are reset
56 * appropriately, whenever traffic secrets change.
57 *
58 * Handshake finished MAC calculation and verification is described in RFC 8446 4.4.4.
59 *
60 * PSKs calculation is described in RFC 8446 4.6.1.
61 */
63 public:
64 enum class PSK_Type : uint8_t {
66 External, // currently not implemented
67 };
68
69 public:
71
72 Cipher_State(const Cipher_State& other) = delete;
73 Cipher_State(Cipher_State&& other) = delete;
74 Cipher_State& operator=(const Cipher_State& other) = delete;
76
77 /**
78 * Construct a Cipher_State from a Pre-Shared-Key.
79 */
80 static std::unique_ptr<Cipher_State> init_with_psk(Connection_Side side,
81 PSK_Type type,
83 std::string_view prf_algo);
84
85 /**
86 * Construct a Cipher_State after receiving a server hello message.
87 */
88 static std::unique_ptr<Cipher_State> init_with_server_hello(Connection_Side side,
89 secure_vector<uint8_t>&& shared_secret,
90 const Ciphersuite& cipher,
91 const Transcript_Hash& transcript_hash,
92 const Secret_Logger& channel);
93
94 /**
95 * Transition internal secrets/keys for transporting early application data.
96 * Note that this state transition is legal only for handshakes using PSK.
97 */
98 void advance_with_client_hello(const Transcript_Hash& transcript_hash, const Secret_Logger& channel);
99
100 /**
101 * Transition internal secrets/keys for transporting handshake data.
102 */
103 void advance_with_server_hello(const Ciphersuite& cipher,
104 secure_vector<uint8_t>&& shared_secret,
105 const Transcript_Hash& transcript_hash,
106 const Secret_Logger& channel);
107
108 /**
109 * Transition internal secrets/keys for transporting application data.
110 */
111 void advance_with_server_finished(const Transcript_Hash& transcript_hash, const Secret_Logger& channel);
112
113 /**
114 * Transition to the final internal state allowing to create resumptions.
115 */
116 void advance_with_client_finished(const Transcript_Hash& transcript_hash);
117
118 /**
119 * Encrypt a TLS record fragment (RFC 8446 5.2 -- TLSInnerPlaintext) using the
120 * currently available traffic secret keys and the current sequence number.
121 * This will internally increment the sequence number. Hence, multiple
122 * calls with the same input will not produce the same result.
123 *
124 * @returns the sequence number of the encrypted record
125 */
126 uint64_t encrypt_record_fragment(const std::vector<uint8_t>& header, secure_vector<uint8_t>& fragment);
127
128 /**
129 * Decrypt a TLS record fragment (RFC 8446 5.2 -- TLSCiphertext.encrypted_record)
130 * using the currently available traffic secret keys and the current sequence number.
131 * This will internally increment the sequence number. Hence, multiple
132 * calls with the same input will not produce the same result.
133 *
134 * @returns the sequence number of the decrypted record
135 */
136 uint64_t decrypt_record_fragment(const std::vector<uint8_t>& header, secure_vector<uint8_t>& encrypted_fragment);
137
138 /**
139 * @returns number of bytes needed to encrypt \p input_length bytes
140 */
141 size_t encrypt_output_length(size_t input_length) const;
142
143 /**
144 * @returns number of bytes needed to decrypt \p input_length bytes
145 */
146 size_t decrypt_output_length(size_t input_length) const;
147
148 /**
149 * @returns the minimum ciphertext length for decryption
150 */
151 size_t minimum_decryption_input_length() const;
152
153 /**
154 * Calculates the MAC for a PSK binder value in Client Hellos. Note that
155 * the transcript hash passed into this method is computed from a partial
156 * Client Hello (RFC 8446 4.2.11.2)
157 */
158 std::vector<uint8_t> psk_binder_mac(const Transcript_Hash& transcript_hash_with_truncated_client_hello) const;
159
160 /**
161 * Calculate the MAC for a TLS "Finished" handshake message (RFC 8446 4.4.4)
162 */
163 std::vector<uint8_t> finished_mac(const Transcript_Hash& transcript_hash) const;
164
165 /**
166 * Validate a MAC received in a TLS "Finished" handshake message (RFC 8446 4.4.4)
167 */
168 bool verify_peer_finished_mac(const Transcript_Hash& transcript_hash, const std::vector<uint8_t>& peer_mac) const;
169
170 /**
171 * Calculate the PSK for the given nonce (RFC 8446 4.6.1)
172 */
173 secure_vector<uint8_t> psk(const Ticket_Nonce& nonce) const;
174
175 /**
176 * Generates a nonce value that is unique for any given Cipher_State object.
177 * Note that the number of nonces is limited to 2^16 and this method will
178 * throw if more nonces are requested.
179 */
181
182 /**
183 * Derive key material to export (RFC 8446 7.5 and RFC 5705)
184 *
185 * TODO: this does not yet support key export based on the `early_exporter_master_secret`.
186 *
187 * RFC 8446 7.5
188 * Implementations MUST use the exporter_master_secret unless explicitly
189 * specified by the application. The early_exporter_master_secret is
190 * defined for use in settings where an exporter is needed for 0-RTT data.
191 * A separate interface for the early exporter is RECOMMENDED [...].
192 *
193 * @param label a disambiguating label string
194 * @param context a per-association context value
195 * @param length the length of the desired key in bytes
196 * @return key of length bytes
197 */
198 secure_vector<uint8_t> export_key(std::string_view label, std::string_view context, size_t length) const;
199
200 /**
201 * Indicates whether the appropriate secrets to export keys are available
202 */
203 bool can_export_keys() const {
204 return (m_state == State::EarlyTraffic || m_state == State::ServerApplicationTraffic ||
205 m_state == State::Completed) &&
206 !m_exporter_master_secret.empty();
207 }
208
209 /**
210 * Indicates whether unprotected Alert records are to be expected
211 */
212 bool must_expect_unprotected_alert_traffic() const;
213
214 /**
215 * Indicates whether the appropriate secrets to encrypt application traffic are available
216 */
217 bool can_encrypt_application_traffic() const;
218
219 /**
220 * Indicates whether the appropriate secrets to decrypt application traffic are available
221 */
222 bool can_decrypt_application_traffic() const;
223
224 /**
225 * The name of the hash algorithm used for the KDF in this cipher suite
226 */
227 std::string hash_algorithm() const;
228
229 /**
230 * @returns true if the selected cipher primitives are compatible with
231 * the \p cipher suite.
232 *
233 * Note that cipher suites are considered "compatible" as long as the
234 * already selected cipher primitives in this cipher state are compatible.
235 */
236 bool is_compatible_with(const Ciphersuite& cipher) const;
237
238 /**
239 * Updates the key material used for decrypting data
240 * This is triggered after we received a Key_Update from the peer.
241 *
242 * Note that this must not be called before the connection is ready for
243 * application traffic.
244 */
245 void update_read_keys(const Secret_Logger& channel);
246
247 /**
248 * Updates the key material used for encrypting data
249 * This is triggered after we send a Key_Update to the peer.
250 *
251 * Note that this must not be called before the connection is ready for
252 * application traffic.
253 */
254 void update_write_keys(const Secret_Logger& channel);
255
256 /**
257 * Remove handshake/traffic secrets for decrypting data from peer
258 */
259 void clear_read_keys();
260
261 /**
262 * Remove handshake/traffic secrets for encrypting data
263 */
264 void clear_write_keys();
265
266 private:
267 /**
268 * @param whoami whether we play the Server or Client
269 * @param hash_function the negotiated hash function to be used
270 */
271 Cipher_State(Connection_Side whoami, std::string_view hash_function);
272
273 void advance_with_psk(PSK_Type type, secure_vector<uint8_t>&& psk);
274 void advance_without_psk();
275
276 void derive_write_traffic_key(const secure_vector<uint8_t>& traffic_secret,
277 bool handshake_traffic_secret = false);
278 void derive_read_traffic_key(const secure_vector<uint8_t>& traffic_secret, bool handshake_traffic_secret = false);
279
280 /**
281 * HKDF-Extract from RFC 8446 7.1
282 */
283 secure_vector<uint8_t> hkdf_extract(std::span<const uint8_t> ikm) const;
284
285 /**
286 * HKDF-Expand-Label from RFC 8446 7.1
287 */
289 std::string_view label,
290 const std::vector<uint8_t>& context,
291 size_t length) const;
292
293 /**
294 * Derive-Secret from RFC 8446 7.1
295 */
296 secure_vector<uint8_t> derive_secret(const secure_vector<uint8_t>& secret,
297 std::string_view label,
298 const Transcript_Hash& messages_hash) const;
299
300 std::vector<uint8_t> empty_hash() const;
301
302 private:
303 enum class State : uint8_t {
304 Uninitialized,
305 PskBinder,
306 EarlyTraffic,
307 HandshakeTraffic,
308 ServerApplicationTraffic,
309 Completed
310 };
311
312 private:
313 State m_state;
314 Connection_Side m_connection_side;
315
316 std::unique_ptr<AEAD_Mode> m_encrypt;
317 std::unique_ptr<AEAD_Mode> m_decrypt;
318
319 std::unique_ptr<HKDF_Extract> m_extract;
320 std::unique_ptr<HKDF_Expand> m_expand;
321 std::unique_ptr<HashFunction> m_hash;
322
324
325 secure_vector<uint8_t> m_write_application_traffic_secret;
326 secure_vector<uint8_t> m_read_application_traffic_secret;
327
328 secure_vector<uint8_t> m_write_key;
329 secure_vector<uint8_t> m_write_iv;
330 secure_vector<uint8_t> m_read_key;
331 secure_vector<uint8_t> m_read_iv;
332
333 uint64_t m_write_seq_no;
334 uint64_t m_read_seq_no;
335
336 uint32_t m_write_key_update_count;
337 uint32_t m_read_key_update_count;
338
339 uint16_t m_ticket_nonce;
340
341 secure_vector<uint8_t> m_finished_key;
342 secure_vector<uint8_t> m_peer_finished_key;
343 secure_vector<uint8_t> m_exporter_master_secret;
344 secure_vector<uint8_t> m_resumption_master_secret;
345
346 secure_vector<uint8_t> m_early_secret;
347 secure_vector<uint8_t> m_binder_key;
348};
349
350} // namespace Botan::TLS
351
352#endif // BOTAN_TLS_CIPHER_STATE_H_
#define BOTAN_TEST_API
Definition api.h:41
static std::unique_ptr< Cipher_State > init_with_server_hello(Connection_Side side, secure_vector< uint8_t > &&shared_secret, const Ciphersuite &cipher, const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
uint64_t decrypt_record_fragment(const std::vector< uint8_t > &header, secure_vector< uint8_t > &encrypted_fragment)
Cipher_State & operator=(Cipher_State &&other)=delete
size_t minimum_decryption_input_length() const
void advance_with_client_finished(const Transcript_Hash &transcript_hash)
bool verify_peer_finished_mac(const Transcript_Hash &transcript_hash, const std::vector< uint8_t > &peer_mac) const
static std::unique_ptr< Cipher_State > init_with_psk(Connection_Side side, PSK_Type type, secure_vector< uint8_t > &&psk, std::string_view prf_algo)
uint64_t encrypt_record_fragment(const std::vector< uint8_t > &header, secure_vector< uint8_t > &fragment)
void advance_with_client_hello(const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
void advance_with_server_finished(const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
Cipher_State(const Cipher_State &other)=delete
secure_vector< uint8_t > psk(const Ticket_Nonce &nonce) const
void advance_with_server_hello(const Ciphersuite &cipher, secure_vector< uint8_t > &&shared_secret, const Transcript_Hash &transcript_hash, const Secret_Logger &channel)
secure_vector< uint8_t > export_key(std::string_view label, std::string_view context, size_t length) const
Cipher_State(Cipher_State &&other)=delete
size_t encrypt_output_length(size_t input_length) const
std::vector< uint8_t > psk_binder_mac(const Transcript_Hash &transcript_hash_with_truncated_client_hello) const
size_t decrypt_output_length(size_t input_length) const
Cipher_State & operator=(const Cipher_State &other)=delete
std::vector< uint8_t > finished_mac(const Transcript_Hash &transcript_hash) const
std::vector< uint8_t > Transcript_Hash
Definition tls_magic.h:81
Strong< std::vector< uint8_t >, struct Ticket_Nonce_ > Ticket_Nonce
Used to derive the ticket's PSK from the resumption_master_secret.
secure_vector< uint8_t > hkdf_expand_label(std::string_view hash_fn, std::span< const uint8_t > secret, std::string_view label, std::span< const uint8_t > hash_val, size_t length)
Definition hkdf.cpp:119
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69