seastar::tls Namespace Reference

Detailed Description

Relatively thin SSL wrapper for socket IO. (Can be expanded to other IO forms).

The current underlying mechanism is gnutls, however, all interfaces are kept agnostic, so in theory it could be replaced with OpenSSL or similar.

Classes
class	dh_params
class	x509_cert
class	abstract_credentials
class	reloadable_credentials
class	certificate_credentials
class	verification_error
class	server_credentials
class	credentials_builder
struct	tls_options
	TLS configuration options. More...
struct	subject_alt_name

Typedefs
typedef std::basic_string_view< char >	blob
using	dn_callback = noncopyable_function< void(session_type type, sstring subject, sstring issuer)>
using	reload_callback = std::function< void(const std::unordered_set< sstring > &, std::exception_ptr)>

Enumerations
enum class	x509_crt_format { DER , PEM }
enum class	session_type { CLIENT , SERVER }
enum class	client_auth { NONE , REQUEST , REQUIRE }
enum class	subject_alt_name_type {   dnsname = 1 , rfc822name , uri , ipaddress ,   othername , dn }

Functions
future< std::optional< session_dn > >	get_dn_information (connected_socket &socket)
future< std::vector< subject_alt_name > >	get_alt_name_information (connected_socket &socket, std::unordered_set< subject_alt_name_type > types={})
std::ostream &	operator<< (std::ostream &, const subject_alt_name::value_type &)
std::ostream &	operator<< (std::ostream &, const subject_alt_name &)
std::string_view	format_as (subject_alt_name_type)
std::ostream &	operator<< (std::ostream &, subject_alt_name_type)
const std::error_category &	error_category ()
future< connected_socket >	connect (shared_ptr< certificate_credentials >, socket_address, sstring name)
future< connected_socket >	connect (shared_ptr< certificate_credentials >, socket_address, socket_address local, sstring name)
future< connected_socket >	connect (shared_ptr< certificate_credentials >, socket_address, tls_options option={})
future< connected_socket >	connect (shared_ptr< certificate_credentials >, socket_address, socket_address local, tls_options options={})
::seastar::socket	socket (shared_ptr< certificate_credentials >, sstring name)
::seastar::socket	socket (shared_ptr< certificate_credentials >, tls_options options={})
future< connected_socket >	wrap_client (shared_ptr< certificate_credentials >, connected_socket &&, sstring name)
future< connected_socket >	wrap_server (shared_ptr< server_credentials >, connected_socket &&)
future< connected_socket >	wrap_client (shared_ptr< certificate_credentials >, connected_socket &&, tls_options options={})
server_socket	listen (shared_ptr< server_credentials >, socket_address sa, listen_options opts=listen_options())
server_socket	listen (shared_ptr< server_credentials >, server_socket)

Variables
const int	ERROR_UNKNOWN_COMPRESSION_ALGORITHM
const int	ERROR_UNKNOWN_CIPHER_TYPE
const int	ERROR_INVALID_SESSION
const int	ERROR_UNEXPECTED_HANDSHAKE_PACKET
const int	ERROR_UNKNOWN_CIPHER_SUITE
const int	ERROR_UNKNOWN_ALGORITHM
const int	ERROR_UNSUPPORTED_SIGNATURE_ALGORITHM
const int	ERROR_SAFE_RENEGOTIATION_FAILED
const int	ERROR_UNSAFE_RENEGOTIATION_DENIED
const int	ERROR_UNKNOWN_SRP_USERNAME
const int	ERROR_PREMATURE_TERMINATION

---

Class Documentation

seastar::tls::reloadable_credentials

class seastar::tls::reloadable_credentials

seastar::tls::tls_options

struct seastar::tls::tls_options

Class Members
sstring	server_name	server name to be used for the SNI TLS extension
bool	wait_for_eof_on_shutdown	whether to wait for EOF from server on session termination

seastar::tls::subject_alt_name

struct seastar::tls::subject_alt_name

Class Members
typedef variant< sstring, inet_address >	value_type

Class Members
subject_alt_name_type	type
value_type	value

Typedef Documentation

dn_callback

using seastar::tls::dn_callback = typedef noncopyable_function<void(session_type type, sstring subject, sstring issuer)>

Callback prototype for receiving Distinguished Name (DN) information

Parameters

type	Our own role in the TLS handshake (client vs. server)
subject	The subject DN string
issuer	The issuer DN string

Enumeration Type Documentation

session_type

enum seastar::tls::session_type

strong

