Native Windows TLS stream for Boost.Asio

wintls.dev

Build	Coverage	Coverity Analysis

Contents

• Introduction
• Requirements
• Building
• Quickstart
• Documentation
• Contributing
• Thanks

Introduction

Implements a TLS stream wrapper for use with Boost.Asio similar to Boost.Asio.SSL but using native Windows API (SSPI/Schannel) functionality instead of OpenSSL for providing TLS encrypted stream functionality.

Requirements

As this library uses Windows specific libraries, it is only supported on Microsoft Windows although it is intended to be used alongside the existing Boost.Asio.SSL implementation.

Boost is required. Currently tested with Boost 1.75 to 1.79 but most newer versions ought to work.

A working C++ compiler supporting the C++14 standard is required. Currently tested compilers are:

• MSVC for Visual Studio 2022
• MSVC for Visual Studio 2019
• Clang
• MinGW64 (GCC)

Only 64 bit builds have been tested.

Building

Boost.Wintls is header-only. To use it just add the necessary #include line to your source files, like this:

#include <boost/wintls.hpp>

CMake may be used to generate a Visual Studio solution for building the tests and examples, e.g.:

mkdir build
cd build
cmake ..
cmake --build .

If the provided CMake scripts are not used and you are using the MinGW64 compiler the crypt32, secur32, ws2_32 and wsock32 libraries needs to be linked with your libraries/executables.

Quickstart

Similar to Boost.Asio.SSL a boost::wintls::context is required to hold certificates and options to use for the TLS stream:

    // Set up context to use the systems default TLS methods (e.g. TLS 1.2)
    boost::wintls::context ctx{boost::wintls::method::system_default};

Using that context a boost::wintls::stream can be constructed using a boost::asio::io_context specifying the underlying stream type (most often a TCP stream):

    boost::asio::io_context ioc;

    boost::wintls::stream<boost::asio::ip::tcp::socket> stream(ioc, ctx);

Although that is all that is required to construct a stream that fully supports the standard boost::asio stream operations like write or async_read the underlying stream probably needs to be connected, a handshake has to be performed and most likely, certificates and keys has to be handled as well.

For details on how to do that, please see the documentation and the examples

Documentation

Documentation is available here.

Contributing

Pull requests, issue reporting etc. are very much welcome.

If you use this library and find it useful, I would love to know. You should also consider donating to one of the funds that help victims of the war in Ukraine:

https://www.stopputin.net/

Thanks

• Vinnie Falco For encouraging me to write this library in the first place as well as code reviews and other useful input.
• Richard Hodges For code reviews and other useful input.
• Damian Jarek For code reviews and other useful input.
• Marcelo Zimbres For coming up with the short and descriptive name for this library