Transport Layer Security (TLS)

Botan has client and server implementations of TLS 1.2 and 1.3. Support for older versions of the protocol was removed with Botan 3.0.

There is also support for DTLS (currently v1.2 only), a variant of TLS adapted for operation on datagram transports such as UDP and SCTP. DTLS support should be considered as beta quality and further testing is invited.

The TLS implementation does not know anything about sockets or the network layer. Instead, it calls a user provided callback (hereafter output_fn) whenever it has data that it would want to send to the other party (for instance, by writing it to a network socket), and whenever the application receives some data from the counterparty (for instance, by reading from a network socket) it passes that information to TLS using TLS::Channel::received_data. If the data passed in results in some change in the state, such as a handshake completing, or some data or an alert being received from the other side, then the appropriate user provided callback will be invoked.

If the reader is familiar with OpenSSL’s BIO layer, it might be analogous to saying the only way of interacting with Botan’s TLS is via a BIO_mem I/O abstraction. This makes the library completely agnostic to how you write your network layer, be it blocking sockets, libevent, asio, a message queue, lwIP on RTOS, some carrier pigeons, etc.

Note that we support an optional Boost ASIO stream that is a convenient way to use Botan’s TLS implementation as an almost drop-in replacement of ASIO’s ssl::stream. Applications that build their network layer on Boost ASIO are advised to use this wrapper of TLS::Client and TLS::Server.

Application callbacks are encapsulated as the class TLS::Callbacks with the following members. The first three (tls_emit_data, tls_record_received, tls_alert) are mandatory for using TLS, all others are optional and provide additional information about the connection.

void tls_emit_data(std::span<const uint8_t> data)

Mandatory. The TLS stack requests that all bytes of data be queued up to send to the counterparty. After this function returns, the buffer containing data will be overwritten, so a copy of the input must be made if the callback cannot send the data immediately.

As an example you could 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.

void tls_record_received(uint64_t rec_no, std::span<const uint8_t> data)

Mandatory. Called once for each application_data record which is received, with the matching (TLS level) record sequence number.

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

As with tls_emit_data, the array will be overwritten sometime after the callback returns, so a copy should be made if needed.

For TLS the record number will always increase.

For DTLS, it is possible to receive records with the rec_no field out of order, or with gaps, corresponding to reordered or lost datagrams.

void tls_alert(Alert alert)

Mandatory. Called when an alert is received from the peer. Note that alerts received before the handshake is complete are not authenticated and could have been inserted by a MITM attacker.

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

Optional - default implementation is a no-op 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.

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, std::string_view hostname, const Policy &policy)

Optional - default implementation should work for many users. It can be overridden for implementing extra validation routines such as public key pinning.

Verifies the certificate chain in cert_chain, assuming the leaf certificate is the first element. Throws an exception if any error makes this certificate chain unacceptable.

If usage is Usage_Type::TLS_SERVER_AUTH, then hostname should match the information in the server certificate. If usage is TLS_CLIENT_AUTH, then hostname specifies the host the client is authenticating against (from SNI); the callback can use this for any special site specific auth logic.

The ocsp_responses is a possibly empty list of OCSP responses provided by the server. In the current implementation of TLS OCSP stapling, only a single OCSP response can be returned. A existing TLS extension allows the server to send multiple OCSP responses, this extension may be supported in the future in which case more than one OCSP response may be given during this callback.

The trusted_roots parameter was returned by a call from the associated Credentials_Manager.

The policy provided is the policy for the TLS session which is being authenticated using this certificate chain. It can be consulted for values such as allowable signature methods and key sizes.

std::chrono::milliseconds tls_verify_cert_chain_ocsp_timeout() const

Called by default tls_verify_cert_chain to set timeout for online OCSP requests on the certificate chain. Return 0 to disable OCSP. Current default is 0.

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

Optional. Called by the server when a client includes a list of protocols in the ALPN extension. The server then choose which protocol to use, or “” to disable sending any ALPN response. The default implementation returns the empty string all of the time, effectively disabling ALPN responses. The server may also throw an exception to reject the connection; this is recommended when the client sends a list of protocols and the server does not understand any of them.

Warning

The ALPN RFC requires that if the server does not understand any of the protocols offered by the client, it should close the connection using an alert. Carrying on the connection (for example by ignoring ALPN when the server does not understand the protocol list) can expose applications to cross-protocol attacks.

void tls_session_activated()

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

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

Optional. This can return a cached OCSP response. This is only used on the server side, and only if the client requests OCSP stapling.

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

Optional. This may be called by TLS 1.3 clients or servers when OCSP stapling was negotiated. In contrast to tls_provide_cert_status, this allows providing OCSP responses for each certificate in the chain.

Note that the returned list of encoded OCSP responses must be of the same length as the input list of certificates in the chain. By default, this will call tls_provide_cert_status to obtain an OCSP response for the end-entity only.

std::string tls_peer_network_identity()

Optional. Return a string that identifies the peer in some unique way (for example, by formatting the remote IP and port into a string). This is currently used to bind DTLS cookies to the network identity.

void tls_inspect_handshake_msg(const Handshake_Message&)

This callback is optional, and can be used to inspect all handshake messages while the session establishment occurs.

void tls_modify_extensions(Extensions &extn, Connection_Side which_side)

This callback is optional, and can be used to modify extensions before they are sent to the peer. For example this enables adding a custom extension, or replacing or removing an extension set by the library.

void tls_examine_extensions(const Extensions &extn, Connection_Side which_side)

This callback is optional, and can be used to examine extensions sent by the peer.

void tls_log_error(const char *msg)

Optional logging for an error message. (Not currently used)

void tls_log_debug(const char *msg)

Optional logging for an debug message. (Not currently used)

void tls_log_debug_bin(const char *descr, const uint8_t val[], size_t len)

Optional logging for an debug value. (Not currently used)

TLS Channels

TLS servers and clients share an interface called TLS::Channel. A TLS channel (either client or server object) has these methods available:

class TLS::Channel

size_t received_data(const uint8_t buf[], size_t buf_size)

size_t received_data(std::span<const uint8_t> buf)

This function is used to provide data sent by the counterparty (eg data that you read off the socket layer). Depending on the current protocol state and the amount of data provided this may result in one or more callback functions that were provided to the constructor being called.

The return value of received_data specifies how many more bytes of input are needed to make any progress, unless the end of the data fell exactly on a message boundary, in which case it will return 0 instead.

void send(const uint8_t buf[], size_t buf_size)

void send(std::string_view str)

void send(std::span<const uint8_t> vec)

Create one or more new TLS application records containing the provided data and send them. This will eventually result in at least one call to the output_fn callback before send returns.

If the current TLS connection state is unable to transmit new application records (for example because a handshake has not yet completed or the connection has already ended due to an error) an exception will be thrown.

void close()

A close notification is sent to the counterparty, and the internal state is cleared.

void send_alert(const Alert &alert)

Some other alert is sent to the counterparty. If the alert is fatal, the internal state is cleared.

bool is_active()

Returns true if and only if a handshake has been completed on this connection and the connection has not been subsequently closed.

bool is_closed()

Returns true if and only if either a close notification or a fatal alert message have been either sent or received.

bool is_closed_for_reading()

TLS 1.3 supports half-open connections. If the peer notified a connection closure, this will return true. For TLS 1.2 this will always return the same is_closed.

bool is_closed_for_writing()

TLS 1.3 supports half-open connections. After calling close on the channel, this will return true. For TLS 1.2 this will always return the same is_closed.

bool timeout_check()

This function does nothing unless the channel represents a DTLS connection and a handshake is actively in progress. In this case it will check the current timeout state and potentially initiate retransmission of handshake packets. Returns true if a timeout condition occurred.

void renegotiate(bool force_full_renegotiation = false)

Initiates a renegotiation. The counterparty is allowed by the protocol to ignore this request. If a successful renegotiation occurs, the handshake_cb callback will be called again.

Note that TLS 1.3 does not support renegotiation. This method will throw when called on a channel that uses TLS 1.3.

If force_full_renegotiation is false, then the client will attempt to simply renew the current session - this will refresh the symmetric keys but will not change the session master secret. Otherwise it will initiate a completely new session.

