mirror of
https://github.com/Icinga/icinga2.git
synced 2025-08-24 02:59:17 +02:00
115 lines
3.9 KiB
ReStructuredText
115 lines
3.9 KiB
ReStructuredText
.. cpp:namespace:: boost::wintls
|
|
|
|
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 :class:`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 :func:`context::verify_server_certificate`
|
|
in addition to either using the standard operating system certificates
|
|
with :func:`context::use_default_certificates` or providing
|
|
certificates with :func:`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 :func:`context::use_certificate`.
|
|
|
|
This library provides :ref:`functions<functions>` for helping interact
|
|
with standard key and certificate formats used by `OpenSSL`_ as
|
|
demonstrated in the :ref:`examples<examples>`.
|
|
|
|
Initializing a stream
|
|
---------------------
|
|
|
|
Assuming an underlying TCP stream, once the context has been setup
|
|
a :class:`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 :func:`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
|
|
:func:`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 :func:`stream::read_some` directly but instead use `boost::asio`_
|
|
functions like `boost::asio::write`_ or `boost::asio::async_read_until`_.
|
|
|
|
Please see the :ref:`examples<examples>` for full examples on how this
|
|
library can be used.
|
|
|
|
.. _OpenSSL: https://www.openssl.org/
|
|
.. _boost::asio: https://www.boost.org/doc/libs/release/doc/html/boost_asio.html
|
|
.. _boost::asio::ssl::stream: https://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/ssl__stream.html
|
|
.. _boost::system: https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html
|
|
.. _boost::asio::write: https://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/write.html
|
|
.. _boost::asio::async_read_until: https://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/async_read_until.html
|