Botan 3.3.0
Crypto and TLS for C&
tls_record_layer_13.h
Go to the documentation of this file.
1/*
2* TLS record layer 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_RECORD_LAYER_13_H_
10#define BOTAN_TLS_RECORD_LAYER_13_H_
11
12#include <optional>
13#include <span>
14#include <variant>
15#include <vector>
16
17#include <botan/secmem.h>
18#include <botan/tls_magic.h>
19#include <botan/internal/tls_channel_impl.h>
20
21namespace Botan::TLS {
22
23/**
24 * Resembles the `TLSPlaintext` structure in RFC 8446 5.1
25 * minus the record protocol specifics and ossified bytes.
26 */
27struct Record {
30 std::optional<uint64_t> seq_no; // unprotected records have no sequence number
31
33 type(record_type), fragment(std::move(frgmnt)), seq_no(std::nullopt) {}
34};
35
36using BytesNeeded = size_t;
37
38class Cipher_State;
39
40/**
41 * Implementation of the TLS 1.3 record protocol layer
42 *
43 * This component transforms bytes received from the peer into bytes
44 * containing plaintext TLS messages and vice versa.
45 */
47 public:
49
50 template <typename ResT>
51 using ReadResult = std::variant<BytesNeeded, ResT>;
52
53 /**
54 * Reads data that was received by the peer and stores it internally for further
55 * processing during the invocation of `next_record()`.
56 *
57 * @param data_from_peer The data to be parsed.
58 */
59 void copy_data(std::span<const uint8_t> data_from_peer);
60
61 /**
62 * Parses one record off the internal buffer that is being filled using `copy_data`.
63 *
64 * Return value contains either the number of bytes (`size_t`) needed to proceed
65 * with processing TLS records or a single plaintext TLS record content containing
66 * higher level protocol or application data.
67 *
68 * @param cipher_state Optional pointer to a Cipher_State instance. If provided, the
69 * cipher_state should be ready to decrypt data. Pass nullptr to
70 * process plaintext data.
71 */
72 ReadResult<Record> next_record(Cipher_State* cipher_state = nullptr);
73
74 std::vector<uint8_t> prepare_records(Record_Type type,
75 std::span<const uint8_t> data,
76 Cipher_State* cipher_state = nullptr) const;
77
78 /**
79 * Clears any data currently stored in the read buffer. This is typically
80 * used for memory cleanup when the peer sent a CloseNotify alert.
81 */
82 void clear_read_buffer() { zap(m_read_buffer); }
83
84 /**
85 * Set the record size limits as negotiated by the "record_size_limit"
86 * extension (RFC 8449). The limits refer to the number of plaintext bytes
87 * to be encrypted/decrypted -- INCLUDING the encrypted content type byte
88 * introduced with TLS 1.3. The record size limit is _not_ applied to
89 * unprotected records. Incoming records that exceed the set limit will
90 * result in a fatal alert.
91 *
92 * @param outgoing_limit the maximal number of plaintext bytes to be
93 * sent in a protected record
94 * @param incoming_limit the maximal number of plaintext bytes to be
95 * accepted in a received protected record
96 */
97 void set_record_size_limits(uint16_t outgoing_limit, uint16_t incoming_limit);
98
99 void disable_sending_compat_mode() { m_sending_compat_mode = false; }
100
101 void disable_receiving_compat_mode() { m_receiving_compat_mode = false; }
102
103 private:
104 std::vector<uint8_t> m_read_buffer;
105 Connection_Side m_side;
106
107 // Those are either the limits set by the TLS 1.3 specification (RFC 8446),
108 // or the ones negotiated via the "record_size_limit" extension (RFC 8449).
109 uint16_t m_outgoing_record_size_limit;
110 uint16_t m_incoming_record_size_limit;
111
112 // Those status flags are required for version validation where the initial
113 // records for sending and receiving is handled differently for backward
114 // compatibility reasons. (RFC 8446 5.1 regarding "legacy_record_version")
115 bool m_sending_compat_mode;
116 bool m_receiving_compat_mode;
117};
118
119} // namespace Botan::TLS
120
121#endif
std::variant< BytesNeeded, ResT > ReadResult
#define BOTAN_TEST_API
Definition compiler.h:51
void zap(std::vector< T, Alloc > &vec)
Definition secmem.h:117
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
std::optional< uint64_t > seq_no
secure_vector< uint8_t > fragment
Record(Record_Type record_type, secure_vector< uint8_t > frgmnt)