Botan::TLS::Record_Layer Class Reference

#include <tls_record_layer_13.h>

Public Types
template<typename ResT>
using	ReadResult = std::variant<BytesNeeded, ResT>

Public Member Functions
void	clear_read_buffer ()
void	copy_data (std::span< const uint8_t > data_from_peer)
void	disable_receiving_compat_mode ()
void	disable_sending_compat_mode ()
ReadResult< Record >	next_record (Cipher_State *cipher_state=nullptr)
std::vector< uint8_t >	prepare_records (Record_Type type, std::span< const uint8_t > data, Cipher_State *cipher_state=nullptr) const
	Record_Layer (Connection_Side side)
void	set_record_size_limits (uint16_t outgoing_limit, uint16_t incoming_limit)

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 46 of file tls_record_layer_13.h.

Member Typedef Documentation

ReadResult

template<typename ResT>

using Botan::TLS::Record_Layer::ReadResult = std::variant<BytesNeeded, ResT>

Definition at line 51 of file tls_record_layer_13.h.

Constructor & Destructor Documentation

Record_Layer()

Botan::TLS::Record_Layer::Record_Layer ( Connection_Side side )

explicit

Definition at line 147 of file tls_record_layer_13.cpp.

                                               :
      m_side(side),
      m_outgoing_record_size_limit(MAX_PLAINTEXT_SIZE + 1 /* content type byte */),
      m_incoming_record_size_limit(MAX_PLAINTEXT_SIZE + 1 /* content type byte */)
 
      // RFC 8446 5.1
      //    legacy_record_version: MUST be set to 0x0303 for all records
      //       generated by a TLS 1.3 implementation other than an initial
      //       ClientHello [...], where it MAY also be 0x0301 for compatibility
      //       purposes.
      //
      // Additionally, older peers might send other values while requesting a
      // protocol downgrade. I.e. we need to be able to tolerate/emit legacy
      // values until we negotiated a TLS 1.3 compliant connection.
      //
      // As a client: we may initially emit the compatibility version and
      //              accept a wider range of incoming legacy record versions.
      // As a server: we start with emitting the specified legacy version of 0x0303
      //              but must also allow a wider range of incoming legacy values.
      //
      // Once TLS 1.3 is negotiateed, the implementations will disable these
      // compatibility modes accordingly or a protocol downgrade will transfer
      // the marshalling responsibility to our TLS 1.2 implementation.
      ,
      m_sending_compat_mode(m_side == Connection_Side::Client),
      m_receiving_compat_mode(true) {}

References Botan::TLS::MAX_PLAINTEXT_SIZE.

Member Function Documentation

clear_read_buffer()

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

inline

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

Definition at line 82 of file tls_record_layer_13.h.

                               {
         zap(m_read_buffer);
         m_read_offset = 0;
      }

References Botan::zap().

copy_data()

void Botan::TLS::Record_Layer::copy_data

(

std::span< const uint8_t >

data_from_peer

)

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

Parameters

data_from_peer

The data to be parsed.

Definition at line 174 of file tls_record_layer_13.cpp.

                                                        {
   // Compact consumed data before appending new data
   BOTAN_ASSERT_NOMSG(m_read_offset <= m_read_buffer.size());
   if(m_read_offset > 0) {
      m_read_buffer.erase(m_read_buffer.begin(), m_read_buffer.begin() + m_read_offset);
      m_read_offset = 0;
   }
 
   m_read_buffer.insert(m_read_buffer.end(), data.begin(), data.end());
}

References BOTAN_ASSERT_NOMSG.

disable_receiving_compat_mode()

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

inline

Definition at line 104 of file tls_record_layer_13.h.

{ m_receiving_compat_mode = false; }

disable_sending_compat_mode()

void Botan::TLS::Record_Layer::disable_sending_compat_mode ( )

inline

Definition at line 102 of file tls_record_layer_13.h.

{ m_sending_compat_mode = false; }

next_record()

Record_Layer::ReadResult< Record > Botan::TLS::Record_Layer::next_record

(

Cipher_State *

cipher_state = nullptr

)

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_state

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

