Botan  2.8.0
Crypto and TLS for C++11
Public Member Functions | List of all members
Botan::TLS::Callbacks Class Referenceabstract

#include <tls_callbacks.h>

Inheritance diagram for Botan::TLS::Callbacks:
Botan::TLS::Compat_Callbacks

Public Member Functions

virtual void tls_alert (Alert alert)=0
 
virtual std::string tls_decode_group_param (Group_Params group_param)
 
virtual std::pair< secure_vector< uint8_t >, std::vector< uint8_t > > tls_dh_agree (const std::vector< uint8_t > &modulus, const std::vector< uint8_t > &generator, const std::vector< uint8_t > &peer_public_value, const Policy &policy, RandomNumberGenerator &rng)
 
virtual std::pair< secure_vector< uint8_t >, std::vector< uint8_t > > tls_ecdh_agree (const std::string &curve_name, const std::vector< uint8_t > &peer_public_value, const Policy &policy, RandomNumberGenerator &rng, bool compressed)
 
virtual void tls_emit_data (const uint8_t data[], size_t size)=0
 
virtual void tls_examine_extensions (const Extensions &extn, Connection_Side which_side)
 
virtual void tls_inspect_handshake_msg (const Handshake_Message &message)
 
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_log_error (const char *err)
 
virtual void tls_modify_extensions (Extensions &extn, Connection_Side which_side)
 
virtual void tls_record_received (uint64_t seq_no, const uint8_t data[], size_t size)=0
 
virtual std::string tls_server_choose_app_protocol (const std::vector< std::string > &client_protos)
 
virtual void tls_session_activated ()
 
virtual bool tls_session_established (const Session &session)=0
 
virtual std::vector< uint8_t > tls_sign_message (const Private_Key &key, RandomNumberGenerator &rng, const std::string &emsa, Signature_Format format, const std::vector< uint8_t > &msg)
 
virtual void tls_verify_cert_chain (const std::vector< X509_Certificate > &cert_chain, const std::vector< std::shared_ptr< const OCSP::Response >> &ocsp_responses, const std::vector< Certificate_Store *> &trusted_roots, Usage_Type usage, const std::string &hostname, const TLS::Policy &policy)
 
virtual std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout () const
 
virtual bool tls_verify_message (const Public_Key &key, const std::string &emsa, Signature_Format format, const std::vector< uint8_t > &msg, const std::vector< uint8_t > &sig)
 
virtual ~Callbacks ()=default
 

Detailed Description

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

Definition at line 39 of file tls_callbacks.h.

Constructor & Destructor Documentation

◆ ~Callbacks()

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

Member Function Documentation

◆ 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).

Parameters
alertthe source of the alert

Implemented in Botan::TLS::Compat_Callbacks.

◆ tls_decode_group_param()

std::string Botan::TLS::Callbacks::tls_decode_group_param ( Group_Params  group_param)
virtual

Optional callback: decode TLS group ID

TLS uses a 16-bit field to identify ECC and DH groups. This callback handles the decoding. You only need to implement this if you are using a custom ECC or DH group (this is extremely uncommon).

Default implementation uses the standard (IETF-defined) mappings.

Definition at line 44 of file tls_callbacks.cpp.

References Botan::TLS::group_param_to_string().

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

45  {
46  return group_param_to_string(group_param);
47  }
std::string group_param_to_string(Group_Params group)
Definition: tls_algos.cpp:155

◆ tls_dh_agree()

std::pair< secure_vector< uint8_t >, std::vector< uint8_t > > Botan::TLS::Callbacks::tls_dh_agree ( const std::vector< uint8_t > &  modulus,
const std::vector< uint8_t > &  generator,
const std::vector< uint8_t > &  peer_public_value,
const Policy policy,
RandomNumberGenerator rng 
)
virtual

Optional callback with default impl: client side DH agreement

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

Parameters
modulusthe modulus p of the discrete logarithm group
generatorthe generator of the DH subgroup
peer_public_valuethe public value of the peer
policythe TLS policy associated with the session being established
rnga random number generator
Returns
a pair consisting of the agreed raw secret and our public value

