Seastar
High performance C++ framework for concurrent servers
Classes | Typedefs | Enumerations | Functions
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_socketconnect (shared_ptr< certificate_credentials >, socket_address, sstring name={})
 
future< connected_socketconnect (shared_ptr< certificate_credentials >, socket_address, socket_address local, sstring name={})
 
::seastar::socket socket (shared_ptr< certificate_credentials >, sstring name={})
 
future< connected_socketwrap_client (shared_ptr< certificate_credentials >, connected_socket &&, sstring name={})
 
future< connected_socketwrap_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
typeOur own role in the TLS handshake (client vs. server)
subjectThe subject DN string
issuerThe issuer DN string

Enumeration Type Documentation

◆ session_type

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

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

◆ subject_alt_name_type

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