For a server, if force_full_renegotiation is false, then a session resumption will be allowed if the client attempts it. Otherwise the server will prevent resumption and force the creation of a new session.

void update_traffic_keys(bool request_peer_update = false)

After a successful handshake, this will update our traffic keys and may send a request to do the same to the peer.

Note that this is a TLS 1.3 feature and invocations on a channel using TLS 1.2 will throw.

std::vector<X509_Certificate> peer_cert_chain()

Returns the certificate chain of the counterparty. When acting as a client, this value will be non-empty. Acting as a server, this value will ordinarily be empty, unless the server requested a certificate and the client responded with one.

std::optional<std::string> external_psk_identity() const

When this connection was established using a user-defined Preshared Key this will return the identity of the PSK used. If no PSK was used in the establishment of the connection this will return std::nullopt.

Note that TLS 1.3 session resumption is based on PSKs internally. Neverthelees, connections that were established using a session resumption will return std::nullopt here.

SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length)

Returns an exported key of length bytes derived from label, context, and the session’s master secret and client and server random values. This key will be unique to this connection, and as long as the session master secret remains secure an attacker should not be able to guess the key.

Per RFC 5705, label should begin with “EXPERIMENTAL” unless the label has been standardized in an RFC.

TLS Clients

class TLS::Client

Client(const std::shared_ptr<Callbacks> &callbacks, const std::shared_ptr<Session_Manager> &session_manager, const std::shared_ptr<Credentials_Manager> &creds, const std::shared_ptr<const Policy> &policy, const std::shared_ptr<RandomNumberGenerator> &rng, Server_Information server_info = Server_Information(), Protocol_Version offer_version = Protocol_Version::latest_tls_version(), const std::vector<std::string> &next_protocols = std::vector<std::string>(), size_t reserved_io_buffer_size = 16 * 1024)

Initialize a new TLS client. The constructor will immediately initiate a new session.

The callbacks parameter specifies the various application callbacks which pertain to this particular client connection.

The session_manager is an interface for storing TLS sessions, which allows for session resumption upon reconnecting to a server. In the absence of a need for persistent sessions, use TLS::Session_Manager_In_Memory which caches connections for the lifetime of a single process. See TLS Session Managers for more about session managers.

The credentials_manager is an interface that will be called to retrieve any certificates, private keys, or pre-shared keys; see Credentials Manager for more information.

Use the optional server_info to specify the DNS name of the server you are attempting to connect to, if you know it. This helps the server select what certificate to use and helps the client validate the connection.

Note that the server name indicator name must be a FQDN. IP addresses are not allowed by RFC 6066 and may lead to interoperability problems.

Use the optional offer_version to control the version of TLS you wish the client to offer. Normally, you’ll want to offer the most recent version of (D)TLS that is available, however some broken servers are intolerant of certain versions being offered, and for classes of applications that have to deal with such servers (typically web browsers) it may be necessary to implement a version backdown strategy if the initial attempt fails.

Warning

Implementing such a backdown strategy allows an attacker to downgrade your connection to the weakest protocol that both you and the server support.

Setting offer_version is also used to offer DTLS instead of TLS; use TLS::Protocol_Version::latest_dtls_version.

Optionally, the client will advertise app_protocols to the server using the ALPN extension.

The optional reserved_io_buffer_size specifies how many bytes to pre-allocate in the I/O buffers. Use this if you want to control how much memory the channel uses initially (the buffers will be resized as needed to process inputs). Otherwise some reasonable default is used.

Code Example: TLS Client

A minimal example of a TLS client is provided below. The full code for a TLS client using BSD sockets is in src/cli/tls_client.cpp

#include <botan/auto_rng.h>
#include <botan/certstor.h>
#include <botan/certstor_system.h>
#include <botan/tls.h>

/**
 * @brief Callbacks invoked by TLS::Channel.
 *
 * Botan::TLS::Callbacks is an abstract class.
 * For improved readability, only the functions that are mandatory
 * to implement are listed here. See src/lib/tls/tls_callbacks.h.
 */
class Callbacks : public Botan::TLS::Callbacks {
   public:
      void tls_emit_data(std::span<const uint8_t> data) override {
         // send data to tls server, e.g., using BSD sockets or boost asio
         BOTAN_UNUSED(data);
      }

      void tls_record_received(uint64_t seq_no, std::span<const uint8_t> data) override {
         // process full TLS record received by tls server, e.g.,
         // by passing it to the application
         BOTAN_UNUSED(seq_no, data);
      }

      void tls_alert(Botan::TLS::Alert alert) override {
         // handle a tls alert received from the tls server
         BOTAN_UNUSED(alert);
      }
};

/**
 * @brief Credentials storage for the tls client.
 *
 * It returns a list of trusted CA certificates.
 * Here we base trust on the system managed trusted CA list.
 * TLS client authentication is disabled. See src/lib/tls/credentials_manager.h.
 */
class Client_Credentials : public Botan::Credentials_Manager {
   public:
      std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(const std::string& type,
                                                                             const std::string& context) override {
         BOTAN_UNUSED(type, context);
         // return a list of certificates of CAs we trust for tls server certificates
         // ownership of the pointers remains with Credentials_Manager
         return {&m_cert_store};
      }

      std::vector<Botan::X509_Certificate> cert_chain(
         const std::vector<std::string>& cert_key_types,
         const std::vector<Botan::AlgorithmIdentifier>& cert_signature_schemes,
         const std::string& type,
         const std::string& context) override {
         BOTAN_UNUSED(cert_key_types, cert_signature_schemes, type, context);

         // when using tls client authentication (optional), return
         // a certificate chain being sent to the tls server,
         // else an empty list
         return {};
      }

      std::shared_ptr<Botan::Private_Key> private_key_for(const Botan::X509_Certificate& cert,
                                                          const std::string& type,
                                                          const std::string& context) override {
         BOTAN_UNUSED(cert, type, context);
         // when returning a chain in cert_chain(), return the private key
         // associated with the leaf certificate here
         return nullptr;
      }

   private:
      Botan::System_Certificate_Store m_cert_store;
};

int main() {
   // prepare all the parameters
   auto callbacks = std::make_shared<Callbacks>();
   auto rng = std::make_shared<Botan::AutoSeeded_RNG>();
   auto session_mgr = std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng);
   auto creds = std::make_shared<Client_Credentials>();
   auto policy = std::make_shared<Botan::TLS::Strict_Policy>();

   // open the tls connection
   Botan::TLS::Client client(callbacks,
                             session_mgr,
                             creds,
                             policy,
                             rng,
                             Botan::TLS::Server_Information("botan.randombit.net", 443),
                             Botan::TLS::Protocol_Version::TLS_V12);

   while(!client.is_closed()) {
      // read data received from the tls server, e.g., using BSD sockets or boost asio
      // ...

      // send data to the tls server using client.send()
   }

   return 0;
}

TLS Servers

class TLS::Server

Server(const std::shared_ptr<Callbacks> &callbacks, const std::shared_ptr<Session_Manager> &session_manager, const std::shared_ptr<Credentials_Manager> &creds, const std::shared_ptr<const Policy> &policy, const std::shared_ptr<RandomNumberGenerator> &rng, bool is_datagram = false, size_t reserved_io_buffer_size = 16 * 1024)

The first 5 arguments as well as the final argument reserved_io_buffer_size, are treated similarly to the client.

If a client sends the ALPN extension, the callbacks function tls_server_choose_app_protocol will be called and the result sent back to the client. If the empty string is returned, the server will not send an ALPN response. The function can also throw an exception to abort the handshake entirely, the ALPN specification says that if this occurs the alert should be of type NO_APPLICATION_PROTOCOL.

The optional argument is_datagram specifies if this is a TLS or DTLS server; unlike clients, which know what type of protocol (TLS vs DTLS) they are negotiating from the start via the offer_version, servers would not until they actually received a client hello.

Code Example: TLS Server

A minimal example of a TLS server is provided below. The full code for a TLS server using asio is in src/cli/tls_proxy.cpp.

#include <botan/auto_rng.h>
#include <botan/certstor.h>
#include <botan/pk_keys.h>
#include <botan/pkcs8.h>
#include <botan/tls.h>

