boost::corosio::openssl_stream

A TLS stream using OpenSSL.

Synopsis

Declared in <boost/corosio/openssl_stream.hpp>

class openssl_stream final
    : public tls_stream

Description

This class wraps an underlying stream satisfying capy::Stream and provides TLS encryption using the OpenSSL library.

Derives from tls_stream to provide a runtime‐polymorphic interface. The TLS operations are implemented as coroutines that orchestrate reads and writes on the underlying stream.

Construction Modes

Two construction modes are supported:

Owning: Pass stream by value. The openssl_stream takes ownership and the stream is moved into internal storage.
Reference: Pass stream by pointer. The openssl_stream does not own the stream; the caller must ensure the stream outlives this object.

Thread Safety

Distinct objects: Safe. Shared objects: Unsafe, with one exception: one read operation and one write operation may be in flight simultaneously. shutdown() may overlap a pending read. When the execution context runs on multiple threads, all operations on one stream must be performed within the same capy::strand (or otherwise never run concurrently); a single‐threaded context needs no strand.

Example

// Two independently connected sockets demonstrate the two construction
// modes; reusing one socket for both would leave tls pointing at sock
// after it was gutted by the move into tls2 (use-after-move), not a
// dangling reference -- sock itself stays in scope.
capy::task<>
reference_and_owning_construction(
    corosio::io_context& ioc, corosio::endpoint ep)
{
    corosio::tls_context ctx;
    if (auto ec = ctx.set_default_verify_paths()) // trust the system CAs
        co_return;
    if (auto ec = ctx.set_verify_mode(corosio::tls_verify_mode::peer))
        co_return;

    // Reference mode - sock must outlive tls
    corosio::tcp_socket sock(ioc);
    auto [ec] = co_await sock.connect(ep);
    if (ec)
        co_return;
    corosio::openssl_stream tls(&sock, ctx);
    tls.set_hostname("example.com");
    auto [hec] = co_await tls.handshake(corosio::tls_role::client);
    if (hec)
        co_return;

    // Or owning mode - tls2 takes ownership of its own connected socket
    corosio::tcp_socket sock2(ioc);
    auto [ec2] = co_await sock2.connect(ep);
    if (ec2)
        co_return;
    corosio::openssl_stream tls2(std::move(sock2), ctx);
}