Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Record_TLS Class Referencefinal

#include <tls_record_13.h>

Public Member Functions

size_t append (std::span< const uint8_t > bytes)
bool complete () const
 Returns true if the record has collected all its bytes.
std::span< uint8_t, TLS_HEADER_SIZE > header ()
std::span< const uint8_t, TLS_HEADER_SIZE > header () const
bool header_complete () const
 Returns true if the record has collected all header bytes.
Protocol_Version legacy_version () const
size_t missing_bytes_hint () const
 Returns the number of bytes needed to complete at least the record.
Record_TLS & operator= (const Record_TLS &)=delete
Record_TLS & operator= (Record_TLS &&)=default
std::span< const uint8_t > payload () const
uint16_t payload_length () const
 Record_TLS ()=default
 Record_TLS (const Record_TLS &)=delete
 Record_TLS (Record_TLS &&)=default
size_t stored_bytes () const
 Returns the total number of bytes in this record, including the header.
secure_vector< uint8_t > take_payload ()
Record_Type type () const
 ~Record_TLS ()=default

Static Public Member Functions

static std::array< uint8_t, TLS_HEADER_SIZE > serialize_header (Record_Type type, Protocol_Version legacy_version, uint16_t payload_length)

Detailed Description

Represents a TLS record composed of a partially ossified header and payload. The record might be incomplete, i.e. not all bytes of the header or the payload have been received, yet. The record can be extended by appending more bytes to it.

Once fully re-assembled, the payload buffer can be extracted from this record for decryption. This avoids an additional copy of the payload bytes.

Definition at line 59 of file tls_record_13.h.

Constructor & Destructor Documentation

◆ Record_TLS() [1/3]

Botan::TLS::Record_TLS::Record_TLS ( )
default

◆ Record_TLS() [2/3]

Botan::TLS::Record_TLS::Record_TLS ( const Record_TLS & )
delete

References Record_TLS().

◆ Record_TLS() [3/3]

Botan::TLS::Record_TLS::Record_TLS ( Record_TLS && )
default

References Record_TLS().

◆ ~Record_TLS()

Botan::TLS::Record_TLS::~Record_TLS ( )
default

Member Function Documentation

◆ append()

size_t Botan::TLS::Record_TLS::append ( std::span< const uint8_t > bytes)

Appends bytes to an incomplete record. Once the record is complete, additional invocations will throw. If bytes contains more bytes than needed to complete the record, only the required number of bytes will be consumed and the rest will be ignored. The caller is responsible for keeping track of the number of bytes consumed and for discarding the consumed bytes from the buffer.

Returns
the number of bytes that were consumed from the buffer.

Definition at line 47 of file tls_record_13.cpp.

47 {
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}
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
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.
Record_Type type() const
uint16_t payload_length() const
Protocol_Version legacy_version() const
@ MAX_PLAINTEXT_SIZE
Definition tls_magic.h:37
@ MAX_CIPHERTEXT_SIZE_TLS13
Definition tls_magic.h:47

References Botan::TLS::Alert, Botan::TLS::ApplicationData, BOTAN_STATE_CHECK, Botan::TLS::ChangeCipherSpec, complete(), Botan::BufferSlicer::copy_into(), Botan::TLS::Handshake, header_complete(), legacy_version(), Botan::TLS::MAX_CIPHERTEXT_SIZE_TLS13, Botan::TLS::MAX_PLAINTEXT_SIZE, payload_length(), Botan::BufferSlicer::remaining(), Botan::BufferSlicer::take(), and type().

Referenced by ~Record_TLS().

◆ complete()

bool Botan::TLS::Record_TLS::complete ( ) const
inline

Returns true if the record has collected all its bytes.

Definition at line 91 of file tls_record_13.h.

91{ return missing_bytes_hint() == 0; }
size_t missing_bytes_hint() const
Returns the number of bytes needed to complete at least the record.

References missing_bytes_hint().

Referenced by append(), payload(), and take_payload().

◆ header() [1/2]

std::span< uint8_t, TLS_HEADER_SIZE > Botan::TLS::Record_TLS::header ( )

Definition at line 180 of file tls_record_13.cpp.

180 {
182 return m_header;
183}

References BOTAN_STATE_CHECK, and header_complete().

Referenced by Botan::TLS::TLS_Cipher_State::deprotect_record().

◆ header() [2/2]

std::span< const uint8_t, TLS_HEADER_SIZE > Botan::TLS::Record_TLS::header ( ) const