Definition at line 291 of file tls_record_layer_13.cpp.

                                                                                   {
   const auto remaining = m_read_buffer.size() - m_read_offset;
 
   if(remaining < TLS_HEADER_SIZE) {
      return TLS_HEADER_SIZE - remaining;
   }
 
   const auto header_begin = m_read_buffer.cbegin() + m_read_offset;
   const auto header_end = header_begin + TLS_HEADER_SIZE;
 
   // The first received record(s) are likely a client or server hello. To be able to
   // perform protocol downgrades we must be less vigorous with the record's
   // legacy version. Hence, `check_tls13_version` is `false` for the first record(s).
   const TLSPlaintext_Header plaintext_header({header_begin, header_end}, !m_receiving_compat_mode);
 
   // After the key exchange phase of the handshake is completed and record protection is engaged,
   // cipher_state is set. At this point, only protected traffic (and CCS) is allowed.
   //
   // RFC 8446 2.
   //    -  Key Exchange: Establish shared keying material and select the
   //       cryptographic parameters.  Everything after this phase is
   //       encrypted.
   // RFC 8446 5.
   //    An implementation may receive an unencrypted [CCS] at any time
   if(cipher_state != nullptr && plaintext_header.type() != Record_Type::ApplicationData &&
      plaintext_header.type() != Record_Type::ChangeCipherSpec &&
      (!cipher_state->must_expect_unprotected_alert_traffic() || plaintext_header.type() != Record_Type::Alert)) {
      throw TLS_Exception(Alert::UnexpectedMessage, "unprotected record received where protected traffic was expected");
   }
 
   if(remaining < TLS_HEADER_SIZE + plaintext_header.fragment_length()) {
      return TLS_HEADER_SIZE + plaintext_header.fragment_length() - remaining;
   }
 
   const auto fragment_begin = header_end;
   const auto fragment_end = fragment_begin + plaintext_header.fragment_length();
 
   if(plaintext_header.type() == Record_Type::ChangeCipherSpec &&
      !verify_change_cipher_spec(fragment_begin, plaintext_header.fragment_length())) {
      throw TLS_Exception(Alert::UnexpectedMessage, "malformed change cipher spec record received");
   }
 
   Record record(plaintext_header.type(), secure_vector<uint8_t>(fragment_begin, fragment_end));
   m_read_offset += TLS_HEADER_SIZE + plaintext_header.fragment_length();
 
   // If all buffered data has been consumed, release the buffer memory
   // to avoid retaining peak allocation on idle connections.
   if(m_read_offset == m_read_buffer.size()) {
      zap(m_read_buffer);
      m_read_offset = 0;
   }
 
   if(record.type == Record_Type::ApplicationData) {
      if(cipher_state == nullptr) {
         // This could also mean a misuse of the interface, i.e. failing to provide a valid
         // cipher_state to parse_records when receiving valid (encrypted) Application Data.
         throw TLS_Exception(Alert::UnexpectedMessage, "premature Application Data received");
      }
 
      if(record.fragment.size() < cipher_state->minimum_decryption_input_length()) {
         throw TLS_Exception(Alert::BadRecordMac, "incomplete record mac received");
      }
 
      if(cipher_state->decrypt_output_length(record.fragment.size()) > m_incoming_record_size_limit) {
         throw TLS_Exception(Alert::RecordOverflow, "Received an encrypted record that exceeds maximum plaintext size");
      }
 
      record.seq_no = cipher_state->decrypt_record_fragment(plaintext_header.serialized(), record.fragment);
 
      // Remove record padding (RFC 8446 5.4). The TLSInnerPlaintext layout is
      //   content || content_type || zero_padding
      auto seen_nonzero = CT::Mask<uint8_t>::cleared();
      uint8_t content_type_byte = 0;
      size_t content_index = 0;
      for(size_t i = record.fragment.size(); i-- > 0;) {
         const uint8_t b = record.fragment[i];
         const auto byte_is_nonzero = CT::Mask<uint8_t>::expand(b);
         // Set on the first non-zero byte we encounter scanning right-to-left.
         const auto first_nonzero = byte_is_nonzero & ~seen_nonzero;
         content_type_byte = first_nonzero.select(b, content_type_byte);
         content_index = CT::Mask<size_t>::expand(first_nonzero.value()).select(i, content_index);
         seen_nonzero |= byte_is_nonzero;
      }
 
      if(!seen_nonzero.as_bool()) {
         // RFC 8446 5.4
         //   If a receiving implementation does not
         //   find a non-zero octet in the cleartext, it MUST terminate the
         //   connection with an "unexpected_message" alert.
         throw TLS_Exception(Alert::UnexpectedMessage, "No content type found in encrypted record");
      }
 
      // hydrate the actual content type from TLSInnerPlaintext
      record.type = read_record_type(content_type_byte);
 
      if(record.type == Record_Type::ChangeCipherSpec) {
         // RFC 8446 5
         //  An implementation [...] which receives a protected change_cipher_spec record MUST
         //  abort the handshake with an "unexpected_message" alert.
         throw TLS_Exception(Alert::UnexpectedMessage, "protected change cipher spec received");
      }
 
      // Truncate to drop the content_type byte and padding. resize() on a
      // vector of trivially-destructible elements is bookkeeping-only and
      // does not allocate or iterate over the dropped suffix.
      record.fragment.resize(content_index);
 
      // RFC 8446 5.4
      //    Implementations MUST NOT send Handshake and Alert records that have
      //    a zero-length TLSInnerPlaintext.content; if such a message is
      //    received, the receiving implementation MUST terminate the connection
      //    with an "unexpected_message" alert.
      if(record.fragment.empty() && record.type != Record_Type::ApplicationData) {
         throw TLS_Exception(Alert::UnexpectedMessage,
                             "Received a protected record with empty TLSInnerPlaintext content");
      }
   }
 
   return record;
}

