Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | List of all members
Botan::TLS::Compat_Callbacks Class Referencefinal

`#include <tls_callbacks.h>`

Inheritance diagram for Botan::TLS::Compat_Callbacks:

## Public Types
typedef std::function< void(Alert, const uint8_t[], size_t)> | alert_cb
typedef std::function< void(const uint8_t[], size_t)> | data_cb
typedef std::function< bool(const Session &)> | handshake_cb
typedef std::function< void(const Handshake_Message &)> | handshake_msg_cb
typedef std::function< std::string(std::vector< std::string >)> | next_protocol_fn
typedef std::function< void(const uint8_t[], size_t)> | output_fn

## Public Member Functions
| Compat_Callbacks (output_fn output_fn, data_cb app_data_cb, alert_cb alert_cb, handshake_cb hs_cb, handshake_msg_cb hs_msg_cb=nullptr, next_protocol_fn next_proto=nullptr)
| Compat_Callbacks (output_fn output_fn, data_cb app_data_cb, std::function< void(Alert)> alert_cb, handshake_cb hs_cb, handshake_msg_cb hs_msg_cb=nullptr, next_protocol_fn next_proto=nullptr)
void | tls_alert (Alert alert) override
void | tls_emit_data (const uint8_t data[], size_t size) override
void | tls_inspect_handshake_msg (const Handshake_Message &hmsg) override
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)
void | tls_record_received (uint64_t, const uint8_t data[], size_t size) override
std::string | tls_server_choose_app_protocol (const std::vector< std::string > &client_protos) override
virtual void | tls_session_activated ()
bool | tls_session_established (const Session &session) override
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

## Detailed Description

TLS::Callbacks using std::function for compatability with the old API signatures. This type is only provided for backward compatibility. New implementations should derive from TLS::Callbacks instead.

Definition at line 202 of file tls_callbacks.h.

## Member Typedef Documentation

typedef std::function<void (Alert, const uint8_t[], size_t)> Botan::TLS::Compat_Callbacks::alert_cb

Definition at line 207 of file tls_callbacks.h.

typedef std::function<void (const uint8_t[], size_t)> Botan::TLS::Compat_Callbacks::data_cb

Definition at line 206 of file tls_callbacks.h.

typedef std::function<bool (const Session&)> Botan::TLS::Compat_Callbacks::handshake_cb

Definition at line 208 of file tls_callbacks.h.

typedef std::function<void (const Handshake_Message&)> Botan::TLS::Compat_Callbacks::handshake_msg_cb

Definition at line 209 of file tls_callbacks.h.

typedef std::function<std::string (std::vector<std::string>)> Botan::TLS::Compat_Callbacks::next_protocol_fn

Definition at line 210 of file tls_callbacks.h.

typedef std::function<void (const uint8_t[], size_t)> Botan::TLS::Compat_Callbacks::output_fn

Definition at line 205 of file tls_callbacks.h.

## Constructor & Destructor Documentation

Botan::TLS::Compat_Callbacks::Compat_Callbacks | ( | output_fn | output_fn,
|  | data_cb | app_data_cb,
|  | alert_cb | alert_cb,
|  | handshake_cb | hs_cb,
|  | handshake_msg_cb | hs_msg_cb = `nullptr`,
|  | next_protocol_fn | next_proto = `nullptr`
| ) |  |
| inline

Parameters

  output_fn | is called with data for the outbound socket
  app_data_cb | is called when new application data is received
  alert_cb | is called when a TLS alert is received
  hs_cb | is called when a handshake is completed
  hs_msg_cb | is called for each handshake message received
  next_proto | is called with ALPN protocol data sent by the client

Definition at line 226 of file tls_callbacks.h.

229 : m_output_function(output_fn), m_app_data_cb(app_data_cb),
230 m_alert_cb(std::bind(alert_cb, std::placeholders::_1, nullptr, 0)),
231 m_hs_cb(hs_cb), m_hs_msg_cb(hs_msg_cb), m_next_proto(next_proto) {}
Botan::TLS::Compat_Callbacks::alert_cb
std::function< void(Alert, const uint8_t[], size_t)> alert_cb
Definition: tls_callbacks.h:207
Botan::TLS::Compat_Callbacks::output_fn
std::function< void(const uint8_t[], size_t)> output_fn
Definition: tls_callbacks.h:205

Botan::TLS::Compat_Callbacks::Compat_Callbacks | ( | output_fn | output_fn,
|  | data_cb | app_data_cb,
|  | std::function< void(Alert)> | alert_cb,
|  | handshake_cb | hs_cb,
|  | handshake_msg_cb | hs_msg_cb = `nullptr`,
|  | next_protocol_fn | next_proto = `nullptr`
| ) |  |
| inline

Definition at line 234 of file tls_callbacks.h.

239 : m_output_function(output_fn), m_app_data_cb(app_data_cb),
240 m_alert_cb(alert_cb),
241 m_hs_cb(hs_cb), m_hs_msg_cb(hs_msg_cb), m_next_proto(next_proto) {}
Botan::TLS::Compat_Callbacks::alert_cb
std::function< void(Alert, const uint8_t[], size_t)> alert_cb
Definition: tls_callbacks.h:207
Botan::TLS::Compat_Callbacks::output_fn
std::function< void(const uint8_t[], size_t)> output_fn
Definition: tls_callbacks.h:205

## Member Function Documentation

void Botan::TLS::Compat_Callbacks::tls_alert | ( | Alert | alert | ) |
| inline override 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

  alert | the source of the alert