#include <memory>

/**
 * @brief Callbacks invoked by TLS::Channel.
 *
 * Botan::TLS::Callbacks is an abstract class.
 * For improved readability, only the functions that are mandatory
 * to implement are listed here. See src/lib/tls/tls_callbacks.h.
 */
class Callbacks : public Botan::TLS::Callbacks {
   public:
      void tls_emit_data(std::span<const uint8_t> data) override {
         // send data to tls client, e.g., using BSD sockets or boost asio
         BOTAN_UNUSED(data);
      }

      void tls_record_received(uint64_t seq_no, std::span<const uint8_t> data) override {
         // process full TLS record received by tls client, e.g.,
         // by passing it to the application
         BOTAN_UNUSED(seq_no, data);
      }

      void tls_alert(Botan::TLS::Alert alert) override {
         // handle a tls alert received from the tls server
         BOTAN_UNUSED(alert);
      }
};

/**
 * @brief Credentials storage for the tls server.
 *
 * It returns a certificate and the associated private key to
 * authenticate the tls server to the client.
 * TLS client authentication is not requested.
 * See src/lib/tls/credentials_manager.h.
 */
class Server_Credentials : public Botan::Credentials_Manager {
   public:
      Server_Credentials() {
         Botan::DataSource_Stream in("botan.randombit.net.key");
         m_key.reset(Botan::PKCS8::load_key(in).release());
      }

      std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(const std::string& type,
                                                                             const std::string& context) override {
         BOTAN_UNUSED(type, context);
         // if client authentication is required, this function
         // shall return a list of certificates of CAs we trust
         // for tls client certificates, otherwise return an empty list
         return {};
      }

      std::vector<Botan::X509_Certificate> cert_chain(
         const std::vector<std::string>& cert_key_types,
         const std::vector<Botan::AlgorithmIdentifier>& cert_signature_schemes,
         const std::string& type,
         const std::string& context) override {
         BOTAN_UNUSED(cert_key_types, cert_signature_schemes, type, context);

         // return the certificate chain being sent to the tls client
         // e.g., the certificate file "botan.randombit.net.crt"
         return {Botan::X509_Certificate("botan.randombit.net.crt")};
      }

      std::shared_ptr<Botan::Private_Key> private_key_for(const Botan::X509_Certificate& cert,
                                                          const std::string& type,
                                                          const std::string& context) override {
         BOTAN_UNUSED(cert, type, context);
         // return the private key associated with the leaf certificate,
         // in this case the one associated with "botan.randombit.net.crt"
         return m_key;
      }

   private:
      std::shared_ptr<Botan::Private_Key> m_key;
};

int main() {
   // prepare all the parameters
   auto callbacks = std::make_shared<Callbacks>();
   auto rng = std::make_shared<Botan::AutoSeeded_RNG>();
   auto session_mgr = std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng);
   auto creds = std::make_shared<Server_Credentials>();
   auto policy = std::make_shared<Botan::TLS::Strict_Policy>();

   // accept tls connection from client
   Botan::TLS::Server server(callbacks, session_mgr, creds, policy, rng);

   // read data received from the tls client, e.g., using BSD sockets or boost asio
   // and pass it to server.received_data().
   // ...

   // send data to the tls client using server.send()
   // ...

   return 0;
}

TLS Sessions

TLS allows clients and servers to support session resumption, where the end point retains some information about an established session and then reuse that information to bootstrap a new session in way that is much cheaper computationally than a full handshake.

Every time the handshake callback (TLS::Callbacks::tls_session_established) is called, a new session has been established, and a TLS::Session_Summary is included that provides information about that session:

class TLS::Session_Summary

Protocol_Version version() const

Returns the protocol version that was negotiated

Ciphersuite ciphersite() const

Returns the ciphersuite that was negotiated.

Server_Information server_info() const

Returns information that identifies the server side of the connection. This is useful for the client in that it identifies what was originally passed to the constructor. For the server, it includes the name the client specified in the server name indicator extension.

bool was_resumption() const

Returns true if the session resulted from a resumption of a previously established session.

std::vector<X509_Certificate> peer_certs() const

Returns the certificate chain of the peer

std::optional<std::string> external_psk_identity() const

If the session was established using a user-provided Preshared Key, its identity will be provided here. If no PSK was used, std::nullopt will be reported.

bool psk_used() const

Returns true if the session was established using a user-provided Preshared Key.

TLS Session Managers

You may want sessions stored in a specific format or storage type. To do so, implement the TLS::Session_Manager interface and pass your implementation to the TLS::Client or TLS::Server constructor.

Note

The serialization format of Session is not considered stable and is allowed to change even across minor releases. In the event of such a change, old sessions will no longer be able to be resumed.

The interface of the TLS::Session_Manager was completely redesigned with Botan 3.0 to accommodate the new requirements of TLS 1.3. Please also see the migration guide for an outline of the differences between the Botan 2.x and 3.x API.

In Botan 3.0 the server-side TLS::Session_Manager gained the competency to decide whether to store sessions in a stateful database and just return a handle to it. Or to serialize the session into an encrypted ticket and pass it back to the client. To distinguish those use cases, Botan 3.0 introduced a TLS::Session_Handle class that is used throughout this API.

Below is a brief overview of the most important methods that a custom implementation must implement. There are more methods that provide applications with full flexibility to handle session objects. More detail can be found in the API documentation inline.

class TLS::Session_Mananger

void store(const Session &session, const Session_Handle &handle)

Attempts to save a new session. Typical implementations will use TLS::Session::encrypt, TLS::Session::DER_encode or TLS::Session::PEM_encode to obtain an opaque and serialized session object for storage. It is legal to simply drop an incoming session for whatever reason.

size_t remove(const Session_Handle &handle)

Remove the session identified by handle. Future attempts at resumption should fail for this session. Returns the number of sessions actually removed.

size_t remove_all()

Empties the session storage. Returns the number of sessions actually removed.

std::optional<Session> retrieve_one(const Session_Handle &handle)

Attempts to retrieve a single session that corresponds to handle from storage. Typical implementations will use TLS::Session::decrypt or the TLS::Session constructors that deserialize a session from DER or PEM. If no session was found for the given handle, return std::nullopt. This method is called in TLS servers to find a specific session for a given handle.

std::vector<Session_with_Handle> find_some(const Server_Information &info, size_t max_sessions_hint)

Try to find some saved sessions using information about the server. TLS 1.3 clients may offer more than one session for resumption to the server. It is okay to ignore the max_sessions_hint and just return exactly one or no sessions at all.

recursive_mutex_type &mutex()

Derived implementations may use this mutex to serialize concurrent requests.

In Memory Session Manager

The TLS::Session_Manager_In_Memory implementation saves sessions in memory, with an upper bound on the maximum number of sessions and the lifetime of a session.

It is safe to share a single object across many threads as it uses a lock internally.

class TLS::Session_Managers_In_Memory

Session_Manager_In_Memory(RandomNumberGenerator &rng, size_t max_sessions = 1000)

Limits the maximum number of saved sessions to max_sessions.

Noop Session Mananger

The TLS::Session_Manager_Noop implementation does not save sessions at all, and thus session resumption always fails. Its constructor has no arguments.

SQLite3 Session Manager

This session manager is only available if support for SQLite3 was enabled at build time. If the macro BOTAN_HAS_TLS_SQLITE3_SESSION_MANAGER is defined, then botan/tls_session_manager_sqlite.h contains TLS::Session_Manager_SQLite which stores sessions persistently to a sqlite3 database. The session data is encrypted using a passphrase, and stored in two tables, named tls_sessions (which holds the actual session information) and tls_sessions_metadata (which holds the PBKDF information).

Warning

The hostnames associated with the saved sessions are stored in the database in plaintext. This may be a serious privacy risk in some applications.

class TLS::Session_Manager_SQLite

Session_Manager_SQLite(std::string_view passphrase, const std::shared_ptr<RandomNumberGenerator> &rng, std::string_view db_filename, size_t max_sessions = 1000)

Uses the sqlite3 database named by db_filename.

Stateless Session Manager

