Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore Class Reference

Helper class that implements Botan::TLS::Callbacks. More...

#include <asio_stream.h>

Inheritance diagram for Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore:

Public Member Functions
	StreamCore (Stream &stream)
void	tls_alert (Botan::TLS::Alert alert) override
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
void	tls_emit_data (const uint8_t data[], std::size_t size) override
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 std::string	tls_peer_network_identity ()
virtual std::vector< uint8_t >	tls_provide_cert_status (const std::vector< X509_Certificate > &chain, const Certificate_Status_Request &csr)
virtual void	tls_record_received (uint64_t seq_no, const uint8_t data[], size_t size)=0
void	tls_record_received (uint64_t, const uint8_t data[], std::size_t size) override
virtual std::string	tls_server_choose_app_protocol (const std::vector< std::string > &client_protos)
virtual void	tls_session_activated ()
bool	tls_session_established (const Botan::TLS::Session &) override
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)
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) override
std::chrono::milliseconds	tls_verify_cert_chain_ocsp_timeout () const override
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	~StreamCore ()=default

Detailed Description

template<class StreamLayer, class ChannelT = Channel>
class Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore

Helper class that implements Botan::TLS::Callbacks.

This class is provided to the stream's native_handle (Botan::TLS::Channel) and implements the callback functions triggered by the native_handle.

Parameters

receive_buffer	reference to the buffer where decrypted data should be placed
send_buffer	reference to the buffer where encrypted data should be placed

Definition at line 588 of file asio_stream.h.

Constructor & Destructor Documentation

StreamCore()

template<class StreamLayer , class ChannelT = Channel>

Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::StreamCore ( Stream &  stream )

inline

Definition at line 591 of file asio_stream.h.

: m_stream(stream) {}

~StreamCore()

template<class StreamLayer , class ChannelT = Channel>

virtual Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::~StreamCore ( )

virtualdefault

Member Function Documentation

tls_alert()

template<class StreamLayer , class ChannelT = Channel>

void Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::tls_alert ( Botan::TLS::Alert  alert )

inlineoverridevirtual

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 609 of file asio_stream.h.

               {
               if(alert.type() == Botan::TLS::Alert::CLOSE_NOTIFY)
                  {
                  m_stream.set_shutdown_received();
                  // Channel::process_alert will automatically write the corresponding close_notify response to the
                  // send_buffer and close the native_handle after this function returns.
                  }
               }

References Botan::TLS::Alert::CLOSE_NOTIFY, Botan::TLS::Stream< StreamLayer, ChannelT >::set_shutdown_received(), and Botan::TLS::Alert::type().

tls_decode_group_param()

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

virtualinherited

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 48 of file tls_callbacks.cpp.

   {
   return group_param_to_string(group_param);
   }

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

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  )

virtualinherited

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

modulus	the modulus p of the discrete logarithm group
generator	the generator of the DH subgroup
peer_public_value	the public value of the peer
policy	the TLS policy associated with the session being established
rng	a random number generator

Returns

a pair consisting of the agreed raw secret and our public value