References Botan::TLS::Alert, Botan::TLS::ApplicationData, Botan::TLS::ChangeCipherSpec, Botan::CT::Mask< T >::cleared(), Botan::TLS::Cipher_State::decrypt_output_length(), Botan::TLS::Cipher_State::decrypt_record_fragment(), Botan::CT::Mask< T >::expand(), Botan::TLS::Record::fragment, Botan::TLS::Cipher_State::minimum_decryption_input_length(), Botan::TLS::Cipher_State::must_expect_unprotected_alert_traffic(), Botan::TLS::Record::seq_no, Botan::TLS::TLS_HEADER_SIZE, Botan::TLS::Record::type, and Botan::zap().

prepare_records()

std::vector< uint8_t > Botan::TLS::Record_Layer::prepare_records	(	Record_Type	type,
		std::span< const uint8_t >	data,
		Cipher_State *	cipher_state = nullptr ) const

Definition at line 185 of file tls_record_layer_13.cpp.

                                                                                     {
   // RFC 8446 5.
   //    Note that [change_cipher_spec records] may appear at a point at the
   //    handshake where the implementation is expecting protected records.
   //
   // RFC 8446 5.
   //    An implementation which receives [...] a protected change_cipher_spec
   //    record MUST abort the handshake [...].
   //
   // ... hence, CHANGE_CIPHER_SPEC is never protected, even if a usable cipher
   // state was passed to this method.
   const bool protect = cipher_state != nullptr && type != Record_Type::ChangeCipherSpec;
 
   // RFC 8446 5.1
   BOTAN_ASSERT(protect || type != Record_Type::ApplicationData,
                "Application Data records MUST NOT be written to the wire unprotected");
 
   // RFC 8446 5.1
   //   "MUST NOT sent zero-length fragments of Handshake types"
   //   "a record with an Alert type MUST contain exactly one message" [of non-zero length]
   //   "Zero-length fragments of Application Data MAY be sent"
   BOTAN_ASSERT(!data.empty() || type == Record_Type::ApplicationData,
                "zero-length fragments of types other than application data are not allowed");
 
   if(type == Record_Type::ChangeCipherSpec && !verify_change_cipher_spec(data.begin(), data.size())) {
      throw Invalid_Argument("TLS 1.3 deprecated CHANGE_CIPHER_SPEC");
   }
 
   std::vector<uint8_t> output;
 
   // RFC 8446 5.2
   //    type:  The TLSPlaintext.type value containing the content type of the record.
   constexpr size_t content_type_tag_length = 1;
 
   // RFC 8449 4.
   //    When the "record_size_limit" extension is negotiated, an endpoint
   //    MUST NOT generate a protected record with plaintext that is larger
   //    than the RecordSizeLimit value it receives from its peer.
   //    Unprotected messages are not subject to this limit.
   const size_t max_plaintext_size =
      (protect) ? m_outgoing_record_size_limit - content_type_tag_length : static_cast<uint16_t>(MAX_PLAINTEXT_SIZE);
 
   const auto records = std::max((data.size() + max_plaintext_size - 1) / max_plaintext_size, size_t(1));
   auto output_length = records * TLS_HEADER_SIZE;
   if(protect) {
      // n-1 full records of size max_plaintext_size
      output_length +=
         (records - 1) * cipher_state->encrypt_output_length(max_plaintext_size + content_type_tag_length);
      // last record with size of remaining data
      output_length += cipher_state->encrypt_output_length(data.size() - ((records - 1) * max_plaintext_size) +
                                                           content_type_tag_length);
   } else {
      output_length += data.size();
   }
   output.reserve(output_length);
 
   size_t pt_offset = 0;
   size_t to_process = data.size();
 
   // For protected records we need to write at least one encrypted fragment,
   // even if the plaintext size is zero. This happens only for Application
   // Data types.
   BOTAN_ASSERT_NOMSG(to_process != 0 || protect);
   // NOLINTNEXTLINE(*-avoid-do-while)
   do {
      const size_t pt_size = std::min<size_t>(to_process, max_plaintext_size);
      const size_t ct_size =
         (!protect) ? pt_size : cipher_state->encrypt_output_length(pt_size + content_type_tag_length);
      const auto pt_type = (!protect) ? type : Record_Type::ApplicationData;
 
      // RFC 8446 5.1
      //    MUST be set to 0x0303 for all records generated by a TLS 1.3
      //    implementation other than an initial ClientHello [...], where
      //    it MAY also be 0x0301 for compatibility purposes.
      const auto record_header = TLSPlaintext_Header(pt_type, ct_size, m_sending_compat_mode).serialized();
 
      output.insert(output.end(), record_header.cbegin(), record_header.cend());
 
      auto pt_fragment = data.subspan(pt_offset, pt_size);
      if(protect) {
         secure_vector<uint8_t> fragment;
         fragment.reserve(ct_size);
 
         // assemble TLSInnerPlaintext structure
         fragment.insert(fragment.end(), pt_fragment.begin(), pt_fragment.end());
         fragment.push_back(static_cast<uint8_t>(type));
         // TODO: zero padding could go here, see RFC 8446 5.4
 
         cipher_state->encrypt_record_fragment(record_header, fragment);
         BOTAN_ASSERT_NOMSG(fragment.size() == ct_size);
 
         output.insert(output.end(), fragment.cbegin(), fragment.cend());
      } else {
         output.insert(output.end(), pt_fragment.begin(), pt_fragment.end());
      }
 
      pt_offset += pt_size;
      to_process -= pt_size;
   } while(to_process > 0);
 
   BOTAN_ASSERT_NOMSG(output.size() == output_length);
   return output;
}

