Asio contains classes and class templates for basic SSL support. These classes allow encrypted communication to be layered on top of an existing stream, such as a TCP socket.

Before creating an encrypted stream, an application must construct an SSL context object. This object is used to set SSL options such as verification mode, certificate files, and so on. As an illustration, client-side initialisation may look something like:

ssl::context ctx(ssl::context::sslv23);
ctx.set_verify_mode(ssl::verify_peer);
ctx.load_verify_file("ca.pem");

To use SSL with a TCP socket, one may write:

ssl::stream<ip::tcp::socket> ssl_sock(my_io_context, ctx);

To perform socket-specific operations, such as establishing an outbound connection or accepting an incoming one, the underlying socket must first be obtained using the ssl::stream template's lowest_layer() member function:

ip::tcp::socket::lowest_layer_type& sock = ssl_sock.lowest_layer();
sock.connect(my_endpoint);

In some use cases the underlying stream object will need to have a longer lifetime than the SSL stream, in which case the template parameter should be a reference to the stream type:

ip::tcp::socket sock(my_io_context);
ssl::stream<ip::tcp::socket&> ssl_sock(sock, ctx);

SSL handshaking must be performed prior to transmitting or receiving data over an encrypted connection. This is accomplished using the ssl::stream template's handshake() or async_handshake() member functions.

Once connected, SSL stream objects are used as synchronous or asynchronous read and write streams. This means the objects can be used with any of the read(), async_read(), write(), async_write(), read_until() or async_read_until() free functions.

Certificate Verification

Asio provides various methods for configuring the way SSL certificates are verified:

To simplify use cases where certificates are verified according to the rules in RFC 6125 (identity verification in the context of Transport Layer Security), Asio provides a reusable verification callback as a function object:

The following example shows verification of a remote host's certificate according to the rules used by HTTPS:

using asio::ip::tcp;
namespace ssl = asio::ssl;
typedef ssl::stream<tcp::socket> ssl_socket;

// Create a context that uses the default paths for
// finding CA certificates.
ssl::context ctx(ssl::context::sslv23);
ctx.set_default_verify_paths();

// Open a socket and connect it to the remote host.
asio::io_context io_context;
ssl_socket sock(io_context, ctx);
tcp::resolver resolver(io_context);
tcp::resolver::query query("host.name", "https");
asio::connect(sock.lowest_layer(), resolver.resolve(query));
sock.lowest_layer().set_option(tcp::no_delay(true));

// Perform SSL handshake and verify the remote host's
// certificate.
sock.set_verify_mode(ssl::verify_peer);
sock.set_verify_callback(ssl::host_name_verification("host.name"));
sock.handshake(ssl_socket::client);

// ... read and write as normal ...

SSL and Threads

SSL stream objects perform no locking of their own. Therefore, it is essential that all asynchronous SSL operations are performed in an implicit or explicit strand. Note that this means that no synchronisation is required (and so no locking overhead is incurred) in single threaded programs.

See Also

ssl::context, ssl::host_name_verification, ssl::stream, SSL example (C++11).

Notes

OpenSSL is required to make use of Asio's SSL support. When an application needs to use OpenSSL functionality that is not wrapped by Asio, the underlying OpenSSL types may be obtained by calling ssl::context::native_handle() or ssl::stream::native_handle().