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	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::ostream &	operator<< (std::ostream &, subject_alt_name_type)
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={})
::seastar::socket	socket (shared_ptr< certificate_credentials >, sstring name={})
future< connected_socket >	wrap_client (shared_ptr< certificate_credentials >, connected_socket &&, sstring name={})
future< connected_socket >	wrap_server (shared_ptr< server_credentials >, connected_socket &&)
server_socket	listen (shared_ptr< server_credentials >, socket_address sa, listen_options opts=listen_options())
server_socket	listen (shared_ptr< server_credentials >, server_socket)

---

Class Documentation

seastar::tls::reloadable_credentials

class seastar::tls::reloadable_credentials

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()

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).

Parameters

name	An optional expected server name for the remote end point

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.

operator<<()

std::ostream& seastar::tls::operator<<	(	std::ostream &	,
		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"

socket()

::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).

Parameters

name	An optional expected server name for the remote end point

wrap_client()

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

Wraps an existing connection in SSL/TLS.