#include <tls_callbacks.h>

Public Member Functions
virtual	~Callbacks ()=default
Mandatory
Those callbacks must be implemented by all applications that use TLS.
virtual void	tls_emit_data (std::span< const uint8_t > data)=0
virtual void	tls_record_received (uint64_t seq_no, std::span< const uint8_t > data)=0
virtual void	tls_alert (Alert alert)=0
Informational
Override these to obtain deeper insights into the TLS connection. Throwing from any of these callbacks will result in the termination of the TLS connection.
virtual void	tls_session_established (const Session_Summary &session)
virtual void	tls_session_activated ()
virtual bool	tls_peer_closed_connection ()
virtual bool	tls_should_persist_resumption_information (const Session &session)
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 void	tls_verify_raw_public_key (const Public_Key &raw_public_key, Usage_Type usage, std::string_view hostname, const TLS::Policy &policy)
virtual std::chrono::milliseconds	tls_verify_cert_chain_ocsp_timeout () const
virtual std::vector< uint8_t >	tls_provide_cert_status (const std::vector< X509_Certificate > &chain, const Certificate_Status_Request &csr)
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::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 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 std::unique_ptr< Public_Key >	tls_deserialize_peer_public_key (const std::variant< TLS::Group_Params, DL_Group > &group, std::span< const uint8_t > key_bits)
virtual std::unique_ptr< Private_Key >	tls_kem_generate_key (TLS::Group_Params group, RandomNumberGenerator &rng)
virtual KEM_Encapsulation	tls_kem_encapsulate (TLS::Group_Params group, const std::vector< uint8_t > &encoded_public_key, 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::unique_ptr< PK_Key_Agreement_Key >	tls_generate_ephemeral_key (const std::variant< TLS::Group_Params, DL_Group > &group, RandomNumberGenerator &rng)
virtual std::unique_ptr< PK_Key_Agreement_Key >	tls12_generate_ephemeral_ecdh_key (TLS::Group_Params group, RandomNumberGenerator &rng, EC_Point_Format tls12_ecc_pubkey_encoding_format)
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 void	tls_inspect_handshake_msg (const Handshake_Message &message)
virtual std::string	tls_server_choose_app_protocol (const std::vector< std::string > &client_protos)
virtual void	tls_modify_extensions (Extensions &extn, Connection_Side which_side, Handshake_Type which_message)
virtual void	tls_examine_extensions (const Extensions &extn, Connection_Side which_side, Handshake_Type which_message)
virtual std::optional< OCSP::Response >	tls_parse_ocsp_response (const std::vector< uint8_t > &raw_response)
virtual std::string	tls_peer_network_identity ()
virtual std::chrono::system_clock::time_point	tls_current_timestamp ()
virtual void	tls_log_error (const char *err)
virtual void	tls_log_debug (const char *what)
virtual void	tls_log_debug_bin (const char *descr, const uint8_t val[], size_t val_len)
virtual void	tls_ssl_key_log_data (std::string_view label, std::span< const uint8_t > client_random, std::span< const uint8_t > secret) const

Detailed Description

Encapsulates the callbacks that a TLS channel will make which are due to channel specific operations.

Definition at line 45 of file tls_callbacks.h.

Constructor & Destructor Documentation

◆ ~Callbacks()

virtual Botan::TLS::Callbacks::~Callbacks ( )

virtualdefault

Member Function Documentation

◆ tls12_generate_ephemeral_ecdh_key()

std::unique_ptr< PK_Key_Agreement_Key > Botan::TLS::Callbacks::tls12_generate_ephemeral_ecdh_key	(	TLS::Group_Params	group,
		RandomNumberGenerator &	rng,
		EC_Point_Format	tls12_ecc_pubkey_encoding_format )

virtual

Generate an ECDH key pair for the TLS 1.2 handshake.

Note that this callback is called exclusively by TLS 1.2 to handle the ECDH public key serialization format explicitly. TLS 1.3 fixes this format to 'uncompressed' and does not allow negotiating anything else. X25519 and X448 feature a defined and fixed public key encoding and are therefore not explicitly handled by this callback either.

Users may override this if they want to provide a custom keypair type to offload TLS 1.2's ECDH handling to custom hardware, for instance. It is worth noting that support for compressed points in Botan is deprecated and this callback will disappear when it is removed in a future release.

Typical use cases of the library don't need to do that and serious security risks are associated with customizing TLS's key exchange mechanism.

Exceptions

TLS_Exception(Alert::DecodeError) if the group is not known.

Parameters

group	ECDH group identifier to generate an ephemeral keypair for
rng	a random number generator
tls12_ecc_pubkey_encoding_format	the key's serialization format

Returns: an ECDH private key of an algorithm usable for key agreement

Definition at line 356 of file tls_callbacks.cpp.

                                                                                                        {
   // Delegating to the "universal" callback to obtain an ECDH key pair
   auto key = tls_generate_ephemeral_key(group, rng);
 
   // For ordinary ECDH key pairs (that are derived from `ECDH_PublicKey`), we
   // set the internal point encoding flag for the key before passing it on into
   // the TLS 1.2 implementation. For user-defined keypair types (e.g. to
   // offload to some crypto hardware) inheriting from Botan's `ECDH_PublicKey`
   // might not be feasible. Such users should consider overriding this
   // ECDH-specific callback and ensure that their custom class handles the
   // public point encoding as requested by `tls12_ecc_pubkey_encoding_format`.
   if(auto* ecc_key = dynamic_cast<ECDH_PublicKey*>(key.get())) {
      ecc_key->set_point_encoding(tls12_ecc_pubkey_encoding_format);
   }
 
   return key;
}

References tls_generate_ephemeral_key().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), and Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ tls_alert()