Enum like tls::session::type but independent of gnutls headers

Warning

Uses a different internal encoding than tls::session::type

subject_alt_name_type

enum seastar::tls::subject_alt_name_type

strong

Subject alt name types.

Function Documentation

connect() [1/2]

future<connected_socket> seastar::tls::connect	(	shared_ptr< certificate_credentials >	,
		socket_address	,
		sstring	name
	)

Creates a TLS client connection using the default network stack and the supplied credentials. Typically these should contain enough information to validate the remote certificate (i.e. trust info).

ATTN: The method is going to be deprecated

Parameters

name	The expected server name for the remote end point

connect() [2/2]

future<connected_socket> seastar::tls::connect	(	shared_ptr< certificate_credentials >	,
		socket_address	,
		tls_options	option = {}
	)

Creates a TLS client connection using the default network stack and the supplied credentials. Typically these should contain enough information to validate the remote certificate (i.e. trust info).

Parameters

options

Optional additional session configuration

error_category()

const std::error_category& seastar::tls::error_category

(

)

Error handling.

The error_category instance used by exceptions thrown by TLS

format_as()

std::string_view seastar::tls::format_as

(

subject_alt_name_type

)

Alt name to string. Note: because naming of alternative names is inconsistent between tools, and because openssl is probably more popular when creating certs anyway, this routine will be inconsistent with both gnutls and openssl (though more in line with the latter) and name the constants as follows:

dnsname: "DNS" rfc822name: "EMAIL" uri: "URI" ipaddress "IP" othername: "OTHERNAME" dn: "DIRNAME"

get_alt_name_information()

future<std::vector<subject_alt_name> > seastar::tls::get_alt_name_information	(	connected_socket &	socket,
		std::unordered_set< subject_alt_name_type >	types = {}
	)

Returns the alt name entries of matching types, or all entries if 'types' is empty The values are extracted from the client authentication certificate, if available. If no certificate authentication is used in the connection, en empty list is returned.

If the socket is not connected a system_error exception will be thrown. If the socket is not a TLS socket an exception will be thrown.

get_dn_information()

future<std::optional<session_dn> > seastar::tls::get_dn_information

(

connected_socket &

socket

)

Get distinguished name from the leaf certificate in the certificate chain that the connected peer is using. This function forces the TLS handshake. If the handshake didn't happen before the call to 'get_dn_information' it will be completed when the returned future will become ready. The function returns DN information on success. If the peer didn't send the certificate during the handshake the function returns nullopt. If the socket is not connected the system_error exception will be thrown.

listen()

server_socket seastar::tls::listen	(	shared_ptr< server_credentials >	,
		socket_address	sa,
		listen_options	opts = listen_options()
	)

Creates a server socket that accepts SSL/TLS clients using default network stack and the supplied credentials. The credentials object should contain certificate info for the server and optionally trust/crl data.

socket() [1/2]

::seastar::socket seastar::tls::socket	(	shared_ptr< certificate_credentials >	,
		sstring	name
	)

Creates a socket through which a TLS client connection can be created, using the default network stack and the supplied credentials. Typically these should contain enough information to validate the remote certificate (i.e. trust info).

ATTN: The method is going to be deprecated

Parameters

name	The expected server name for the remote end point

socket() [2/2]

::seastar::socket seastar::tls::socket	(	shared_ptr< certificate_credentials >	,
		tls_options	options = {}
	)

Creates a socket through which a TLS client connection can be created, using the default network stack and the supplied credentials. Typically these should contain enough information to validate the remote certificate (i.e. trust info).

Parameters

options

Optional additional session configuration

wrap_client() [1/2]

future<connected_socket> seastar::tls::wrap_client	(	shared_ptr< certificate_credentials >	,
		connected_socket &&	,
		sstring	name
	)

Wraps an existing connection in SSL/TLS.

ATTN: The method is going to be deprecated

Parameters

name	The expected server name for the remote end point

wrap_client() [2/2]

future<connected_socket> seastar::tls::wrap_client	(	shared_ptr< certificate_credentials >	,
		connected_socket &&	,
		tls_options	options = {}
	)

Wraps an existing connection in SSL/TLS.

Parameters

options

Optional additional session configuration

Variable Documentation

ERROR_UNKNOWN_COMPRESSION_ALGORITHM

const int seastar::tls::ERROR_UNKNOWN_COMPRESSION_ALGORITHM

extern

The more common error codes encountered in TLS. Not an exhaustive list. Add exports as needed.