Botan 3.14.1
Crypto and TLS for C&
tls_handshake_state.h
Go to the documentation of this file.
1/*
2* TLS Handshake State
3* (C) 2004-2006,2011,2012 Jack Lloyd
4* 2017 Harry Reimann, Rohde & Schwarz Cybersecurity
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_HANDSHAKE_STATE_H_
10#define BOTAN_TLS_HANDSHAKE_STATE_H_
11
12#include <botan/assert.h>
13#include <botan/tls_ciphersuite.h>
14#include <botan/tls_exceptn.h>
15#include <botan/tls_extensions.h>
16#include <botan/tls_handshake_msg.h>
17#include <botan/tls_session.h>
18#include <botan/x509cert.h>
19#include <botan/internal/tls_handshake_hash.h>
20#include <botan/internal/tls_handshake_io.h>
21#include <botan/internal/tls_handshake_transitions.h>
22#include <botan/internal/tls_session_key.h>
23#include <optional>
24#include <vector>
25
26namespace Botan {
27
28enum class Signature_Format : uint8_t;
29class Public_Key;
30class KDF;
31
32namespace TLS {
33
34class Callbacks;
35class Policy;
37
39class Client_Hello_12;
40class Server_Hello_12;
41class Certificate_12;
49class Finished_12;
50
51/**
52* SSL/TLS Handshake State
53*
54* This is a data holder object for all state aggregated during the handshake,
55* both on client and server side and across protocol versions.
56* It does not implement any logic and offers no guarantees regarding state
57* consistency and legal TLS state transitions.
58*
59* TODO: currently it implements some logic for TLS 1.2, which should be removed
60* TODO: investigate moving the handshake_io to the channel
61*/
63 public:
64 Handshake_State(std::unique_ptr<Handshake_IO> io, Callbacks& callbacks);
66
67 Handshake_State(const Handshake_State& other) = delete;
69 Handshake_State& operator=(const Handshake_State& other) = delete;
71
72 Handshake_IO& handshake_io() { return *m_handshake_io; }
73
74 std::unique_ptr<Handshake_IO> take_handshake_io() { return std::move(m_handshake_io); }
75
76 /**
77 * Return true iff we have received a particular message already
78 * @param msg_type the message type
79 */
80 bool received_handshake_msg(Handshake_Type msg_type) const;
81
82 /**
83 * Confirm that we were expecting this message type
84 * @param msg_type the message type
85 */
87
88 /**
89 * Record that we are expecting a particular message type next
90 * @param msg_type the message type
91 */
92 void set_expected_next(Handshake_Type msg_type);
93
94 std::pair<Handshake_Type, std::vector<uint8_t>> get_next_handshake_msg(size_t max_handshake_msg_size);
95
97
98 std::pair<std::string, Signature_Format> parse_sig_format(const Public_Key& key,
99 Signature_Scheme scheme,
100 const std::vector<Signature_Scheme>& offered_schemes,
101 bool for_client_auth,
102 const Policy& policy) const;
103
104 std::pair<std::string, Signature_Format> choose_sig_format(const Private_Key& key,
105 Signature_Scheme& scheme,
106 bool for_client_auth,
107 const Policy& policy) const;
108
109 std::unique_ptr<KDF> protocol_specific_prf() const;
110
111 Protocol_Version version() const { return m_version; }
112
114
115 void hello_verify_request(const Hello_Verify_Request& hello_verify);
116
117 void client_hello(std::unique_ptr<Client_Hello_12> client_hello);
118 void server_hello(std::unique_ptr<Server_Hello_12> server_hello);
119 void server_cert_status(std::unique_ptr<Certificate_Status> server_cert_status);
120 void server_kex(std::unique_ptr<Server_Key_Exchange> server_kex);
121 void cert_req(std::unique_ptr<Certificate_Request_12> cert_req);
122 void server_hello_done(std::unique_ptr<Server_Hello_Done> server_hello_done);
123 void client_kex(std::unique_ptr<Client_Key_Exchange> client_kex);
124
125 void client_certs(std::unique_ptr<Certificate_12> client_certs);
126 void server_certs(std::unique_ptr<Certificate_12> server_certs);
127
128 void client_verify(std::unique_ptr<Certificate_Verify_12> client_verify);
129 void server_verify(std::unique_ptr<Certificate_Verify_12> server_verify);
130
131 void server_finished(std::unique_ptr<Finished_12> server_finished);
132 void client_finished(std::unique_ptr<Finished_12> client_finished);
133
134 void new_session_ticket(std::unique_ptr<New_Session_Ticket_12> new_session_ticket);
135
136 /*
137 * Whether a given handshake message has been received/stored yet.
138 */
139 bool has_client_hello() const { return m_client_hello != nullptr; }
140
141 bool has_server_hello() const { return m_server_hello != nullptr; }
142
143 bool has_server_certs() const { return m_server_certs != nullptr; }
144
145 bool has_server_kex() const { return m_server_kex != nullptr; }
146
147 bool has_cert_req() const { return m_cert_req != nullptr; }
148
149 bool has_server_hello_done() const { return m_server_hello_done != nullptr; }
150
151 bool has_client_certs() const { return m_client_certs != nullptr; }
152
153 bool has_client_kex() const { return m_client_kex != nullptr; }
154
155 bool has_client_verify() const { return m_client_verify != nullptr; }
156
157 bool has_server_verify() const { return m_server_verify != nullptr; }
158
159 bool has_server_cert_status() const { return m_server_cert_status != nullptr; }
160
161 bool has_new_session_ticket() const { return m_new_session_ticket != nullptr; }
162
163 bool has_server_finished() const { return m_server_finished != nullptr; }
164
165 bool has_client_finished() const { return m_client_finished != nullptr; }
166
167 /*
168 * Accessors for the handshake messages. Each asserts the message is
169 * present and returns a reference, for the common case where the protocol
170 * state machine has already established that it must exist.
171 */
172 const Client_Hello_12& client_hello() const { return require(m_client_hello); }
173
174 const Server_Hello_12& server_hello() const { return require(m_server_hello); }
175
176 const Certificate_12& server_certs() const { return require(m_server_certs); }
177
178 const Server_Key_Exchange& server_kex() const { return require(m_server_kex); }
179
180 const Certificate_Request_12& cert_req() const { return require(m_cert_req); }
181
182 const Server_Hello_Done& server_hello_done() const { return require(m_server_hello_done); }
183
184 const Certificate_12& client_certs() const { return require(m_client_certs); }
185
186 const Client_Key_Exchange& client_kex() const { return require(m_client_kex); }
187
188 const Certificate_Verify_12& client_verify() const { return require(m_client_verify); }
189
190 const Certificate_Verify_12& server_verify() const { return require(m_server_verify); }
191
192 const Certificate_Status& server_cert_status() const { return require(m_server_cert_status); }
193
194 const New_Session_Ticket_12& new_session_ticket() const { return require(m_new_session_ticket); }
195
196 const Finished_12& server_finished() const { return require(m_server_finished); }
197
198 const Finished_12& client_finished() const { return require(m_client_finished); }
199
200 /*
201 * Pointer accessors that return nullptr when the message has not been received
202 */
203 const Client_Hello_12* maybe_client_hello() const { return m_client_hello.get(); }
204
205 const Server_Hello_12* maybe_server_hello() const { return m_server_hello.get(); }
206
207 const Certificate_12* maybe_server_certs() const { return m_server_certs.get(); }
208
209 const Server_Key_Exchange* maybe_server_kex() const { return m_server_kex.get(); }
210
211 const Certificate_Request_12* maybe_cert_req() const { return m_cert_req.get(); }
212
213 const Server_Hello_Done* maybe_server_hello_done() const { return m_server_hello_done.get(); }
214
215 const Certificate_12* maybe_client_certs() const { return m_client_certs.get(); }
216
217 const Client_Key_Exchange* maybe_client_kex() const { return m_client_kex.get(); }
218
219 const Certificate_Verify_12* maybe_client_verify() const { return m_client_verify.get(); }
220
221 const Certificate_Verify_12* maybe_server_verify() const { return m_server_verify.get(); }
222
223 const Certificate_Status* maybe_server_cert_status() const { return m_server_cert_status.get(); }
224
225 const New_Session_Ticket_12* maybe_new_session_ticket() const { return m_new_session_ticket.get(); }
226
227 const Finished_12* maybe_server_finished() const { return m_server_finished.get(); }
228
229 const Finished_12* maybe_client_finished() const { return m_client_finished.get(); }
230
231 virtual std::vector<X509_Certificate> peer_cert_chain() const = 0;
232
233 const Ciphersuite& ciphersuite() const;
234
235 std::optional<std::string> psk_identity() const;
236
237 const Session_Keys& session_keys() const { return m_session_keys; }
238
239 Callbacks& callbacks() const { return m_callbacks; }
240
242
243 void compute_session_keys(const secure_vector<uint8_t>& resume_master_secret);
244
245 Handshake_Hash& hash() { return m_handshake_hash; }
246
247 const Handshake_Hash& hash() const { return m_handshake_hash; }
248
249 void note_message(const Handshake_Message& msg);
250
251 private:
252 template <typename T>
253 static const T& require(const std::unique_ptr<T>& msg) {
255 return *msg;
256 }
257
258 Callbacks& m_callbacks;
259
260 std::unique_ptr<Handshake_IO> m_handshake_io;
261
262 Handshake_Transitions m_transitions;
263 Protocol_Version m_version;
264 std::optional<Ciphersuite> m_ciphersuite;
265 Session_Keys m_session_keys;
266 Handshake_Hash m_handshake_hash;
267
268 std::unique_ptr<Client_Hello_12> m_client_hello;
269 std::unique_ptr<Server_Hello_12> m_server_hello;
270
271 std::unique_ptr<Certificate_12> m_server_certs;
272 std::unique_ptr<Certificate_Status> m_server_cert_status;
273 std::unique_ptr<Server_Key_Exchange> m_server_kex;
274 std::unique_ptr<Certificate_Request_12> m_cert_req;
275 std::unique_ptr<Server_Hello_Done> m_server_hello_done;
276 std::unique_ptr<Certificate_12> m_client_certs;
277 std::unique_ptr<Client_Key_Exchange> m_client_kex;
278 std::unique_ptr<Certificate_Verify_12> m_client_verify;
279 std::unique_ptr<Certificate_Verify_12> m_server_verify;
280 std::unique_ptr<New_Session_Ticket_12> m_new_session_ticket;
281 std::unique_ptr<Finished_12> m_server_finished;
282 std::unique_ptr<Finished_12> m_client_finished;
283};
284
285} // namespace TLS
286
287} // namespace Botan
288
289#endif
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
std::pair< std::string, Signature_Format > parse_sig_format(const Public_Key &key, Signature_Scheme scheme, const std::vector< Signature_Scheme > &offered_schemes, bool for_client_auth, const Policy &policy) const
const Finished_12 * maybe_client_finished() const
const Certificate_12 * maybe_client_certs() const
const Finished_12 & server_finished() const
Handshake_State & operator=(const Handshake_State &other)=delete
void hello_verify_request(const Hello_Verify_Request &hello_verify)
void set_expected_next(Handshake_Type msg_type)
const Certificate_Verify_12 * maybe_client_verify() const
void note_message(const Handshake_Message &msg)
std::pair< Handshake_Type, std::vector< uint8_t > > get_next_handshake_msg(size_t max_handshake_msg_size)
const Server_Hello_Done * maybe_server_hello_done() const
const Server_Hello_12 * maybe_server_hello() const
const Certificate_Verify_12 & client_verify() const
const Certificate_Verify_12 & server_verify() const
Handshake_State(std::unique_ptr< Handshake_IO > io, Callbacks &callbacks)
const Server_Key_Exchange & server_kex() const
const Certificate_Verify_12 * maybe_server_verify() const
const Session_Keys & session_keys() const
const Certificate_Status * maybe_server_cert_status() const
const Certificate_Request_12 * maybe_cert_req() const
const Client_Hello_12 * maybe_client_hello() const
const New_Session_Ticket_12 & new_session_ticket() const
const Server_Hello_12 & server_hello() const
const Certificate_Status & server_cert_status() const
const Finished_12 * maybe_server_finished() const
const Handshake_Hash & hash() const
Handshake_State(const Handshake_State &other)=delete
const Finished_12 & client_finished() const
const Client_Hello_12 & client_hello() const
void confirm_transition_to(Handshake_Type msg_type)
const Certificate_12 & server_certs() const
std::unique_ptr< Handshake_IO > take_handshake_io()
void set_version(const Protocol_Version &version)
std::optional< std::string > psk_identity() const
const Server_Hello_Done & server_hello_done() const
const Certificate_12 * maybe_server_certs() const
const Client_Key_Exchange & client_kex() const
const Ciphersuite & ciphersuite() const
Handshake_State(Handshake_State &&other)=delete
Session_Ticket session_ticket() const
const Certificate_Request_12 & cert_req() const
Handshake_State & operator=(Handshake_State &&other)=delete
const Certificate_12 & client_certs() const
virtual std::vector< X509_Certificate > peer_cert_chain() const =0
const Client_Key_Exchange * maybe_client_kex() const
bool received_handshake_msg(Handshake_Type msg_type) const
const New_Session_Ticket_12 * maybe_new_session_ticket() const
std::unique_ptr< KDF > protocol_specific_prf() const
std::pair< std::string, Signature_Format > choose_sig_format(const Private_Key &key, Signature_Scheme &scheme, bool for_client_auth, const Policy &policy) const
const Server_Key_Exchange * maybe_server_kex() const
Protocol_Version version() const
Strong< std::vector< uint8_t >, struct Session_Ticket_ > Session_Ticket
holds a TLS 1.2 session ticket for stateless resumption
Signature_Format
Definition pk_keys.h:36
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128