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

#include <tls_handshake_layer_13.h>

Inheritance diagram for Botan::TLS::Handshake_Layer:
Botan::TLS::TLS_Handshake_Layer

Public Member Functions

virtual void copy_data (const Policy &policy, const Handshake_Record &data_from_peer)=0
 Handshake_Layer (const Handshake_Layer &)=delete
 Handshake_Layer (Handshake_Layer &&)=delete
virtual bool has_pending_data () const =0
virtual std::optional< Handshake_Message_13 > next_message (const Policy &policy, Transcript_Hash_State &transcript_hash)=0
virtual std::optional< Post_Handshake_Message_13 > next_post_handshake_message (const Policy &policy)=0
Handshake_Layer & operator= (const Handshake_Layer &)=delete
Handshake_Layer & operator= (Handshake_Layer &&)=delete
void set_selected_certificate_type (Certificate_Type cert_type)
virtual ~Handshake_Layer ()=default

Static Public Member Functions

static SerializedHandshakeMessage serialize (const Handshake_Message &message)
static void update_transcript_for_psk_binder_calc (const Client_Hello_13 &message, Transcript_Hash_State &transcript_hash)

Protected Types

enum class  Handshake_Phase : bool { Handshake , PostHandshake }

Protected Member Functions

Certificate_Type certificate_type () const
 Handshake_Layer (Connection_Side whoami)
virtual Handshake_Message_13 parse_handshake_message (Handshake_Type type, std::span< const uint8_t > msg, const Policy &policy) const
Post_Handshake_Message_13 parse_post_handshake_message (Handshake_Type type, std::span< const uint8_t > msg) const
Connection_Side peer () const

Static Protected Member Functions

static Handshake_Type read_handshake_message_type (uint8_t value, Handshake_Phase phase)

Detailed Description

Implementation of the TLS 1.3 handshake protocol layer

This component transforms payload bytes received in TLS records from the peer into parsed handshake messages and vice versa.

Definition at line 30 of file tls_handshake_layer_13.h.

Member Enumeration Documentation

◆ Handshake_Phase

enum class Botan::TLS::Handshake_Layer::Handshake_Phase : bool
strongprotected
Enumerator
Handshake 
PostHandshake 

Definition at line 122 of file tls_handshake_layer_13.h.

122: bool { Handshake, PostHandshake };

Constructor & Destructor Documentation

◆ Handshake_Layer() [1/3]

Botan::TLS::Handshake_Layer::Handshake_Layer ( Connection_Side whoami)
inlineexplicitprotected

Definition at line 32 of file tls_handshake_layer_13.h.

32 :
34 // RFC 8446 4.4.2
35 // If the corresponding certificate type extension
36 // ("server_certificate_type" or "client_certificate_type") was not
37 // negotiated in EncryptedExtensions, or the X.509 certificate type
38 // was negotiated, then each CertificateEntry contains a DER-encoded
39 // X.509 certificate.
40 //
41 // We need the certificate_type info to parse Certificate messages.
42 ,
43 m_certificate_type(Certificate_Type::X509) {}

Referenced by Handshake_Layer(), Handshake_Layer(), operator=(), operator=(), and Botan::TLS::TLS_Handshake_Layer::TLS_Handshake_Layer().

◆ Handshake_Layer() [2/3]

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

References Handshake_Layer().

◆ Handshake_Layer() [3/3]

Botan::TLS::Handshake_Layer::Handshake_Layer ( Handshake_Layer && )
delete

References Handshake_Layer().

◆ ~Handshake_Layer()

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

Member Function Documentation

◆ certificate_type()

Certificate_Type Botan::TLS::Handshake_Layer::certificate_type ( ) const
inlineprotected

Definition at line 128 of file tls_handshake_layer_13.h.

128{ return m_certificate_type; }

Referenced by parse_handshake_message().

◆ copy_data()

virtual void Botan::TLS::Handshake_Layer::copy_data ( const Policy & policy,
const Handshake_Record & data_from_peer )
pure virtual

Reads data that was received in handshake records and stores it internally for further processing during the invocation of next_message().

Parameters
policyThe TLS policy
data_from_peerThe data to be parsed; typically the payload of one handshake record

Implemented in Botan::TLS::TLS_Handshake_Layer.

◆ has_pending_data()

virtual bool Botan::TLS::Handshake_Layer::has_pending_data ( ) const
pure virtual

Check if the Handshake_Layer has stored a partial message in its internal buffer. This can happen if a handshake message spans multiple records.

