Botan 3.14.1
Crypto and TLS for C&
tls_record_13.cpp
Go to the documentation of this file.
1/*
2* TLS record structure 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#include <botan/internal/tls_record_13.h>
11
12#include <botan/tls_exceptn.h>
13#include <botan/internal/buffer_slicer.h>
14#include <botan/internal/concat_util.h>
15#include <botan/internal/loadstor.h>
16#include <botan/internal/stl_util.h>
17
18namespace Botan::TLS {
19
21 switch(record.type) {
23 return ChangeCipherSpec_Record{std::move(record)};
25 return Alert_Record{std::move(record)};
27 return Handshake_Record{std::move(record)};
29 return ApplicationData_Record{std::move(record)};
30
32 case Record_Type::Heartbeat: // not supported
33 break;
34 }
35
36 throw TLS_Exception(Alert::UnexpectedMessage, "TLS record type had unexpected value");
37}
38
39std::array<uint8_t, TLS_HEADER_SIZE> Record_TLS::serialize_header(Record_Type type,
41 uint16_t payload_length) {
43 store_be(legacy_version.version_code()), //
45}
46
47size_t Record_TLS::append(std::span<const uint8_t> bytes) {
49
50 BufferSlicer bs(bytes);
51
52 if(!header_complete()) {
53 // If we don't have the complete header yet, we have to first assemble
54 // that before we can know the amount of payload to store.
55
56 const auto remaining_header_portion = std::span{m_header}.subspan(m_header_bytes_stored);
57 const auto bytes_to_consume = std::min(remaining_header_portion.size(), bs.remaining());
58 bs.copy_into(remaining_header_portion.first(bytes_to_consume));
59 m_header_bytes_stored = static_cast<uint8_t>(m_header_bytes_stored + bytes_to_consume);
60 }
61
62 if(header_complete()) {
63 // Now we have the complete record header, we can look into the expected
64 // header information and start assembling the payload.
65
66 // The legacy major version is essentially ossified to 0x03 and anything
67 // else can be rejected right away.
68 if(legacy_version().major_version() != 0x03) {
69 throw TLS_Exception(Alert::IllegalParameter, "Received unexpected record version");
70 }
71
72 // RFC 9846 5.
73 // Implementations MUST NOT send record types not defined in this
74 // document unless negotiated by some extension. If a TLS
75 // implementation receives an unexpected record type, it MUST terminate
76 // the connection with an "unexpected_message" alert.
77 //
78 // RFC 9846 5.1
79 // enum {
80 // invalid(0),
81 // change_cipher_spec(20),
82 // alert(21),
83 // handshake(22),
84 // application_data(23),
85 // (255)
86 // } ContentType;
87 const auto record_type = type();
88 if(record_type != Record_Type::ApplicationData && //
89 record_type != Record_Type::Handshake && //
90 record_type != Record_Type::Alert && //
91 record_type != Record_Type::ChangeCipherSpec) {
92 throw TLS_Exception(Alert::UnexpectedMessage, "TLS record type had unexpected value");
93 }
94
95 const size_t expected_payload_length = payload_length();
96
97 // RFC 9846 5.1
98 // Implementations MUST NOT send zero-length fragments of Handshake
99 // types, even if those fragments contain padding.
100 //
101 // Zero-length fragments of Application Data MAY be sent, as they are
102 // potentially useful as a traffic analysis countermeasure.
103 //
104 // Hence, the payload length must always be non-null. Even for application
105 // data, the protected payload would contain at least the authentication
106 // tag and won't ever be empty either.
107 if(expected_payload_length == 0) {
108 throw TLS_Exception(Alert::DecodeError, "empty record received");
109 }
110
111 // TODO: we could restrict the payload length sanity checks further based
112 // on the record type: e.g. a reasonable unprotected alert record
113 // should be much smaller than 2^14 bytes.
114 if(record_type != Record_Type::ApplicationData) {
115 // RFC 9846 5.1 "Record Layer"
116 // The length MUST NOT exceed 2^14 bytes. An endpoint that receives
117 // a record that exceeds this length MUST terminate the connection
118 // with a "record_overflow" alert.
119 if(expected_payload_length > MAX_PLAINTEXT_SIZE) {
120 throw TLS_Exception(Alert::RecordOverflow, "Received a record that exceeds maximum size");
121 }
122 } else {
123 // RFC 9846 5.2 "Record Payload Protection"
124 // The length MUST NOT exceed 2^14 + 256 bytes. An endpoint that
125 // receives a record that exceeds this length MUST terminate the
126 // connection with a "record_overflow" alert.
127 //
128 // Note: Limits imposed by a "record_size_limit" extension do not come
129 // into play here, as those limits are on the plaintext _not_ the
130 // encrypted data. Constricted devices must be able to deal with
131 // data overhead inflicted by the AEAD.
132 if(expected_payload_length > MAX_CIPHERTEXT_SIZE_TLS13) {
133 throw TLS_Exception(Alert::RecordOverflow, "Received a protected record that exceeds maximum size");
134 }
135 }
136
137 // We now know the expected size of the payload and we sanity-checked it
138 // against the protocol limits. We can reserve enough space to hold it.
139 m_payload.reserve(expected_payload_length);
140
141 // Append as many payload bytes as we can, but don't overshoot into any
142 // other records that may be present in the input buffer.
143 const size_t remaining_payload_bytes = expected_payload_length - m_payload.size();
144 const size_t bytes_to_consume = std::min(remaining_payload_bytes, bs.remaining());
145 const auto new_payload_fragment = bs.take(bytes_to_consume);
146 m_payload.insert(m_payload.end(), new_payload_fragment.begin(), new_payload_fragment.end());
147 }
148
149 // Calculate the number of bytes consumed from the input buffer.
150 return bytes.size() - bs.remaining();
151}
152
154 // If we don't even have the complete header, we need at least the remaining
155 // header bytes to know the entire length of the record.
156 if(!header_complete()) {
157 return TLS_HEADER_SIZE - m_header_bytes_stored;
158 }
159
160 // If we have the header, we can determine the expected length of the
161 // payload and return the number of bytes still needed to complete it.
162 return payload_length() - m_payload.size();
163}
164
167 return static_cast<Record_Type>(m_header[0]);
168}
169
172 return Protocol_Version(load_be(std::span{m_header}.subspan<1, 2>()));
173}
174
177 return load_be(std::span{m_header}.subspan<3, 2>());
178}
179
180std::span<uint8_t, TLS_HEADER_SIZE> Record_TLS::header() {
182 return m_header;
183}
184
185std::span<const uint8_t, TLS_HEADER_SIZE> Record_TLS::header() const {
187 return m_header;
188}
189
190std::span<const uint8_t> Record_TLS::payload() const {
192 return m_payload;
193}
194
197 return std::exchange(m_payload, {});
198}
199
200} // namespace Botan::TLS
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
size_t remaining() const
void copy_into(std::span< uint8_t > sink)
std::span< const uint8_t > take(const size_t count)
secure_vector< uint8_t > take_payload()
bool header_complete() const
Returns true if the record has collected all header bytes.
bool complete() const
Returns true if the record has collected all its bytes.
std::span< uint8_t, TLS_HEADER_SIZE > header()
Record_Type type() const
size_t missing_bytes_hint() const
Returns the number of bytes needed to complete at least the record.
static std::array< uint8_t, TLS_HEADER_SIZE > serialize_header(Record_Type type, Protocol_Version legacy_version, uint16_t payload_length)
size_t append(std::span< const uint8_t > bytes)
std::span< const uint8_t > payload() const
uint16_t payload_length() const
Protocol_Version legacy_version() const
std::variant< ChangeCipherSpec_Record, Alert_Record, Handshake_Record, ApplicationData_Record > Record
@ MAX_PLAINTEXT_SIZE
Definition tls_magic.h:37
@ MAX_CIPHERTEXT_SIZE_TLS13
Definition tls_magic.h:47
@ TLS_HEADER_SIZE
Definition tls_magic.h:30
Record annotate_record_type(Record_Content &&record)
auto to_underlying(T e) noexcept
Definition stl_util.h:158
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504