This session manager is useful for servers that want to implement stateless session resumption. If supported by the client, sessions are always encoded as opaque and encrypted session tickets. Sessions are encrypted with a symmetric secret obtained via TLS::Credentials_Manager::session_ticket_key().

Session_Manager_Stateless(const std::shared_ptr<Credentials_Manager> &credentials_manager, const std::shared_ptr<RandomNumberGenerator> &rng)

Creates a stateless session manager.

Hybrid Session Manager

This is a meta-manager that combines a TLS::Session_Manager_Stateless with any (built-in or user-provided) stateful session manager. Typically, such a hybrid manager is useful for TLS servers that want to support both stateless session tickets and stateful session storage.

Session_Manager_Hybrid(std::unique_ptr<Session_Manager> stateful_manager, const std::shared_ptr<Credentials_Manager> &credentials_manager, const std::shared_ptr<RandomNumberGenerator> &rng, bool prefer_tickets = true)

Creates a hybrid session manager that uses stateful_manager as its storage backend when session tickets are not supported or desired.

TLS Policies

TLS::Policy is how an application can control details of what will be negotiated during a handshake. The base class acts as the default policy. There is also a Strict_Policy (which forces only secure options, reducing compatibility) and Text_Policy which reads policy settings from a file.

class TLS::Policy

std::vector<std::string> allowed_ciphers() const

Returns the list of ciphers we are willing to negotiate, in order of preference.

Clients send a list of ciphersuites in order of preference, servers are free to choose any of them. Some servers will use the clients preferences, others choose from the clients list prioritizing based on its preferences.

No export key exchange mechanisms or ciphersuites are supported by botan. The null encryption ciphersuites (which provide only authentication, sending data in cleartext) are also not supported by the implementation and cannot be negotiated.

Cipher names without an explicit mode refers to CBC+HMAC ciphersuites.

Default value: “ChaCha20Poly1305”, “AES-256/GCM”, “AES-128/GCM”

Also allowed: “AES-256”, “AES-128”, “AES-256/CCM”, “AES-128/CCM”, “AES-256/CCM(8)”, “AES-128/CCM(8)”, “Camellia-256/GCM”, “Camellia-128/GCM”, “ARIA-256/GCM”, “ARIA-128/GCM”

Also allowed (though currently experimental): “AES-128/OCB(12)”, “AES-256/OCB(12)”

In versions up to 2.8.0, the CBC and CCM ciphersuites “AES-256”, “AES-128”, “AES-256/CCM” and “AES-128/CCM” were enabled by default.

Also allowed (although not recommended): “3DES”

Note

Before 1.11.30 only the non-standard ChaCha20Poly1305 ciphersuite was implemented. The RFC 7905 ciphersuites are supported in 1.11.30 onwards.

Note

Support for the broken RC4 cipher was removed in 1.11.17

Note

All CBC ciphersuites are deprecated and will be removed in a future release.

std::vector<std::string> allowed_macs() const

Returns the list of algorithms we are willing to use for message authentication, in order of preference.

Default: “AEAD”, “SHA-256”, “SHA-384”, “SHA-1”

A plain hash function indicates HMAC

Note

SHA-256 is preferred over SHA-384 in CBC mode because the protections against the Lucky13 attack are somewhat more effective for SHA-256 than SHA-384.

std::vector<std::string> allowed_key_exchange_methods() const

Returns the list of key exchange methods we are willing to use, in order of preference.

Default: “ECDH”, “DH”

Also allowed: “RSA”, “ECDHE_PSK”, “PSK”

Note

Static RSA ciphersuites are disabled by default since 1.11.34. In addition to not providing forward security, any server which is willing to negotiate these ciphersuites exposes themselves to a variety of chosen ciphertext oracle attacks which are all easily avoided by signing (as in PFS) instead of decrypting.

Note

In order to enable RSA or PSK ciphersuites one must also enable authentication method “IMPLICIT”, see allowed_signature_methods.

std::vector<std::string> allowed_signature_hashes() const

Returns the list of hash algorithms we are willing to use for public key signatures, in order of preference.

Default: “SHA-512”, “SHA-384”, “SHA-256”

Also allowed (although not recommended): “SHA-1”

Note

This is only used with TLS v1.2. In earlier versions of the protocol, signatures are fixed to using only SHA-1 (for DSA/ECDSA) or a MD5/SHA-1 pair (for RSA).

std::vector<std::string> allowed_signature_methods() const

Default: “ECDSA”, “RSA”

Also allowed (disabled by default): “IMPLICIT”

“IMPLICIT” enables ciphersuites which are authenticated not by a signature but through a side-effect of the key exchange. In particular this setting is required to enable PSK and static RSA ciphersuites.

std::vector<Group_Params> key_exchange_groups() const

Return a list of ECC curve and DH group TLS identifiers we are willing to use, in order of preference. The default ordering puts the best performing ECC first.

Default: Group_Params::X25519, Group_Params::SECP256R1, Group_Params::BRAINPOOL256R1, Group_Params::SECP384R1, Group_Params::BRAINPOOL384R1, Group_Params::SECP521R1, Group_Params::BRAINPOOL512R1, Group_Params::FFDHE_2048, Group_Params::FFDHE_3072, Group_Params::FFDHE_4096, Group_Params::FFDHE_6144, Group_Params::FFDHE_8192

No other values are currently defined.

std::vector<Group_Param> key_exchange_groups_to_offer() const

Return a list of groups to opportunistically offer key exchange information for in the initial ClientHello when offering TLS 1.3. This policy has no effect on TLS 1.2 connections.

bool use_ecc_point_compression() const

Prefer ECC point compression.

Signals that we prefer ECC points to be compressed when transmitted to us. The other party may not support ECC point compression and therefore may still send points uncompressed.

Note that the certificate used during authentication must also follow the other party’s preference.

Default: false

Note

Support for EC point compression is deprecated and will be removed in a future major release.

bool acceptable_protocol_version(Protocol_Version version)

Return true if this version of the protocol is one that we are willing to negotiate.

Default: Accepts TLS v1.2 and DTLS v1.2, and rejects all older versions.

bool server_uses_own_ciphersuite_preferences() const

If this returns true, a server will pick the cipher it prefers the most out of the client’s list. Otherwise, it will negotiate the first cipher in the client’s ciphersuite list that it supports.

Default: true

bool allow_client_initiated_renegotiation() const

If this function returns true, a server will accept a client-initiated renegotiation attempt. Otherwise it will send the client a non-fatal no_renegotiation alert.

Default: false

bool allow_server_initiated_renegotiation() const

If this function returns true, a client will accept a server-initiated renegotiation attempt. Otherwise it will send the server a non-fatal no_renegotiation alert.

Default: false

bool abort_connection_on_undesired_renegotiation() const

If a renegotiation attempt is being rejected due to the configuration of TLS::Policy::allow_client_initiated_renegotiation or TLS::Policy::allow_server_initiated_renegotiation, and this function returns true then the connection is closed with a fatal alert instead of the default warning alert.

Default: false

bool allow_insecure_renegotiation() const

If this function returns true, we will allow renegotiation attempts even if the counterparty does not support the RFC 5746 extensions.

Warning

Returning true here could expose you to attacks

Default: false

size_t minimum_signature_strength() const

Return the minimum strength (as n, representing 2**n work) we will accept for a signature algorithm on any certificate.

Use 80 to enable RSA-1024 (not recommended), or 128 to require either ECC or large (~3000 bit) RSA keys.

Default: 110 (allowing 2048 bit RSA)

bool require_cert_revocation_info() const

If this function returns true, and a ciphersuite using certificates was negotiated, then we must have access to a valid CRL or OCSP response in order to trust the certificate.

Warning

Returning false here could expose you to attacks

Default: true

Group_Params default_dh_group() const

For ephemeral Diffie-Hellman key exchange, the server sends a group parameter. Return the 2 Byte TLS group identifier specifying the group parameter a server should use.

Default: 2048 bit IETF IPsec group (“modp/ietf/2048”)

size_t minimum_dh_group_size() const