Implemented in Botan::TLS::TLS_Handshake_Layer.

◆ next_message()

virtual std::optional< Handshake_Message_13 > Botan::TLS::Handshake_Layer::next_message ( const Policy & policy,
Transcript_Hash_State & transcript_hash )
pure virtual

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

Parameters
policythe TLS policy
transcript_hashthe transcript hash state to be updated
Returns
the parsed handshake message, or nullopt if more data is needed to complete the message

Implemented in Botan::TLS::TLS_Handshake_Layer.

◆ next_post_handshake_message()

virtual std::optional< Post_Handshake_Message_13 > Botan::TLS::Handshake_Layer::next_post_handshake_message ( const Policy & policy)
pure virtual

Parses one post-handshake message off the internal buffer that is being filled using copy_data.

Parameters
policythe TLS policy
Returns
the parsed post-handshake message, or nullopt if more data is needed to complete the message

Implemented in Botan::TLS::TLS_Handshake_Layer.

References update_transcript_for_psk_binder_calc().

◆ operator=() [1/2]

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

References Handshake_Layer().

◆ operator=() [2/2]

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

References Handshake_Layer().

◆ parse_handshake_message()

Handshake_Message_13 Botan::TLS::Handshake_Layer::parse_handshake_message ( Handshake_Type type,
std::span< const uint8_t > msg,
const Policy & policy ) const
protectedvirtual

Definition at line 30 of file tls_handshake_layer_13.cpp.

32 {
33 switch(type) {
34 // Client Hello and Server Hello messages are ambiguous. Both may come
35 // from non-TLS 1.3 peers. Hence, their parsing is somewhat different.
37 // ... might be TLS 1.2 Client Hello or TLS 1.3 Client Hello
40 // ... might be TLS 1.2 Server Hello or TLS 1.3 Server Hello or
41 // a TLS 1.3 Hello Retry Request disguising as a Server Hello
43 // case Handshake_Type::EndOfEarlyData:
44 // return End_Of_Early_Data(msg);
46 return Encrypted_Extensions(msg);
48 return Certificate_13(msg, policy, peer(), certificate_type());
50 return Certificate_Request_13(msg, peer());
52 return Certificate_Verify_13(msg, peer());
54 return Finished_13({msg.begin(), msg.end()});
55 default:
56 throw TLS_Exception(AlertType::UnexpectedMessage, "Unexpected handshake message received");
57 }
58}
static std::variant< Client_Hello_13, Client_Hello_12_Shim > parse(std::span< const uint8_t > buf)
Certificate_Type certificate_type() const
static std::variant< Hello_Retry_Request, Server_Hello_13, Server_Hello_12_Shim > parse(std::span< const uint8_t > buf)
constexpr GeneralVariantT generalize_to(SpecialT &&specific)
Converts a given variant into another variant-ish whose type states are a super set of the given vari...
Definition stl_util.h:88

References Botan::TLS::Certificate, certificate_type(), Botan::TLS::CertificateRequest, Botan::TLS::CertificateVerify, Botan::TLS::ClientHello, Botan::TLS::EncryptedExtensions, Botan::TLS::Finished, Botan::generalize_to(), Botan::TLS::Client_Hello_13::parse(), Botan::TLS::Server_Hello_13::parse(), peer(), Botan::TLS::ServerHello, and Botan::TLS::UnexpectedMessage.

Referenced by Botan::TLS::TLS_Handshake_Layer::next_message().

◆ parse_post_handshake_message()

Post_Handshake_Message_13 Botan::TLS::Handshake_Layer::parse_post_handshake_message ( Handshake_Type type,
std::span< const uint8_t > msg ) const
protected

Definition at line 60 of file tls_handshake_layer_13.cpp.

61 {
62 switch(type) {
64 return New_Session_Ticket_13(msg, peer());
66 return Key_Update(msg);
67 default:
68 throw TLS_Exception(AlertType::UnexpectedMessage, "Unexpected post-handshake message received");
69 }
70}

References Botan::TLS::KeyUpdate, Botan::TLS::NewSessionTicket, peer(), and Botan::TLS::UnexpectedMessage.

Referenced by Botan::TLS::TLS_Handshake_Layer::next_post_handshake_message().

◆ peer()

Connection_Side Botan::TLS::Handshake_Layer::peer ( ) const
inlineprotected

Definition at line 126 of file tls_handshake_layer_13.h.

126{ return m_peer; }