virtual void Botan::TLS::Callbacks::tls_alert ( Alert alert )

pure virtual

Mandatory callback: alert received

Called when an alert is received from the peer. If fatal, the connection is closing. If not fatal, the connection may still be closing (depending on the error and the peer).

Note that alerts received before the handshake is complete are not authenticated and could have been inserted by a MITM attacker.

References tls_session_established().

◆ tls_current_timestamp()

std::chrono::system_clock::time_point Botan::TLS::Callbacks::tls_current_timestamp ( )

virtual

Optional callback: return a custom time stamp value

This allows the library user to specify a custom "now" timestamp when needed. By default it will use the current system clock time.

Note that typical usages will not need to override this callback but it is useful for testing purposes to allow for deterministic test outcomes.

Definition at line 58 of file tls_callbacks.cpp.

                                                                    {
   return std::chrono::system_clock::now();
}

Referenced by Botan::TLS::make_hello_random(), Botan::TLS::PSK::PSK(), Botan::TLS::Session_Manager::retrieve(), and tls_verify_cert_chain().

◆ tls_deserialize_peer_public_key()

std::unique_ptr< Public_Key > Botan::TLS::Callbacks::tls_deserialize_peer_public_key	(	const std::variant< TLS::Group_Params, DL_Group > &	group,
		std::span< const uint8_t >	key_bits )

virtual

Optional callback: deserialize a public key received from the peer

Default implementation simply parses the public key using Botan's public keys. Override to provide a different approach, e.g. using an external device.

If deserialization fails, the default implementation throws a Botan::Decoding_Error exception that will be translated into a TLS_Exception with an Alert::IllegalParameter.

Parameters

group	the group identifier or (in case of TLS 1.2) an explicit discrete-log group of the public key
key_bits	the serialized public key

Returns: the deserialized and ready-to-use public key

Definition at line 180 of file tls_callbacks.cpp.

                                                                                        {
   if(is_dh_group(group)) {
      // TLS 1.2 allows specifying arbitrary DL_Group parameters in-lieu of
      // a standardized DH group identifier.
      const auto dl_group = get_dl_group(group);
 
      auto Y = BigInt::from_bytes(key_bits);
 
      /*
       * A basic check for key validity. As we do not know q here we
       * cannot check that Y is in the right subgroup. However since
       * our key is ephemeral there does not seem to be any
       * advantage to bogus keys anyway.
       */
      if(Y <= 1 || Y >= dl_group.get_p() - 1) {
         throw Decoding_Error("Server sent bad DH key for DHE exchange");
      }
 
      return std::make_unique<DH_PublicKey>(dl_group, Y);
   }
 
   // The special case for TLS 1.2 with an explicit DH group definition is
   // handled above. All other cases are based on the opaque group definition.
   BOTAN_ASSERT_NOMSG(std::holds_alternative<TLS::Group_Params>(group));
   const auto group_params = std::get<TLS::Group_Params>(group);
 
   if(group_params.is_ecdh_named_curve()) {
      const auto ec_group = EC_Group::from_name(group_params.to_string().value());
      return std::make_unique<ECDH_PublicKey>(ec_group, EC_AffinePoint(ec_group, key_bits));
   }
 
#if defined(BOTAN_HAS_X25519)
   if(group_params.is_x25519()) {
      return std::make_unique<X25519_PublicKey>(key_bits);
   }
#endif
 
#if defined(BOTAN_HAS_X448)
   if(group_params.is_x448()) {
      return std::make_unique<X448_PublicKey>(key_bits);
   }
#endif
 
#if defined(BOTAN_HAS_TLS_13_PQC)
   if(group_params.is_pqc_hybrid()) {
      return Hybrid_KEM_PublicKey::load_for_group(group_params, key_bits);
   }
#endif
 
#if defined(BOTAN_HAS_ML_KEM)
   if(group_params.is_pure_ml_kem()) {
      return std::make_unique<ML_KEM_PublicKey>(key_bits, ML_KEM_Mode(group_params.to_string().value()));
   }
#endif
 
#if defined(BOTAN_HAS_FRODOKEM)
   if(group_params.is_pure_frodokem()) {
      return std::make_unique<FrodoKEM_PublicKey>(key_bits, FrodoKEMMode(group_params.to_string().value()));
   }
#endif
 
   throw Decoding_Error("cannot create a key offering without a group definition");
}

References BOTAN_ASSERT_NOMSG, Botan::BigInt::from_bytes(), Botan::EC_Group::from_name(), and Botan::TLS::Hybrid_KEM_PublicKey::load_for_group().

Referenced by tls_ephemeral_key_agreement(), and tls_kem_encapsulate().

◆ tls_emit_data()

virtual void Botan::TLS::Callbacks::tls_emit_data ( std::span< const uint8_t > data )

pure virtual

Mandatory callback: output function

The channel will call this with data which needs to be sent to the peer (eg, over a socket or some other form of IPC). The array will be overwritten when the function returns so a copy must be made if the data cannot be sent immediately.

As an example you could use the syscall send to perform a blocking write on a socket, or append the data to a queue managed by your application and initiate an asynchronous write.

For TLS all writes must occur in the order requested. For DTLS this ordering is not strictly required, but is still recommended.

Parameters

