Botan 3.3.0
Crypto and TLS for C&
tls_callbacks.cpp
Go to the documentation of this file.
1/*
2* TLS Callbacks
3* (C) 2016 Jack Lloyd
4* 2017 Harry Reimann, Rohde & Schwarz Cybersecurity
5* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
6* 2023 René Meusel - Rohde & Schwarz Cybersecurity
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#include <botan/tls_callbacks.h>
12
13#include <botan/dh.h>
14#include <botan/dl_group.h>
15#include <botan/ecdh.h>
16#include <botan/ocsp.h>
17#include <botan/pk_algs.h>
18#include <botan/tls_algos.h>
19#include <botan/tls_exceptn.h>
20#include <botan/tls_policy.h>
21#include <botan/x509path.h>
22#include <botan/internal/ct_utils.h>
23#include <botan/internal/stl_util.h>
24
25#if defined(BOTAN_HAS_CURVE_25519)
26 #include <botan/curve25519.h>
27#endif
28
29#if defined(BOTAN_HAS_KYBER)
30 #include <botan/kyber.h>
31#endif
32
33#if defined(BOTAN_HAS_FRODOKEM)
34 #include <botan/frodokem.h>
35#endif
36
37#if defined(BOTAN_HAS_TLS_13_PQC)
38 #include <botan/internal/hybrid_public_key.h>
39#endif
40
41namespace Botan {
42
44 // default is no op
45}
46
47std::string TLS::Callbacks::tls_server_choose_app_protocol(const std::vector<std::string>& /*unused*/) {
48 return "";
49}
50
52 return "";
53}
54
55std::chrono::system_clock::time_point TLS::Callbacks::tls_current_timestamp() {
56 return std::chrono::system_clock::now();
57}
58
60 Connection_Side /*unused*/,
61 Handshake_Type /*unused*/) {}
62
64 Connection_Side /*unused*/,
65 Handshake_Type /*unused*/) {}
66
68 // RFC 5077 3.3
69 // The ticket_lifetime_hint field contains a hint from the server about
70 // how long the ticket should be stored. A value of zero is reserved to
71 // indicate that the lifetime of the ticket is unspecified.
72 //
73 // RFC 8446 4.6.1
74 // [A ticket_lifetime] of zero indicates that the ticket should be discarded
75 // immediately.
76 //
77 // By default we opt to keep all sessions, except for TLS 1.3 with a lifetime
78 // hint of zero.
79 return session.lifetime_hint().count() > 0 || session.version().is_pre_tls_13();
80}
81
82void TLS::Callbacks::tls_verify_cert_chain(const std::vector<X509_Certificate>& cert_chain,
83 const std::vector<std::optional<OCSP::Response>>& ocsp_responses,
84 const std::vector<Certificate_Store*>& trusted_roots,
85 Usage_Type usage,
86 std::string_view hostname,
87 const TLS::Policy& policy) {
88 if(cert_chain.empty()) {
89 throw Invalid_Argument("Certificate chain was empty");
90 }
91
94
96 restrictions,
97 trusted_roots,
98 (usage == Usage_Type::TLS_SERVER_AUTH ? hostname : ""),
99 usage,
100 tls_current_timestamp(),
101 tls_verify_cert_chain_ocsp_timeout(),
102 ocsp_responses);
103
104 if(!result.successful_validation()) {
105 throw TLS_Exception(Alert::BadCertificate, "Certificate validation failure: " + result.result_string());
106 }
107}
108
110 Usage_Type usage,
111 std::string_view hostname,
112 const TLS::Policy& policy) {
113 BOTAN_UNUSED(raw_public_key, usage, hostname, policy);
114 // There is no good default implementation for authenticating raw public key.
115 // Applications that wish to use them for authentication, must override this.
116 throw TLS_Exception(Alert::CertificateUnknown, "Application did not provide a means to validate the raw public key");
117}
118
119std::optional<OCSP::Response> TLS::Callbacks::tls_parse_ocsp_response(const std::vector<uint8_t>& raw_response) {
120 try {
121 return OCSP::Response(raw_response);
122 } catch(const Decoding_Error&) {
123 // ignore parsing errors and just ignore the broken OCSP response
124 return std::nullopt;
125 }
126}
127
128std::vector<std::vector<uint8_t>> TLS::Callbacks::tls_provide_cert_chain_status(
129 const std::vector<X509_Certificate>& chain, const Certificate_Status_Request& csr) {
130 std::vector<std::vector<uint8_t>> result(chain.size());
131 if(!chain.empty()) {
132 result[0] = tls_provide_cert_status(chain, csr);
133 }
134 return result;
135}
136
137std::vector<uint8_t> TLS::Callbacks::tls_sign_message(const Private_Key& key,
139 std::string_view padding,
140 Signature_Format format,
141 const std::vector<uint8_t>& msg) {
142 PK_Signer signer(key, rng, padding, format);
143
144 return signer.sign_message(msg, rng);
145}
146
148 std::string_view padding,
149 Signature_Format format,
150 const std::vector<uint8_t>& msg,
151 const std::vector<uint8_t>& sig) {
152 PK_Verifier verifier(key, padding, format);
153
154 return verifier.verify_message(msg, sig);
155}
156
158#if defined(BOTAN_HAS_KYBER)
159 if(group.is_pure_kyber()) {
160 return std::make_unique<Kyber_PrivateKey>(rng, KyberMode(group.to_string().value()));
161 }
162#endif
163
164#if defined(BOTAN_HAS_FRODOKEM)
165 if(group.is_pure_frodokem()) {
166 return std::make_unique<FrodoKEM_PrivateKey>(rng, FrodoKEMMode(group.to_string().value()));
167 }
168#endif
169
170#if defined(BOTAN_HAS_TLS_13_PQC)
171 if(group.is_pqc_hybrid()) {
173 }
174#endif
175
176 return tls_generate_ephemeral_key(group, rng);
177}
178
180 const std::vector<uint8_t>& encoded_public_key,
182 const Policy& policy) {
183 if(group.is_kem()) {
184 auto kem_pub_key = [&]() -> std::unique_ptr<Public_Key> {
185
186#if defined(BOTAN_HAS_TLS_13_PQC)
187 if(group.is_pqc_hybrid()) {
188 return Hybrid_KEM_PublicKey::load_for_group(group, encoded_public_key);
189 }
190#endif
191
192#if defined(BOTAN_HAS_KYBER)
193 if(group.is_pure_kyber()) {
194 return std::make_unique<Kyber_PublicKey>(encoded_public_key, KyberMode(group.to_string().value()));
195 }
196#endif
197
198#if defined(BOTAN_HAS_FRODOKEM)
199 if(group.is_pure_frodokem()) {
200 return std::make_unique<FrodoKEM_PublicKey>(encoded_public_key, FrodoKEMMode(group.to_string().value()));
201 }
202#endif
203
204 throw TLS_Exception(Alert::IllegalParameter, "KEM is not supported");
205 }();
206
207 return PK_KEM_Encryptor(*kem_pub_key, "Raw").encrypt(rng);
208 }
209
210 // TODO: We could use the KEX_to_KEM_Adapter to remove the case distinction
211 // of KEM and KEX. However, the workarounds in this adapter class
212 // should first be addressed.
213 auto ephemeral_keypair = tls_generate_ephemeral_key(group, rng);
214 return KEM_Encapsulation(ephemeral_keypair->public_value(),
215 tls_ephemeral_key_agreement(group, *ephemeral_keypair, encoded_public_key, rng, policy));
216}
217
219 const Private_Key& private_key,
220 const std::vector<uint8_t>& encapsulated_bytes,
222 const Policy& policy) {
223 if(group.is_kem()) {
224 PK_KEM_Decryptor kemdec(private_key, rng, "Raw");
225 return kemdec.decrypt(encapsulated_bytes, 0, {});
226 }
227
228 try {
229 auto& key_agreement_key = dynamic_cast<const PK_Key_Agreement_Key&>(private_key);
230 return tls_ephemeral_key_agreement(group, key_agreement_key, encapsulated_bytes, rng, policy);
231 } catch(const std::bad_cast&) {
232 throw Invalid_Argument("provided ephemeral key is not a PK_Key_Agreement_Key");
233 }
234}
235
236namespace {
237
238bool is_dh_group(const std::variant<TLS::Group_Params, DL_Group>& group) {
239 return std::holds_alternative<DL_Group>(group) || std::get<TLS::Group_Params>(group).is_dh_named_group();
240}
241
242DL_Group get_dl_group(const std::variant<TLS::Group_Params, DL_Group>& group) {
243 BOTAN_ASSERT_NOMSG(is_dh_group(group));
244
245 // TLS 1.2 allows specifying arbitrary DL_Group parameters in-lieu of
246 // a standardized DH group identifier. TLS 1.3 just offers pre-defined
247 // groups.
248 return std::visit(
249 overloaded{[](const DL_Group& dl_group) { return dl_group; },
250 [&](TLS::Group_Params group_param) { return DL_Group(group_param.to_string().value()); }},
251 group);
252}
253
254} // namespace
255
256std::unique_ptr<PK_Key_Agreement_Key> TLS::Callbacks::tls_generate_ephemeral_key(
257 const std::variant<TLS::Group_Params, DL_Group>& group, RandomNumberGenerator& rng) {
258 if(is_dh_group(group)) {
259 const DL_Group dl_group = get_dl_group(group);
260 return std::make_unique<DH_PrivateKey>(rng, dl_group);
261 }
262
263 BOTAN_ASSERT_NOMSG(std::holds_alternative<TLS::Group_Params>(group));
264 const auto group_params = std::get<TLS::Group_Params>(group);
265
266 if(group_params.is_ecdh_named_curve()) {
267 const EC_Group ec_group(group_params.to_string().value());
268 return std::make_unique<ECDH_PrivateKey>(rng, ec_group);
269 }
270
271#if defined(BOTAN_HAS_CURVE_25519)
272 if(group_params.is_x25519()) {
273 return std::make_unique<X25519_PrivateKey>(rng);
274 }
275#endif
276
277 if(group_params.is_kem()) {
278 throw TLS_Exception(Alert::IllegalParameter, "cannot generate an ephemeral KEX key for a KEM");
279 }
280
281 throw TLS_Exception(Alert::DecodeError, "cannot create a key offering without a group definition");
282}
283
285 const std::variant<TLS::Group_Params, DL_Group>& group,
286 const PK_Key_Agreement_Key& private_key,
287 const std::vector<uint8_t>& public_value,
289 const Policy& policy) {
290 auto agree = [&](const PK_Key_Agreement_Key& sk, const auto& pk) {
291 PK_Key_Agreement ka(sk, rng, "Raw");
292 return ka.derive_key(0, pk.public_value()).bits_of();
293 };
294
295 if(is_dh_group(group)) {
296 // TLS 1.2 allows specifying arbitrary DL_Group parameters in-lieu of
297 // a standardized DH group identifier.
298 const auto dl_group = get_dl_group(group);
299
300 auto Y = BigInt::decode(public_value);
301
302 /*
303 * A basic check for key validity. As we do not know q here we
304 * cannot check that Y is in the right subgroup. However since
305 * our key is ephemeral there does not seem to be any
306 * advantage to bogus keys anyway.
307 */
308 if(Y <= 1 || Y >= dl_group.get_p() - 1) {
309 throw TLS_Exception(Alert::IllegalParameter, "Server sent bad DH key for DHE exchange");
310 }
311
312 DH_PublicKey peer_key(dl_group, Y);
313 policy.check_peer_key_acceptable(peer_key);
314
315 return agree(private_key, peer_key);
316 }
317
318 BOTAN_ASSERT_NOMSG(std::holds_alternative<TLS::Group_Params>(group));
319 const auto group_params = std::get<TLS::Group_Params>(group);
320
321 if(group_params.is_ecdh_named_curve()) {
322 const EC_Group ec_group(group_params.to_string().value());
323 ECDH_PublicKey peer_key(ec_group, ec_group.OS2ECP(public_value));
324 policy.check_peer_key_acceptable(peer_key);
325
326 return agree(private_key, peer_key);
327 }
328
329#if defined(BOTAN_HAS_CURVE_25519)
330 if(group_params.is_x25519()) {
331 if(public_value.size() != 32) {
332 throw TLS_Exception(Alert::HandshakeFailure, "Invalid X25519 key size");
333 }
334
335 Curve25519_PublicKey peer_key(public_value);
336 policy.check_peer_key_acceptable(peer_key);
337
338 return agree(private_key, peer_key);
339 }
340#endif
341
342 throw TLS_Exception(Alert::IllegalParameter, "Did not recognize the key exchange group");
343}
344
345} // namespace Botan
#define BOTAN_UNUSED
Definition assert.h:118
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:59
static BigInt decode(const uint8_t buf[], size_t length)
Definition bigint.h:772
EC_Point OS2ECP(const uint8_t bits[], size_t len) const
Definition ec_group.cpp:561
secure_vector< uint8_t > bits_of() const
Definition symkey.h:36
void decrypt(std::span< uint8_t > out_shared_key, std::span< const uint8_t > encap_key, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.cpp:190
KEM_Encapsulation encrypt(RandomNumberGenerator &rng, size_t desired_shared_key_len=32, std::span< const uint8_t > salt={})
Definition pubkey.h:651
SymmetricKey derive_key(size_t key_len, const uint8_t in[], size_t in_len, const uint8_t params[], size_t params_len) const
Definition pubkey.cpp:231
std::vector< uint8_t > sign_message(const uint8_t in[], size_t length, RandomNumberGenerator &rng)
Definition pubkey.h:186
bool verify_message(const uint8_t msg[], size_t msg_length, const uint8_t sig[], size_t sig_length)
Definition pubkey.cpp:368
std::string result_string() const
virtual std::string tls_peer_network_identity()
virtual void tls_modify_extensions(Extensions &extn, Connection_Side which_side, Handshake_Type which_message)
virtual std::vector< std::vector< uint8_t > > tls_provide_cert_chain_status(const std::vector< X509_Certificate > &chain, const Certificate_Status_Request &csr)
virtual std::string tls_server_choose_app_protocol(const std::vector< std::string > &client_protos)
virtual std::optional< OCSP::Response > tls_parse_ocsp_response(const std::vector< uint8_t > &raw_response)
virtual void tls_examine_extensions(const Extensions &extn, Connection_Side which_side, Handshake_Type which_message)
virtual std::vector< uint8_t > tls_sign_message(const Private_Key &key, RandomNumberGenerator &rng, std::string_view padding, Signature_Format format, const std::vector< uint8_t > &msg)
virtual void tls_verify_raw_public_key(const Public_Key &raw_public_key, Usage_Type usage, std::string_view hostname, const TLS::Policy &policy)
virtual KEM_Encapsulation tls_kem_encapsulate(TLS::Group_Params group, const std::vector< uint8_t > &encoded_public_key, RandomNumberGenerator &rng, const Policy &policy)
virtual bool tls_should_persist_resumption_information(const Session &session)
virtual std::unique_ptr< Private_Key > tls_kem_generate_key(TLS::Group_Params group, RandomNumberGenerator &rng)
virtual secure_vector< uint8_t > tls_ephemeral_key_agreement(const std::variant< TLS::Group_Params, DL_Group > &group, const PK_Key_Agreement_Key &private_key, const std::vector< uint8_t > &public_value, RandomNumberGenerator &rng, const Policy &policy)
virtual secure_vector< uint8_t > tls_kem_decapsulate(TLS::Group_Params group, const Private_Key &private_key, const std::vector< uint8_t > &encapsulated_bytes, RandomNumberGenerator &rng, const Policy &policy)
virtual std::chrono::system_clock::time_point tls_current_timestamp()
virtual std::unique_ptr< PK_Key_Agreement_Key > tls_generate_ephemeral_key(const std::variant< TLS::Group_Params, DL_Group > &group, RandomNumberGenerator &rng)
virtual void tls_verify_cert_chain(const std::vector< X509_Certificate > &cert_chain, const std::vector< std::optional< OCSP::Response > > &ocsp_responses, const std::vector< Certificate_Store * > &trusted_roots, Usage_Type usage, std::string_view hostname, const TLS::Policy &policy)
virtual bool tls_verify_message(const Public_Key &key, std::string_view padding, Signature_Format format, const std::vector< uint8_t > &msg, const std::vector< uint8_t > &sig)
virtual void tls_inspect_handshake_msg(const Handshake_Message &message)
constexpr bool is_pqc_hybrid() const
Definition tls_algos.h:207
constexpr bool is_kem() const
Definition tls_algos.h:225
constexpr bool is_pure_frodokem() const
Definition tls_algos.h:194
constexpr bool is_pure_kyber() const
Definition tls_algos.h:189
std::optional< std::string > to_string() const
static std::unique_ptr< Hybrid_KEM_PrivateKey > generate_from_group(Group_Params group, RandomNumberGenerator &rng)
static std::unique_ptr< Hybrid_KEM_PublicKey > load_for_group(Group_Params group, std::span< const uint8_t > concatenated_public_values)
virtual void check_peer_key_acceptable(const Public_Key &public_key) const
virtual bool require_cert_revocation_info() const
virtual size_t minimum_signature_strength() const
Protocol_Version version() const
std::chrono::seconds lifetime_hint() const
FE_25519 Y
Definition ge.cpp:26
Path_Validation_Result x509_path_validate(const std::vector< X509_Certificate > &end_certs, const Path_Validation_Restrictions &restrictions, const std::vector< Certificate_Store * > &trusted_roots, std::string_view hostname, Usage_Type usage, std::chrono::system_clock::time_point ref_time, std::chrono::milliseconds ocsp_timeout, const std::vector< std::optional< OCSP::Response > > &ocsp_resp)
Definition x509path.cpp:839
Usage_Type
Definition x509cert.h:22
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:61
Signature_Format
Definition pk_keys.h:31