References Botan::TLS::ApplicationData, BOTAN_ASSERT, BOTAN_ASSERT_NOMSG, Botan::TLS::ChangeCipherSpec, Botan::TLS::Cipher_State::encrypt_output_length(), Botan::TLS::Cipher_State::encrypt_record_fragment(), Botan::TLS::MAX_PLAINTEXT_SIZE, and Botan::TLS::TLS_HEADER_SIZE.

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_limit	the maximal number of plaintext bytes to be sent in a protected record
incoming_limit	the maximal number of plaintext bytes to be accepted in a received protected record

Definition at line 412 of file tls_record_layer_13.cpp.

                                                                                                      {
   BOTAN_ARG_CHECK(outgoing_limit >= 64, "Invalid outgoing record size limit");
   BOTAN_ARG_CHECK(incoming_limit >= 64 && incoming_limit <= MAX_PLAINTEXT_SIZE + 1,
                   "Invalid incoming record size limit");
 
   // RFC 8449 4.
   //    Even if a larger record size limit is provided by a peer, an endpoint
   //    MUST NOT send records larger than the protocol-defined limit, unless
   //    explicitly allowed by a future TLS version or extension.
   m_outgoing_record_size_limit = std::min(outgoing_limit, static_cast<uint16_t>(MAX_PLAINTEXT_SIZE + 1));
   m_incoming_record_size_limit = incoming_limit;
}

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

---

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

• src/lib/tls/tls13/tls_record_layer_13.h
• src/lib/tls/tls13/tls_record_layer_13.cpp