data	a contiguous data buffer to send

◆ tls_ephemeral_key_agreement()

secure_vector< uint8_t > Botan::TLS::Callbacks::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

Agree on a shared secret with the peer's ephemeral public key for the TLS handshake.

Applications may use this to add custom groups, curves or entirely different ephemeral key agreement mechanisms to the TLS handshake. Note that this callback must be used in conjunction with Callbacks::tls_generate_ephemeral_key.

Typical use cases of the library don't need to do that and serious security risks are associated with customizing TLS's key exchange mechanism.

Parameters

group	the TLS group identifier to be used TLS 1.2 allows for specifying custom discrete logarithm parameters as part of the protocol. Hence the variant<>.
private_key	the private key (generated ahead in tls_generate_ephemeral_key)
public_value	the public key exchange information received by the peer
rng	a random number generator
policy	a TLS policy object

Returns: the shared secret derived from public_value and private_key

Definition at line 375 of file tls_callbacks.cpp.

                         {
   const auto kex_pub_key = [&]() {
      try {
         return tls_deserialize_peer_public_key(group, public_value);
      } catch(const Decoding_Error& ex) {
         // This exception means that the public key was invalid. However,
         // TLS' DecodeError would imply that a protocol message was invalid.
         throw TLS_Exception(Alert::IllegalParameter, ex.what());
      }
   }();
 
   BOTAN_ASSERT_NONNULL(kex_pub_key);
   policy.check_peer_key_acceptable(*kex_pub_key);
 
   // RFC 8422 - 5.11.
   //   With X25519 and X448, a receiving party MUST check whether the
   //   computed premaster secret is the all-zero value and abort the
   //   handshake if so, as described in Section 6 of [RFC7748].
   //
   // This is done within the key agreement operation and throws
   // an Invalid_Argument exception if the shared secret is all-zero.
   try {
      PK_Key_Agreement ka(private_key, rng, "Raw");
      return ka.derive_key(0, kex_pub_key->raw_public_key_bits()).bits_of();
   } catch(const Invalid_Argument& ex) {
      throw TLS_Exception(Alert::IllegalParameter, ex.what());
   }
}

References Botan::OctetString::bits_of(), BOTAN_ASSERT_NONNULL, Botan::TLS::Policy::check_peer_key_acceptable(), Botan::PK_Key_Agreement::derive_key(), tls_deserialize_peer_public_key(), and Botan::Exception::what().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), tls_kem_decapsulate(), and tls_kem_encapsulate().

◆ tls_examine_extensions()

void Botan::TLS::Callbacks::tls_examine_extensions	(	const Extensions &	extn,
		Connection_Side	which_side,
		Handshake_Type	which_message )

virtual

Optional callback: examine peer extensions.

Both client and server will call this callback with the Extensions object after receiving it from the peer. This allows examining the Extensions, for example to implement a custom extension. It also allows an application to require that a particular extension be implemented; throw an exception from this function to abort the handshake.

Default implementation does nothing.

Parameters

extn	the extensions
which_side	will be Connection_Side::Client if these are are the clients extensions (ie we are the server) or Connection_Side::Server if these are the server extensions (we are the client).
which_message	will state the handshake message type containing the extensions

Definition at line 66 of file tls_callbacks.cpp.

68 {}

Referenced by Botan::TLS::Certificate_13::validate_extensions().

◆ tls_generate_ephemeral_key()

std::unique_ptr< PK_Key_Agreement_Key > Botan::TLS::Callbacks::tls_generate_ephemeral_key	(	const std::variant< TLS::Group_Params, DL_Group > &	group,
		RandomNumberGenerator &	rng )

virtual

Generate an ephemeral key pair for the TLS handshake.

Applications may use this to add custom groups, curves or entirely different ephemeral key agreement mechanisms to the TLS handshake. Note that this callback must be used in conjunction with Callbacks::tls_ephemeral_key_agreement.

Typical use cases of the library don't need to do that and serious security risks are associated with customizing TLS's key exchange mechanism.

Exceptions

TLS_Exception(Alert::DecodeError) if the group is not known.

Parameters

group	the group identifier to generate an ephemeral keypair for TLS 1.2 allows for specifying custom discrete logarithm parameters as part of the protocol. Hence the variant<>.
rng	a random number generator

Returns: a private key of an algorithm usable for key agreement

Definition at line 322 of file tls_callbacks.cpp.

                                                                                   {
   if(is_dh_group(group)) {
      const DL_Group dl_group = get_dl_group(group);
      return std::make_unique<DH_PrivateKey>(rng, dl_group);
   }
 
   BOTAN_ASSERT_NOMSG(std::holds_alternative<TLS::Group_Params>(group));
   const auto group_params = std::get<TLS::Group_Params>(group);
 
   if(group_params.is_ecdh_named_curve()) {
      const auto ec_group = EC_Group::from_name(group_params.to_string().value());
      return std::make_unique<ECDH_PrivateKey>(rng, ec_group);
   }
 
#if defined(BOTAN_HAS_X25519)
   if(group_params.is_x25519()) {
      return std::make_unique<X25519_PrivateKey>(rng);
   }
#endif
 
#if defined(BOTAN_HAS_X448)
   if(group_params.is_x448()) {
      return std::make_unique<X448_PrivateKey>(rng);
   }
#endif
 
   if(group_params.is_kem()) {
      throw TLS_Exception(Alert::IllegalParameter, "cannot generate an ephemeral KEX key for a KEM");
   }
 
   throw TLS_Exception(Alert::DecodeError, "cannot create a key offering without a group definition");
}

