Botan 3.14.1
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* 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#ifndef BOTAN_TLS_RECORD_LAYER_13_H_
11#define BOTAN_TLS_RECORD_LAYER_13_H_
12
13#include <botan/secmem.h>
14#include <botan/tls_magic.h>
15#include <botan/internal/stl_util.h>
16#include <botan/internal/tls_record_13.h>
17#include <botan/internal/tls_types_13.h>
18#include <deque>
19#include <memory>
20#include <span>
21
22namespace Botan::TLS {
23
24class Cipher_State;
25class Policy;
26
27/**
28 * Implementation of the TLS 1.3 record protocol layer
29 *
30 * This component transforms bytes received from the peer into bytes
31 * containing plaintext TLS messages and vice versa.
32 */
34 protected:
36
37 public:
38 virtual ~Record_Layer() = default;
39 Record_Layer(const Record_Layer&) = delete;
43
45
46 /// @name Record Ingestion
47 /// @{
48
49 /**
50 * Reads data that was received by the peer and stores it internally for further
51 * processing during the invocation of `next_record()`.
52 *
53 * @param data_from_peer The data to be parsed.
54 */
55 virtual void copy_data(std::span<const uint8_t> data_from_peer) = 0;
56
57 /**
58 * Parses one record off the internal buffer that is being filled using `copy_data`.
59 *
60 * Return value contains either the number of bytes (`size_t`) needed to proceed
61 * with processing TLS records or a single plaintext TLS record content containing
62 * higher level protocol or application data.
63 *
64 * @param cipher_state Optional pointer to a Cipher_State instance. If provided, the
65 * cipher_state should be ready to decrypt data. Pass nullptr to
66 * process plaintext data.
67 */
68 virtual ReadResult next_record(Cipher_State* cipher_state = nullptr) = 0;
69
70 /// @}
71
72 /// @name Record Preparation
73 /// @{
74
75 /**
76 * Prepares a record for transmission.
77 *
78 * The payload passed into this function must fit into a single record,
79 * @sa record_payload_size_limit() for the maximum allowed payload size.
80 *
81 * @param policy The TLS policy for record size constraints
82 * @param type The type of the record to be prepared.
83 * @param payload The plaintext payload to be included in the
84 * record.
85 * @param cipher_state If not nullptr, the record will be encrypted using
86 * this cipher state. Pass nullptr to prepare a
87 * plaintext record.
88 * @param out The container the marshalled record is written to
89 */
90 virtual void prepare_record(const Policy& policy,
91 Record_Type type,
92 std::span<const uint8_t> payload,
93 Cipher_State* cipher_state,
94 secure_vector<uint8_t>& out) = 0;
95
96 /// @}
97
98 /**
99 * Returns the maximum number of bytes that can be put into a record.
100 *
101 * Both the specified and negotiated record size limit is taken into
102 * account. Depending on the @p cipher_state, the size of the record
103 * overhead (e.g. MAC, padding, record header, etc.) is also considered.
104 */
105 virtual uint16_t record_payload_size_limit(const Policy& policy, Cipher_State* cipher_state = nullptr) const = 0;
106
107 /**
108 * Clears any data currently stored in the read buffer. This is typically
109 * used for memory cleanup when the peer sent a CloseNotify alert.
110 */
111 virtual void clear_read_buffer() = 0;
112
113 public:
114 /**
115 * Set the record size limits as negotiated by the "record_size_limit"
116 * extension (RFC 8449). The limits refer to the number of plaintext bytes
117 * to be encrypted/decrypted -- INCLUDING the encrypted content type byte
118 * introduced with TLS 1.3. The record size limit is _not_ applied to
119 * unprotected records. Incoming records that exceed the set limit will
120 * result in a fatal alert.
121 *
122 * @param outgoing_limit the maximal number of plaintext bytes to be
123 * sent in a protected record
124 * @param incoming_limit the maximal number of plaintext bytes to be
125 * accepted in a received protected record
126 */
127 void set_record_size_limits(uint16_t outgoing_limit, uint16_t incoming_limit);
128
129 uint16_t outgoing_record_size_limit() const noexcept { return m_outgoing_record_size_limit; }
130
131 uint16_t incoming_record_size_limit() const noexcept { return m_incoming_record_size_limit; }
132
133 void disable_receiving_compat_mode() noexcept { m_receiving_compat_mode = false; }
134
135 bool receiving_compat_mode() const noexcept { return m_receiving_compat_mode; }
136
137 private:
138 // Those are either the limits set by the TLS 1.3 specification (RFC 8446),
139 // or the ones negotiated via the "record_size_limit" extension (RFC 8449).
140 uint16_t m_outgoing_record_size_limit;
141 uint16_t m_incoming_record_size_limit;
142
143 // This status flag is required for version validation where the initial
144 // records for sending and receiving is handled differently for backward
145 // compatibility reasons. (RFC 8446 5.1 regarding "legacy_record_version")
146 bool m_receiving_compat_mode;
147};
148
150 public:
151 explicit TLS_Record_Layer(Connection_Side side);
152
153 void copy_data(std::span<const uint8_t> data) override;
154 ReadResult next_record(Cipher_State* cipher_state = nullptr) override;
155 void prepare_record(const Policy& policy,
156 Record_Type type,
157 std::span<const uint8_t> payload,
158 Cipher_State* cipher_state,
159 secure_vector<uint8_t>& out) override;
160
161 void clear_read_buffer() override;
162
163 uint16_t record_payload_size_limit(const Policy& policy, Cipher_State* cipher_state = nullptr) const override;
164
165 void disable_sending_compat_mode() noexcept { m_sending_compat_mode = false; }
166
167 private:
168 bool m_sending_compat_mode;
169 std::deque<Record_TLS> m_incoming_records;
170};
171
172} // namespace Botan::TLS
173
174#endif
#define BOTAN_TEST_API
Definition api.h:41
virtual void copy_data(std::span< const uint8_t > data_from_peer)=0
uint16_t outgoing_record_size_limit() const noexcept
Record_Layer & operator=(Record_Layer &&)=delete
void set_record_size_limits(uint16_t outgoing_limit, uint16_t incoming_limit)
variant_append_t< Record, BytesNeeded > ReadResult
virtual ReadResult next_record(Cipher_State *cipher_state=nullptr)=0
Record_Layer & operator=(const Record_Layer &)=delete
uint16_t incoming_record_size_limit() const noexcept
virtual ~Record_Layer()=default
virtual void prepare_record(const Policy &policy, Record_Type type, std::span< const uint8_t > payload, Cipher_State *cipher_state, secure_vector< uint8_t > &out)=0
virtual void clear_read_buffer()=0
Record_Layer(Record_Layer &&)=delete
void disable_receiving_compat_mode() noexcept
virtual uint16_t record_payload_size_limit(const Policy &policy, Cipher_State *cipher_state=nullptr) const =0
bool receiving_compat_mode() const noexcept
Record_Layer(const Record_Layer &)=delete
TLS_Record_Layer(Connection_Side side)
void prepare_record(const Policy &policy, Record_Type type, std::span< const uint8_t > payload, Cipher_State *cipher_state, secure_vector< uint8_t > &out) override
void copy_data(std::span< const uint8_t > data) override
uint16_t record_payload_size_limit(const Policy &policy, Cipher_State *cipher_state=nullptr) const override
ReadResult next_record(Cipher_State *cipher_state=nullptr) override
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
typename variant_append< Variant, T >::type variant_append_t
Converts a given variant into another variant with all its alternative types and an additional altern...
Definition stl_util.h:143