Return the minimum size in bits for a Diffie-Hellman group that a client will accept. Due to the design of the protocol the client has only two options - accept the group, or reject it with a fatal alert then attempt to reconnect after disabling ephemeral Diffie-Hellman.

Default: 2048 bits

bool allow_tls12() const

Return true from here to allow TLS v1.2. Returns true by default.

bool allow_tls13() const

Return true from here to allow TLS v1.3. Returns true by default.

size_t minimum_rsa_bits() const

Minimum accepted RSA key size. Default 2048 bits.

size_t minimum_dsa_group_size() const

Minimum accepted DSA key size. Default 2048 bits.

size_t minimum_ecdsa_group_size() const

Minimum size for ECDSA keys (256 bits).

size_t minimum_ecdh_group_size() const

Minimum size for ECDH keys (255 bits).

void check_peer_key_acceptable(const Public_Key &public_key) const

Allows the policy to examine peer public keys. Throw an exception if the key should be rejected. Default implementation checks against policy values minimum_dh_group_size, minimum_rsa_bits, minimum_ecdsa_group_size, and minimum_ecdh_group_size.

bool hide_unknown_users() const

The PSK suites work using an identifier along with a shared secret. If this function returns true, when an identifier that the server does not recognize is provided by a client, a random shared secret will be generated in such a way that a client should not be able to tell the difference between the identifier not being known and the secret being wrong. This can help protect against some username probing attacks. If it returns false, the server will instead send an unknown_psk_identity alert when an unknown identifier is used.

Default: false

std::chrono::seconds session_ticket_lifetime() const

Return the lifetime of session tickets. Each session includes the start time. Sessions resumptions using tickets older than session_ticket_lifetime seconds will fail, forcing a full renegotiation.

Default: 86400 seconds (1 day)

size_t new_session_tickets_upon_handshake_success() const

Return the number of session tickets a TLS 1.3 server should issue automatically once a successful handshake was made. Alternatively, users may manually call TLS::Server::send_new_session_tickets() at any time after a successful handshake.

Default: 1

std::optional<uint16_t> record_size_limit() const

Defines the maximum TLS record length this peer is willing to receive or std::nullopt in case of no preference (will use the maximum allowed).

This is currently implemented for TLS 1.3 only and will not be negotiated if TLS 1.2 is used or allowed.

Default: no preference (use maximum allowed by the protocol)

bool tls_13_middlebox_compatibility_mode() const

Enables middlebox compatibility mode as defined in RFC 8446 Appendix D.4.

Default: true

TLS Ciphersuites

class TLS::Ciphersuite

uint16_t ciphersuite_code() const

Return the numerical code for this ciphersuite

std::string to_string() const

Return the full name of ciphersuite (for example “RSA_WITH_RC4_128_SHA” or “ECDHE_RSA_WITH_AES_128_GCM_SHA256”)

std::string kex_algo() const

Return the key exchange algorithm of this ciphersuite

std::string sig_algo() const

Return the signature algorithm of this ciphersuite

std::string cipher_algo() const

Return the cipher algorithm of this ciphersuite

std::string mac_algo() const

Return the authentication algorithm of this ciphersuite

bool acceptable_ciphersuite(const Ciphersuite &suite) const

Return true if ciphersuite is accepted by the policy.

Allows an application to reject any ciphersuites, which are undesirable for whatever reason without having to reimplement TLS::Ciphersuite::ciphersuite_list

std::vector<uint16_t> ciphersuite_list(Protocol_Version version, bool have_srp) const

Return allowed ciphersuites in order of preference

Allows an application to have full control over ciphersuites by returning desired ciphersuites in preference order.

TLS Alerts

A TLS::Alert is passed to every invocation of a channel’s alert_cb.

class TLS::Alert

is_valid() const

Return true if this alert is not a null alert

is_fatal() const

Return true if this alert is fatal. A fatal alert causes the connection to be immediately disconnected. Otherwise, the alert is a warning and the connection remains valid.

Type type() const

Returns the type of the alert as an enum

std::string type_string()

Returns the type of the alert as a string

TLS Protocol Version

TLS has several different versions with slightly different behaviors. The TLS::Protocol_Version class represents a specific version:

class TLS::Protocol_Version

enum Version_Code

TLS_V10, TLS_V11, TLS_V12, DTLS_V10, DTLS_V12

Protocol_Version(Version_Code named_version)

Create a specific version

uint8_t major_version() const

Returns major number of the protocol version

uint8_t minor_version() const

Returns minor number of the protocol version

std::string to_string() const

Returns string description of the version, for instance “TLS v1.1” or “DTLS v1.0”.

static Protocol_Version latest_tls_version()

Returns the latest version of the TLS protocol known to the library (currently TLS v1.2)

static Protocol_Version latest_dtls_version()

Returns the latest version of the DTLS protocol known to the library (currently DTLS v1.2)

Post-quantum-secure key exchange

New in version ::: 3.2

Botan allows TLS 1.3 handshakes using both pure post-quantum secure algorithms or a hybrid key exchange that combines a classical and a post-quantum secure algorithm. For the latter it implements the recent IETF draft-ietf-tls-hybrid-design.

Note that post-quantum key exchanges in TLS 1.3 are not conclusively standardized. Therefore, the key exchange group identifiers used by various TLS 1.3 implementations are not consistent. Applications that wish to enable hybrid key exchanges must enable the hybrid algorithms in their TLS policy. Override TLS::Policy::key_exchange_groups() and return a list of the desired exchange groups. For text-based policy configurations use the identifiers in parenthesis.

Currently, Botan supports the following post-quantum secure key exchanges:

• used in Open Quantum Safe (PQC algorithm without a classical algorithm)

  • KYBER_512_R3 (“Kyber-512-r3”)

  • KYBER_768_R3 (“Kyber-768-r3”)

  • KYBER_1024_R3 (“Kyber-1024-r3”)

• used in Open Quantum Safe (hybrid between Kyber and a classical ECDH algorithm)

  • HYBRID_X25519_KYBER_512_R3_OQS (“x25519/Kyber-512-r3”)

  • HYBRID_X25519_KYBER_768_R3_OQS (“x25519/Kyber-768-r3”)

  • HYBRID_SECP256R1_KYBER_512_R3_OQS (“secp256r1/Kyber-512-r3”)

  • HYBRID_SECP384R1_KYBER_768_R3_OQS (“secp384r1/Kyber-768-r3”)

  • HYBRID_SECP521R1_KYBER_1024_R3_OQS (“secp521r1/Kyber-1024-r3”)

• used by Cloudflare (hybrid between Kyber and the classical X25519 algorithm)

  • HYBRID_X25519_KYBER_512_R3_CLOUDFLARE (“x25519/Kyber-512-r3/cloudflare”)

  • HYBRID_X25519_KYBER_768_R3_CLOUDFLARE (“x25519/Kyber-768-r3/cloudflare”)

Code Example: Hybrid TLS Client

#include <botan/auto_rng.h>
#include <botan/certstor.h>
#include <botan/tls.h>

/**
 * @brief Callbacks invoked by TLS::Channel.
 *
 * Botan::TLS::Callbacks is an abstract class.
 * For improved readability, only the functions that are mandatory
 * to implement are listed here. See src/lib/tls/tls_callbacks.h.
 */
class Callbacks : public Botan::TLS::Callbacks {
   public:
      void tls_emit_data(std::span<const uint8_t> data) override {
         BOTAN_UNUSED(data);
         // send data to tls server, e.g., using BSD sockets or boost asio
      }

      void tls_record_received(uint64_t seq_no, std::span<const uint8_t> data) override {
         BOTAN_UNUSED(seq_no, data);
         // process full TLS record received by tls server, e.g.,
         // by passing it to the application
      }

      void tls_alert(Botan::TLS::Alert alert) override {
         BOTAN_UNUSED(alert);
         // handle a tls alert received from the tls server
      }
};

/**
 * @brief Credentials storage for the tls client.
 *
 * It returns a list of trusted CA certificates from a local directory.
 * TLS client authentication is disabled. See src/lib/tls/credentials_manager.h.
 */
class Client_Credentials : public Botan::Credentials_Manager {
   public:
      std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(const std::string& type,
                                                                             const std::string& context) override {
         BOTAN_UNUSED(type, context);
         // return a list of certificates of CAs we trust for tls server certificates,
         // e.g., all the certificates in the local directory "cas"
         return {&m_cert_store};
      }