References BOTAN_ASSERT_NOMSG, and Botan::EC_Group::from_name().

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::TLS::Server_Key_Exchange::Server_Key_Exchange(), tls12_generate_ephemeral_ecdh_key(), tls_kem_encapsulate(), and tls_kem_generate_key().

◆ tls_inspect_handshake_msg()

void Botan::TLS::Callbacks::tls_inspect_handshake_msg ( const Handshake_Message & message )

virtual

Optional callback: inspect handshake message Throw an exception to abort the handshake. Default simply ignores the message.

Note: On connections that negotiated TLS 1.3 this callback is also invoked for post-handshake messages.

Parameters

message the handshake message

Definition at line 46 of file tls_callbacks.cpp.

                                                                       {
   // default is no op
}

◆ tls_kem_decapsulate()

secure_vector< uint8_t > Botan::TLS::Callbacks::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

Performs a key decapsulation operation (used for TLS 1.3 clients).

Applications may use this to add custom KEM algorithms or entirely different key exchange schemes to the TLS 1.3 handshake. For instance, this could provide an entry point to implement a hybrid key exchange with both a traditional algorithm like ECDH and a quantum-secure KEM. Typical use cases of the library don't need to do that and serious security risks are associated with customizing TLS's key encapsulation mechanism.

Note that the KEM interface is usable for TLS 1.3 handshakes, only.

The default implementation simply delegates this to the tls_ephemeral_key_agreement() callback to obtain the shared secret.

Parameters

group	the group identifier of the KEM/KEX algorithm
private_key	the private key used for decapsulation/KEX
encapsulated_bytes	the content to decapsulate (or the public key share)
rng	a random number generator
policy	a TLS policy object

Returns: the plaintext shared secret from encapsulated_bytes after decapsulation with private_key.

Definition at line 301 of file tls_callbacks.cpp.

                                                                                 {
   if(group.is_kem()) {
      PK_KEM_Decryptor kemdec(private_key, rng, "Raw");
      if(encapsulated_bytes.size() != kemdec.encapsulated_key_length()) {
         throw TLS_Exception(Alert::IllegalParameter, "Invalid encapsulated key length");
      }
      return kemdec.decrypt(encapsulated_bytes, 0, {});
   }
 
   try {
      const auto& key_agreement_key = dynamic_cast<const PK_Key_Agreement_Key&>(private_key);
      return tls_ephemeral_key_agreement(group, key_agreement_key, encapsulated_bytes, rng, policy);
   } catch(const std::bad_cast&) {
      throw Invalid_Argument("provided ephemeral key is not a PK_Key_Agreement_Key");
   }
}

References Botan::PK_KEM_Decryptor::decrypt(), Botan::PK_KEM_Decryptor::encapsulated_key_length(), Botan::TLS::Group_Params::is_kem(), and tls_ephemeral_key_agreement().

◆ tls_kem_encapsulate()

KEM_Encapsulation Botan::TLS::Callbacks::tls_kem_encapsulate	(	TLS::Group_Params	group,
		const std::vector< uint8_t > &	encoded_public_key,
		RandomNumberGenerator &	rng,
		const Policy &	policy )

virtual

Performs a key encapsulation operation (used for TLS 1.3 servers)

Applications may use this to add custom KEM algorithms or entirely different key exchange schemes to the TLS 1.3 handshake. For instance, this could provide an entry point to implement a hybrid key exchange with both a traditional algorithm like ECDH and a quantum-secure KEM. Typical use cases of the library don't need to do that and serious security risks are associated with customizing TLS's key encapsulation mechanism.

Note that the KEM interface is usable for TLS 1.3 handshakes, only.

The default implementation implements this key encapsulation as a combination of tls_generate_ephemeral_key() followed by tls_ephemeral_key_agreement() with the provided encoded_public_key. The just-generated ephemeral private key is destroyed immediately.

Parameters

group	the group identifier of the KEM/KEX algorithm
encoded_public_key	the public key used for encapsulation/KEX
rng	a random number generator
policy	a TLS policy object

Returns: the shared secret both in plaintext and encapsulated with encoded_public_key.

Definition at line 267 of file tls_callbacks.cpp.

                                                                            {
   if(group.is_kem()) {
      auto kem_pub_key = [&] {
         try {
            return tls_deserialize_peer_public_key(group, encoded_public_key);
         } catch(const Decoding_Error& ex) {
            // This exception means that the public key was invalid. However,
            // TLS' DecodeError would imply that a protocol message was invalid.
            throw TLS_Exception(Alert::IllegalParameter, ex.what());
         }
      }();
 
      BOTAN_ASSERT_NONNULL(kem_pub_key);
      policy.check_peer_key_acceptable(*kem_pub_key);
 
      try {
         return PK_KEM_Encryptor(*kem_pub_key, "Raw").encrypt(rng);
      } catch(const Invalid_Argument& ex) {
         throw TLS_Exception(Alert::IllegalParameter, ex.what());
      }
   } else {
      // TODO: We could use the KEX_to_KEM_Adapter to remove the case distinction
      //       of KEM and KEX. However, the workarounds in this adapter class
      //       should first be addressed.
      auto ephemeral_keypair = tls_generate_ephemeral_key(group, rng);
      BOTAN_ASSERT_NONNULL(ephemeral_keypair);
      return {ephemeral_keypair->public_value(),
              tls_ephemeral_key_agreement(group, *ephemeral_keypair, encoded_public_key, rng, policy)};
   }
}

