Native Windows TLS stream for Asio

wintls.dev

Build	Coverage	Coverity Analysis

Contents

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

Introduction

Implements a TLS stream wrapper for use with Asio or Boost.Asio similar to 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 Asio.SSL implementation.

Code using this library must target at least Windows 7 (NT 6.1).

Either Asio or the Boost libraries are required. Currently tested with Boost 1.81 to 1.84 and Asio 1.28 to 1.29 but at least most newer versions ought to work.

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

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

Building

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

#include <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.

Currently this library expects the Boost libraries to be available (i.e. found in the include path). If standalone Asio is to be used instead, define #WINTLS_USE_STANDALONE_ASIO before including wintls.hpp and make sure that Asio is found in the include path instead.

Quickstart

Similar to Asio.SSL a 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)
    wintls::context ctx{wintls::method::system_default};

Using that context a 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;

    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