Classes¶

context¶

class context¶

Holds certificates and related options required for setting up TLS connections.

Public Functions

explicit context(method connection_method)¶

Construct a context.

Parameters:: connection_method – The method to use for connections.

void add_certificate_authority(const CERT_CONTEXT *cert)¶

Add certification authority for performing verification.

This function is used to add one trusted certification authority to the contexts certificate store used for certificate validation

Parameters:: cert – The certificate to add to the certificate store
Throws:: wintls::system_error – Thrown on failure.

void add_certificate_authority(const CERT_CONTEXT *cert, wintls::error_code &ec)¶

Add certification authority for performing verification.

This function is used to add one trusted certification authority to the contexts certificate store used for certificate validation

Parameters:

cert – The certificate to add to the certificate store
ec – Set to indicate what error occurred, if any.

void verify_server_certificate(bool verify)¶

Enables/disables remote server certificate verification.

This function may be used to enable clients to verify the certificate presented by the server with the known trusted certificates.

Parameters:: verify – True if the remote server certificate should be verified

void use_default_certificates(bool use_system_certs)¶

Use the default operating system certificates.

This function may be used to verify the server certificates against the certificates installed in the operating system when performing handshakes as a client.

It is still possible to add additional certificates for verification in addition to the ones installed by the operating system.

Parameters:: use_system_certs – True if the default operating system certificates should be used for verification.

void use_certificate(const CERT_CONTEXT *cert)¶

Set the certificate to use when operating as a server.

This function sets the certificate to use when using a stream as server.

Note

The certificate must be a private certificate, ie. containing a reference to a private key. If the certificate is imported from a public certificate assign_private_key can be used for that.

Parameters:: cert – The private certificate the stream will use for encrypting messages when operating as a server.
Throws:: wintls::system_error – Thrown on failure.

void use_certificate(const CERT_CONTEXT *cert, wintls::error_code &ec)¶

Set the certificate to use when operating as a server.

This function sets the certificate to use when using a stream as server.

Note

The certificate must be a private certificate, ie. containing a reference to a private key. If the certificate is imported from a public certificate assign_private_key can be used for that.

Parameters:

cert – The private certificate the stream will use for encrypting messages when operating as a server.
ec – Set to indicate what error occurred, if any.

stream¶

template<class NextLayer> class stream¶

Provides stream-oriented functionality using Windows SSPI/Schannel.

The stream class template provides asynchronous and blocking stream-oriented functionality using Windows SSPI/Schannel.

Template Parameters:: NextLayer – The type representing the next layer, to which data will be read and written during operations. For synchronous operations, the type must support the SyncStream concept. For asynchronous operations, the type must support the AsyncStream concept.

Public Types

using next_layer_type = typename std::remove_reference<NextLayer>::type¶: The type of the next layer.

using executor_type = typename std::remove_reference<next_layer_type>::type::executor_type¶: The type of the executor associated with the object.

Public Functions

template<class Arg> stream(Arg &&arg, context &ctx)¶

Construct a stream.

This constructor creates a stream and initialises the underlying stream object.

Parameters:

arg – The argument to be passed to initialise the underlying stream.
ctx – The wintls context to be used for the stream.

executor_type get_executor()¶

Get the executor associated with the object.

This function may be used to obtain the executor object that the stream uses to dispatch handlers for asynchronous operations.

Returns:: A copy of the executor that stream will use to dispatch handlers.

const next_layer_type &next_layer() const¶

Get a reference to the next layer.

This function returns a reference to the next layer in a stack of stream layers.

Returns:: A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller.

next_layer_type &next_layer()¶

Get a reference to the next layer.

This function returns a reference to the next layer in a stack of stream layers.

Returns:: A reference to the next layer in the stack of stream layers. Ownership is not transferred to the caller.

void set_server_hostname(const std::string &hostname)¶

Set SNI hostname.

Sets the SNI hostname the client will use for requesting and validating the server certificate.

Only used when handshake is performed as handshake_type::client

Parameters:: hostname – The hostname to use in certificate validation

void set_certificate_revocation_check(bool check)¶

Set revocation checking.

Enable revocation checking for remote certificates.

Enabling this also causes the TLS certificate status request extension to be sent during the handshake. (I.e. we request OCSP stapling from the remote.)

Parameters:: check – Whether to enable revocation checking

void handshake(handshake_type type, wintls::error_code &ec)¶

Perform TLS handshaking.

This function is used to perform TLS handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters:

type – The handshake_type to be performed, i.e. client or server.
ec – Set to indicate what error occurred, if any.

void handshake(handshake_type type)¶

Perform TLS handshaking.

