E-MailRelay
Public Types | Public Member Functions | Static Public Member Functions | List of all members
GSsl::Library Class Reference

A singleton class for initialising the underlying TLS library. More...

#include <gssl.h>

Public Types

using LogFn = void(*)(int, const std::string &)
 

Public Member Functions

 Library (bool active=true, const std::string &library_config=std::string(), LogFn=Library::log, bool verbose=true)
 Constructor. More...
 
 ~Library ()
 Destructor. Cleans up the underlying TLS library. More...
 
void addProfile (const std::string &profile_name, bool is_server_profile, const std::string &key_file=std::string(), const std::string &cert_file=std::string(), const std::string &ca_path=std::string(), const std::string &default_peer_certificate_name=std::string(), const std::string &default_peer_host_name=std::string(), const std::string &profile_config=std::string())
 Creates a named Profile object that can be retrieved by profile(). More...
 
bool hasProfile (const std::string &profile_name) const
 Returns true if the named profile has been add()ed. More...
 
const Profileprofile (const std::string &profile_name) const
 Returns an opaque reference to the named profile. More...
 
bool enabled () const
 Returns true if this is a real TLS library and the constructor's active parameter was set. More...
 
std::string id () const
 Returns the TLS library name and version. More...
 
bool generateKeyAvailable () const
 Returns true if generateKey() is implemented. More...
 
std::string generateKey (const std::string &name) const
 Generates a test certificate as a PEM string with embedded newlines, also containing the private-key. More...
 
Digester digester (const std::string &name, const std::string &state=std::string(), bool need_state=false) const
 Returns a digester object. More...
 
 Library (const Library &)=delete
 
 Library (Library &&)=delete
 
void operator= (const Library &)=delete
 
void operator= (Library &&)=delete
 

Static Public Member Functions

static void log (int level, const std::string &line)
 The default logging callback function, where the level is 1 for debug, 2 for info, 3 for warnings, and 4 for errors. More...
 
static Libraryinstance ()
 Returns a pointer to a library object, if any. More...
 
static LibraryImpBaseimpstance ()
 Returns a reference to the pimple object when enabled(). More...
 
static bool real ()
 Returns true if this is a real TLS library. More...
 
static std::string credit (const std::string &prefix, const std::string &eol, const std::string &eot)
 Returns a multi-line library credit for all available TLS libraries. More...
 
static std::string ids ()
 Returns a concatenation of all available TLS library names and versions. More...
 
static bool enabledAs (const std::string &profile_name)
 A static convenience function that returns true if there is an enabled() Library instance() that has the named profile. More...
 
static G::StringArray digesters (bool need_state=false)
 Returns a list of hash function names (such as "MD5") that the TLS library can do, ordered roughly from strongest to weakest. More...
 

Detailed Description

A singleton class for initialising the underlying TLS library.

The library is configured with one or more named "profiles", and Protocol objects are constructed with reference to a particular profile. Typical profile names are "server" and "client".

Definition at line 252 of file gssl.h.

Member Typedef Documentation

◆ LogFn

using GSsl::Library::LogFn = void (*)(int, const std::string &)

Definition at line 255 of file gssl.h.

Constructor & Destructor Documentation

◆ Library()

GSsl::Library::Library ( bool  active = true,
const std::string &  library_config = std::string(),
LogFn  log_fn = Library::log,
bool  verbose = true 
)
explicit

Constructor.

The 'active' parameter can be set to false as an optimisation if the library is not going to be used; calls to addProfile() will do nothing, calls to hasProfile() will return false, and calls to profile() will throw.

The library-config parameter should be empty by default; the format and interpretation are undefined at this interface.

Definition at line 30 of file gssl.cpp.

◆ ~Library()

GSsl::Library::~Library ( )

Destructor. Cleans up the underlying TLS library.

Definition at line 45 of file gssl.cpp.

Member Function Documentation

◆ addProfile()

void GSsl::Library::addProfile ( const std::string &  profile_name,
bool  is_server_profile,
const std::string &  key_file = std::string(),
const std::string &  cert_file = std::string(),
const std::string &  ca_path = std::string(),
const std::string &  default_peer_certificate_name = std::string(),
const std::string &  default_peer_host_name = std::string(),
const std::string &  profile_config = std::string() 
)

Creates a named Profile object that can be retrieved by profile().

A typical application will have two profiles named "client" and "server". The "is-server-profile" flag indicates whether Protocol::connect() or Protocol::accept() will be used.