References BOTAN_ASSERT_NONNULL, Botan::TLS::Policy::check_peer_key_acceptable(), Botan::PK_KEM_Encryptor::encrypt(), Botan::TLS::Group_Params::is_kem(), tls_deserialize_peer_public_key(), tls_ephemeral_key_agreement(), tls_generate_ephemeral_key(), and Botan::Exception::what().

◆ tls_kem_generate_key()

std::unique_ptr< Private_Key > Botan::TLS::Callbacks::tls_kem_generate_key	(	TLS::Group_Params	group,
		RandomNumberGenerator &	rng )

virtual

Generate an ephemeral KEM key for a TLS 1.3 handshake

Applications may use this to add custom KEM algorithms or entirely different key exchange schemes to the TLS 1.3 handshake. For instance, this could provide an entry point to implement a hybrid key exchange with both a traditional algorithm like ECDH and a quantum-secure KEM. Typical use cases of the library don't need to do that and serious security risks are associated with customizing TLS's key encapsulation mechanism.

Note that the KEM interface is usable for TLS 1.3 handshakes, only.

The default implementation simply delegates this to the tls_generate_ephemeral_key() call when appropriate.

Parameters

group	the group identifier to generate an ephemeral keypair for
rng	a random number generator

Returns: a keypair whose public key will be provided to the peer and the private key will be provided to tls_kem_decapsulate later in the handshake.

Definition at line 245 of file tls_callbacks.cpp.

                                                                                                               {
#if defined(BOTAN_HAS_ML_KEM)
   if(group.is_pure_ml_kem()) {
      return std::make_unique<ML_KEM_PrivateKey>(rng, ML_KEM_Mode(group.to_string().value()));
   }
#endif
 
#if defined(BOTAN_HAS_FRODOKEM)
   if(group.is_pure_frodokem()) {
      return std::make_unique<FrodoKEM_PrivateKey>(rng, FrodoKEMMode(group.to_string().value()));
   }
#endif
 
#if defined(BOTAN_HAS_TLS_13_PQC)
   if(group.is_pqc_hybrid()) {
      return Hybrid_KEM_PrivateKey::generate_from_group(group, rng);
   }
#endif
 
   return tls_generate_ephemeral_key(group, rng);
}

References Botan::TLS::Hybrid_KEM_PrivateKey::generate_from_group(), Botan::TLS::Group_Params::is_pqc_hybrid(), Botan::TLS::Group_Params::is_pure_frodokem(), Botan::TLS::Group_Params::is_pure_ml_kem(), tls_generate_ephemeral_key(), and Botan::TLS::Group_Params::to_string().

◆ tls_log_debug()

void Botan::TLS::Callbacks::tls_log_debug ( const char * what )

virtual

Optional callback: debug logging. (not currently called)

Parameters

what	Some hopefully informative string

Definition at line 423 of file tls_callbacks.cpp.

                                                 {
   BOTAN_UNUSED(what);
}

References BOTAN_UNUSED.

◆ tls_log_debug_bin()

void Botan::TLS::Callbacks::tls_log_debug_bin	(	const char *	descr,
		const uint8_t	val[],
		size_t	val_len )

virtual

Optional callback: debug logging taking a buffer. (not currently called)

Parameters

descr	What this buffer is
val	the bytes
val_len	length of val

Definition at line 427 of file tls_callbacks.cpp.

                                                                                           {
   BOTAN_UNUSED(descr, val, val_len);
}

References BOTAN_UNUSED.

◆ tls_log_error()

void Botan::TLS::Callbacks::tls_log_error ( const char * err )

virtual

Optional callback: error logging. (not currently called)

Parameters

err	An error message related to this connection.

Definition at line 419 of file tls_callbacks.cpp.

                                                {
   BOTAN_UNUSED(err);
}

References BOTAN_UNUSED.

◆ tls_modify_extensions()

void Botan::TLS::Callbacks::tls_modify_extensions	(	Extensions &	extn,
		Connection_Side	which_side,
		Handshake_Type	which_message )

virtual

Optional callback: examine/modify Extensions before sending.

Both client and server will call this callback on the Extensions object before serializing it in the specific handshake message. This allows an application to modify which extensions are sent during the handshake.

Default implementation does nothing.

Parameters

extn	the extensions
which_side	will be Connection_Side::Client or Connection_Side::Server which is the current applications role in the exchange.
which_message	will state the handshake message type containing the extensions

Definition at line 62 of file tls_callbacks.cpp.

64 {}

Referenced by Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Client_Hello_12::Client_Hello_12(), Botan::TLS::Client_Hello_13::Client_Hello_13(), Botan::TLS::Encrypted_Extensions::Encrypted_Extensions(), Botan::TLS::Hello_Retry_Request::Hello_Retry_Request(), Botan::TLS::New_Session_Ticket_13::New_Session_Ticket_13(), and Botan::TLS::Client_Hello_13::retry().

◆ tls_parse_ocsp_response()

std::optional< OCSP::Response > Botan::TLS::Callbacks::tls_parse_ocsp_response ( const std::vector< uint8_t > & raw_response )

virtual

Optional callback: parse a single OCSP Response

Note: Typically a user of the library would not want to override this callback. We provide this callback to be able to support OCSP related tests from BoringSSL's BoGo tests that provide unparsable responses.

Default implementation tries to parse the provided raw OCSP response.

This function should not throw an exception but return a std::nullopt if the OCSP response cannot be parsed.

Parameters

raw_response raw OCSP response buffer

Returns: the parsed OCSP response or std::nullopt on error

Definition at line 122 of file tls_callbacks.cpp.

                                                                                                      {
   try {
      return OCSP::Response(raw_response);
   } catch(const Decoding_Error&) {
      // ignore parsing errors and just ignore the broken OCSP response
      return std::nullopt;
   }
}

◆ tls_peer_closed_connection()

virtual bool Botan::TLS::Callbacks::tls_peer_closed_connection ( )

inlinevirtual

Optional callback: peer closed connection (sent a "close_notify" alert)

The peer signaled that it wishes to shut down the connection. The application should not expect to receive any more data from the peer and may tear down the underlying transport socket.

Prior to TLS 1.3 it was required that peers discard pending writes and immediately respond with their own "close_notify". With TLS 1.3, applications can continue to send data despite the peer having already signaled their wish to shut down.

Returning true will cause the TLS 1.3 implementation to write all pending data and then also signal a connection shut down. Otherwise the application is responsible to call the Channel::close() method.

For TLS 1.2 the return value has no effect.

Returns: true causes the implementation to respond with a "close_notify"

Definition at line 164 of file tls_callbacks.h.

164{ return true; }

◆ tls_peer_network_identity()

std::string Botan::TLS::Callbacks::tls_peer_network_identity ( )

virtual

Optional callback: return peer network identity

There is no expected or specified format. The only expectation is this function will return a unique value. For example returning the peer host IP and port.

This is used to bind the DTLS cookie to a particular network identity. It is only called if the dtls-cookie-secret PSK is also defined.

Definition at line 54 of file tls_callbacks.cpp.

                                                  {
   return "";
}

◆ tls_provide_cert_chain_status()

std::vector< std::vector< uint8_t > > Botan::TLS::Callbacks::tls_provide_cert_chain_status	(	const std::vector< X509_Certificate > &	chain,
		const Certificate_Status_Request &	csr )

virtual

Called by TLS 1.3 client or server whenever the peer indicated that OCSP stapling is supported. In contrast to tls_provide_cert_status, this allows providing OCSP responses for each certificate in the chain.

The default implementation invokes tls_provide_cert_status assuming that no OCSP responses for intermediate certificates are available.

Returns: a vector of OCSP response buffers. An empty buffer indicates that no OCSP response should be provided for the respective certificate (at the same list index). The returned vector MUST be exactly the same length as the incoming chain.

Definition at line 131 of file tls_callbacks.cpp.

                                                                                    {
   std::vector<std::vector<uint8_t>> result(chain.size());
   if(!chain.empty()) {
      result[0] = tls_provide_cert_status(chain, csr);
   }
   return result;
}

References tls_provide_cert_status().

◆ tls_provide_cert_status()

std::vector< uint8_t > Botan::TLS::Callbacks::tls_provide_cert_status	(	const std::vector< X509_Certificate > &	chain,
		const Certificate_Status_Request &	csr )

virtual

Called by the TLS server whenever the client included the status_request extension (see RFC 6066, a.k.a OCSP stapling) in the ClientHello.

Returns: the encoded OCSP response to be sent to the client which indicates the revocation status of the server certificate. Return an empty vector to indicate that no response is available, and thus suppress the Certificate_Status message.

Default implementation returns an empty vector, disabling certificate status

Definition at line 413 of file tls_callbacks.cpp.

                                                                                                    {
   BOTAN_UNUSED(chain, csr);
   return std::vector<uint8_t>();
}

References BOTAN_UNUSED.

Referenced by tls_provide_cert_chain_status().

◆ tls_record_received()

virtual void Botan::TLS::Callbacks::tls_record_received	(	uint64_t	seq_no,
		std::span< const uint8_t >	data )

pure virtual

Mandatory callback: process application data

Called when application data record is received from the peer. The array is overwritten immediately after the function returns.

Currently empty records are ignored and do not instigate a callback, but this may change in a future release.

For TLS the record number will always increase. For DTLS, it is possible to receive records with the seq_no field out of order, or with gaps, corresponding to reordered or lost datagrams.

Parameters

seq_no	the underlying TLS/DTLS record sequence number
data	a contiguous data buffer containing the received record

Referenced by Botan::TLS::Channel_Impl_13::from_peer().

◆ tls_server_choose_app_protocol()

std::string Botan::TLS::Callbacks::tls_server_choose_app_protocol ( const std::vector< std::string > & client_protos )

virtual

Optional callback for server: choose ALPN protocol

ALPN (RFC 7301) works by the client sending a list of application protocols it is willing to negotiate. The server then selects which protocol to use. RFC 7301 requires that if the server does not support any protocols offered by the client, then it should close the connection with an alert of no_application_protocol. Within this callback this would be done by throwing a TLS_Exception(Alert::NoApplicationProtocol)

Parameters

client_protos the vector of protocols the client is willing to negotiate

Returns: the protocol selected by the server; if the empty string is returned, the server does not reply to the client ALPN extension.

The default implementation returns the empty string, causing client ALPN to be ignored.

It is highly recommended to support ALPN whenever possible to avoid cross-protocol attacks.

Definition at line 50 of file tls_callbacks.cpp.

                                                                                    {
   return "";
}

Referenced by Botan::TLS::Encrypted_Extensions::Encrypted_Extensions().

◆ tls_session_activated()

virtual void Botan::TLS::Callbacks::tls_session_activated ( )

inlinevirtual

Optional callback: session activated

By default does nothing. This is called when the session is activated, that is once it is possible to send or receive data on the channel. In particular it is possible for an implementation of this function to perform an initial write on the channel.

Definition at line 142 of file tls_callbacks.h.

142{}

Referenced by Botan::TLS::Channel_Impl_12::activate_session().

◆ tls_session_established()

void Botan::TLS::Callbacks::tls_session_established ( const Session_Summary & session )

virtual

Optional callback: session established

Called whenever a negotiation completes. This can happen more than once on TLS 1.2 connections, if renegotiation occurs. The session parameter provides information about the session which was just established.

If this function wishes to cancel the handshake, it can throw an exception which will send a close message to the counterparty and reset the connection state.

Parameters

session the session descriptor

Definition at line 409 of file tls_callbacks.cpp.

                                                                         {
   BOTAN_UNUSED(session);
}

References BOTAN_UNUSED.

Referenced by tls_alert().

◆ tls_should_persist_resumption_information()

bool Botan::TLS::Callbacks::tls_should_persist_resumption_information ( const Session & session )

virtual

Optional callback: Resumption information was received/established

TLS 1.3 calls this when we sent or received a TLS 1.3 session ticket at any point after the initial handshake has finished.

TLS 1.2 calls this when a session was established successfully and its resumption information may be stored for later usage.

Note that for servers this is called as soon as resumption information is available and could be sent to the client. If this callback returns 'false', the information will neither be cached nor sent.

Parameters

session the session descriptor

Returns: false to prevent the resumption information from being cached, and true to cache it in the configured Session_Manager

Definition at line 70 of file tls_callbacks.cpp.

                                                                                   {
   // RFC 5077 3.3
   //    The ticket_lifetime_hint field contains a hint from the server about
   //    how long the ticket should be stored. A value of zero is reserved to
   //    indicate that the lifetime of the ticket is unspecified.
   //
   // RFC 8446 4.6.1
   //    [A ticket_lifetime] of zero indicates that the ticket should be discarded
   //    immediately.
   //
   // By default we opt to keep all sessions, except for TLS 1.3 with a lifetime
   // hint of zero.
   return session.lifetime_hint().count() > 0 || session.version().is_pre_tls_13();
}

References Botan::TLS::Protocol_Version::is_pre_tls_13(), Botan::TLS::Session::lifetime_hint(), and Botan::TLS::Session_Base::version().

◆ tls_sign_message()

std::vector< uint8_t > Botan::TLS::Callbacks::tls_sign_message	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		std::string_view	padding,
		Signature_Format	format,
		const std::vector< uint8_t > &	msg )

virtual

Optional callback with default impl: sign a message

Default implementation uses PK_Signer::sign_message(). Override to provide a different approach, e.g. using an external device.

Parameters

key	the private key of the signer
rng	a random number generator
padding	the encoding method to be applied to the message
format	the signature format
msg	the input data for the signature

Returns: the signature

Definition at line 140 of file tls_callbacks.cpp.

                                                                                     {
   PK_Signer signer(key, rng, padding, format);
 
   return signer.sign_message(msg, rng);
}

References Botan::PK_Signer::sign_message().

Referenced by Botan::TLS::Certificate_Verify_12::Certificate_Verify_12(), Botan::TLS::Certificate_Verify_13::Certificate_Verify_13(), and Botan::TLS::Server_Key_Exchange::Server_Key_Exchange().

◆ tls_ssl_key_log_data()

void Botan::TLS::Callbacks::tls_ssl_key_log_data	(	std::string_view	label,
		std::span< const uint8_t >	client_random,
		std::span< const uint8_t >	secret ) const

virtual

Optional callback: Allows access to a connection's secret data

Useful to implement the SSLKEYLOGFILE for connection debugging as specified in ietf.org/archive/id/draft-thomson-tls-keylogfile-00.html

Invoked if Policy::allow_ssl_key_log_file returns true.

Default implementation simply ignores the inputs.

Parameters

label	Identifies the reported secret type See draft-thomson-tls-keylogfile-00 Section 3.1 and 3.2
client_random	random value from ClientHello message acting as an identifier of the TLS sessions
secret	the actual secret value

Definition at line 431 of file tls_callbacks.cpp.

                                                                               {
   BOTAN_UNUSED(label, client_random, secret);
}

References BOTAN_UNUSED.

◆ tls_verify_cert_chain()

void Botan::TLS::Callbacks::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

Optional callback with default impl: verify cert chain

Default implementation performs a standard PKIX validation and initiates network OCSP request for end-entity cert. Override to provide different behavior.

Check the certificate chain is valid up to a trusted root, and optionally (if hostname != "") that the hostname given is consistent with the leaf certificate.

This function should throw an exception derived from std::exception with an informative what() result if the certificate chain cannot be verified.

Parameters

cert_chain	specifies a certificate chain leading to a trusted root CA certificate.
ocsp_responses	the server may have provided some
trusted_roots	the list of trusted certificates
usage	what this cert chain is being used for Usage_Type::TLS_SERVER_AUTH for server chains, Usage_Type::TLS_CLIENT_AUTH for client chains, Usage_Type::UNSPECIFIED for other uses
hostname	when authenticating a server, this is the hostname the client requested (eg via SNI). When authenticating a client, this is the server name the client is authenticating to. Empty in other cases or if no hostname was used.
policy	the TLS policy associated with the session being authenticated using the certificate chain

Definition at line 85 of file tls_callbacks.cpp.

                                                                    {
   if(cert_chain.empty()) {
      throw Invalid_Argument("Certificate chain was empty");
   }
 
   Path_Validation_Restrictions restrictions(policy.require_cert_revocation_info(),
                                             policy.minimum_signature_strength());
 
   Path_Validation_Result result = x509_path_validate(cert_chain,
                                                      restrictions,
                                                      trusted_roots,
                                                      hostname,
                                                      usage,
                                                      tls_current_timestamp(),
                                                      tls_verify_cert_chain_ocsp_timeout(),
                                                      ocsp_responses);
 
   if(!result.successful_validation()) {
      throw TLS_Exception(Alert::BadCertificate, "Certificate validation failure: " + result.result_string());
   }
}

References Botan::TLS::Policy::minimum_signature_strength(), Botan::TLS::Policy::require_cert_revocation_info(), Botan::Path_Validation_Result::result_string(), Botan::Path_Validation_Result::successful_validation(), tls_current_timestamp(), tls_verify_cert_chain_ocsp_timeout(), and Botan::x509_path_validate().

◆ tls_verify_cert_chain_ocsp_timeout()

virtual std::chrono::milliseconds Botan::TLS::Callbacks::tls_verify_cert_chain_ocsp_timeout ( ) const

inlinevirtual

Called by default tls_verify_cert_chain to get the timeout to use for OCSP requests. Return 0 to disable online OCSP checks.

This function should not be "const" since the implementation might need to perform some side effecting operation to compute the result.

Definition at line 261 of file tls_callbacks.h.

                                                                               {
         return std::chrono::milliseconds(0);
      }

Referenced by tls_verify_cert_chain().

◆ tls_verify_message()

bool Botan::TLS::Callbacks::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

Optional callback with default impl: verify a message signature

Default implementation uses PK_Verifier::verify_message(). Override to provide a different approach, e.g. using an external device.

Parameters

key	the public key of the signer
padding	the encoding method to be applied to the message
format	the signature format
msg	the input data for the signature
sig	the signature to be checked

Returns: true if the signature is valid, false otherwise

Definition at line 150 of file tls_callbacks.cpp.

                                                                       {
   PK_Verifier verifier(key, padding, format);
 
   return verifier.verify_message(msg, sig);
}

References Botan::PK_Verifier::verify_message().

Referenced by Botan::TLS::Certificate_Verify_12::verify(), Botan::TLS::Certificate_Verify_13::verify(), and Botan::TLS::Server_Key_Exchange::verify().

◆ tls_verify_raw_public_key()

void Botan::TLS::Callbacks::tls_verify_raw_public_key	(	const Public_Key &	raw_public_key,
		Usage_Type	usage,
		std::string_view	hostname,
		const TLS::Policy &	policy )

virtual

Optional callback. Default impl always rejects.

This allows using raw public keys for authentication of peers as described in RFC 7250 and RFC 8446 4.2.2. Applications that wish to use raw public keys MUST override this callback to verify the authenticity of the received public keys.

Default implementation always rejects the raw public key.

This function should throw an exception derived from std::exception with an informative what() result if the raw public key cannot be verified.

Parameters

raw_public_key	specifies the raw public key to be used for peer authentication
usage	what this cert chain is being used for Usage_Type::TLS_SERVER_AUTH for server chains, Usage_Type::TLS_CLIENT_AUTH for client chains,
hostname	when authenticating a server, this is the hostname the client requested (eg via SNI). When authenticating a client, this is the server name the client is authenticating to. Empty in other cases or if no hostname was used.
policy	the TLS policy associated with the session being authenticated using the raw public key

Definition at line 112 of file tls_callbacks.cpp.

                                                                        {
   BOTAN_UNUSED(raw_public_key, usage, hostname, policy);
   // There is no good default implementation for authenticating raw public key.
   // Applications that wish to use them for authentication, must override this.
   throw TLS_Exception(Alert::CertificateUnknown, "Application did not provide a means to validate the raw public key");
}

References BOTAN_UNUSED.

Referenced by Botan::TLS::Certificate_13::verify().

The documentation for this class was generated from the following files:

src/lib/tls/tls_callbacks.h
src/lib/tls/tls_callbacks.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Callbacks()

Member Function Documentation

◆ tls12_generate_ephemeral_ecdh_key()

◆ tls_alert()

◆ tls_current_timestamp()

◆ tls_deserialize_peer_public_key()

◆ tls_emit_data()

◆ tls_ephemeral_key_agreement()

◆ tls_examine_extensions()

◆ tls_generate_ephemeral_key()

◆ tls_inspect_handshake_msg()

◆ tls_kem_decapsulate()

◆ tls_kem_encapsulate()

◆ tls_kem_generate_key()

◆ tls_log_debug()

◆ tls_log_debug_bin()

◆ tls_log_error()

◆ tls_modify_extensions()

◆ tls_parse_ocsp_response()

◆ tls_peer_closed_connection()

◆ tls_peer_network_identity()

◆ tls_provide_cert_chain_status()

◆ tls_provide_cert_status()

◆ tls_record_received()

◆ tls_server_choose_app_protocol()

◆ tls_session_activated()

◆ tls_session_established()

◆ tls_should_persist_resumption_information()

◆ tls_sign_message()

◆ tls_ssl_key_log_data()

◆ tls_verify_cert_chain()

◆ tls_verify_cert_chain_ocsp_timeout()

◆ tls_verify_message()

◆ tls_verify_raw_public_key()