   private:
      Botan::Certificate_Store_In_Memory m_cert_store{"cas"};
};

class Client_Policy : public Botan::TLS::Default_Policy {
   public:
      // This needs to be overridden to enable the hybrid PQ/T groups
      // additional to the default (classical) key exchange groups
      std::vector<Botan::TLS::Group_Params> key_exchange_groups() const override {
         auto groups = Botan::TLS::Default_Policy::key_exchange_groups();
         groups.push_back(Botan::TLS::Group_Params::HYBRID_X25519_KYBER_512_R3_CLOUDFLARE);
         groups.push_back(Botan::TLS::Group_Params::HYBRID_X25519_KYBER_512_R3_OQS);
         return groups;
      }

      // Define that the client should exclusively pre-offer hybrid groups
      // in its initial Client Hello.
      std::vector<Botan::TLS::Group_Params> key_exchange_groups_to_offer() const override {
         return {Botan::TLS::Group_Params::HYBRID_X25519_KYBER_512_R3_CLOUDFLARE,
                 Botan::TLS::Group_Params::HYBRID_X25519_KYBER_512_R3_OQS};
      }
};

int main() {
   // prepare all the parameters
   auto rng = std::make_shared<Botan::AutoSeeded_RNG>();
   auto callbacks = std::make_shared<Callbacks>();
   auto session_mgr = std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng);
   auto creds = std::make_shared<Client_Credentials>();
   auto policy = std::make_shared<Botan::TLS::Strict_Policy>();

   // open the tls connection
   Botan::TLS::Client client(callbacks,
                             session_mgr,
                             creds,
                             policy,
                             rng,
                             Botan::TLS::Server_Information("botan.randombit.net", 443),
                             Botan::TLS::Protocol_Version::TLS_V12);

   while(!client.is_closed()) {
      // read data received from the tls server, e.g., using BSD sockets or boost asio
      // ...

      // send data to the tls server using client.send()
   }

   return 0;
}

TLS Custom Key Exchange Mechanisms

Applications can override the ephemeral key exchange mechanism used in TLS. This is not necessary for typical applications and might pose a serious security risk. Though, it allows the usage of custom groups or curves, offloading of cryptographic calculations to special hardware or the addition of entirely different algorithms (e.g. for post-quantum resilience).

From a technical point of view, the supported_groups TLS extension is used in the client hello to advertise a list of supported elliptic curves and DH groups. The server subsequently selects one of the groups, which is supported by both endpoints. Groups are represented by their TLS identifier. This two-byte identifier is standardized for commonly used groups and curves. In addition, the standard reserves the identifiers 0xFE00 to 0xFEFF for custom groups, curves or other algorithms.

To use custom curves with the Botan TLS::Client or TLS::Server the following additional adjustments have to be implemented as shown in the following code examples.

1. Registration of the custom curve

2. Implementation TLS callbacks tls_generate_ephemeral_key and tls_ephemeral_key_agreement

3. Adjustment of the TLS policy by allowing the custom curve

Below is a code example for a TLS client using a custom curve. For servers, it works exactly the same.

Code Example: TLS Client using Custom Curve

#include <botan/auto_rng.h>
#include <botan/certstor.h>
#include <botan/ecdh.h>
#include <botan/tls.h>

/**
 * @brief Callbacks invoked by TLS::Channel.
 *
 * Botan::TLS::Callbacks is an abstract class.
 * For improved readability, only the functions that are mandatory
 * to implement are listed here. See src/lib/tls/tls_callbacks.h.
 */
class Callbacks : public Botan::TLS::Callbacks {
   public:
      void tls_emit_data(std::span<const uint8_t> data) override {
         BOTAN_UNUSED(data);
         // send data to tls server, e.g., using BSD sockets or boost asio
      }

      void tls_record_received(uint64_t seq_no, std::span<const uint8_t> data) override {
         BOTAN_UNUSED(seq_no, data);
         // process full TLS record received by tls server, e.g.,
         // by passing it to the application
      }

      void tls_alert(Botan::TLS::Alert alert) override {
         BOTAN_UNUSED(alert);
         // handle a tls alert received from the tls server
      }

      std::unique_ptr<Botan::PK_Key_Agreement_Key> tls_generate_ephemeral_key(
         const std::variant<Botan::TLS::Group_Params, Botan::DL_Group>& group,
         Botan::RandomNumberGenerator& rng) override {
         if(std::holds_alternative<Botan::TLS::Group_Params>(group) &&
            std::get<Botan::TLS::Group_Params>(group) == Botan::TLS::Group_Params(0xFE00)) {
            // generate a private key of my custom curve
            const Botan::EC_Group ec_group("testcurve1102");
            return std::make_unique<Botan::ECDH_PrivateKey>(rng, ec_group);
         } else {
            // no custom curve used: up-call the default implementation
            return tls_generate_ephemeral_key(group, rng);
         }
      }

      Botan::secure_vector<uint8_t> tls_ephemeral_key_agreement(
         const std::variant<Botan::TLS::Group_Params, Botan::DL_Group>& group,
         const Botan::PK_Key_Agreement_Key& private_key,
         const std::vector<uint8_t>& public_value,
         Botan::RandomNumberGenerator& rng,
         const Botan::TLS::Policy& policy) override {
         if(std::holds_alternative<Botan::TLS::Group_Params>(group) &&
            std::get<Botan::TLS::Group_Params>(group) == Botan::TLS::Group_Params(0xFE00)) {
            // perform a key agreement on my custom curve
            const Botan::EC_Group ec_group("testcurve1102");
            Botan::ECDH_PublicKey peer_key(ec_group, ec_group.OS2ECP(public_value));
            Botan::PK_Key_Agreement ka(private_key, rng, "Raw");
            return ka.derive_key(0, peer_key.public_value()).bits_of();
         } else {
            // no custom curve used: up-call the default implementation
            return tls_ephemeral_key_agreement(group, private_key, public_value, rng, policy);
         }
      }
};

/**
 * @brief Credentials storage for the tls client.
 *
 * It returns a list of trusted CA certificates from a local directory.
 * TLS client authentication is disabled. See src/lib/tls/credentials_manager.h.
 */
class Client_Credentials : public Botan::Credentials_Manager {
   public:
      std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(const std::string& type,
                                                                             const std::string& context) override {
         BOTAN_UNUSED(type, context);
         // return a list of certificates of CAs we trust for tls server certificates,
         // e.g., all the certificates in the local directory "cas"
         return {&m_cert_store};
      }

   private:
      Botan::Certificate_Store_In_Memory m_cert_store{"cas"};
};

class Client_Policy : public Botan::TLS::Strict_Policy {
   public:
      std::vector<Botan::TLS::Group_Params> key_exchange_groups() const override {
         // modified strict policy to allow our custom curves
         return {static_cast<Botan::TLS::Group_Params>(0xFE00)};
      }
};

