Botan 3.14.1
Crypto and TLS for C&
tls_callbacks.h
Go to the documentation of this file.
1/*
2* TLS Callbacks
3* (C) 2016 Matthias Gierlings
4* 2016 Jack Lloyd
5* 2017 Harry Reimann, Rohde & Schwarz Cybersecurity
6* 2022 René Meusel, Rohde & Schwarz Cybersecurity
7* 2025 Frederik Dornemann, CARIAD SE
8*
9* Botan is released under the Simplified BSD License (see license.txt)
10*/
11
12#ifndef BOTAN_TLS_CALLBACKS_H_
13#define BOTAN_TLS_CALLBACKS_H_
14
15#include <botan/ec_point_format.h>
16#include <botan/kdf.h>
17#include <botan/pubkey.h>
18#include <botan/tls_alert.h>
19#include <botan/tls_algos.h>
20#include <botan/tls_magic.h>
21#include <chrono>
22#include <functional>
23#include <memory>
24#include <optional>
25#include <variant>
26
27namespace Botan {
28
29enum class Signature_Format : uint8_t;
30enum class Usage_Type : uint8_t;
31class DL_Group;
35class Public_Key;
36class Private_Key;
38
39namespace OCSP {
40
41class Response;
42
43}
44
45namespace TLS {
46
47class Handshake_Message;
48class Policy;
49class Extensions;
50class Certificate_Status_Request;
51class Session_Summary;
52class Session;
53
54/**
55* Encapsulates the callbacks that a TLS channel will make which are due to
56* channel specific operations.
57*/
58class BOTAN_PUBLIC_API(2, 0) Callbacks /* NOLINT(*-special-member-functions) */ {
59 public:
60 virtual ~Callbacks() = default;
61
62 /**
63 * @name Mandatory
64 *
65 * Those callbacks must be implemented by all applications that use TLS.
66 * @{
67 */
68
69 /**
70 * Mandatory callback: output function
71 *
72 * The channel will call this with data which needs to be sent to the peer
73 * (eg, over a socket or some other form of IPC). The array will be overwritten
74 * when the function returns so a copy must be made if the data cannot be
75 * sent immediately.
76 *
77 * As an example you could use the syscall ``send`` to perform a blocking
78 * write on a socket, or append the data to a queue managed by your
79 * application and initiate an asynchronous write.
80 *
81 * For TLS all writes must occur *in the order requested*. For DTLS this
82 * ordering is not strictly required, but is still recommended.
83 *
84 * @param data a contiguous data buffer to send
85 */
86 virtual void tls_emit_data(std::span<const uint8_t> data) = 0;
87
88 /**
89 * Mandatory callback: process application data
90 *
91 * Called when application data record is received from the peer. The
92 * array is overwritten immediately after the function returns.
93 *
94 * Currently empty records are ignored and do not instigate a callback,
95 * but this may change in a future release.
96 *
97 * For TLS the record number will always increase, except that it starts
98 * again from zero whenever the peer switches to new keys (in TLS 1.3 after
99 * a KeyUpdate, in TLS 1.2 after a renegotiation). For DTLS, it is
100 * possible to receive records with the @p seq_no field out of order, or
101 * with gaps, corresponding to reordered or lost datagrams.
102 *
103 * @param seq_no the underlying TLS/DTLS record sequence number
104 *
105 * @param data a contiguous data buffer containing the received record
106 */
107 virtual void tls_record_received(uint64_t seq_no, std::span<const uint8_t> data) = 0;
108
109 /**
110 * Mandatory callback: alert received
111 *
112 * Called when an alert is received from the peer. If fatal, the
113 * connection is closing. If not fatal, the connection may still be
114 * closing (depending on the error and the peer).
115 *
116 * Note that alerts received before the handshake is complete are not
117 * authenticated and could have been inserted by a MITM attacker.
118 */
119 virtual void tls_alert(Alert alert) = 0;
120
121 /// @}
122 // End of mandatory callbacks
123
124 /**
125 * @name Informational
126 *
127 * Override these to obtain deeper insights into the TLS connection.
128 * Throwing from any of these callbacks will result in the termination of
129 * the TLS connection.
130 * @{
131 */
132
133 /**
134 * Optional callback: session established
135 *
136 * Called whenever a negotiation completes. This can happen more than once
137 * on TLS 1.2 connections, if renegotiation occurs. The @p session
138 * parameter provides information about the session which was just
139 * established.
140 *
141 * If this function wishes to cancel the handshake, it can throw an
142 * exception which will send a close message to the counterparty and reset
143 * the connection state.
144 *
145 * @param session the session descriptor
146 */
147 virtual void tls_session_established(const Session_Summary& session);
148
149 /**
150 * Optional callback: session activated
151 *
152 * By default does nothing. This is called when the session is activated,
153 * that is once it is possible to send or receive data on the channel. In
154 * particular it is possible for an implementation of this function to
155 * perform an initial write on the channel.
156 */
157 virtual void tls_session_activated() {}
158
159 /**
160 * Optional callback: peer closed connection (sent a "close_notify" alert)
161 *
162 * The peer signaled that it wishes to shut down the connection. The
163 * application should not expect to receive any more data from the peer
164 * and may tear down the underlying transport socket.
165 *
166 * Prior to TLS 1.3 it was required that peers discard pending writes
167 * and immediately respond with their own "close_notify". With TLS 1.3,
168 * applications can continue to send data despite the peer having already
169 * signaled their wish to shut down.
170 *
171 * Returning `true` will cause the TLS 1.3 implementation to write all
172 * pending data and then also signal a connection shut down. Otherwise
173 * the application is responsible to call the `Channel::close()` method.
174 *
175 * For TLS 1.2 the return value has no effect.
176 *
177 * @return true causes the implementation to respond with a "close_notify"
178 */
179 virtual bool tls_peer_closed_connection() { return true; }
180
181 /**
182 * Optional callback: Resumption information was received/established
183 *
184 * TLS 1.3 calls this when we sent or received a TLS 1.3 session ticket at
185 * any point after the initial handshake has finished.
186 *
187 * TLS 1.2 calls this when a session was established successfully and
188 * its resumption information may be stored for later usage.
189 *
190 * Note that for servers this is called as soon as resumption information
191 * is available and _could_ be sent to the client. If this callback
192 * returns 'false', the information will neither be cached nor sent.
193 *
194 * @param session the session descriptor
195 *
196 * @return false to prevent the resumption information from being cached,
197 * and true to cache it in the configured Session_Manager
198 */
199 virtual bool tls_should_persist_resumption_information(const Session& session);
200
201 /**
202 * Optional callback with default impl: verify cert chain
203 *
204 * Default implementation performs a standard PKIX validation
205 * and initiates network OCSP request for end-entity cert.
206 * Override to provide different behavior.
207 *
208 * Check the certificate chain is valid up to a trusted root, and
209 * optionally (if hostname != "") that the hostname given is
210 * consistent with the leaf certificate.
211 *
212 * This function should throw an exception derived from
213 * std::exception with an informative what() result if the
214 * certificate chain cannot be verified.
215 *
216 * @param cert_chain specifies a certificate chain leading to a
217 * trusted root CA certificate.
218 * @param ocsp_responses the server may have provided some
219 * @param trusted_roots the list of trusted certificates
220 * @param usage what this cert chain is being used for
221 * Usage_Type::TLS_SERVER_AUTH for server chains,
222 * Usage_Type::TLS_CLIENT_AUTH for client chains,
223 * Usage_Type::UNSPECIFIED for other uses
224 * @param hostname when authenticating a server, this is the hostname
225 * the client requested (eg via SNI). When authenticating a client,
226 * this is the server name the client is authenticating *to*.
227 * Empty in other cases or if no hostname was used.
228 * @param policy the TLS policy associated with the session being authenticated
229 * using the certificate chain
230 */
231 virtual void tls_verify_cert_chain(const std::vector<X509_Certificate>& cert_chain,
232 const std::vector<std::optional<OCSP::Response>>& ocsp_responses,
233 const std::vector<Certificate_Store*>& trusted_roots,
234 Usage_Type usage,
235 std::string_view hostname,
236 const TLS::Policy& policy);
237
238 /**
239 * Optional callback. Default impl always rejects.
240 *
241 * This allows using raw public keys for authentication of peers as
242 * described in RFC 7250 and RFC 8446 4.2.2. Applications that wish
243 * to use raw public keys MUST override this callback to verify the
244 * authenticity of the received public keys.
245 *
246 * Default implementation always rejects the raw public key.
247 *
248 * This function should throw an exception derived from
249 * std::exception with an informative what() result if the
250 * raw public key cannot be verified.
251 *
252 * @param raw_public_key specifies the raw public key to be used
253 * for peer authentication
254 * @param usage what this cert chain is being used for
255 * Usage_Type::TLS_SERVER_AUTH for server chains,
256 * Usage_Type::TLS_CLIENT_AUTH for client chains,
257 * @param hostname when authenticating a server, this is the hostname
258 * the client requested (eg via SNI). When authenticating a client,
259 * this is the server name the client is authenticating *to*.
260 * Empty in other cases or if no hostname was used.
261 * @param policy the TLS policy associated with the session being authenticated
262 * using the raw public key
263 */
264 virtual void tls_verify_raw_public_key(const Public_Key& raw_public_key,
265 Usage_Type usage,
266 std::string_view hostname,
267 const TLS::Policy& policy);
268
269 /**
270 * Called by default `tls_verify_cert_chain` to get the timeout to use for OCSP
271 * requests. Return 0 to disable online OCSP checks.
272 *
273 * This function should not be "const" since the implementation might need
274 * to perform some side effecting operation to compute the result.
275 *
276 * TODO(Botan4) change return type to uint64_t
277 */
278 virtual std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout() const {
279 return std::chrono::milliseconds(0);
280 }
281
282 /**
283 * Called by the TLS server whenever the client included the
284 * status_request extension (see RFC 6066, a.k.a OCSP stapling)
285 * in the ClientHello.
286 *
287 * @return the encoded OCSP response to be sent to the client which
288 * indicates the revocation status of the server certificate. Return an
289 * empty vector to indicate that no response is available, and thus
290 * suppress the Certificate_Status message.
291 *
292 * Default implementation returns an empty vector, disabling certificate status
293 */
294 virtual std::vector<uint8_t> tls_provide_cert_status(const std::vector<X509_Certificate>& chain,
295 const Certificate_Status_Request& csr);
296
297 /**
298 * Called by TLS 1.3 client or server whenever the peer indicated that
299 * OCSP stapling is supported. In contrast to `tls_provide_cert_status`,
300 * this allows providing OCSP responses for each certificate in the chain.
301 *
302 * The default implementation invokes `tls_provide_cert_status` assuming
303 * that no OCSP responses for intermediate certificates are available.
304 *
305 * @return a vector of OCSP response buffers. An empty buffer indicates
306 * that no OCSP response should be provided for the respective
307 * certificate (at the same list index). The returned vector
308 * MUST be exactly the same length as the incoming \p chain.
309 */
310 virtual std::vector<std::vector<uint8_t>> tls_provide_cert_chain_status(
311 const std::vector<X509_Certificate>& chain, const Certificate_Status_Request& csr);
312
313 /**
314 * Optional callback with default impl: sign a message
315 *
316 * Default implementation uses PK_Signer::sign_message().
317 * Override to provide a different approach, e.g. using an external device.
318 *
319 * @param key the private key of the signer
320 * @param rng a random number generator
321 * @param padding the encoding method to be applied to the message
322 * @param format the signature format
323 * @param msg the input data for the signature
324 *
325 * @return the signature
326 */
327 virtual std::vector<uint8_t> tls_sign_message(const Private_Key& key,
329 std::string_view padding,
330 Signature_Format format,
331 const std::vector<uint8_t>& msg);
332
333 /**
334 * Optional callback with default impl: verify a message signature
335 *
336 * Default implementation uses PK_Verifier::verify_message().
337 * Override to provide a different approach, e.g. using an external device.
338 *
339 * @param key the public key of the signer
340 * @param padding the encoding method to be applied to the message
341 * @param format the signature format
342 * @param msg the input data for the signature
343 * @param sig the signature to be checked
344 *
345 * @return true if the signature is valid, false otherwise
346 */
347 virtual bool tls_verify_message(const Public_Key& key,
348 std::string_view padding,
349 Signature_Format format,
350 const std::vector<uint8_t>& msg,
351 const std::vector<uint8_t>& sig);
352
353 /**
354 * Optional callback: deserialize a public key received from the peer
355 *
356 * Default implementation simply parses the public key using Botan's
357 * public keys. Override to provide a different approach, e.g. using an
358 * external device.
359 *
360 * If deserialization fails, the default implementation throws a
361 * Botan::Decoding_Error exception that will be translated into a
362 * TLS_Exception with an Alert::IllegalParameter.
363 *
364 * @param group the group identifier or (in case of TLS 1.2) an explicit
365 * discrete-log group of the public key
366 * @param key_bits the serialized public key
367 *
368 * @return the deserialized and ready-to-use public key
369 */
370 virtual std::unique_ptr<Public_Key> tls_deserialize_peer_public_key(
371 const std::variant<TLS::Group_Params, DL_Group>& group, std::span<const uint8_t> key_bits);
372
373 /**
374 * Generate an ephemeral KEM key for a TLS 1.3 handshake
375 *
376 * Applications may use this to add custom KEM algorithms or entirely
377 * different key exchange schemes to the TLS 1.3 handshake. For instance,
378 * this could provide an entry point to implement a hybrid key exchange
379 * with both a traditional algorithm like ECDH and a quantum-secure KEM.
380 * Typical use cases of the library don't need to do that and serious
381 * security risks are associated with customizing TLS's key encapsulation
382 * mechanism.
383 *
384 * Note that the KEM interface is usable for TLS 1.3 handshakes, only.
385 *
386 * The default implementation simply delegates this to the
387 * tls_generate_ephemeral_key() call when appropriate.
388 *
389 * @param group the group identifier to generate an ephemeral keypair for
390 * @param rng a random number generator
391 *
392 * @returns a keypair whose public key will be provided to the peer and
393 * the private key will be provided to tls_kem_decapsulate later
394 * in the handshake.
395 */
396 virtual std::unique_ptr<Private_Key> tls_kem_generate_key(TLS::Group_Params group, RandomNumberGenerator& rng);
397
398 /**
399 * Performs a key encapsulation operation (used for TLS 1.3 servers)
400 *
401 * Applications may use this to add custom KEM algorithms or entirely
402 * different key exchange schemes to the TLS 1.3 handshake. For instance,
403 * this could provide an entry point to implement a hybrid key exchange
404 * with both a traditional algorithm like ECDH and a quantum-secure KEM.
405 * Typical use cases of the library don't need to do that and serious
406 * security risks are associated with customizing TLS's key encapsulation
407 * mechanism.
408 *
409 * Note that the KEM interface is usable for TLS 1.3 handshakes, only.
410 *
411 * The default implementation implements this key encapsulation as a
412 * combination of tls_generate_ephemeral_key() followed by
413 * tls_ephemeral_key_agreement() with the provided @p encoded_public_key.
414 * The just-generated ephemeral private key is destroyed immediately.
415 *
416 * @param group the group identifier of the KEM/KEX algorithm
417 * @param encoded_public_key the public key used for encapsulation/KEX
418 * @param rng a random number generator
419 * @param policy a TLS policy object
420 *
421 * @returns the shared secret both in plaintext and encapsulated with
422 * @p encoded_public_key.
423 *
424 * TODO(Botan4) change this return type to something else so the pubkey.h
425 * dependency is removed
426 * TODO(Botan4) change encoded_public_key to a span
427 */
428 virtual KEM_Encapsulation tls_kem_encapsulate(TLS::Group_Params group,
429 const std::vector<uint8_t>& encoded_public_key,
431 const Policy& policy);
432
433 /**
434 * Performs a key decapsulation operation (used for TLS 1.3 clients).
435 *
436 * Applications may use this to add custom KEM algorithms or entirely
437 * different key exchange schemes to the TLS 1.3 handshake. For instance,
438 * this could provide an entry point to implement a hybrid key exchange
439 * with both a traditional algorithm like ECDH and a quantum-secure KEM.
440 * Typical use cases of the library don't need to do that and serious
441 * security risks are associated with customizing TLS's key encapsulation
442 * mechanism.
443 *
444 * Note that the KEM interface is usable for TLS 1.3 handshakes, only.
445 *
446 * The default implementation simply delegates this to the
447 * tls_ephemeral_key_agreement() callback to obtain the shared secret.
448 *
449 * @param group the group identifier of the KEM/KEX algorithm
450 * @param private_key the private key used for decapsulation/KEX
451 * @param encapsulated_bytes the content to decapsulate (or the public key share)
452 * @param rng a random number generator
453 * @param policy a TLS policy object
454 *
455 * @returns the plaintext shared secret from @p encapsulated_bytes after
456 * decapsulation with @p private_key.
457 *
458 * TODO(Botan4) change encapsulated_bytes to a std::span
459 */
460 virtual secure_vector<uint8_t> tls_kem_decapsulate(TLS::Group_Params group,
461 const Private_Key& private_key,
462 const std::vector<uint8_t>& encapsulated_bytes,
464 const Policy& policy);
465
466 /**
467 * Generate an ephemeral key pair for the TLS handshake.
468 *
469 * Applications may use this to add custom groups, curves or entirely
470 * different ephemeral key agreement mechanisms to the TLS handshake.
471 * Note that this callback must be used in conjunction with
472 * Callbacks::tls_ephemeral_key_agreement.
473 *
474 * Typical use cases of the library don't need to do that and serious
475 * security risks are associated with customizing TLS's key exchange
476 * mechanism.
477 *
478 * @throws TLS_Exception(Alert::DecodeError) if the @p group is not known.
479 *
480 * @param group the group identifier to generate an ephemeral keypair for
481 * TLS 1.2 allows for specifying custom discrete logarithm
482 * parameters as part of the protocol. Hence the variant<>.
483 * @param rng a random number generator
484 *
485 * @return a private key of an algorithm usable for key agreement
486 */
487 virtual std::unique_ptr<PK_Key_Agreement_Key> tls_generate_ephemeral_key(
488 const std::variant<TLS::Group_Params, DL_Group>& group, RandomNumberGenerator& rng);
489
490 /**
491 * Generate an ECDH key pair for the TLS 1.2 handshake.
492 *
493 * Note that this callback is called exclusively by TLS 1.2 to handle the
494 * ECDH public key serialization format explicitly. TLS 1.3 fixes this
495 * format to 'uncompressed' and does not allow negotiating anything else.
496 * X25519 and X448 feature a defined and fixed public key encoding and are
497 * therefore not explicitly handled by this callback either.
498 *
499 * Users may override this if they want to provide a custom keypair type
500 * to offload TLS 1.2's ECDH handling to custom hardware, for instance. It
501 * is worth noting that support for compressed points in Botan is
502 * deprecated and this callback will disappear when it is removed in a
503 * future release.
504 *
505 * Typical use cases of the library don't need to do that and serious
506 * security risks are associated with customizing TLS's key exchange
507 * mechanism.
508 *
509 * @throws TLS_Exception(Alert::DecodeError) if the @p group is not known.
510 *
511 * @param group ECDH group identifier to generate an ephemeral keypair for
512 * @param rng a random number generator
513 * @param tls12_ecc_pubkey_encoding_format the key's serialization format
514 *
515 * @return an ECDH private key of an algorithm usable for key agreement
516 */
517 virtual std::unique_ptr<PK_Key_Agreement_Key> tls12_generate_ephemeral_ecdh_key(
518 TLS::Group_Params group, RandomNumberGenerator& rng, EC_Point_Format tls12_ecc_pubkey_encoding_format);
519
520 /**
521 * Agree on a shared secret with the peer's ephemeral public key for
522 * the TLS handshake.
523 *
524 * Applications may use this to add custom groups, curves or entirely
525 * different ephemeral key agreement mechanisms to the TLS handshake.
526 * Note that this callback must be used in conjunction with
527 * Callbacks::tls_generate_ephemeral_key.
528 *
529 * Typical use cases of the library don't need to do that and serious
530 * security risks are associated with customizing TLS's key exchange
531 * mechanism.
532 *
533 * @param group the TLS group identifier to be used
534 * TLS 1.2 allows for specifying custom discrete
535 * logarithm parameters as part of the protocol.
536 * Hence the variant<>.
537 * @param private_key the private key (generated ahead in tls_generate_ephemeral_key)
538 * @param public_value the public key exchange information received by the peer
539 * @param rng a random number generator
540 * @param policy a TLS policy object
541 *
542 * @return the shared secret derived from public_value and private_key
543 *
544 * TODO(Botan4) change public_value to a std::span
545 */
546 virtual secure_vector<uint8_t> tls_ephemeral_key_agreement(const std::variant<TLS::Group_Params, DL_Group>& group,
547 const PK_Key_Agreement_Key& private_key,
548 const std::vector<uint8_t>& public_value,
550 const Policy& policy);
551
552 /**
553 * Optional callback: inspect handshake message
554 * Throw an exception to abort the handshake.
555 * Default simply ignores the message.
556 *
557 * Note: On connections that negotiated TLS 1.3 this callback is also
558 * invoked for post-handshake messages.
559 *
560 * @param message the handshake message
561 */
562 virtual void tls_inspect_handshake_msg(const Handshake_Message& message);
563
564 /**
565 * Optional callback for server: choose ALPN protocol
566 *
567 * ALPN (RFC 7301) works by the client sending a list of application
568 * protocols it is willing to negotiate. The server then selects which
569 * protocol to use. RFC 7301 requires that if the server does not support
570 * any protocols offered by the client, then it should close the connection
571 * with an alert of no_application_protocol. Within this callback this would
572 * be done by throwing a TLS_Exception(Alert::NoApplicationProtocol)
573 *
574 * @param client_protos the vector of protocols the client is willing to negotiate
575 *
576 * @return the protocol selected by the server; if the empty string is
577 * returned, the server does not reply to the client ALPN extension.
578 *
579 * The default implementation returns the empty string, causing client
580 * ALPN to be ignored.
581 *
582 * It is highly recommended to support ALPN whenever possible to avoid
583 * cross-protocol attacks.
584 */
585 virtual std::string tls_server_choose_app_protocol(const std::vector<std::string>& client_protos);
586
587 /**
588 * Optional callback: examine/modify Extensions before sending.
589 *
590 * Both client and server will call this callback on the Extensions object
591 * before serializing it in the specific handshake message. This allows an
592 * application to modify which extensions are sent during the handshake.
593 *
594 * Default implementation does nothing.
595 *
596 * @param extn the extensions
597 * @param which_side will be Connection_Side::Client or Connection_Side::Server which is the current
598 * applications role in the exchange.
599 * @param which_message will state the handshake message type containing the extensions
600 */
601 virtual void tls_modify_extensions(Extensions& extn, Connection_Side which_side, Handshake_Type which_message);
602
603 /**
604 * Optional callback: examine peer extensions.
605 *
606 * Both client and server will call this callback with the Extensions
607 * object after receiving it from the peer. This allows examining the
608 * Extensions, for example to implement a custom extension. It also allows
609 * an application to require that a particular extension be implemented;
610 * throw an exception from this function to abort the handshake.
611 *
612 * Default implementation does nothing.
613 *
614 * @param extn the extensions
615 * @param which_side will be Connection_Side::Client if these are are the clients extensions (ie we are
616 * the server) or Connection_Side::Server if these are the server extensions (we are the client).
617 * @param which_message will state the handshake message type containing the extensions
618 */
619 virtual void tls_examine_extensions(const Extensions& extn,
620 Connection_Side which_side,
621 Handshake_Type which_message);
622
623 /**
624 * Optional callback: parse a single OCSP Response
625 *
626 * Note: Typically a user of the library would not want to override this
627 * callback. We provide this callback to be able to support OCSP
628 * related tests from BoringSSL's BoGo tests that provide unparsable
629 * responses.
630 *
631 * Default implementation tries to parse the provided raw OCSP response.
632 *
633 * This function should not throw an exception but return a std::nullopt
634 * if the OCSP response cannot be parsed.
635 *
636 * @param raw_response raw OCSP response buffer
637 * @returns the parsed OCSP response or std::nullopt on error
638 *
639 * TODO(Botan4) change raw_response to a std::span
640 */
641 virtual std::optional<OCSP::Response> tls_parse_ocsp_response(const std::vector<uint8_t>& raw_response);
642
643 /**
644 * Callback: return peer network identity
645 *
646 * There is no expected or specified format. The only expectation is this
647 * function will return a unique value. For example returning the peer
648 * host IP and port.
649 *
650 * This is used to bind the DTLS cookie to a particular network identity
651 * (RFC 6347 4.2.1 / RFC 9147 11: "the cookie MUST depend on the client's
652 * address"). DTLS servers MUST override this to return a non-empty value;
653 * the default empty implementation will cause cookie verification to throw.
654 */
655 virtual std::string tls_peer_network_identity();
656
657 /**
658 * Optional callback: return a custom time stamp value
659 *
660 * This allows the library user to specify a custom "now" timestamp when
661 * needed. By default it will use the current system clock time.
662 *
663 * Note that typical usages will not need to override this callback but it
664 * is useful for testing purposes to allow for deterministic test outcomes.
665 *
666 * TODO(Botan4) change return type to uint64_t
667 */
668 virtual std::chrono::system_clock::time_point tls_current_timestamp();
669
670 /**
671 * Optional callback: provide the current monotonic timer in milliseconds.
672 *
673 * Used internally by DTLS for retransmit timer scheduling. The default
674 * implementation reads std::chrono::steady_clock. Override only to
675 * substitute a deterministic / virtual clock for testing; production
676 * code should not need to.
677 */
678 virtual uint64_t tls_current_monotonic_clock_ms();
679
680 /**
681 * Optional callback: Channel registers a deferred operation to be
682 * invoked by the user exactly once after a given delay.
683 *
684 * @note The TLS implementation is not re-entrant. The @p op must be
685 * invoked in a thread-safe manner when no other thread is
686 * concurrently interacting with the respective instance of the
687 * TLS channel.
688 *
689 * @note Invoking @p op might throw an exception. Typically this indicates
690 * that the maximum number of retransmission attempts has been
691 * reached (see also Policy::dtls_maximum_retransmissions()) and the
692 * association is being abandoned.
693 *
694 * @note During an invocation of @p op the DTLS implementation might call
695 * tls_register_deferred_operation() again to schedule another
696 * operation. This must be supported by the user implementation.
697 *
698 * By default, this callback does nothing. If the downstream application
699 * chooses not to override and implement this callback, it has to
700 * independently invoke Channel::timeout_check() regularly whenever a DTLS
701 * handshake is in progress. In contrast, if the downstream application
702 * implements this callback, it must never invoke Channel::timeout_check()
703 * directly!
704 *
705 * TODO(Botan4): Change the default to throw an exception to force users
706 * of DTLS to implement this callback and remove the public
707 * ::timeout_check() and ::next_retransmission_timeout()
708 * mechanisms from the Channel.
709 *
710 * @param monotonic_delay_ms the delay in milliseconds with respect to
711 * tls_current_monotonic_clock_ms() after which
712 * the operation @p op should be invoked
713 * @param op the operation to be executed by the user
714 * after the delay @p monotonic_delay_ms
715 */
716 virtual void tls_register_deferred_operation(uint64_t monotonic_delay_ms, std::function<void()> op);
717
718 /**
719 * Optional callback: error logging. (not currently called)
720 * @param err An error message related to this connection.
721 *
722 * TODO(Botan4) remove this
723 */
724 virtual void tls_log_error(const char* err);
725
726 /**
727 * Optional callback: debug logging. (not currently called)
728 * @param what Some hopefully informative string
729 *
730 * TODO(Botan4) remove this
731 */
732 virtual void tls_log_debug(const char* what);
733
734 /**
735 * Optional callback: debug logging taking a buffer. (not currently called)
736 * @param descr What this buffer is
737 * @param val the bytes
738 * @param val_len length of val
739 *
740 * TODO(Botan4) remove this
741 */
742 virtual void tls_log_debug_bin(const char* descr, const uint8_t val[], size_t val_len);
743
744 /**
745 * Optional callback: Allows access to a connection's secret data
746 *
747 * Useful to implement the SSLKEYLOGFILE for connection debugging as
748 * specified in ietf.org/archive/id/draft-thomson-tls-keylogfile-00.html
749 *
750 * Invoked if Policy::allow_ssl_key_log_file returns true.
751 *
752 * Default implementation simply ignores the inputs.
753 *
754 * @param label Identifies the reported secret type
755 * See draft-thomson-tls-keylogfile-00 Section 3.1 and 3.2
756 * @param client_random random value from ClientHello message acting as
757 * an identifier of the TLS sessions
758 * @param secret the actual secret value
759 */
760 virtual void tls_ssl_key_log_data(std::string_view label,
761 std::span<const uint8_t> client_random,
762 std::span<const uint8_t> secret) const;
763
764 /**
765 * Returns the key derivation function to be used for TLS 1.2
766 *
767 * The default implementation can be overridden to provide a user-defined
768 * key derivation function, for example to delegate key derivation to a
769 * hardware-protected environment when a pre-shared key must remain
770 * inaccessible to the non-secure world.
771 *
772 * @param prf_algo name of the hash function (e.g. "SHA-256")
773 *
774 * @return TLS 1.2 KDF implementation
775 */
776 virtual std::unique_ptr<KDF> tls12_protocol_specific_kdf(std::string_view prf_algo) const;
777};
778
779} // namespace TLS
780
781} // namespace Botan
782
783#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
virtual std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout() const
virtual ~Callbacks()=default
virtual void tls_session_activated()
virtual void tls_session_established(const Session_Summary &session)
virtual void tls_record_received(uint64_t seq_no, std::span< const uint8_t > data)=0
virtual void tls_alert(Alert alert)=0
virtual bool tls_peer_closed_connection()
virtual void tls_emit_data(std::span< const uint8_t > data)=0
Signature_Format
Definition pk_keys.h:36
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128