Referenced by parse_handshake_message(), and parse_post_handshake_message().

◆ read_handshake_message_type()

Handshake_Type Botan::TLS::Handshake_Layer::read_handshake_message_type ( uint8_t value,
Handshake_Phase phase )
staticprotected

Definition at line 78 of file tls_handshake_layer_13.cpp.

78 {
79 const auto type = static_cast<Handshake_Type>(value);
80
81 switch(type) {
82 // Handshake message types
90 if(phase == Handshake_Phase::Handshake) {
91 return type;
92 }
93 break;
94
95 // Post-handshake message types
99 return type;
100 }
101 break;
102
103 // TODO(0-RTT): implement handling for EndOfEarlyData
105
106 // TLS 1.2 specific handshake messages
114
115 // Pseudo handshake messages that aren't actually expected on the wire
120 break;
121 };
122
123 if(phase == Handshake_Phase::Handshake) {
124 throw TLS_Exception(AlertType::UnexpectedMessage, "Unknown handshake message received");
125 } else {
126 throw TLS_Exception(AlertType::UnexpectedMessage, "Unknown post-handshake message received");
127 }
128}

References Botan::TLS::Certificate, Botan::TLS::CertificateRequest, Botan::TLS::CertificateStatus, Botan::TLS::CertificateUrl, Botan::TLS::CertificateVerify, Botan::TLS::ClientHello, Botan::TLS::ClientKeyExchange, Botan::TLS::EncryptedExtensions, Botan::TLS::EndOfEarlyData, Botan::TLS::Finished, Handshake, Botan::TLS::HandshakeCCS, Botan::TLS::HelloRequest, Botan::TLS::HelloRetryRequest, Botan::TLS::HelloVerifyRequest, Botan::TLS::KeyUpdate, Botan::TLS::MessageHash, Botan::TLS::NewSessionTicket, Botan::TLS::None, PostHandshake, Botan::TLS::ServerHello, Botan::TLS::ServerHelloDone, Botan::TLS::ServerKeyExchange, and Botan::TLS::UnexpectedMessage.

◆ serialize()

SerializedHandshakeMessage Botan::TLS::Handshake_Layer::serialize ( const Handshake_Message & message)
inlinestatic

Definition at line 46 of file tls_handshake_layer_13.h.

46 {
47 return SerializedHandshakeMessage(message.serialize());
48 }
Strong< std::vector< uint8_t >, struct SerializedHandshakeMessage_ > SerializedHandshakeMessage

References Botan::TLS::Handshake_Message::serialize().

Referenced by update_transcript_for_psk_binder_calc().

◆ set_selected_certificate_type()

void Botan::TLS::Handshake_Layer::set_selected_certificate_type ( Certificate_Type cert_type)
inline

Set the certificate_type used for parsing Certificate messages. This is determined via (client/server)_certificate_type extensions during the handshake.

RFC 7250 4.3 and 4.4 When the TLS server has specified RawPublicKey as the [client_certificate_type/server_certificate_type], authentication of the TLS [client/server] to the TLS [server/client] is supported only through authentication of the received client SubjectPublicKeyInfo via an out-of-band method.

If the peer sends a Certificate message containing an incompatible means of authentication, a 'decode_error' will be generated.

Definition at line 119 of file tls_handshake_layer_13.h.

119{ m_certificate_type = cert_type; }

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

◆ update_transcript_for_psk_binder_calc()

void Botan::TLS::Handshake_Layer::update_transcript_for_psk_binder_calc ( const Client_Hello_13 & message,
Transcript_Hash_State & transcript_hash )
static

Marshals a ClientHello prematurely for a truncated transcript hash calculation (cf. RFC 8446 Section 4.2.11.2).

Parameters
messagethe ClientHello message to be marshalled
transcript_hashthe transcript hash state to be updated

Definition at line 72 of file tls_handshake_layer_13.cpp.

73 {
74 const auto msg_bytes = serialize(message);
75 transcript_hash.update(TLS_Handshake_Layer::prepare_header(message.wire_type(), msg_bytes.size()), msg_bytes);
76}
static SerializedHandshakeMessage serialize(const Handshake_Message &message)
static HandshakeProtocolHeader prepare_header(Handshake_Type type, size_t payload_length)

References Botan::TLS::TLS_Handshake_Layer::prepare_header(), serialize(), Botan::TLS::Transcript_Hash_State::update(), and Botan::TLS::Handshake_Message::wire_type().

Referenced by next_post_handshake_message().


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