Definition at line 101 of file tls_callbacks.cpp.

References Botan::TLS::Policy::check_peer_key_acceptable(), Botan::BigInt::decode(), Botan::PK_Key_Agreement::derive_key(), Botan::TLS::Alert::INSUFFICIENT_SECURITY, Botan::DH_PublicKey::public_value(), Botan::DH_PrivateKey::public_value(), Botan::CT::strip_leading_zeros(), Botan::DL_Group::verify_group(), and Y.

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

107  {
108  BigInt p = BigInt::decode(modulus);
109  BigInt g = BigInt::decode(generator);
110  BigInt Y = BigInt::decode(peer_public_value);
111 
112  /*
113  * A basic check for key validity. As we do not know q here we
114  * cannot check that Y is in the right subgroup. However since
115  * our key is ephemeral there does not seem to be any
116  * advantage to bogus keys anyway.
117  */
118  if(Y <= 1 || Y >= p - 1)
119  throw TLS_Exception(Alert::INSUFFICIENT_SECURITY,
120  "Server sent bad DH key for DHE exchange");
121 
122  DL_Group group(p, g);
123 
124  if(!group.verify_group(rng, false))
125  throw TLS_Exception(Alert::INSUFFICIENT_SECURITY,
126  "DH group validation failed");
127 
128  DH_PublicKey peer_key(group, Y);
129 
130  policy.check_peer_key_acceptable(peer_key);
131 
132  DH_PrivateKey priv_key(rng, group);
133  PK_Key_Agreement ka(priv_key, rng, "Raw");
134  secure_vector<uint8_t> dh_secret = CT::strip_leading_zeros(
135  ka.derive_key(0, peer_key.public_value()).bits_of());
136 
137  return std::make_pair(dh_secret, priv_key.public_value());
138  }
fe Y
Definition: ge.cpp:28
static BigInt decode(const uint8_t buf[], size_t length)
Definition: bigint.h:713
secure_vector< uint8_t > strip_leading_zeros(const uint8_t in[], size_t length)
Definition: ct_utils.h:191

◆ tls_ecdh_agree()

std::pair< secure_vector< uint8_t >, std::vector< uint8_t > > Botan::TLS::Callbacks::tls_ecdh_agree ( const std::string &  curve_name,
const std::vector< uint8_t > &  peer_public_value,
const Policy policy,
RandomNumberGenerator rng,
bool  compressed 
)
virtual

Optional callback with default impl: client side ECDH agreement

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

Parameters
curve_namethe name of the elliptic curve
peer_public_valuethe public value of the peer
policythe TLS policy associated with the session being established
rnga random number generator
compressedthe compression preference for our public value
Returns
a pair consisting of the agreed raw secret and our public value

Definition at line 140 of file tls_callbacks.cpp.

References Botan::TLS::Policy::check_peer_key_acceptable(), Botan::PointGFp::COMPRESSED, Botan::PK_Key_Agreement::derive_key(), Botan::TLS::Alert::HANDSHAKE_FAILURE, Botan::OIDS::lookup(), Botan::EC_Group::OS2ECP(), Botan::Curve25519_PublicKey::public_value(), Botan::Curve25519_PrivateKey::public_value(), Botan::ECDH_PrivateKey::public_value(), and Botan::PointGFp::UNCOMPRESSED.

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