The "key-file" and "cert-file" parameters point to a PEM files containing our own key and certificate, and this can be the same file if it contains both. These are required if acting as a server, but if not supplied this method will succeed with the failures occuring in any subsequent server-side session setup.

The "ca-path" parameter points to a file or directory containing a database of CA certificates used for peer certificate verification. If this is "<none>" then a server will not ask its client for a certificate; if it is empty then the peer certificate will be requested, but the server will not require a certificate from the client, and any certificate received will not be not verified; if it is a file system path or "<default>" then a peer certificate will be required and it will be verified against the CA database.

The "default-peer-certificate-name" parameter is used by Protocol objects created from this Profile in cases when the Protocol does not get a more specific peer-certificate-name passed in its constructor.

Similarly the "default-peer-host-name" is used by Protocol objects if they do not get a more specific peer-host-name in their constructor.

The "profile-config" parameter is used for any additional configuration items; the format and interpretation are undefined at this interface.

Definition at line 81 of file gssl.cpp.

◆ credit()

std::string GSsl::Library::credit ( const std::string &  prefix,
const std::string &  eol,
const std::string &  eot 
)
static

Returns a multi-line library credit for all available TLS libraries.

Definition at line 30 of file gssl_use_openssl.cpp.

◆ digester()

GSsl::Digester GSsl::Library::digester ( const std::string &  name,
const std::string &  state = std::string(),
bool  need_state = false 
) const

Returns a digester object.

Definition at line 144 of file gssl.cpp.

◆ digesters()

G::StringArray GSsl::Library::digesters ( bool  need_state = false)
static

Returns a list of hash function names (such as "MD5") that the TLS library can do, ordered roughly from strongest to weakest.

Returns the empty list if there is no Library instance. If the boolean parameter is true then the returned list is limited to those hash functions that can generate and be initialised with an intermediate state.

Definition at line 139 of file gssl.cpp.

◆ enabled()

bool GSsl::Library::enabled ( ) const

Returns true if this is a real TLS library and the constructor's active parameter was set.

Definition at line 61 of file gssl.cpp.

◆ enabledAs()

bool GSsl::Library::enabledAs ( const std::string &  profile_name)
static

A static convenience function that returns true if there is an enabled() Library instance() that has the named profile.

Definition at line 103 of file gssl.cpp.

◆ generateKey()

std::string GSsl::Library::generateKey ( const std::string &  name) const

Generates a test certificate as a PEM string with embedded newlines, also containing the private-key.

Returns the empty string if not implemented. Throws on error. The implementation will normally be slow and blocking.

Definition at line 76 of file gssl.cpp.

◆ generateKeyAvailable()

bool GSsl::Library::generateKeyAvailable ( ) const

Returns true if generateKey() is implemented.

Definition at line 71 of file gssl.cpp.

◆ hasProfile()

bool GSsl::Library::hasProfile ( const std::string &  profile_name) const

Returns true if the named profile has been add()ed.

Definition at line 91 of file gssl.cpp.

◆ id()

std::string GSsl::Library::id ( ) const

Returns the TLS library name and version.

Definition at line 66 of file gssl.cpp.

◆ ids()

std::string GSsl::Library::ids ( )
static

Returns a concatenation of all available TLS library names and versions.

Definition at line 35 of file gssl_use_openssl.cpp.

◆ impstance()

GSsl::LibraryImpBase & GSsl::Library::impstance ( )
static

Returns a reference to the pimple object when enabled().

Used in implementations. Throws if none.

Definition at line 108 of file gssl.cpp.

◆ instance()

GSsl::Library * GSsl::Library::instance ( )
static

Returns a pointer to a library object, if any.

Definition at line 56 of file gssl.cpp.

◆ log()

void GSsl::Library::log ( int  level,
const std::string &  line 
)
static

The default logging callback function, where the level is 1 for debug, 2 for info, 3 for warnings, and 4 for errors.

There will be no level 1 logging if the constructor's 'verbose' flag was false.

Definition at line 129 of file gssl.cpp.

◆ profile()

const GSsl::Profile & GSsl::Library::profile ( const std::string &  profile_name) const

Returns an opaque reference to the named profile.

The profile can be used to construct a protocol instance.

Definition at line 96 of file gssl.cpp.

◆ real()

bool GSsl::Library::real ( )
static

Returns true if this is a real TLS library.

Definition at line 51 of file gssl.cpp.


The documentation for this class was generated from the following files: