caf::net::ssl Namespace Reference

Contains wrappers for convenient access to SSL. More...

Classes
class	connection
	SSL state for a single connections. More...
class	context
	SSL state, shared by multiple connections. More...
class	tcp_acceptor
	Wraps a TCP accept socket and an SSL context. More...
class	transport
	Implements a octet stream transport that manages a stream socket with encrypted communication over TLS. More...

Enumerations
enum class	dtls {   any ,   v1_0 ,   v1_2 }
	Configures the allowed DTLS versions on a context.
enum class	errc : uint8_t {   none = 0 ,   closed ,   want_read ,   want_write ,   want_connect ,   want_accept ,   want_x509_lookup ,   want_async ,   want_async_job ,   want_client_hello ,   syscall_failed ,   fatal ,   unspecified }
	SSL error code for I/O operations on a connection. More...
enum class	format {   pem ,   asn1 }
	Format of keys and certificates. More...
enum class	tls {   any ,   v1_0 ,   v1_1 ,   v1_2 ,   v1_3 }
	Configures the allowed TLS versions on a context.
enum class	verify_t
	Bitmask type for the SSL verification mode.

Functions
bool	valid (const connection &conn)
auto	emplace_context (tls min_version, tls max_version=tls::any)
auto	emplace_server (tls min_version, tls max_version=tls::any)
auto	emplace_client (tls min_version, tls max_version=tls::any)
auto	emplace_context (dtls min_version, dtls max_version=dtls::any)
auto	emplace_server (dtls min_version, dtls max_version=dtls::any)
auto	emplace_client (dtls min_version, dtls max_version=dtls::any)
auto	new_connection (stream_socket fd)
	Creates a new SSL connection on fd.
auto	new_connection (stream_socket fd, close_on_shutdown_t)
	Creates a new SSL connection on fd.
auto	enable_default_verify_paths ()
	Configure a context to use the default locations for loading CA certificates.
auto	add_verify_path (dsl::arg::cstring path)
	Configures the context to load CA certificate from a directory.
auto	add_verify_path_if (dsl::arg::cstring path)
	Configures the context to load CA certificate from a directory if all arguments are non-null.
auto	load_verify_file (dsl::arg::cstring path)
	Loads a CA certificate file.
auto	load_verify_file_if (dsl::arg::cstring path)
	Loads a CA certificate file if all arguments are non-null.
auto	use_certificate_file (dsl::arg::cstring path, dsl::arg::val< format > file_format)
	Loads the first certificate found in given file.
auto	use_certificate_file_if (dsl::arg::cstring path, dsl::arg::val< format > file_format)
	Loads the first certificate found in given file if all arguments are non-null.
auto	use_certificate_chain_file (dsl::arg::cstring path)
	Loads a certificate chain from a PEM-formatted file.
auto	use_certificate_chain_file_if (dsl::arg::cstring path)
	Loads a certificate chain from a PEM-formatted file if all arguments are non-null.
auto	use_private_key_file (dsl::arg::cstring path, dsl::arg::val< format > file_format)
	Loads the first private key found in given file.
auto	use_private_key_file_if (dsl::arg::cstring path, dsl::arg::val< format > file_format)
	Loads the first private key found in given file if all arguments are non-null.
CAF_NET_EXPORT void	startup ()
	Initializes the SSL layer.
CAF_NET_EXPORT void	cleanup ()
	Cleans up any state for the SSL layer.
bool CAF_NET_EXPORT	valid (const tcp_acceptor &acc)
	Checks whether acc has a valid socket descriptor.
void CAF_NET_EXPORT	close (tcp_acceptor &acc)
	Closes the socket of obj.
expected< connection > CAF_NET_EXPORT	accept (tcp_acceptor &acc)
	Tries to accept a new connection on acc.
constexpr int	to_integer (verify_t x)
verify_t &	operator|= (verify_t &x, verify_t y) noexcept
constexpr verify_t	operator| (verify_t x, verify_t y) noexcept

Variables
constexpr close_on_shutdown_t	close_on_shutdown = close_on_shutdown_t{}

Detailed Description

Contains wrappers for convenient access to SSL.

Enumeration Type Documentation

errc

enum class caf::net::ssl::errc : uint8_t

strong

SSL error code for I/O operations on a connection.

Enumerator
none	Not-an-error.
closed	SSL has closed the connection. The underlying transport may remain open.
want_read	Temporary error. SSL failed to write to a socket because it needs to read first.
want_write	Temporary error. SSL failed to read from a socket because it needs to write first.
want_connect	Temporary error. The SSL client handshake did not complete yet.
want_accept	Temporary error. The SSL server handshake did not complete yet.
want_x509_lookup	Temporary error. An application callback has asked to be called again.
want_async	Temporary error. An asynchronous is still processing data and the user must call the preceding function again from the same thread.
want_async_job	The pool for starting asynchronous jobs is exhausted.
want_client_hello	Temporary error. An application callback has asked to be called again.
syscall_failed	The operating system reported a non-recoverable, fatal I/O error. Users may consult OS-specific means to retrieve the underlying error, e.g., errno on UNIX or WSAGetLastError on Windows.
fatal	SSL encountered a fatal error, usually a protocol violation.
unspecified	An unexpected error occurred with no further explanation available.

format

enum class caf::net::ssl::format

strong

Format of keys and certificates.

Enumerator
pem	Privacy Enhanced Mail format.
asn1	Binary ASN1 format.

Function Documentation

accept()

expected< connection > CAF_NET_EXPORT caf::net::ssl::accept

(

tcp_acceptor &

acc

)

Tries to accept a new connection on acc.

On success, wraps the new socket into an SSL connection and returns it.

add_verify_path()

auto caf::net::ssl::add_verify_path

(

dsl::arg::cstring

path

)

Configures the context to load CA certificate from a directory.

Parameters

path	Null-terminated string with a path to a directory. Files in the directory must use the CA subject name hash value as file name with a suffix to disambiguate multiple certificates, e.g., 9d66eef0.0 and 9d66eef0.1.

Returns

a function object for chaining expected<T>::and_then().

add_verify_path_if()

auto caf::net::ssl::add_verify_path_if

(

dsl::arg::cstring

path

)

Configures the context to load CA certificate from a directory if all arguments are non-null.

Otherwise, does nothing.

Parameters

path	Null-terminated string with a path to a directory. Files in the directory must use the CA subject name hash value as file name with a suffix to disambiguate multiple certificates, e.g., 9d66eef0.0 and 9d66eef0.1.

Returns

a function object for chaining expected<T>::and_then().

cleanup()

CAF_NET_EXPORT void caf::net::ssl::cleanup

(

)

Cleans up any state for the SSL layer.

Like startup, this step is mandatory for some versions of the linked SSL library.

enable_default_verify_paths()

auto caf::net::ssl::enable_default_verify_paths

(

)

Configure a context to use the default locations for loading CA certificates.

Returns

a function object for chaining expected<T>::and_then().

load_verify_file()

auto caf::net::ssl::load_verify_file

(

dsl::arg::cstring

path

)

Loads a CA certificate file.

Parameters

path	String with a path to a single PEM file.

Returns

true on success, false otherwise and last_error can be used to retrieve a human-readable error representation.

a function object for chaining expected<T>::and_then().

load_verify_file_if()

auto caf::net::ssl::load_verify_file_if

(

dsl::arg::cstring

path

)

Loads a CA certificate file if all arguments are non-null.

Otherwise, does nothing.

Parameters

path	String with a path to a single PEM file.

Returns

true on success, false otherwise and last_error can be used to retrieve a human-readable error representation.

a function object for chaining expected<T>::and_then().

new_connection() [1/2]

auto caf::net::ssl::new_connection

(

stream_socket

fd

)

Creates a new SSL connection on fd.

The connection does not take ownership of the socket, i.e., does not close the socket when the SSL session end or on error.

Parameters

fd	the stream socket for adding encryption.

Returns

a function object for chaining expected<T>::and_then().

new_connection() [2/2]

auto caf::net::ssl::new_connection	(	stream_socket	fd,
		close_on_shutdown_t
	)

Creates a new SSL connection on fd.

The connection takes ownership of the socket, i.e., closes the socket when the SSL session ends.

Parameters

fd	the stream socket for adding encryption.

Returns

a function object for chaining expected<T>::and_then().

startup()

CAF_NET_EXPORT void caf::net::ssl::startup

(

)

Initializes the SSL layer.

Depending on the version, this may be mandatory to call before accessing any SSL functions (OpenSSL prior to version 1.1) or it may have no effect (newer versions of OpenSSL).

use_certificate_chain_file()

auto caf::net::ssl::use_certificate_chain_file

(

dsl::arg::cstring

path

)

Loads a certificate chain from a PEM-formatted file.

Note

calls SSL_CTX_use_certificate_chain_file

Returns

a function object for chaining expected<T>::and_then().

use_certificate_chain_file_if()

auto caf::net::ssl::use_certificate_chain_file_if

(

dsl::arg::cstring

path

)

Loads a certificate chain from a PEM-formatted file if all arguments are non-null.

Otherwise, does nothing.

Note

calls SSL_CTX_use_certificate_chain_file

Returns

a function object for chaining expected<T>::and_then().

use_certificate_file()

auto caf::net::ssl::use_certificate_file	(	dsl::arg::cstring	path,
		dsl::arg::val< format >	file_format
	)

Loads the first certificate found in given file.

Parameters

path	Null-terminated string with a path to a single file.
file_format	Denotes the format of the certificate file.

Returns

a function object for chaining expected<T>::and_then().

use_certificate_file_if()

auto caf::net::ssl::use_certificate_file_if	(	dsl::arg::cstring	path,
		dsl::arg::val< format >	file_format
	)

Loads the first certificate found in given file if all arguments are non-null.

Otherwise, does nothing.

Parameters

path	Null-terminated string with a path to a single file.
file_format	Denotes the format of the certificate file.

Returns

a function object for chaining expected<T>::and_then().

use_private_key_file()

auto caf::net::ssl::use_private_key_file	(	dsl::arg::cstring	path,
		dsl::arg::val< format >	file_format
	)

Loads the first private key found in given file.

Returns

a function object for chaining expected<T>::and_then().

use_private_key_file_if()

auto caf::net::ssl::use_private_key_file_if	(	dsl::arg::cstring	path,
		dsl::arg::val< format >	file_format
	)

Loads the first private key found in given file if all arguments are non-null.

Otherwise, does nothing.

Returns

a function object for chaining expected<T>::and_then().