146  {
147  secure_vector<uint8_t> ecdh_secret;
148  std::vector<uint8_t> our_public_value;
149 
150  if(curve_name == "x25519")
151  {
152 #if defined(BOTAN_HAS_CURVE_25519)
153  if(peer_public_value.size() != 32)
154  {
155  throw TLS_Exception(Alert::HANDSHAKE_FAILURE, "Invalid X25519 key size");
156  }
157 
158  Curve25519_PublicKey peer_key(peer_public_value);
159  policy.check_peer_key_acceptable(peer_key);
160  Curve25519_PrivateKey priv_key(rng);
161  PK_Key_Agreement ka(priv_key, rng, "Raw");
162  ecdh_secret = ka.derive_key(0, peer_key.public_value()).bits_of();
163 
164  // X25519 is always compressed but sent as "uncompressed" in TLS
165  our_public_value = priv_key.public_value();
166 #else
167  throw Internal_Error("Negotiated X25519 somehow, but it is disabled");
168 #endif
169  }
170  else
171  {
172  EC_Group group(OIDS::lookup(curve_name));
173  ECDH_PublicKey peer_key(group, group.OS2ECP(peer_public_value));
174  policy.check_peer_key_acceptable(peer_key);
175  ECDH_PrivateKey priv_key(rng, group);
176  PK_Key_Agreement ka(priv_key, rng, "Raw");
177  ecdh_secret = ka.derive_key(0, peer_key.public_value()).bits_of();
178  our_public_value = priv_key.public_value(compressed ? PointGFp::COMPRESSED : PointGFp::UNCOMPRESSED);
179  }
180 
181  return std::make_pair(ecdh_secret, our_public_value);
182  }
std::string lookup(const OID &oid)
Definition: oids.cpp:113

◆ tls_emit_data()

virtual void Botan::TLS::Callbacks::tls_emit_data ( const uint8_t  data[],
size_t  size 
)
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.

Parameters
datathe vector of data to send
sizethe number of bytes to send

Implemented in Botan::TLS::Compat_Callbacks.

◆ tls_examine_extensions()

void Botan::TLS::Callbacks::tls_examine_extensions ( const Extensions extn,
Connection_Side  which_side 
)
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
extnthe extensions
which_sidewill be CLIENT if these are are the clients extensions (ie we are the server) or SERVER if these are the server extensions (we are the client).

Definition at line 40 of file tls_callbacks.cpp.

41  {
42  }

◆ 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.

Parameters
messagethe handshake message

Reimplemented in Botan::TLS::Compat_Callbacks.

Definition at line 26 of file tls_callbacks.cpp.

Referenced by Botan::TLS::Handshake_State::note_message().

27  {
28  // default is no op
29  }

◆ tls_log_debug()

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

Optional callback: debug logging. (not currently called)

Parameters
whatSome hopefully informative string

Definition at line 310 of file tls_callbacks.h.

References BOTAN_UNUSED.

311  {
312  BOTAN_UNUSED(what);
313  }
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ tls_log_debug_bin()

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

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

Parameters
descrWhat this buffer is
valthe bytes
val_lenlength of val

Definition at line 321 of file tls_callbacks.h.

References BOTAN_UNUSED.

322  {
323  BOTAN_UNUSED(descr, val, val_len);
324  }
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ tls_log_error()

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

Optional callback: error logging. (not currently called)

Parameters
errAn error message related to this connection.

Definition at line 301 of file tls_callbacks.h.

References BOTAN_UNUSED.

302  {
303  BOTAN_UNUSED(err);
304  }
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ tls_modify_extensions()

void Botan::TLS::Callbacks::tls_modify_extensions ( Extensions extn,
Connection_Side  which_side 
)
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 client/server hellos. This allows an application to modify which extensions are sent during the handshake.

Default implementation does nothing.

Parameters
extnthe extensions
which_sidewill be CLIENT or SERVER which is the current applications role in the exchange.

Definition at line 36 of file tls_callbacks.cpp.

Referenced by Botan::TLS::Client_Hello::Client_Hello(), and Botan::TLS::Server_Hello::Server_Hello().

37  {
38  }

◆ tls_record_received()

virtual void Botan::TLS::Callbacks::tls_record_received ( uint64_t  seq_no,
const uint8_t  data[],
size_t  size 
)
pure virtual

Mandatory callback: process application data Called when application data record is received from the peer. Again the array is overwritten immediately after the function returns.

Parameters
seq_nothe underlying TLS/DTLS record sequence number
datathe vector containing the received record
sizethe length of the received record, in bytes

Implemented in Botan::TLS::Compat_Callbacks.

◆ 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, which is not necessarily even on the list that the client sent.