Definition at line 185 of file tls_record_13.cpp.

185 {
187 return m_header;
188}

References BOTAN_STATE_CHECK, and header_complete().

◆ header_complete()

bool Botan::TLS::Record_TLS::header_complete ( ) const
inline

Returns true if the record has collected all header bytes.

Definition at line 88 of file tls_record_13.h.

88{ return m_header_bytes_stored == TLS_HEADER_SIZE; }
@ TLS_HEADER_SIZE
Definition tls_magic.h:30

References Botan::TLS::TLS_HEADER_SIZE.

Referenced by append(), header(), header(), legacy_version(), missing_bytes_hint(), payload_length(), and type().

◆ legacy_version()

Protocol_Version Botan::TLS::Record_TLS::legacy_version ( ) const

Definition at line 170 of file tls_record_13.cpp.

170 {
172 return Protocol_Version(load_be(std::span{m_header}.subspan<1, 2>()));
173}
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504

References BOTAN_STATE_CHECK, header_complete(), and Botan::load_be().

Referenced by append(), serialize_header(), and ~Record_TLS().

◆ missing_bytes_hint()

size_t Botan::TLS::Record_TLS::missing_bytes_hint ( ) const

Returns the number of bytes needed to complete at least the record.

Definition at line 153 of file tls_record_13.cpp.

153 {
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}

References header_complete(), payload_length(), and Botan::TLS::TLS_HEADER_SIZE.

Referenced by complete().

◆ operator=() [1/2]

Record_TLS & Botan::TLS::Record_TLS::operator= ( const Record_TLS & )
delete

References Record_TLS().

◆ operator=() [2/2]

Record_TLS & Botan::TLS::Record_TLS::operator= ( Record_TLS && )
default

References Record_TLS().

◆ payload()

std::span< const uint8_t > Botan::TLS::Record_TLS::payload ( ) const

Definition at line 190 of file tls_record_13.cpp.

190 {
192 return m_payload;
193}

References BOTAN_STATE_CHECK, and complete().

Referenced by Botan::TLS::TLS_Cipher_State::deprotect_record().

◆ payload_length()

uint16_t Botan::TLS::Record_TLS::payload_length ( ) const

Definition at line 175 of file tls_record_13.cpp.

175 {
177 return load_be(std::span{m_header}.subspan<3, 2>());
178}

References BOTAN_STATE_CHECK, header_complete(), and Botan::load_be().

Referenced by append(), missing_bytes_hint(), serialize_header(), and ~Record_TLS().

◆ serialize_header()

std::array< uint8_t, TLS_HEADER_SIZE > Botan::TLS::Record_TLS::serialize_header ( Record_Type type,
Protocol_Version legacy_version,
uint16_t payload_length )
static

Definition at line 39 of file tls_record_13.cpp.

41 {
43 store_be(legacy_version.version_code()), //
45}
auto to_underlying(T e) noexcept
Definition stl_util.h:158
constexpr auto concat(Rs &&... ranges)
Definition concat_util.h:95
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

References Botan::concat(), legacy_version(), payload_length(), Botan::store_be(), Botan::to_underlying(), and type().

Referenced by Botan::TLS::TLS_Record_Layer::prepare_record(), Botan::TLS::TLS_Cipher_State::protect_record(), and ~Record_TLS().

◆ stored_bytes()

size_t Botan::TLS::Record_TLS::stored_bytes ( ) const
inline

Returns the total number of bytes in this record, including the header.

Definition at line 94 of file tls_record_13.h.

94{ return m_header_bytes_stored + m_payload.size(); }

◆ take_payload()

secure_vector< uint8_t > Botan::TLS::Record_TLS::take_payload ( )

Definition at line 195 of file tls_record_13.cpp.

195 {
197 return std::exchange(m_payload, {});
198}

References BOTAN_STATE_CHECK, and complete().

Referenced by Botan::TLS::TLS_Cipher_State::deprotect_record().

◆ type()

Record_Type Botan::TLS::Record_TLS::type ( ) const

Definition at line 165 of file tls_record_13.cpp.

165 {
167 return static_cast<Record_Type>(m_header[0]);
168}

References BOTAN_STATE_CHECK, and header_complete().

Referenced by append(), Botan::TLS::TLS_Cipher_State::deprotect_record(), serialize_header(), and ~Record_TLS().


The documentation for this class was generated from the following files: