Botan 3.14.1
Crypto and TLS for C&
Botan::TLS::Record_Layer Class Referenceabstract

#include <tls_record_layer_13.h>

Inheritance diagram for Botan::TLS::Record_Layer:
Botan::TLS::TLS_Record_Layer

Public Types

using ReadResult = variant_append_t<Record, BytesNeeded>

Public Member Functions

virtual void clear_read_buffer ()=0
void disable_receiving_compat_mode () noexcept
uint16_t incoming_record_size_limit () const noexcept
Record_Layer & operator= (const Record_Layer &)=delete
Record_Layer & operator= (Record_Layer &&)=delete
uint16_t outgoing_record_size_limit () const noexcept
bool receiving_compat_mode () const noexcept
 Record_Layer (const Record_Layer &)=delete
 Record_Layer (Record_Layer &&)=delete
virtual uint16_t record_payload_size_limit (const Policy &policy, Cipher_State *cipher_state=nullptr) const =0
void set_record_size_limits (uint16_t outgoing_limit, uint16_t incoming_limit)
virtual ~Record_Layer ()=default
Record Ingestion
virtual void copy_data (std::span< const uint8_t > data_from_peer)=0
virtual ReadResult next_record (Cipher_State *cipher_state=nullptr)=0
Record Preparation
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

Protected Member Functions

 Record_Layer ()

Detailed Description

Implementation of the TLS 1.3 record protocol layer

This component transforms bytes received from the peer into bytes containing plaintext TLS messages and vice versa.

Definition at line 33 of file tls_record_layer_13.h.

Member Typedef Documentation

◆ ReadResult

Constructor & Destructor Documentation

◆ Record_Layer() [1/3]

Botan::TLS::Record_Layer::Record_Layer ( )
protected

Definition at line 44 of file tls_record_layer_13.cpp.

44 :
45 m_outgoing_record_size_limit(MAX_PLAINTEXT_SIZE + content_type_tag_length),
46 m_incoming_record_size_limit(MAX_PLAINTEXT_SIZE + content_type_tag_length),
47
48 // RFC 8446 5.1
49 // legacy_record_version: MUST be set to 0x0303 for all records
50 // generated by a TLS 1.3 implementation other than an initial
51 // ClientHello [...], where it MAY also be 0x0301 for compatibility
52 // purposes.
53 //
54 // Additionally, older peers might send other values while requesting a
55 // protocol downgrade. I.e. we need to be able to tolerate/emit legacy
56 // values until we negotiated a TLS 1.3 compliant connection.
57 //
58 // As a client: we may initially emit the compatibility version and
59 // accept a wider range of incoming legacy record versions.
60 // As a server: we start with emitting the specified legacy version of 0x0303
61 // but must also allow a wider range of incoming legacy values.
62 //
63 // Once TLS 1.3 is negotiateed, the implementations will disable these
64 // compatibility modes accordingly or a protocol downgrade will transfer
65 // the marshalling responsibility to our TLS 1.2 implementation.
66 m_receiving_compat_mode(true) {}
@ MAX_PLAINTEXT_SIZE
Definition tls_magic.h:37

References Botan::TLS::MAX_PLAINTEXT_SIZE.

Referenced by operator=(), operator=(), Record_Layer(), and Record_Layer().

◆ ~Record_Layer()

virtual Botan::TLS::Record_Layer::~Record_Layer ( )
virtualdefault

◆ Record_Layer() [2/3]

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

References Record_Layer().

◆ Record_Layer() [3/3]

Botan::TLS::Record_Layer::Record_Layer ( Record_Layer && )
delete

References Record_Layer().

Member Function Documentation

◆ clear_read_buffer()

virtual void Botan::TLS::Record_Layer::clear_read_buffer ( )
pure virtual

Clears any data currently stored in the read buffer. This is typically used for memory cleanup when the peer sent a CloseNotify alert.

Implemented in Botan::TLS::TLS_Record_Layer.

References set_record_size_limits().

Referenced by Botan::TLS::Channel_IO::notify_closed_for_reading().

◆ copy_data()

virtual void Botan::TLS::Record_Layer::copy_data ( std::span< const uint8_t > data_from_peer)
pure virtual

Reads data that was received by the peer and stores it internally for further processing during the invocation of next_record().

Parameters
data_from_peerThe data to be parsed.

Implemented in Botan::TLS::TLS_Record_Layer.

Referenced by Botan::TLS::Channel_IO::copy_data().

◆ disable_receiving_compat_mode()

void Botan::TLS::Record_Layer::disable_receiving_compat_mode ( )
inlinenoexcept

Definition at line 133 of file tls_record_layer_13.h.

133{ m_receiving_compat_mode = false; }

◆ incoming_record_size_limit()

uint16_t Botan::TLS::Record_Layer::incoming_record_size_limit ( ) const
inlinenoexcept

Definition at line 131 of file tls_record_layer_13.h.

131{ return m_incoming_record_size_limit; }

Referenced by Botan::TLS::TLS_Record_Layer::next_record().

◆ next_record()

virtual ReadResult Botan::TLS::Record_Layer::next_record ( Cipher_State * cipher_state = nullptr)
pure virtual

Parses one record off the internal buffer that is being filled using copy_data.

Return value contains either the number of bytes (size_t) needed to proceed with processing TLS records or a single plaintext TLS record content containing higher level protocol or application data.

Parameters
cipher_stateOptional pointer to a Cipher_State instance. If provided, the cipher_state should be ready to decrypt data. Pass nullptr to process plaintext data.

Implemented in Botan::TLS::TLS_Record_Layer.

Referenced by Botan::TLS::Channel_IO::next_pending_event().

◆ operator=() [1/2]

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

References Record_Layer().

◆ operator=() [2/2]

Record_Layer & Botan::TLS::Record_Layer::operator= ( Record_Layer && )
delete

References Record_Layer().

◆ outgoing_record_size_limit()

uint16_t Botan::TLS::Record_Layer::outgoing_record_size_limit ( ) const
inlinenoexcept

Definition at line 129 of file tls_record_layer_13.h.

129{ return m_outgoing_record_size_limit; }

Referenced by Botan::TLS::TLS_Record_Layer::prepare_record(), and Botan::TLS::TLS_Record_Layer::record_payload_size_limit().

◆ prepare_record()

virtual void Botan::TLS::Record_Layer::prepare_record ( const Policy & policy,
Record_Type type,
std::span< const uint8_t > payload,
Cipher_State * cipher_state,
secure_vector< uint8_t > & out )
pure virtual

Prepares a record for transmission.

The payload passed into this function must fit into a single record,

See also
record_payload_size_limit() for the maximum allowed payload size.
Parameters
policyThe TLS policy for record size constraints
typeThe type of the record to be prepared.
payloadThe plaintext payload to be included in the record.
cipher_stateIf not nullptr, the record will be encrypted using this cipher state. Pass nullptr to prepare a plaintext record.
outThe container the marshalled record is written to

Implemented in Botan::TLS::TLS_Record_Layer.

◆ receiving_compat_mode()

bool Botan::TLS::Record_Layer::receiving_compat_mode ( ) const
inlinenoexcept

Definition at line 135 of file tls_record_layer_13.h.

135{ return m_receiving_compat_mode; }

Referenced by Botan::TLS::TLS_Record_Layer::next_record().

◆ record_payload_size_limit()

virtual uint16_t Botan::TLS::Record_Layer::record_payload_size_limit ( const Policy & policy,
Cipher_State * cipher_state = nullptr ) const
pure virtual

Returns the maximum number of bytes that can be put into a record.

Both the specified and negotiated record size limit is taken into account. Depending on the cipher_state, the size of the record overhead (e.g. MAC, padding, record header, etc.) is also considered.

Implemented in Botan::TLS::TLS_Record_Layer.

◆ set_record_size_limits()

void Botan::TLS::Record_Layer::set_record_size_limits ( uint16_t outgoing_limit,
uint16_t incoming_limit )

Set the record size limits as negotiated by the "record_size_limit" extension (RFC 8449). The limits refer to the number of plaintext bytes to be encrypted/decrypted – INCLUDING the encrypted content type byte introduced with TLS 1.3. The record size limit is not applied to unprotected records. Incoming records that exceed the set limit will result in a fatal alert.

Parameters
outgoing_limitthe maximal number of plaintext bytes to be sent in a protected record
incoming_limitthe maximal number of plaintext bytes to be accepted in a received protected record

Definition at line 68 of file tls_record_layer_13.cpp.

68 {
69 // RFC 8449 4.
70 // Endpoints MUST NOT send a "record_size_limit" extension with a value
71 // smaller than 64.
72 BOTAN_ARG_CHECK(outgoing_limit >= 64, "Invalid outgoing record size limit");
73 BOTAN_ARG_CHECK(incoming_limit >= 64 && incoming_limit <= MAX_PLAINTEXT_SIZE + content_type_tag_length,
74 "Invalid incoming record size limit");
75
76 // RFC 8449 4.
77 // Even if a larger record size limit is provided by a peer, an endpoint
78 // MUST NOT send records larger than the protocol-defined limit, unless
79 // explicitly allowed by a future TLS version or extension.
80 m_outgoing_record_size_limit =
81 std::min(outgoing_limit, static_cast<uint16_t>(MAX_PLAINTEXT_SIZE + content_type_tag_length));
82 m_incoming_record_size_limit = incoming_limit;
83}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK, and Botan::TLS::MAX_PLAINTEXT_SIZE.

Referenced by clear_read_buffer(), and Botan::TLS::Channel_IO::set_record_size_limits().


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