Parameters
client_protosthe vector of protocols the client is willing to negotiate
Returns
the protocol selected by the server, which need not be on the list that the client sent; if this is the empty string, the server ignores the client ALPN extension. Default return value is empty string.

Reimplemented in Botan::TLS::Compat_Callbacks.

Definition at line 31 of file tls_callbacks.cpp.

32  {
33  return "";
34  }

◆ tls_session_activated()

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

Optional callback: session activated Called when a session is active and can be written to

Definition at line 96 of file tls_callbacks.h.

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

96 {}

◆ tls_session_established()

virtual bool Botan::TLS::Callbacks::tls_session_established ( const Session session)
pure virtual

Mandatory callback: session established Called when a session is established. Throw an exception to abort the connection.

Parameters
sessionthe session descriptor
Returns
return false to prevent the session from being cached, return true to cache the session in the configured session manager

Implemented in Botan::TLS::Compat_Callbacks.

Referenced by Botan::TLS::Channel::save_session().

◆ tls_sign_message()

std::vector< uint8_t > Botan::TLS::Callbacks::tls_sign_message ( const Private_Key key,
RandomNumberGenerator rng,
const std::string &  emsa,
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
keythe private key of the signer
rnga random number generator
emsathe encoding method to be applied to the message
formatthe signature format
msgthe input data for the signature
Returns
the signature

Definition at line 77 of file tls_callbacks.cpp.

References Botan::PK_Signer::sign_message().

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

83  {
84  PK_Signer signer(key, rng, emsa, format);
85 
86  return signer.sign_message(msg, rng);
87  }

◆ tls_verify_cert_chain()

void Botan::TLS::Callbacks::tls_verify_cert_chain ( const std::vector< X509_Certificate > &  cert_chain,
const std::vector< std::shared_ptr< const OCSP::Response >> &  ocsp_responses,
const std::vector< Certificate_Store *> &  trusted_roots,
Usage_Type  usage,
const std::string &  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_chainspecifies a certificate chain leading to a trusted root CA certificate.
ocsp_responsesthe server may have provided some
trusted_rootsthe list of trusted certificates
usagewhat 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
hostnamewhen 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.
policythe TLS policy associated with the session being authenticated using the certificate chain

Definition at line 49 of file tls_callbacks.cpp.

References Botan::TLS::Policy::minimum_signature_strength(), Botan::TLS::Policy::require_cert_revocation_info(), Botan::TLS_SERVER_AUTH, and Botan::x509_path_validate().

56  {
57  if(cert_chain.empty())
58  throw Invalid_Argument("Certificate chain was empty");
59 
60  Path_Validation_Restrictions restrictions(policy.require_cert_revocation_info(),
61  policy.minimum_signature_strength());
62 
63  Path_Validation_Result result =
64  x509_path_validate(cert_chain,
65  restrictions,
66  trusted_roots,
67  (usage == Usage_Type::TLS_SERVER_AUTH ? hostname : ""),
68  usage,
69  std::chrono::system_clock::now(),
71  ocsp_responses);
72 
73  if(!result.successful_validation())
74  throw Exception("Certificate validation failure: " + result.result_string());
75  }
virtual std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout() const
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, const std::string &hostname, Usage_Type usage, std::chrono::system_clock::time_point ref_time, std::chrono::milliseconds ocsp_timeout, const std::vector< std::shared_ptr< const OCSP::Response >> &ocsp_resp)
Definition: x509path.cpp:830

◆ 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.

Definition at line 140 of file tls_callbacks.h.

141  {
142  return std::chrono::milliseconds(0);
143  }

◆ tls_verify_message()

bool Botan::TLS::Callbacks::tls_verify_message ( const Public_Key key,
const std::string &  emsa,
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
keythe public key of the signer
emsathe encoding method to be applied to the message
formatthe signature format
msgthe input data for the signature
sigthe signature to be checked
Returns
true if the signature is valid, false otherwise

Definition at line 89 of file tls_callbacks.cpp.

References Botan::PK_Verifier::verify_message().

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

95  {
96  PK_Verifier verifier(key, emsa, format);
97 
98  return verifier.verify_message(msg, sig);
99  }

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