int main() {
   // prepare rng
   auto rng = std::make_shared<Botan::AutoSeeded_RNG>();

   // prepare custom curve

   // prepare curve parameters
   const Botan::BigInt p("0x92309a3e88b94312f36891a2055725bb35ab51af96b3a651d39321b7bbb8c51575a76768c9b6b323");
   const Botan::BigInt a("0x4f30b8e311f6b2dce62078d70b35dacb96aa84b758ab5a8dff0c9f7a2a1ff466c19988aa0acdde69");
   const Botan::BigInt b("0x9045A513CFFF9AE1F1CC84039D852D240344A1D5C9DB203C844089F855C387823EB6FCDDF49C909C");

   const Botan::BigInt x("0x9120f3779a31296cefcb5a5a08831f1a6d438ad5a3f2ce60585ac19c74eebdc65cadb96bb92622c7");
   const Botan::BigInt y("0x836db8251c152dfee071b72c6b06c5387d82f1b5c30c5a5b65ee9429aa2687e8426d5d61276a4ede");
   const Botan::BigInt order("0x248c268fa22e50c4bcda24688155c96ecd6ad46be5c82d7a6be6e7068cb5d1ca72b2e07e8b90d853");

   const Botan::BigInt cofactor(4);

   const Botan::OID oid("1.2.3.1");

   // create EC_Group object to register the curve
   Botan::EC_Group testcurve1102(p, a, b, x, y, order, cofactor, oid);

   if(!testcurve1102.verify_group(*rng)) {
      // Warning: if verify_group returns false the curve parameters are insecure
   }

   // register name to specified oid
   Botan::OID::register_oid(oid, "testcurve1102");

   // prepare all the parameters
   auto callbacks = std::make_shared<Callbacks>();
   auto session_mgr = std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng);
   auto creds = std::make_shared<Client_Credentials>();
   auto policy = std::make_shared<Botan::TLS::Strict_Policy>();

   // open the tls connection
   Botan::TLS::Client client(callbacks,
                             session_mgr,
                             creds,
                             policy,
                             rng,
                             Botan::TLS::Server_Information("botan.randombit.net", 443),
                             Botan::TLS::Protocol_Version::TLS_V12);

   while(!client.is_closed()) {
      // read data received from the tls server, e.g., using BSD sockets or boost asio
      // ...

      // send data to the tls server using client.send()
   }

   return 0;
}

TLS Stream

TLS::Stream offers a Boost.Asio compatible wrapper around TLS::Client and TLS::Server. It can be used as an alternative to Boost.Asio’s ssl::stream with minor adjustments to the using code.

To use the asio stream wrapper, a relatively recent version of boost is required. Include botan/asio_compat.h and check that BOTAN_FOUND_COMPATIBLE_BOOST_ASIO_VERSION is defined before including botan/asio_stream.h to be ensure compatibility at compile time of your application.

The asio Stream offers the following interface:

template<class StreamLayer, class ChannelT>
class TLS::Stream

StreamLayer specifies the type of the stream’s next layer, for example a Boost.Asio TCP socket. ChannelT is the type of the stream’s native handle; it defaults to TLS::Channel and should not be specified manually.

template<typename ...Args>
explicit Stream(Context &context, Args&&... args)

Construct a new TLS stream. The context parameter will be used to initialize the underlying native handle, i.e. the TLS::Client or TLS::Server, when handshake is called. Using code must ensure the context is kept alive for the lifetime of the stream. The further args will be forwarded to the next layer’s constructor.

template<typename ...Args>
explicit Stream(Arg &&arg, Context &context)

Convenience constructor for boost::asio::ssl::stream compatibility. The parameters have the same meaning as for the first constructor, but their order is changed and only one argument can be passed to the next layer constructor.

void handshake(Connection_Side side, boost::system::error_code &ec)

Set up the native handle and perform the TLS handshake.

void handshake(Connection_Side side)

Overload of handshake that throws an exception if an error occurs.

template<typename HandshakeHandler>
DEDUCED async_handshake(Connection_Side side, HandshakeHandler &&handler)

Asynchronous variant of handshake. The function returns immediately and calls the handler callback function after performing asynchronous I/O to complete the TLS handshake. The return type is an automatically deduced specialization of boost::asio::async_result, depending on the HandshakeHandler type.

void shutdown(boost::system::error_code &ec)

Calls TLS::Channel::close on the native handle and writes the TLS alert to the next layer.

void shutdown()

Overload of shutdown that throws an exception if an error occurs.

template<typename ShutdownHandler>
void async_shutdown(ShutdownHandler &&handler)

Asynchronous variant of shutdown. The function returns immediately and calls the handler callback function after performing asynchronous I/O to complete the TLS shutdown.

template<typename MutableBufferSequence>
std::size_t read_some(const MutableBufferSequence &buffers, boost::system::error_code &ec)

Reads encrypted data from the next layer, decrypts it, and writes it into the provided buffers. If an error occurs, error_code is set. Returns the number of bytes read.

template<typename MutableBufferSequence>
std::size_t read_some(const MutableBufferSequence &buffers)

Overload of read_some that throws an exception if an error occurs.

template<typename MutableBufferSequence, typename ReadHandler>
DEDUCED async_read_some(const MutableBufferSequence &buffers, ReadHandler &&handler)

Asynchronous variant of read_some. The function returns immediately and calls the handler callback function after writing the decrypted data into the provided buffers. The return type is an automatically deduced specialization of boost::asio::async_result, depending on the ReadHandler type. ReadHandler should suffice the requirements to a Boost.Asio read handler.

template<typename ConstBufferSequence>
std::size_t write_some(const ConstBufferSequence &buffers, boost::system::error_code &ec)

Encrypts data from the provided buffers and writes it to the next layer. If an error occurs, error_code is set. Returns the number of bytes written.

template<typename ConstBufferSequence>
std::size_t write_some(const ConstBufferSequence &buffers)

Overload of write_some that throws an exception rather than setting an error code.

template<typename ConstBufferSequence, typename WriteHandler>
DEDUCED async_write_some(const ConstBufferSequence &buffers, WriteHandler &&handler)

Asynchronous variant of write_some. The function returns immediately and calls the handler callback function after writing the encrypted data to the next layer. The return type is an automatically deduced specialization of boost::asio::async_result, depending on the WriteHandler type. WriteHandler should suffice the requirements to a Boost.Asio write handler.

class TLS::Context

A helper class to initialize and configure the Stream’s underlying native handle (see TLS::Client and TLS::Server).

Context(Credentials_Manager &credentialsManager, RandomNumberGenerator &randomNumberGenerator, Session_Manager &sessionManager, Policy &policy, Server_Information serverInfo = Server_Information())

Constructor for TLS::Context.

void set_verify_callback(Verify_Callback_T callback)

Set a user-defined callback function for certificate chain verification. This will cause the stream to override the default implementation of the tls_verify_cert_chain callback.

Code Examples: HTTPS Client using Boost Beast

Starting with Botan 3.3.0 (and assuming a recent version of Boost), one may use Botan’s TLS using C++20 coroutines. The following example implements a simple HTTPS client that may be used to fetch content from web servers:

#include <iostream>

#include <botan/asio_compat.h>

// Boost 1.81.0 introduced support for the finalized C++20 coroutines
// in clang 14 and newer. Older versions of Boost might work with other
// compilers, though.
#if defined(BOTAN_FOUND_COMPATIBLE_BOOST_ASIO_VERSION) && BOOST_VERSION >= 108100

   #include <botan/asio_stream.h>
   #include <botan/auto_rng.h>
   #include <botan/certstor_system.h>
   #include <botan/credentials_manager.h>
   #include <botan/tls_session_manager_memory.h>
   #include <botan/version.h>

   #include <boost/asio/awaitable.hpp>
   #include <boost/asio/co_spawn.hpp>
   #include <boost/asio/detached.hpp>
   #include <boost/asio/use_awaitable.hpp>
   #include <boost/beast/core.hpp>
   #include <boost/beast/http.hpp>
   #include <boost/beast/version.hpp>

namespace beast = boost::beast;
namespace http = beast::http;
namespace net = boost::asio;
namespace tls = Botan::TLS;
using tcp = boost::asio::ip::tcp;

namespace {

/**
 * A simple credentials manager that uses the system's trust store
 * to verify certificates.
 */
class System_Credentials_Manager : public Botan::Credentials_Manager {
   public:
      std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(const std::string&,
                                                                             const std::string&) override {
         return {&m_cert_store};
      }

   private:
      Botan::System_Certificate_Store m_cert_store;
};

/**
 * Helper function to set up a Botan TLS Context for the ASIO wrapper.
 */
std::shared_ptr<tls::Context> prepare_context_for(std::string_view server_info) {
   auto rng = std::make_shared<Botan::AutoSeeded_RNG>();
   return std::make_shared<tls::Context>(std::make_shared<System_Credentials_Manager>(),
                                         rng,
                                         std::make_shared<tls::Session_Manager_In_Memory>(rng),
                                         std::make_shared<tls::Policy>(),
                                         tls::Server_Information(server_info));
}

http::request<http::string_body> create_GET_request(const std::string& host, const std::string& target) {
   http::request<http::string_body> req;
   req.version(11);
   req.method(http::verb::get);
   req.target(target);
   req.set(http::field::host, host);
   req.set(http::field::user_agent, Botan::version_string());
   return req;
}

}  // namespace