This function is used to perform TLS handshaking on the stream. The function call will block until handshaking is complete or an error occurs.

Parameters:: type – The handshake_type to be performed, i.e. client or server.
Throws:: wintls::system_error – Thrown on failure.

template<class CompletionToken> auto async_handshake(handshake_type type, CompletionToken &&handler)¶

Start an asynchronous TLS handshake.

This function is used to asynchronously perform an TLS handshake on the stream. This function call always returns immediately.

Note

Regardless of whether the asynchronous operation completes immediately or not, the handler will not be invoked from within this function. Invocation of the handler will be performed in a manner equivalent to using net::post.

Parameters:

type – The handshake_type to be performed, i.e. client or server.
handler – The handler to be called when the operation completes. The implementation takes ownership of the handler by performing a decay-copy. The handler must be invocable with this signature:
```
void handler(
    wintls::error_code // Result of operation.
);
```

template<class MutableBufferSequence> size_t read_some(const MutableBufferSequence &buffers, wintls::error_code &ec)¶

Read some data from the stream.

This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Note

The read_some operation may not read all of the requested number of bytes. Consider using the net::read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

Parameters:

ec – Set to indicate what error occurred, if any.
buffers – The buffers into which the data will be read.

Returns:

The number of bytes read.

template<class MutableBufferSequence> size_t read_some(const MutableBufferSequence &buffers)¶

Read some data from the stream.

This function is used to read data from the stream. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

Note

Parameters:: buffers – The buffers into which the data will be read.
Throws:: wintls::system_error – Thrown on failure.
Returns:: The number of bytes read.

template<class MutableBufferSequence, class CompletionToken> auto async_read_some(const MutableBufferSequence &buffers, CompletionToken &&handler)¶

Start an asynchronous read.

This function is used to asynchronously read one or more bytes of data from the stream. The function call always returns immediately.

Note

The async_read_some operation may not read all of the requested number of bytes. Consider using the net::async_read function if you need to ensure that the requested amount of data is read before the asynchronous operation completes.

Parameters:

buffers – The buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler – The handler to be called when the read operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
```
void handler(
    const wintls::error_code& error, // Result of operation.
    std::size_t bytes_transferred    // Number of bytes read.
); 
```

template<class ConstBufferSequence> std::size_t write_some(const ConstBufferSequence &buffers, wintls::error_code &ec)¶

Write some data to the stream.

This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.

Note

The write_some operation may not transmit all of the data to the peer. Consider using the net::write function if you need to ensure that all data is written before the blocking operation completes.

Parameters:

buffers – The data to be written.
ec – Set to indicate what error occurred, if any.

Returns:

The number of bytes written.

template<class ConstBufferSequence> std::size_t write_some(const ConstBufferSequence &buffers)¶

Write some data to the stream.

This function is used to write data on the stream. The function call will block until one or more bytes of data has been written successfully, or until an error occurs.

Note

Parameters:: buffers – The data to be written.
Throws:: wintls::system_error – Thrown on failure.
Returns:: The number of bytes written.

template<class ConstBufferSequence, class CompletionToken> auto async_write_some(const ConstBufferSequence &buffers, CompletionToken &&handler)¶

Start an asynchronous write.

This function is used to asynchronously write one or more bytes of data to the stream. The function call always returns immediately.

Note

The async_write_some operation may not transmit all of the data to the peer. Consider using the net::async_write function if you need to ensure that all data is written before the asynchronous operation completes.

Parameters:

buffers – The data to be written to the stream. Although the buffers object may be copied as necessary, ownership of the underlying buffers is retained by the caller, which must guarantee that they remain valid until the handler is called.
handler – The handler to be called when the write operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:
```
void handler(
    const wintls::error_code& error, // Result of operation.
    std::size_t bytes_transferred    // Number of bytes written.
);
```

void shutdown(wintls::error_code &ec)¶

Shut down TLS on the stream.

This function is used to shut down TLS on the stream. The function call will block until TLS has been shut down or an error occurs.

Parameters:: ec – Set to indicate what error occurred, if any.

void shutdown()¶

Shut down TLS on the stream.

This function is used to shut down TLS on the stream. The function call will block until TLS has been shut down or an error occurs.

Throws:: wintls::system_error – Thrown on failure.

template<class CompletionToken> auto async_shutdown(CompletionToken &&handler)¶

Asynchronously shut down TLS on the stream.

This function is used to asynchronously shut down TLS on the stream. This function call always returns immediately.

Parameters:

handler – The handler to be called when the shutdown operation completes. Copies will be made of the handler as required. The equivalent function signature of the handler must be:

 void handler(
     const wintls::error_code& error // Result of operation.
);