Botan 3.14.1
Crypto and TLS for C&
tls_messages_internal.h
Go to the documentation of this file.
1/*
2* TLS Client/Server Hello Internal Data Containers
3* (C) 2004-2026 Jack Lloyd
4* 2021 Elektrobit Automotive GmbH
5* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
6* 2026 René Meusel - Rohde & Schwarz Cybersecurity GmbH
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#ifndef BOTAN_TLS_MESSAGES_INTERNAL_H_
12#define BOTAN_TLS_MESSAGES_INTERNAL_H_
13
14#include <botan/tls_extensions.h>
15#include <botan/tls_session.h>
16#include <botan/tls_version.h>
17#include <vector>
18
19namespace Botan {
21
22namespace TLS {
23class Callbacks;
24class Policy;
25} // namespace TLS
26
27} // namespace Botan
28
29namespace Botan::TLS {
30
31/**
32 * Generate a (client) hello random value.
33 *
34 * Depending on the policy, the RNG output may be hashed and if TLS 1.2 is
35 * offered, the random value may contain a timestamp.
36 */
37std::vector<uint8_t> make_hello_random(RandomNumberGenerator& rng, Callbacks& cb, const Policy& policy);
38
39/**
40 * Generate a server hello random value for the given protocol version.
41 *
42 * Depending on the protocol version, the random value is generated differently.
43 * For instance, TLS 1.2 requested a timestamp in the random value. Also, when
44 * downgrading to TLS 1.2 from a peer that could also negotiate TLS 1.3, the
45 * random value must be slightly modified to signal the downgrade.
46 */
47std::vector<uint8_t> make_server_hello_random(RandomNumberGenerator& rng,
48 Protocol_Version offered_version,
49 Callbacks& cb,
50 const Policy& policy,
51 TLS_Flavor flavor);
52
53/**
54 * The Brainpool group code points of RFC 7027 are only defined up to TLS 1.2,
55 * those of RFC 8734 and all KEM groups only for TLS 1.3.
56 */
58
59/**
60 * Filter @p groups by group_usable_in_version()
61 */
62std::vector<Group_Params> groups_usable_in_version(std::span<const Group_Params> groups, Protocol_Version version);
63
64/**
65 * Return true if @p group is an elliptic curve group, or an unknown group outside
66 * the FFDHE range which the application may implement as a curve via the callbacks
67 */
69
70/**
71 * Compute a cookie value from the ClientHello and the client's identity. Used
72 * by both the DTLS 1.2 HelloVerifyRequest and the DTLS 1.3 HelloRetryRequest
73 * cookie extension.
74 *
75 * Note: Currently, Botan does not support proper stateless handling of
76 * HelloVerifyRequest/HelloRetryRequest messages using Cookies.
77 */
78std::vector<uint8_t> calculate_cookie(std::span<const uint8_t> client_hello_bits,
79 std::string_view client_identity,
80 std::span<const uint8_t> cookie_secret);
81
82/**
83 * Parse a "status_request" extension. In a ClientHello, a request for any
84 * status_type other than "ocsp" is not supported and is treated as an unknown
85 * extension.
86 */
87std::unique_ptr<Extension> make_certificate_status_request(TLS_Data_Reader& reader,
88 uint16_t extension_size,
89 Handshake_Type message_type,
90 Connection_Side from);
91
92/**
93 * Version-agnostic internal client hello data container that allows
94 * parsing Client_Hello messages without prior knowledge of the contained
95 * protocol version.
96 */
98 public:
100
101 explicit Client_Hello_Internal(std::span<const uint8_t> buf);
102
103 /**
104 * This distinguishes between a TLS 1.3 compliant Client Hello (containing
105 * the "supported_version" extension) and legacy Client Hello messages.
106 *
107 * @return TLS 1.3 if the Client Hello contains "supported_versions", or
108 * the content of the "legacy_version" version field if it
109 * indicates (D)TLS 1.2 or older, or
110 * (D)TLS 1.2 if the "legacy_version" was some other odd value.
111 */
112 Protocol_Version version() const;
113
115
116 const Session_ID& session_id() const { return m_session_id; }
117
118 const std::vector<uint8_t>& random() const { return m_random; }
119
120 const std::vector<uint16_t>& ciphersuites() const { return m_suites; }
121
122 const std::vector<uint8_t>& comp_methods() const { return m_comp_methods; }
123
124 const std::vector<uint8_t>& hello_cookie() const { return m_hello_cookie; }
125
126 const std::vector<uint8_t>& hello_cookie_input_bits() const { return m_cookie_input_bits; }
127
128 const Extensions& extensions() const { return m_extensions; }
129
131
132 public:
133 Protocol_Version m_legacy_version; // NOLINT(*-non-private-member-variable*)
134 Session_ID m_session_id; // NOLINT(*-non-private-member-variable*)
135 std::vector<uint8_t> m_random; // NOLINT(*-non-private-member-variable*)
136 std::vector<uint16_t> m_suites; // NOLINT(*-non-private-member-variable*)
137 std::vector<uint8_t> m_comp_methods; // NOLINT(*-non-private-member-variable*)
138 Extensions m_extensions; // NOLINT(*-non-private-member-variable*)
139
140 // These fields are only for DTLS:
141 std::vector<uint8_t> m_hello_cookie; // NOLINT(*-non-private-member-variable*)
142 std::vector<uint8_t> m_cookie_input_bits; // NOLINT(*-non-private-member-variable*)
143};
144
145/**
146* Version-agnostic internal server hello data container that allows
147* parsing Server_Hello messages without prior knowledge of the contained
148* protocol version.
149*/
151 public:
152 /**
153 * Deserialize a Server Hello message
154 */
155 explicit Server_Hello_Internal(std::span<const uint8_t> buf);
156
158 Session_ID sid,
159 std::vector<uint8_t> r,
160 const uint16_t cs,
161 const uint8_t cm,
162 bool is_hrr = false) :
163 m_legacy_version(lv),
164 m_session_id(std::move(sid)),
165 m_random(std::move(r)),
166 m_is_hello_retry_request(is_hrr),
167 m_ciphersuite(cs),
168 m_comp_method(cm) {}
169
171
172 Protocol_Version legacy_version() const { return m_legacy_version; }
173
174 const Session_ID& session_id() const { return m_session_id; }
175
176 const std::vector<uint8_t>& random() const { return m_random; }
177
178 uint16_t ciphersuite() const { return m_ciphersuite; }
179
180 uint8_t comp_method() const { return m_comp_method; }
181
182 bool is_hello_retry_request() const { return m_is_hello_retry_request; }
183
184 const Extensions& extensions() const { return m_extensions; }
185
186 Extensions& extensions() { return m_extensions; }
187
188 private:
189 Protocol_Version m_legacy_version;
190 Session_ID m_session_id;
191 std::vector<uint8_t> m_random;
192 bool m_is_hello_retry_request;
193 uint16_t m_ciphersuite;
194 uint8_t m_comp_method;
195
196 Extensions m_extensions;
197};
198
199} // namespace Botan::TLS
200
201#endif
const Session_ID & session_id() const
const Extensions & extensions() const
const std::vector< uint8_t > & comp_methods() const
const std::vector< uint8_t > & hello_cookie() const
const std::vector< uint8_t > & hello_cookie_input_bits() const
const std::vector< uint8_t > & random() const
const std::vector< uint16_t > & ciphersuites() const
Server_Hello_Internal(std::span< const uint8_t > buf)
Server_Hello_Internal(Protocol_Version lv, Session_ID sid, std::vector< uint8_t > r, const uint16_t cs, const uint8_t cm, bool is_hrr=false)
const Extensions & extensions() const
const std::vector< uint8_t > & random() const
const Session_ID & session_id() const
std::vector< uint8_t > make_server_hello_random(RandomNumberGenerator &rng, Protocol_Version offered_version, Callbacks &cb, const Policy &policy, TLS_Flavor flavor)
bool group_usable_in_version(Group_Params group, Protocol_Version version)
std::vector< uint8_t > make_hello_random(RandomNumberGenerator &rng, Callbacks &cb, const Policy &policy)
std::vector< Group_Params > groups_usable_in_version(std::span< const Group_Params > groups, Protocol_Version version)
bool group_may_be_ecc(Group_Params group)
std::vector< uint8_t > calculate_cookie(std::span< const uint8_t > client_hello_bits, std::string_view client_identity, std::span< const uint8_t > cookie_secret)
Strong< std::vector< uint8_t >, struct Session_ID_ > Session_ID
holds a TLS 1.2 session ID for stateful resumption
std::unique_ptr< Extension > make_certificate_status_request(TLS_Data_Reader &reader, uint16_t extension_size, Handshake_Type message_type, Connection_Side from)