boost::corosio::tls_context

A portable TLS context for certificate and settings storage.

Synopsis

Declared in <boost/corosio/tls_context.hpp>

class tls_context;

Description

The tls_context class provides a backend‐agnostic interface for configuring TLS connections. It stores credentials (certificates and private keys), trust anchors, protocol settings, and verification options that are used when establishing TLS connections.

This class is a shared handle to an opaque implementation. Copies share the same underlying state. This allows contexts to be passed by value and shared across multiple TLS streams.

This class abstracts the configuration phase of TLS across multiple backend implementations (OpenSSL, WolfSSL, mbedTLS, Schannel, etc.), allowing portable code that works regardless of which TLS library is linked.

Modification After Stream Creation

Modifying a context after a TLS stream has been created from it results in undefined behavior. The context's configuration is captured when the first stream is constructed, and subsequent modifications are not reflected in existing or new streams sharing the context.

If different configurations are needed, create separate context objects.

Thread Safety

Distinct objects: Safe.

Shared objects: Unsafe. A context must not be modified while any thread is creating streams from it.

Example

// A default-constructed context verifies nothing: tls_verify_mode::none is
// the default. These two calls are what make a client context safe. A factory
// has no error code to return alongside the context, so it throws; the
// members themselves report failure by returning std::error_code.
corosio::tls_context
make_verified_client_context()
{
    corosio::tls_context ctx;
    if (auto ec = ctx.set_default_verify_paths())
        throw std::system_error(ec);
    if (auto ec = ctx.set_verify_mode(corosio::tls_verify_mode::peer))
        throw std::system_error(ec);
    return ctx;
}

// Construct a backend stream -- corosio::openssl_stream or
// corosio::wolfssl_stream -- over a connected socket and that context, then
// hand it here: the context's settings are captured when the stream is
// built, and every backend handshakes through this same interface.
capy::task<>
handshake_as_client(corosio::tls_stream& secure, std::string_view hostname)
{
    // Sets SNI and the name the peer certificate must match. A verified
    // chain on its own says nothing about who is on the other end.
    secure.set_hostname(hostname);

    if (auto [ec] = co_await secure.handshake(corosio::tls_role::client); ec)
        co_return; // report the error
}