Botan 3.14.1
Crypto and TLS for C&
tls_handshake_layer_13.h
Go to the documentation of this file.
1/*
2* TLS handshake layer implementation for TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_HANDSHAKE_LAYER_13_H_
10#define BOTAN_TLS_HANDSHAKE_LAYER_13_H_
11
12#include <optional>
13
14#include <botan/tls_magic.h>
15#include <botan/tls_messages_13.h>
16#include <botan/internal/tls_types_13.h>
17
18#include <botan/internal/tls_record_13.h>
19
20namespace Botan::TLS {
21
23
24/**
25 * Implementation of the TLS 1.3 handshake protocol layer
26 *
27 * This component transforms payload bytes received in TLS records
28 * from the peer into parsed handshake messages and vice versa.
29 */
31 protected:
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) {}
44
45 public:
49
50 public:
55
56 virtual ~Handshake_Layer() = default;
57
58 /**
59 * Reads data that was received in handshake records and stores it internally for further
60 * processing during the invocation of `next_message()`.
61 *
62 * @param policy The TLS policy
63 * @param data_from_peer The data to be parsed; typically the payload
64 * of one handshake record
65 */
66 virtual void copy_data(const Policy& policy, const Handshake_Record& data_from_peer) = 0;
67
68 /**
69 * Parses one handshake message off the internal buffer that is being filled using `copy_data`.
70 *
71 * @param policy the TLS policy
72 * @param transcript_hash the transcript hash state to be updated
73 *
74 * @return the parsed handshake message, or nullopt if more data is needed to complete the message
75 */
76 virtual std::optional<Handshake_Message_13> next_message(const Policy& policy,
77 Transcript_Hash_State& transcript_hash) = 0;
78
79 /**
80 * Parses one post-handshake message off the internal buffer that is being filled using `copy_data`.
81 *
82 * @param policy the TLS policy
83 *
84 * @return the parsed post-handshake message, or nullopt if more data is needed to complete the message
85 */
86 virtual std::optional<Post_Handshake_Message_13> next_post_handshake_message(const Policy& policy) = 0;
87
88 /**
89 * Marshals a ClientHello prematurely for a truncated transcript hash
90 * calculation (cf. RFC 8446 Section 4.2.11.2).
91 *
92 * @param message the ClientHello message to be marshalled
93 * @param transcript_hash the transcript hash state to be updated
94 */
96 Transcript_Hash_State& transcript_hash);
97
98 /**
99 * Check if the Handshake_Layer has stored a partial message in its internal buffer.
100 * This can happen if a handshake message spans multiple records.
101 */
102 virtual bool has_pending_data() const = 0;
103
104 /**
105 * Set the certificate_type used for parsing Certificate messages. This
106 * is determined via (client/server)_certificate_type extensions during
107 * the handshake.
108 *
109 * RFC 7250 4.3 and 4.4
110 * When the TLS server has specified RawPublicKey as the
111 * [client_certificate_type/server_certificate_type], authentication
112 * of the TLS [client/server] to the TLS [server/client] is supported
113 * only through authentication of the received client
114 * SubjectPublicKeyInfo via an out-of-band method.
115 *
116 * If the peer sends a Certificate message containing an incompatible
117 * means of authentication, a 'decode_error' will be generated.
118 */
119 void set_selected_certificate_type(Certificate_Type cert_type) { m_certificate_type = cert_type; }
120
121 protected:
122 enum class Handshake_Phase : bool { Handshake, PostHandshake };
123
124 static Handshake_Type read_handshake_message_type(uint8_t value, Handshake_Phase phase);
125
126 Connection_Side peer() const { return m_peer; }
127
128 Certificate_Type certificate_type() const { return m_certificate_type; }
129
130 virtual Handshake_Message_13 parse_handshake_message(Handshake_Type type,
131 std::span<const uint8_t> msg,
132 const Policy& policy) const;
133
134 Post_Handshake_Message_13 parse_post_handshake_message(Handshake_Type type, std::span<const uint8_t> msg) const;
135
136 private:
137 Connection_Side m_peer;
138 Certificate_Type m_certificate_type;
139};
140
142 public:
144
145 /**
146 * Prepare the TLS message header according to RFC9846 Section 4
147 */
148 static HandshakeProtocolHeader prepare_header(Handshake_Type type, size_t payload_length);
149
150 bool has_pending_data() const override { return m_read_offset < m_read_buffer.size(); }
151
152 void copy_data(const Policy& policy, const Handshake_Record& data_from_peer) override;
153
154 std::optional<Handshake_Message_13> next_message(const Policy& policy,
155 Transcript_Hash_State& transcript_hash) override;
156
157 std::optional<Post_Handshake_Message_13> next_post_handshake_message(const Policy& policy) override;
158
159 private:
160 struct IncomingMessage {
162 HandshakeProtocolHeader header = {};
163 SerializedHandshakeMessage message;
164 };
165
166 std::optional<IncomingMessage> next_incoming_message(const Policy& policy, Handshake_Phase phase);
167
168 private:
169 std::vector<uint8_t> m_read_buffer;
170 size_t m_read_offset = 0;
171};
172
173} // namespace Botan::TLS
174
175#endif
#define BOTAN_TEST_API
Definition api.h:41
static void update_transcript_for_psk_binder_calc(const Client_Hello_13 &message, Transcript_Hash_State &transcript_hash)
virtual ~Handshake_Layer()=default
virtual void copy_data(const Policy &policy, const Handshake_Record &data_from_peer)=0
Handshake_Layer & operator=(const Handshake_Layer &)=delete
virtual std::optional< Post_Handshake_Message_13 > next_post_handshake_message(const Policy &policy)=0
Handshake_Layer(Connection_Side whoami)
Handshake_Layer(Handshake_Layer &&)=delete
virtual std::optional< Handshake_Message_13 > next_message(const Policy &policy, Transcript_Hash_State &transcript_hash)=0
virtual bool has_pending_data() const =0
Handshake_Layer & operator=(Handshake_Layer &&)=delete
Handshake_Layer(const Handshake_Layer &)=delete
Certificate_Type certificate_type() const
static SerializedHandshakeMessage serialize(const Handshake_Message &message)
void set_selected_certificate_type(Certificate_Type cert_type)
virtual std::vector< uint8_t > serialize() const =0
TLS_Handshake_Layer(Connection_Side whoami)
Strong< std::array< uint8_t, 4 >, struct HandshakeProtocolHeader_ > HandshakeProtocolHeader
Holds the serialization of a TLS 1.3 handshake protocol header.
std::variant< Client_Hello_13, Client_Hello_12_Shim, Server_Hello_13, Server_Hello_12_Shim, Hello_Retry_Request, Encrypted_Extensions, Certificate_13, Certificate_Request_13, Certificate_Verify_13, Finished_13 > Handshake_Message_13
Strong< std::vector< uint8_t >, struct SerializedHandshakeMessage_ > SerializedHandshakeMessage
std::variant< New_Session_Ticket_13, Key_Update > Post_Handshake_Message_13