static net::awaitable<void> request(std::string host, std::string port, std::string target) {
   // Lookup host address
   auto resolver = net::use_awaitable.as_default_on(tcp::resolver(co_await net::this_coro::executor));
   const auto dns_result = co_await resolver.async_resolve(host, port);

   // Connect to host and establish a TLS session
   auto tls_stream =
      tls::Stream(prepare_context_for(host),
                  net::use_awaitable.as_default_on(beast::tcp_stream(co_await net::this_coro::executor)));
   tls_stream.next_layer().expires_after(std::chrono::seconds(30));
   co_await tls_stream.next_layer().async_connect(dns_result);
   co_await tls_stream.async_handshake(tls::Connection_Side::Client);

   // Send HTTP GET request
   tls_stream.next_layer().expires_after(std::chrono::seconds(30));
   co_await http::async_write(tls_stream, create_GET_request(host, target));

   // Receive HTTP response and print result
   beast::flat_buffer b;
   http::response<http::dynamic_body> res;
   co_await http::async_read(tls_stream, b, res);
   std::cout << res << std::endl;

   // Terminate connection
   co_await tls_stream.async_shutdown();
   tls_stream.next_layer().close();
}

int main(int argc, char* argv[]) {
   if(argc != 4) {
      std::cerr << "Usage: tls_stream_coroutine_client <host> <port> <target>\n"
                << "Example:\n"
                << "    tls_stream_coroutine_client botan.randombit.net 443 /news.html\n";
      return 1;
   }

   const auto host = argv[1];
   const auto port = argv[2];
   const auto target = argv[3];

   net::io_context ioc;

   int return_code = 0;
   net::co_spawn(ioc, request(host, port, target), [&](std::exception_ptr eptr) {
      if(eptr) {
         try {
            std::rethrow_exception(eptr);
         } catch(std::exception& ex) {
            std::cerr << "Error: " << ex.what() << "\n";
            return_code = 1;
         }
      }
   });

   ioc.run();

   return return_code;
}

#else

int main() {
   std::cout << "Your boost version is too old, sorry.\n"
             << "Or did you compile Botan without --with-boost?\n";
   return 1;
}

#endif

Of course, the ASIO stream may also be used in a more traditional way, using callback handler methods instead of coroutines:

#include <iostream>

#include <botan/asio_compat.h>
#if defined(BOTAN_FOUND_COMPATIBLE_BOOST_ASIO_VERSION)

   #include <botan/asio_stream.h>
   #include <botan/auto_rng.h>
   #include <botan/certstor_system.h>
   #include <botan/tls.h>
   #include <botan/version.h>

   #include <boost/asio.hpp>
   #include <boost/beast.hpp>
   #include <boost/bind.hpp>
   #include <utility>

namespace http = boost::beast::http;
namespace ap = boost::asio::placeholders;

// very basic credentials manager
class Credentials_Manager : public Botan::Credentials_Manager {
   public:
      Credentials_Manager() = default;

      std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(const std::string&,
                                                                             const std::string&) override {
         return {&m_cert_store};
      }

   private:
      Botan::System_Certificate_Store m_cert_store;
};

// a simple https client based on TLS::Stream
class client {
   public:
      client(boost::asio::io_context& io_context,
             boost::asio::ip::tcp::resolver::iterator endpoint_iterator,
             std::string_view host,
             const http::request<http::string_body>& req) :
            m_request(req),
            m_ctx(std::make_shared<Botan::TLS::Context>(std::make_shared<Credentials_Manager>(),
                                                        std::make_shared<Botan::AutoSeeded_RNG>(),
                                                        std::make_shared<Botan::TLS::Session_Manager_Noop>(),
                                                        std::make_shared<Botan::TLS::Policy>(),
                                                        host)),
            m_stream(io_context, m_ctx) {
         boost::asio::async_connect(m_stream.lowest_layer(),
                                    std::move(endpoint_iterator),
                                    boost::bind(&client::handle_connect, this, ap::error));
      }

      void handle_connect(const boost::system::error_code& error) {
         if(error) {
            std::cout << "Connect failed: " << error.message() << '\n';
            return;
         }
         m_stream.async_handshake(Botan::TLS::Connection_Side::Client,
                                  boost::bind(&client::handle_handshake, this, ap::error));
      }

      void handle_handshake(const boost::system::error_code& error) {
         if(error) {
            std::cout << "Handshake failed: " << error.message() << '\n';
            return;
         }
         http::async_write(
            m_stream, m_request, boost::bind(&client::handle_write, this, ap::error, ap::bytes_transferred));
      }

      void handle_write(const boost::system::error_code& error, size_t) {
         if(error) {
            std::cout << "Write failed: " << error.message() << '\n';
            return;
         }
         http::async_read(
            m_stream, m_reply, m_response, boost::bind(&client::handle_read, this, ap::error, ap::bytes_transferred));
      }

      void handle_read(const boost::system::error_code& error, size_t) {
         if(!error) {
            std::cout << "Reply: ";
            std::cout << m_response.body() << '\n';
         } else {
            std::cout << "Read failed: " << error.message() << '\n';
         }
      }

   private:
      http::request<http::dynamic_body> m_request;
      http::response<http::string_body> m_response;
      boost::beast::flat_buffer m_reply;

      std::shared_ptr<Botan::TLS::Context> m_ctx;
      Botan::TLS::Stream<boost::asio::ip::tcp::socket> m_stream;
};

int main(int argc, char* argv[]) {
   if(argc != 4) {
      std::cerr << "Usage: tls_stream_client <host> <port> <target>\n"
                << "Example:\n"
                << "    tls_stream_client botan.randombit.net 443 /news.html\n";
      return 1;
   }

   const auto host = argv[1];
   const auto port = argv[2];
   const auto target = argv[3];

   try {
      boost::asio::io_context io_context;

      boost::asio::ip::tcp::resolver resolver(io_context);
      boost::asio::ip::tcp::resolver::query query(host, port);
      boost::asio::ip::tcp::resolver::iterator iterator = resolver.resolve(query);

      http::request<http::string_body> req;
      req.version(11);
      req.method(http::verb::get);
      req.target(target);
      req.set(http::field::host, host);
      req.set(http::field::user_agent, Botan::version_string());

      client c(io_context, iterator, host, req);

      io_context.run();
   } catch(std::exception& e) {
      std::cerr << e.what();
      return 1;
   }

   return 0;
}

#else

int main() {
   std::cout << "Your boost version is too old, sorry.\n"
             << "Or did you compile Botan without --with-boost?\n";
   return 1;
}

#endif

For some websites this might not work and report a “bad_certificate”. Botan’s default TLS policy requires that the server sends a valid CRL or OCSP response. Some servers don’t do that and thus the certificate is rejected. To disable this check, derive the default policy and override require_cert_revocation_info() accordingly.

TLS Session Encryption

A unified format is used for encrypting TLS sessions either for durable storage (on client or server) or when creating TLS session tickets. This format is not stable even across the same major version.

The current session encryption scheme was introduced in 2.13.0, replacing the format previously used since 1.11.13.

Session encryption accepts a key of any length, though for best security a key of 256 bits should be used. This master key is used to key an instance of HMAC using the SHA-512/256 hash.

First a “key name” or identifier is created, by HMAC’ing the fixed string “BOTAN TLS SESSION KEY NAME” and truncating to 4 bytes. This is the initial prefix of the encrypted session, and will remain fixed as long as the same ticket key is used. This allows quickly rejecting sessions which are encrypted using an unknown or incorrect key.

Then a key used for AES-256 in GCM mode is created by first choosing a 128 bit random seed, and HMAC’ing it to produce a 256-bit value. This means for any one master key as many as 2¹²⁸ GCM keys can be created. This is done because NIST recommends that when using random nonces no one GCM key be used to encrypt more than 2³² messages (to avoid the possiblity of nonce reuse).

A random 96-bit nonce is created and included in the header.

AES in GCM is used to encrypt and authenticate the serialized session. The key name, key seed, and AEAD nonce are all included as additional data.