Implements Botan::TLS::Callbacks.

Definition at line 257 of file tls_callbacks.h.

References BOTAN_ASSERT.

258 {
259 BOTAN_ASSERT(m_alert_cb != nullptr,
260 "Invalid TLS alert callback.");
261 m_alert_cb(alert);
262 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27

void Botan::TLS::Compat_Callbacks::tls_emit_data | ( | const uint8_t | data[],
|  | size_t | size
| ) |  |
| inline override 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

  data | the vector of data to send
  size | the number of bytes to send

Implements Botan::TLS::Callbacks.

Definition at line 243 of file tls_callbacks.h.

References BOTAN_ASSERT.

244 {
245 BOTAN_ASSERT(m_output_function != nullptr,
246 "Invalid TLS output function callback.");
247 m_output_function(data, size);
248 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27

void Botan::TLS::Compat_Callbacks::tls_inspect_handshake_msg | ( | const Handshake_Message & | message | ) |
| inline override virtual

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

Parameters

  message | the handshake message

Reimplemented from Botan::TLS::Callbacks.

Definition at line 277 of file tls_callbacks.h.

278 {
279 // The handshake message callback is optional so we can
280 // not assume it has been set.
281 if(m_hs_msg_cb != nullptr) { m_hs_msg_cb(hmsg); }
282 }

virtual void Botan::TLS::Callbacks::tls_log_debug | ( | const char * | what | ) |
| inline virtual inherited

Optional callback: debug logging. (not currently called)

Parameters

  what | Some hopefully informative string

Definition at line 178 of file tls_callbacks.h.

References BOTAN_UNUSED.

179 {
180 BOTAN_UNUSED(what);
181 }
BOTAN_UNUSED
#define BOTAN_UNUSED(v)
Definition: assert.h:92

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

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 189 of file tls_callbacks.h.

References BOTAN_UNUSED.

190 {
191 BOTAN_UNUSED(descr);
192 BOTAN_UNUSED(val);
193 BOTAN_UNUSED(val_len);
194 }
BOTAN_UNUSED
#define BOTAN_UNUSED(v)
Definition: assert.h:92

virtual void Botan::TLS::Callbacks::tls_log_error | ( | const char * | err | ) |
| inline virtual inherited

Optional callback: error logging. (not currently called)

Parameters

  err | An error message related to this connection.

Definition at line 169 of file tls_callbacks.h.

References BOTAN_UNUSED.

170 {
171 BOTAN_UNUSED(err);
172 }
BOTAN_UNUSED
#define BOTAN_UNUSED(v)
Definition: assert.h:92

void Botan::TLS::Compat_Callbacks::tls_record_received | ( | uint64_t | seq_no,
|  | const uint8_t | data[],
|  | size_t | size
| ) |  |
| inline override 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_no | the underlying TLS/DTLS record sequence number
  data | the vector containing the received record
  size | the length of the received record, in bytes

Implements Botan::TLS::Callbacks.

Definition at line 250 of file tls_callbacks.h.

References BOTAN_ASSERT.

251 {
252 BOTAN_ASSERT(m_app_data_cb != nullptr,
253 "Invalid TLS app data callback.");
254 m_app_data_cb(data, size);
255 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27

std::string Botan::TLS::Compat_Callbacks::tls_server_choose_app_protocol | ( | const std::vector< std::string > & | client_protos | ) |
| inline override 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_protos | the 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 from Botan::TLS::Callbacks.

Definition at line 271 of file tls_callbacks.h.

272 {
273 if(m_next_proto != nullptr) { return m_next_proto(client_protos); }
274 return "";
275 }

virtual void Botan::TLS::Callbacks::tls_session_activated | ( |  | ) |
| inline virtual inherited

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

Definition at line 92 of file tls_callbacks.h.

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

92 {}

bool Botan::TLS::Compat_Callbacks::tls_session_established | ( | const Session & | session | ) |
| inline override virtual

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

Parameters

  session | the session descriptor

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

Implements Botan::TLS::Callbacks.

Definition at line 264 of file tls_callbacks.h.

References BOTAN_ASSERT.

265 {
266 BOTAN_ASSERT(m_hs_cb != nullptr,
267 "Invalid TLS handshake callback.");
268 return m_hs_cb(session);
269 }
BOTAN_ASSERT
#define BOTAN_ASSERT(expr, assertion_made)
Definition: assert.h:27

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 inherited

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 26 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().

33 {
34 if(cert_chain.empty())
35 throw Invalid_Argument("Certificate chain was empty");
36
37 Path_Validation_Restrictions restrictions(policy.require_cert_revocation_info(),
38 policy.minimum_signature_strength());
39
40 Path_Validation_Result result =
41 x509_path_validate(cert_chain,
42 restrictions,
43 trusted_roots,
44 (usage == Usage_Type::TLS_SERVER_AUTH ? hostname : ""),
45 usage,
46 std::chrono::system_clock::now(),
47 tls_verify_cert_chain_ocsp_timeout(),
48 ocsp_responses);
49
50 if(!result.successful_validation())
51 throw Exception("Certificate validation failure: " + result.result_string());
52 }
Botan::Usage_Type::TLS_SERVER_AUTH
Botan::x509_path_validate
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:562
Botan::TLS::Callbacks::tls_verify_cert_chain_ocsp_timeout
virtual std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout() const
Definition: tls_callbacks.h:136

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

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 136 of file tls_callbacks.h.

137 {
138 return std::chrono::milliseconds(0);
139 }

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

- src/lib/tls/tls_callbacks.h