Definition at line 108 of file tls_callbacks.cpp.

   {
   BigInt p = BigInt::decode(modulus);
   BigInt g = BigInt::decode(generator);
   BigInt Y = BigInt::decode(peer_public_value);
 
   /*
    * 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 >= p - 1)
      throw TLS_Exception(Alert::ILLEGAL_PARAMETER,
                          "Server sent bad DH key for DHE exchange");
 
   DL_Group group(p, g);
 
   if(!group.verify_group(rng, false))
      throw TLS_Exception(Alert::INSUFFICIENT_SECURITY,
                          "DH group validation failed");
 
   DH_PublicKey peer_key(group, Y);
 
   policy.check_peer_key_acceptable(peer_key);
 
   DH_PrivateKey priv_key(rng, group);
   PK_Key_Agreement ka(priv_key, rng, "Raw");
   secure_vector<uint8_t> dh_secret = CT::strip_leading_zeros(
      ka.derive_key(0, peer_key.public_value()).bits_of());
 
   return std::make_pair(dh_secret, priv_key.public_value());
   }

References Botan::OctetString::bits_of(), Botan::TLS::Policy::check_peer_key_acceptable(), Botan::BigInt::decode(), Botan::PK_Key_Agreement::derive_key(), Botan::TLS::Alert::ILLEGAL_PARAMETER, 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().

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  )

virtualinherited

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_name	the name of the elliptic curve
peer_public_value	the public value of the peer
policy	the TLS policy associated with the session being established
rng	a random number generator
compressed	the compression preference for our public value

Returns

a pair consisting of the agreed raw secret and our public value

Definition at line 147 of file tls_callbacks.cpp.

   {
   secure_vector<uint8_t> ecdh_secret;
   std::vector<uint8_t> our_public_value;
 
   if(curve_name == "x25519")
      {
#if defined(BOTAN_HAS_CURVE_25519)
      if(peer_public_value.size() != 32)
         {
         throw TLS_Exception(Alert::HANDSHAKE_FAILURE, "Invalid X25519 key size");
         }
 
      Curve25519_PublicKey peer_key(peer_public_value);
      policy.check_peer_key_acceptable(peer_key);
      Curve25519_PrivateKey priv_key(rng);
      PK_Key_Agreement ka(priv_key, rng, "Raw");
      ecdh_secret = ka.derive_key(0, peer_key.public_value()).bits_of();
 
      // X25519 is always compressed but sent as "uncompressed" in TLS
      our_public_value = priv_key.public_value();
#else
      throw Internal_Error("Negotiated X25519 somehow, but it is disabled");
#endif
      }
   else
      {
      EC_Group group(OID::from_string(curve_name));
      ECDH_PublicKey peer_key(group, group.OS2ECP(peer_public_value));
      policy.check_peer_key_acceptable(peer_key);
      ECDH_PrivateKey priv_key(rng, group);
      PK_Key_Agreement ka(priv_key, rng, "Raw");
      ecdh_secret = ka.derive_key(0, peer_key.public_value()).bits_of();
      our_public_value = priv_key.public_value(compressed ? PointGFp::COMPRESSED : PointGFp::UNCOMPRESSED);
      }
 
   return std::make_pair(ecdh_secret, our_public_value);
   }

References Botan::OctetString::bits_of(), Botan::TLS::Policy::check_peer_key_acceptable(), Botan::PointGFp::COMPRESSED, Botan::PK_Key_Agreement::derive_key(), Botan::OID::from_string(), Botan::TLS::Alert::HANDSHAKE_FAILURE, Botan::EC_Group::OS2ECP(), Botan::Curve25519_PublicKey::public_value(), Botan::ECDH_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().

tls_emit_data() [1/2]

virtual void Botan::TLS::Callbacks::tls_emit_data ( const uint8_t  data[], size_t  size  )

pure virtualinherited

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

Implemented in Botan::TLS::Compat_Callbacks.

tls_emit_data() [2/2]

template<class StreamLayer , class ChannelT = Channel>

void Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::tls_emit_data ( const uint8_t  data[], std::size_t  size  )

inlineoverride

Definition at line 595 of file asio_stream.h.

               {
               m_stream.m_send_buffer.commit(
                  boost::asio::buffer_copy(m_stream.m_send_buffer.prepare(size), boost::asio::buffer(data, size))
               );
               }

References Botan::TLS::Stream< StreamLayer, ChannelT >::m_send_buffer.

tls_examine_extensions()

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

virtualinherited

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 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 44 of file tls_callbacks.cpp.

   {
   }

tls_inspect_handshake_msg()

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

virtualinherited

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

Parameters

message

the handshake message

Reimplemented in Botan::TLS::Compat_Callbacks.

Definition at line 25 of file tls_callbacks.cpp.

   {
   // default is no op
   }

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

tls_log_debug()

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

inlinevirtualinherited

Optional callback: debug logging. (not currently called)

Parameters

what	Some hopefully informative string

Definition at line 344 of file tls_callbacks.h.

          {
          BOTAN_UNUSED(what);
          }

References BOTAN_UNUSED.

tls_log_debug_bin()

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

inlinevirtualinherited

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

          {
          BOTAN_UNUSED(descr, val, val_len);
          }

References BOTAN_UNUSED.

tls_log_error()

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

inlinevirtualinherited

Optional callback: error logging. (not currently called)

Parameters

err	An error message related to this connection.

Definition at line 335 of file tls_callbacks.h.

          {
          BOTAN_UNUSED(err);
          }

References BOTAN_UNUSED.

tls_modify_extensions()

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

virtualinherited

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

extn	the extensions
which_side	will be CLIENT or SERVER which is the current applications role in the exchange.

Definition at line 40 of file tls_callbacks.cpp.

   {
   }

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

tls_peer_network_identity()

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

virtualinherited

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 35 of file tls_callbacks.cpp.

   {
   return "";
   }

tls_provide_cert_status()

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

inlinevirtualinherited

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.

Definition at line 159 of file tls_callbacks.h.

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

References BOTAN_UNUSED.

tls_record_received() [1/2]

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

pure virtualinherited

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

Implemented in Botan::TLS::Compat_Callbacks.

tls_record_received() [2/2]

template<class StreamLayer , class ChannelT = Channel>

void Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::tls_record_received ( uint64_t  , const uint8_t  data[], std::size_t  size  )

inlineoverride

Definition at line 602 of file asio_stream.h.

               {
               m_stream.m_receive_buffer.commit(
                  boost::asio::buffer_copy(m_stream.m_receive_buffer.prepare(size), boost::asio::const_buffer(data, size))
               );
               }

References Botan::TLS::Stream< StreamLayer, ChannelT >::m_receive_buffer.

tls_server_choose_app_protocol()

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

virtualinherited

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 in Botan::TLS::Compat_Callbacks.

Definition at line 30 of file tls_callbacks.cpp.

   {
   return "";
   }

tls_session_activated()

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

inlinevirtualinherited

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

Definition at line 97 of file tls_callbacks.h.

{}

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

tls_session_established()

template<class StreamLayer , class ChannelT = Channel>

bool Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::tls_session_established ( const Botan::TLS::Session &  session )

inlineoverridevirtual

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 624 of file asio_stream.h.

               {
               // TODO: it should be possible to configure this in the using application (via callback?)
               return true;
               }

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  )

virtualinherited

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
emsa	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 84 of file tls_callbacks.cpp.

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

References Botan::PK_Signer::sign_message().

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

tls_verify_cert_chain()

template<class StreamLayer , class ChannelT = Channel>

void Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::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  )

inlineoverridevirtual

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

Reimplemented from Botan::TLS::Callbacks.

Definition at line 630 of file asio_stream.h.

               {
               if(m_stream.m_context.has_verify_callback())
                  {
                  m_stream.m_context.get_verify_callback()(cert_chain, ocsp_responses, trusted_roots, usage, hostname, policy);
                  }
               else
                  {
                  Callbacks::tls_verify_cert_chain(cert_chain, ocsp_responses, trusted_roots, usage, hostname, policy);
                  }
               }

References Botan::TLS::Context::get_verify_callback(), Botan::TLS::Context::has_verify_callback(), Botan::TLS::Stream< StreamLayer, ChannelT >::m_context, and Botan::TLS::Callbacks::tls_verify_cert_chain().

tls_verify_cert_chain_ocsp_timeout()

template<class StreamLayer , class ChannelT = Channel>

std::chrono::milliseconds Botan::TLS::Stream< StreamLayer, ChannelT >::StreamCore::tls_verify_cert_chain_ocsp_timeout ( ) const

inlineoverridevirtual

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.

Reimplemented from Botan::TLS::Callbacks.

Definition at line 619 of file asio_stream.h.

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

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  )

virtualinherited

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
emsa	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 96 of file tls_callbacks.cpp.

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

References Botan::PK_Verifier::verify_message().

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

---

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

• src/lib/tls/asio/asio_stream.h