Botan 3.14.1
Crypto and TLS for C&
tls_record.cpp
Go to the documentation of this file.
1/*
2* TLS Record Handling
3* (C) 2012,2013,2014,2015,2016,2019 Jack Lloyd
4* 2016 Juraj Somorovsky
5* 2016 Matthias Gierlings
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#include <botan/internal/tls_record.h>
11
12#include <botan/aead.h>
13#include <botan/block_cipher.h>
14#include <botan/mac.h>
15#include <botan/rng.h>
16#include <botan/tls_ciphersuite.h>
17#include <botan/tls_exceptn.h>
18#include <botan/internal/fmt.h>
19#include <botan/internal/loadstor.h>
20#include <botan/internal/tls_seq_numbers.h>
21#include <botan/internal/tls_session_key.h>
22
23#if defined(BOTAN_HAS_TLS_CBC)
24 #include <botan/internal/tls_cbc.h>
25#endif
26
27#if defined(BOTAN_HAS_TLS_NULL)
28 #include <botan/internal/tls_null.h>
29#endif
30
31namespace Botan::TLS {
32
34
36 Connection_Side side,
37 bool our_side,
38 const Ciphersuite& suite,
39 const Session_Keys& keys,
40 bool uses_encrypt_then_mac) {
41 // NOLINTBEGIN(*-prefer-member-initializer)
42 m_nonce_format = suite.nonce_format();
43 m_nonce_bytes_from_record = suite.nonce_bytes_from_record(version);
44 m_nonce_bytes_from_handshake = suite.nonce_bytes_from_handshake();
45
46 const secure_vector<uint8_t>& aead_key = keys.aead_key(side);
47 m_nonce = keys.nonce(side);
48 // NOLINTEND(*-prefer-member-initializer)
49
50 BOTAN_ASSERT_NOMSG(m_nonce.size() == m_nonce_bytes_from_handshake);
51
53#if defined(BOTAN_HAS_TLS_CBC)
54 // legacy CBC+HMAC mode
55 auto mac = MessageAuthenticationCode::create_or_throw(fmt("HMAC({})", suite.mac_algo()));
56 auto cipher = BlockCipher::create_or_throw(suite.cipher_algo());
57
58 if(our_side) {
59 m_aead = std::make_unique<TLS_CBC_HMAC_AEAD_Encryption>(std::move(cipher),
60 std::move(mac),
61 suite.cipher_keylen(),
62 suite.mac_keylen(),
63 version,
64 uses_encrypt_then_mac);
65 } else {
66 m_aead = std::make_unique<TLS_CBC_HMAC_AEAD_Decryption>(std::move(cipher),
67 std::move(mac),
68 suite.cipher_keylen(),
69 suite.mac_keylen(),
70 version,
71 uses_encrypt_then_mac);
72 }
73
74#else
75 BOTAN_UNUSED(uses_encrypt_then_mac);
76 throw Internal_Error("Negotiated disabled TLS CBC+HMAC ciphersuite");
77#endif
79#if defined(BOTAN_HAS_TLS_NULL)
80 auto mac = MessageAuthenticationCode::create_or_throw(fmt("HMAC({})", suite.mac_algo()));
81
82 if(our_side) {
83 m_aead = std::make_unique<TLS_NULL_HMAC_AEAD_Encryption>(std::move(mac), suite.mac_keylen());
84 } else {
85 m_aead = std::make_unique<TLS_NULL_HMAC_AEAD_Decryption>(std::move(mac), suite.mac_keylen());
86 }
87#else
88 throw Internal_Error("Negotiated disabled TLS NULL ciphersuite");
89#endif
90 } else {
91 m_aead =
93 }
94
95 m_aead->set_key(aead_key);
96}
97
99 switch(m_nonce_format) {
101 return Record_Nonce();
102 }
105 rng.randomize(nonce.get());
106 return nonce;
107 }
109 BOTAN_ASSERT_NOMSG(m_nonce.size() == 12);
110 Record_Nonce nonce(12);
111 store_be(seq, nonce.get().last<sizeof(seq)>());
112 xor_buf(nonce.get(), m_nonce);
113 return nonce;
114 }
116 BOTAN_ASSERT_NOMSG(m_nonce.size() == 4);
117 Record_Nonce nonce(12);
118 copy_mem(nonce.get().first<4>(), m_nonce);
119 store_be(seq, nonce.get().last<sizeof(seq)>());
120 return nonce;
121 }
122 }
123
124 throw Invalid_State("Unknown nonce format specified");
125}
126
127Record_Nonce Connection_Cipher_State::aead_nonce(const uint8_t record[], size_t record_len, uint64_t seq) const {
128 switch(m_nonce_format) {
130 return Record_Nonce();
131 }
133 if(record_len < nonce_bytes_from_record()) {
134 throw Decoding_Error("Invalid CBC packet too short to be valid");
135 }
137 copy_mem(nonce.get(), std::span(record, nonce_bytes_from_record()));
138 return nonce;
139 }
141 BOTAN_ASSERT_NOMSG(m_nonce.size() == 12);
142 Record_Nonce nonce(12);
143 store_be(seq, nonce.get().last<sizeof(seq)>());
144 xor_buf(nonce.get(), m_nonce);
145 return nonce;
146 }
148 BOTAN_ASSERT_NOMSG(m_nonce.size() == 4);
149 if(record_len < nonce_bytes_from_record()) {
150 throw Decoding_Error("Invalid AEAD packet too short to be valid");
151 }
152 Record_Nonce nonce(12);
153 copy_mem(nonce.get().first<4>(), m_nonce);
154 copy_mem(nonce.get().subspan(nonce_bytes_from_handshake()), std::span(record, nonce_bytes_from_record()));
155 return nonce;
156 }
157 }
158
159 throw Invalid_State("Unknown nonce format specified");
160}
161
162std::array<uint8_t, 13> Connection_Cipher_State::format_ad(uint64_t msg_sequence,
163 Record_Type msg_type,
164 Protocol_Version version,
165 uint16_t msg_length) {
166 std::array<uint8_t, 13> ad{};
167
168 store_be(msg_sequence, ad.data());
169 ad[8] = static_cast<uint8_t>(msg_type);
170 ad[9] = version.major_version();
171 ad[10] = version.minor_version();
172 ad[11] = get_byte<0>(msg_length);
173 ad[12] = get_byte<1>(msg_length);
174
175 return ad;
176}
177
178namespace {
179
180inline void append_u16_len(secure_vector<uint8_t>& output, size_t len_field) {
181 const uint16_t len16 = static_cast<uint16_t>(len_field);
182 BOTAN_ASSERT_EQUAL(len_field, len16, "No truncation");
183 output.push_back(get_byte<0>(len16));
184 output.push_back(get_byte<1>(len16));
185}
186
187void write_record_header(secure_vector<uint8_t>& output,
188 Record_Type record_type,
189 Protocol_Version version,
190 uint64_t record_sequence) {
191 output.clear();
192
193 output.push_back(static_cast<uint8_t>(record_type));
194 output.push_back(version.major_version());
195 output.push_back(version.minor_version());
196
197 if(version.is_datagram_protocol()) {
198 for(size_t i = 0; i != 8; ++i) {
199 output.push_back(get_byte_var(i, record_sequence));
200 }
201 }
202}
203
204} // namespace
205
207 Record_Type record_type,
208 Protocol_Version version,
209 uint64_t record_sequence,
210 const uint8_t* message,
211 size_t message_len) {
212 if(record_type == Record_Type::ApplicationData) {
213 throw Internal_Error("Writing an unencrypted TLS application data record");
214 }
215 write_record_header(output, record_type, version, record_sequence);
216 append_u16_len(output, message_len);
217 output.insert(output.end(), message, message + message_len);
218}
219
221 Record_Type record_type,
222 Protocol_Version version,
223 uint64_t record_sequence,
224 const uint8_t* message,
225 size_t message_len,
228 write_record_header(output, record_type, version, record_sequence);
229
230 AEAD_Mode& aead = cs.aead();
231 const auto aad = cs.format_ad(record_sequence, record_type, version, static_cast<uint16_t>(message_len));
232
233 const size_t ctext_size = aead.output_length(message_len);
234
235 const size_t rec_size = ctext_size + cs.nonce_bytes_from_record();
236
237 aead.set_associated_data(aad);
238
239 const auto nonce = cs.aead_nonce(record_sequence, rng);
240
241 append_u16_len(output, rec_size);
242
243 if(cs.nonce_bytes_from_record() > 0) {
245 output += nonce.get();
246 } else {
247 output += nonce.get().subspan(cs.nonce_bytes_from_handshake(), cs.nonce_bytes_from_record());
248 }
249 }
250
251 const size_t header_size = output.size();
252 output += std::make_pair(message, message_len);
253
254 aead.start(nonce.get());
255 aead.finish(output, header_size);
256
257 BOTAN_ASSERT(output.size() < MAX_CIPHERTEXT_SIZE, "Produced ciphertext larger than protocol allows");
258}
259
260namespace {
261
262size_t fill_buffer_to(
263 secure_vector<uint8_t>& readbuf, const uint8_t*& input, size_t& input_size, size_t& input_consumed, size_t desired) {
264 if(readbuf.size() >= desired) {
265 return 0; // already have it
266 }
267
268 const size_t taken = std::min(input_size, desired - readbuf.size());
269
270 readbuf.insert(readbuf.end(), input, input + taken);
271 input_consumed += taken;
272 input_size -= taken;
273 input += taken;
274
275 return (desired - readbuf.size()); // how many bytes do we still need?
276}
277
278void decrypt_record(secure_vector<uint8_t>& output,
279 uint8_t record_contents[],
280 size_t record_len,
281 uint64_t record_sequence,
282 Protocol_Version record_version,
283 Record_Type record_type,
285 AEAD_Mode& aead = cs.aead();
286
287 const size_t nonce_from_record = cs.nonce_bytes_from_record();
288 if(record_len <= nonce_from_record) {
289 throw TLS_Exception(Alert::BadRecordMac, "AEAD packet too short to be valid");
290 }
291 const auto nonce = cs.aead_nonce(record_contents, record_len, record_sequence);
292 const uint8_t* msg = &record_contents[nonce_from_record];
293 const size_t msg_length = record_len - nonce_from_record;
294
295 /*
296 * This early rejection is based just on public information (length of the
297 * encrypted packet) and so does not leak any information. We used to use
298 * decode_error here which really is more appropriate, but that confuses some
299 * tools which are attempting automated detection of padding oracles,
300 * including older versions of TLS-Attacker.
301 */
302 if(msg_length < aead.minimum_final_size()) {
303 throw TLS_Exception(Alert::BadRecordMac, "AEAD packet is shorter than the tag");
304 }
305
306 const size_t ptext_size = aead.output_length(msg_length);
307
308 aead.set_associated_data(
309 cs.format_ad(record_sequence, record_type, record_version, static_cast<uint16_t>(ptext_size)));
310
311 aead.start(nonce.get());
312
313 output.assign(msg, msg + msg_length);
314 aead.finish(output, 0);
315}
316
317Record_Header read_tls_record(secure_vector<uint8_t>& readbuf,
318 const uint8_t input[],
319 size_t input_len,
320 size_t& consumed,
322 Connection_Sequence_Numbers* sequence_numbers,
323 const get_cipherstate_fn& get_cipherstate) {
324 if(readbuf.size() < TLS_HEADER_SIZE) {
325 // header incomplete
326 if(const size_t needed = fill_buffer_to(readbuf, input, input_len, consumed, TLS_HEADER_SIZE)) {
327 return Record_Header(needed);
328 }
329
330 BOTAN_ASSERT_EQUAL(readbuf.size(), TLS_HEADER_SIZE, "Have an entire header");
331 }
332
333 /*
334 Verify that the record type and record version are within some expected
335 range, so we can quickly reject totally invalid packets.
336
337 Unfortunately we cannot be more strict about the record number than just
338 checking the major version, at least at this level, due to this requirement
339 in RFC 7568
340
341 TLS servers MUST accept any value {03,XX} (including {03,00}) as
342 the record layer version number for ClientHello
343 */
344 const bool bad_record_type = readbuf[0] < 20 || readbuf[0] > 23;
345 const bool bad_record_version = readbuf[1] != 3;
346
347 if(bad_record_type || bad_record_version) {
348 // We know we read up to at least the 5 byte TLS header
349 const std::string first5 = std::string(reinterpret_cast<const char*>(readbuf.data()), 5);
350
351 if(first5 == "GET /" || first5 == "PUT /" || first5 == "POST " || first5 == "HEAD ") {
352 throw TLS_Exception(Alert::ProtocolVersion, "Client sent plaintext HTTP request instead of TLS handshake");
353 }
354
355 if(first5 == "CONNE") {
356 throw TLS_Exception(Alert::ProtocolVersion,
357 "Client sent plaintext HTTP proxy CONNECT request instead of TLS handshake");
358 }
359
360 if(bad_record_type) {
361 // RFC 5246 Section 6.
362 // If a TLS implementation receives an unexpected record type, it MUST
363 // send an unexpected_message alert.
364 throw TLS_Exception(Alert::UnexpectedMessage, "TLS record type had unexpected value");
365 }
366 throw TLS_Exception(Alert::ProtocolVersion, "TLS record version had unexpected value");
367 }
368
369 const Protocol_Version version(readbuf[1], readbuf[2]);
370
371 if(version.is_datagram_protocol()) {
372 throw TLS_Exception(Alert::ProtocolVersion, "Expected TLS but got a record with DTLS version");
373 }
374
375 const size_t record_size = make_uint16(readbuf[TLS_HEADER_SIZE - 2], readbuf[TLS_HEADER_SIZE - 1]);
376
377 if(record_size > MAX_CIPHERTEXT_SIZE) {
378 throw TLS_Exception(Alert::RecordOverflow, "Received a record that exceeds maximum size");
379 }
380
381 if(record_size == 0) {
382 throw TLS_Exception(Alert::DecodeError, "Received a completely empty record");
383 }
384
385 if(const size_t needed = fill_buffer_to(readbuf, input, input_len, consumed, TLS_HEADER_SIZE + record_size)) {
386 return Record_Header(needed);
387 }
388
389 BOTAN_ASSERT_EQUAL(static_cast<size_t>(TLS_HEADER_SIZE) + record_size, readbuf.size(), "Have the full record");
390
391 const Record_Type type = static_cast<Record_Type>(readbuf[0]);
392
393 uint16_t epoch = 0;
394
395 uint64_t sequence = 0;
396 if(sequence_numbers != nullptr) {
397 sequence = sequence_numbers->next_read_sequence();
398 epoch = sequence_numbers->current_read_epoch();
399 } else {
400 // server initial handshake case
401 epoch = 0;
402 }
403
404 if(epoch == 0) {
405 // Unencrypted initial handshake
406 recbuf.assign(readbuf.begin() + TLS_HEADER_SIZE, readbuf.begin() + TLS_HEADER_SIZE + record_size);
407 readbuf.clear();
408 return Record_Header(sequence, version, type);
409 }
410
411 // Otherwise, decrypt, check MAC, return plaintext
412 const auto cs = get_cipherstate(epoch);
413
414 BOTAN_ASSERT(cs, "Have cipherstate for this epoch");
415
416 decrypt_record(recbuf, &readbuf[TLS_HEADER_SIZE], record_size, sequence, version, type, *cs);
417
418 if(sequence_numbers != nullptr) {
419 sequence_numbers->read_accept(sequence);
420 }
421
422 readbuf.clear();
423 return Record_Header(sequence, version, type);
424}
425
426Record_Header read_dtls_record(secure_vector<uint8_t>& readbuf,
427 const uint8_t input[],
428 size_t input_len,
429 size_t& consumed,
431 Connection_Sequence_Numbers* sequence_numbers,
432 const get_cipherstate_fn& get_cipherstate,
433 bool allow_epoch0_restart) {
434 if(readbuf.size() < DTLS_HEADER_SIZE) {
435 // header incomplete
436 if(fill_buffer_to(readbuf, input, input_len, consumed, DTLS_HEADER_SIZE) != 0) {
437 readbuf.clear();
438 return Record_Header(0);
439 }
440
441 BOTAN_ASSERT_EQUAL(readbuf.size(), DTLS_HEADER_SIZE, "Have an entire header");
442 }
443
444 const Protocol_Version version(readbuf[1], readbuf[2]);
445
446 if(version.is_datagram_protocol() == false) {
447 readbuf.clear();
448 return Record_Header(0);
449 }
450
451 const size_t record_size = make_uint16(readbuf[DTLS_HEADER_SIZE - 2], readbuf[DTLS_HEADER_SIZE - 1]);
452
453 if(record_size > MAX_CIPHERTEXT_SIZE) {
454 // Too large to be valid, ignore it
455 readbuf.clear();
456 return Record_Header(0);
457 }
458
459 if(fill_buffer_to(readbuf, input, input_len, consumed, DTLS_HEADER_SIZE + record_size) != 0) {
460 // Truncated packet?
461 readbuf.clear();
462 return Record_Header(0);
463 }
464
465 BOTAN_ASSERT_EQUAL(static_cast<size_t>(DTLS_HEADER_SIZE) + record_size, readbuf.size(), "Have the full record");
466
467 const Record_Type type = static_cast<Record_Type>(readbuf[0]);
468
469 // RFC 6347 4.1.2.7
470 // In general, invalid records SHOULD be silently discarded, thus
471 // preserving the association; however, an error MAY be logged for
472 // diagnostic purposes.
475 readbuf.clear();
476 return Record_Header(0);
477 }
478
479 const uint64_t sequence = load_be<uint64_t>(&readbuf[3], 0);
480 const uint16_t epoch = (sequence >> 48);
481
482 const bool already_seen = sequence_numbers != nullptr && sequence_numbers->already_seen(sequence);
483
484 if(already_seen && !(epoch == 0 && allow_epoch0_restart)) {
485 readbuf.clear();
486 return Record_Header(0);
487 }
488
489 if(epoch == 0) {
490 // Unencrypted initial handshake. Epoch-0 records are unauthenticated and
491 // deliberately do not advance the replay window: one spoofed record with a
492 // high sequence number would otherwise silently drop every later record
493 // from the real peer. Duplicates are filtered by handshake reassembly.
494 recbuf.assign(readbuf.begin() + DTLS_HEADER_SIZE, readbuf.begin() + DTLS_HEADER_SIZE + record_size);
495 readbuf.clear();
496 return Record_Header(sequence, version, type);
497 }
498
499 try {
500 // Otherwise, decrypt, check MAC, return plaintext
501 const auto cs = get_cipherstate(epoch);
502
503 BOTAN_ASSERT(cs, "Have cipherstate for this epoch");
504
505 decrypt_record(recbuf, readbuf.data() + DTLS_HEADER_SIZE, record_size, sequence, version, type, *cs);
506 } catch(std::exception&) {
507 readbuf.clear();
508 return Record_Header(0);
509 }
510
511 if(sequence_numbers != nullptr) {
512 sequence_numbers->read_accept(sequence);
513 }
514
515 readbuf.clear();
516 return Record_Header(sequence, version, type);
517}
518
519} // namespace
520
522 secure_vector<uint8_t>& readbuf,
523 const uint8_t input[],
524 size_t input_len,
525 size_t& consumed,
527 Connection_Sequence_Numbers* sequence_numbers,
528 const get_cipherstate_fn& get_cipherstate,
529 bool allow_epoch0_restart) {
530 if(flavor == TLS_Flavor::DTLS) {
531 return read_dtls_record(
532 readbuf, input, input_len, consumed, recbuf, sequence_numbers, get_cipherstate, allow_epoch0_restart);
533 } else {
534 return read_tls_record(readbuf, input, input_len, consumed, recbuf, sequence_numbers, get_cipherstate);
535 }
536}
537
538} // namespace Botan::TLS
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition assert.h:95
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
void set_associated_data(std::span< const uint8_t > ad)
Definition aead.h:59
static std::unique_ptr< AEAD_Mode > create_or_throw(std::string_view algo, Cipher_Dir direction, std::string_view provider="")
Definition aead.cpp:51
static std::unique_ptr< BlockCipher > create_or_throw(std::string_view algo_spec, std::string_view provider="")
void start(std::span< const uint8_t > nonce)
Definition cipher_mode.h:98
void finish(secure_vector< uint8_t > &final_block, size_t offset=0)
virtual size_t output_length(size_t input_length) const =0
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:142
void randomize(std::span< uint8_t > output)
Definition rng.h:86
size_t nonce_bytes_from_record(Protocol_Version version) const
Nonce_Format nonce_format() const
size_t nonce_bytes_from_handshake() const
std::string mac_algo() const
std::string cipher_algo() const
Record_Nonce aead_nonce(uint64_t seq, RandomNumberGenerator &rng) const
Nonce_Format nonce_format() const
Definition tls_record.h:99
size_t nonce_bytes_from_handshake() const
Definition tls_record.h:95
std::array< uint8_t, 13 > format_ad(uint64_t seq, Record_Type type, Protocol_Version version, uint16_t ptext_length)
Connection_Cipher_State(Protocol_Version version, Connection_Side which_side, bool is_our_side, const Ciphersuite &suite, const Session_Keys &keys, bool uses_encrypt_then_mac)
uint8_t major_version() const
Definition tls_version.h:88
uint8_t minor_version() const
Definition tls_version.h:93
std::span< uint8_t > get()
Definition tls_record.h:49
const std::vector< uint8_t > & nonce(Connection_Side side) const
const secure_vector< uint8_t > & aead_key(Connection_Side side) const
@ MAX_CIPHERTEXT_SIZE
Definition tls_magic.h:40
@ TLS_HEADER_SIZE
Definition tls_magic.h:30
@ DTLS_HEADER_SIZE
Definition tls_magic.h:31
void write_unencrypted_record(secure_vector< uint8_t > &output, Record_Type record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len)
std::function< std::shared_ptr< Connection_Cipher_State >(uint16_t)> get_cipherstate_fn
Definition tls_record.h:180
void write_record(secure_vector< uint8_t > &output, Record_Type record_type, Protocol_Version version, uint64_t record_sequence, const uint8_t *message, size_t message_len, Connection_Cipher_State &cs, RandomNumberGenerator &rng)
Record_Header read_record(TLS_Flavor flavor, secure_vector< uint8_t > &readbuf, const uint8_t input[], size_t input_len, size_t &consumed, secure_vector< uint8_t > &recbuf, Connection_Sequence_Numbers *sequence_numbers, const get_cipherstate_fn &get_cipherstate, bool allow_epoch0_restart)
constexpr uint8_t get_byte(T input)
Definition loadstor.h:79
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144
constexpr void xor_buf(ranges::contiguous_output_range< uint8_t > auto &&out, ranges::contiguous_range< uint8_t > auto &&in)
Definition mem_ops.h:403
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
constexpr uint8_t get_byte_var(size_t byte_num, T input)
Definition loadstor.h:69
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504
constexpr uint16_t make_uint16(uint8_t i0, uint8_t i1)
Definition loadstor.h:92