Usage

This library implements a stream similar to boost::asio::ssl::stream. Basic knowledge of boost::asio is expected as this documentation mainly deals with the specifics of this library.

Setting up a context

Client usage

A context is required for holding certificates and for setting options like which TLS versions to support.

To construct a context using the operating system default methods:

#include <boost/wintls.hpp>

boost::wintls::context ctx(boost::wintls::method::system_default);

While that is all which is required to construct a context for client-side operations, most users would at least want to enable certificate validation with context::verify_server_certificate() in addition to either using the standard operating system certificates with context::use_default_certificates() or providing certificates with context::add_certificate_authority().

For example, initializing a context which will use the certificates provided by the operating system and verify the server certificate, would look something like:

#include <boost/wintls.hpp>

boost::wintls::context ctx(boost::wintls::method::system_default);
ctx.use_default_certificates(true);
ctx.verify_server_certificate(true);

Server usage

When creating a context for server usage, a certificate is required as well as private key. Unlike OpenSSL Windows has the concept of a certificate with an associated private key that must be available to the process or user running the server process. Such a certificate can be used using context::use_certificate().

This library provides functions for helping interact with standard key and certificate formats used by OpenSSL as demonstrated in the examples.

Initializing a stream

Assuming an underlying TCP stream, once the context has been setup a stream can be constructed like:

boost::wintl::stream<ip::tcp::socket> my_stream(my_io_service, ctx);

In the case of a TCP stream, the underlying stream needs to be connected before it can be used. To access the underlying stream use the stream::next_layer() member function.

Handshaking

Before a TLS stream can be used, a handshake needs to be performed, either as a server or a client. Similar to the rest of the boost::asio functions both a synchronous and asynchronous version exists.

When performing a handshake as a client, it is often required to include the hostname of the server in the handshake with stream::set_server_hostname().

Performing a synchronous handshake as a client might look like:

strean.set_server_hostname("wintls.dev");
stream.handshake(boost::wintls::handshake_type::client);

Similar to the boost::asio functions, this library provides overloads for accepting a boost::system::error_codes.

Using the stream

Once the stream has been constructed and a successful handshake has been done it can be used with all the usual operations provided by the boost::asio library.

Most users would probably not use the member functions on the stream like stream::read_some() directly but instead use boost::asio functions like boost::asio::write or boost::asio::async_read_until.

Please see the examples for full examples on how this library can be used.