TLS security context. More...

#include <tlscontext.hpp>

Inheritance diagram for dodo::network::TLSContext:

Collaboration diagram for dodo::network::TLSContext:

[legend]

Public Types
enum	PeerVerification { PeerVerification::pvVerifyNone, PeerVerification::pvVerifyPeer, PeerVerification::pvVerifyFQDN }
	The TLS peer verification method. More...

enum	TLSVersion { TLSVersion::tls1_1, TLSVersion::tls1_2, TLSVersion::tls1_3, TLSVersion::tlsBest = tls1_3 }
	The TLS version. More...

Public Member Functions
	TLSContext (const PeerVerification &peerverficiation=PeerVerification::pvVerifyFQDN, const TLSVersion &tlsversion=TLSVersion::tlsBest, bool enableSNI=true, bool allowSANWildcards=true)
	Construct a TLS context. More...

	TLSContext (const YAML::Node &yaml)
	Construct a TLSContext from a YAML node. More...

SSL_CTX *	getContext () const
	Return a pointer to the SSL_CTX. More...

PeerVerification	getPeerVerification () const
	Return the getPeerVerification mode. More...

bool	isAllowSANWildcards () const
	If true, TLS will allow SAN wildcard matching. More...

bool	isSNIEnabled () const
	Return true when SNI (server Name Information) is to be enabled by TLSSocket objects using this TLSContext. More...

void	loadPEMIdentity (const std::string &certfile, const std::string &keyfile, const std::string &passphrase)
	Load a certificate and the corresponding private key for an identity. More...

void	loadPKCS12 (const std::string &p12file, const std::string &p12passphrase)
	Loads a private key, matching certificate and optional CA certificates (eg a truststore) from a PKCS12 file. More...

void	setCipherList (const std::string &cipherlist)
	Set a list of ciphers, separated by a colon, the TLSContext will accept. More...

long	setOptions (long option)
	Set SSL options. More...

void	setTrustPaths (const std::string &cafile, const std::string &capath)
	Trust all certificates (PEM format) in the specified file and/or directory. More...

Public Member Functions inherited from dodo::common::DebugObject
	DebugObject ()
	Default constructor does nothing. More...

virtual	~DebugObject ()
	Destructor does nothing. More...

std::string	debugString () const
	Return the object dump to string. More...

Static Public Member Functions
static PeerVerification	peerVerficiationFromString (const std::string &src)
	Get a PeerVerfication enum from a string. More...

static TLSVersion	tlsVersionFromString (const std::string &src)
	Convert the src string to a TLSVersion or throw a common::Exception if that mapping fails. More...

Private Member Functions
void	construct (const PeerVerification &peerverficiation, const TLSVersion &tlsversion, bool enableSNI, bool allowSANWildcards)
	Construct the TLSContext. More...

Static Private Member Functions
static void	InitializeSSL ()
	Initialize the SSL library. More...

static int	pem_passwd_cb (char buf, int size, int rwflag, void userdata)
	Password callback, returns the passphrase set in the TLS context by the passphrase argument of loadCertificate or pkeypassphrase argument of the loadPKCS12 method. More...

static void	ShutdownSSL ()
	Shutdown the SSL library. More...

Private Attributes
bool	allow_san_wildcards_
	Allow SAN names to match agains wildcards (eg foo.domain.org matches *.domain.org). More...

bool	enable_clr_
	Enable / disable CRL (Certificate Revocation List) checking. More...

bool	enable_sni_
	Enable / disable SNI on TLSSocket objects using this TLSContext. More...

std::string	passphrase_
	The passphrase to decrypt encrypted private keys (may be empty when the key is not encrypted). More...

PeerVerification	peerverficiation_
	The peer verification method used. More...

SSL_CTX *	tlsctx_
	The openssl SSL_CTX. More...

TLSVersion	tlsversion_
	The TLS version. More...

Additional Inherited Members
Protected Member Functions inherited from dodo::common::DebugObject
virtual std::string	debugDetail () const
	Descendant classes can override to dump details specific to the class. More...

std::string	debugHeader () const
	Generates a debug header (address of this object and a demangled class name. More...

Detailed Description

TLS security context.

A single TLSContext can be shared among multiple TLSSocket classes.

See Secure sockets for more information on the role of this class.

Todo:: Implement the OCSP protocol for revoked cert check

See also: http://www.zedwood.com/article/cpp-x509-certificate-revocation-check-by-ocsp; https://stackoverflow.com/questions/56253312/how-to-create-ocsp-request-using-openssl-in-c

Definition at line 50 of file tlscontext.hpp.

Member Enumeration Documentation

◆ PeerVerification

enum dodo::network::TLSContext::PeerVerification

strong

The TLS peer verification method.

PeerVerification	SSL_CTX_set_verify
pvVerifyNone	SSL_VERIFY_NONE
pvVerifyPeer	SSL_VERIFY_PEER \| SSL_VERIFY_FAIL_IF_NO_PEER_CERT
pvVerifyFQDN	SSL_VERIFY_PEER \| SSL_VERIFY_FAIL_IF_NO_PEER_CERT

PeerVerification	Server / accept	Client / connect
pvVerifyNone	encryption of traffic	encryption of traffic
pvVerifyPeer	pvVerifyNone + client must present trusted cert	pvVerifyNone + server must present trusted cert
pvVerifyFQDN	pvVerifyPeer	pvVerifyPeer + X509Certificate::verifyName()

See also: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_verify.html

Enumerator
pvVerifyNone	No peer verification - transmission is encrypted, peer is accepted even if peer certificate is invalid - so any peer can read all data sent.
pvVerifyPeer	The peer must have a trusted certificate (unless a anonymous cipher is used).
pvVerifyFQDN	As pvVerifyPeer, but the remote DNS name must match either the peer cert commonname or match one of the peer cert subjectAltNames.

Definition at line 80 of file tlscontext.hpp.

◆ TLSVersion

enum dodo::network::TLSContext::TLSVersion

strong

The TLS version.

Use tlsBest.

Enumerator
tls1_1	TLS 1.1 disables SSLv2, SSLv3 and TLS 1.0.
tls1_2	TLS 1.2 disables SSLv2, SSLv3, TLS 1.0 and TLS 1.1.
tls1_3	TLS 1.3 disables SSLv2, SSLv3, TLS 1.0, TLS 1.1 and TLS 1.2.
tlsBest	Use as default TLS version.

Definition at line 56 of file tlscontext.hpp.

Constructor & Destructor Documentation

◆ TLSContext() [1/2]

dodo::network::TLSContext::TLSContext	(	const PeerVerification &	peerverficiation = `PeerVerification::pvVerifyFQDN`,
		const TLSVersion &	tlsversion = `TLSVersion::tlsBest`,
		bool	enableSNI = `true`,
		bool	allowSANWildcards = `true`
	)

Construct a TLS context.

Use depends on the context being either server or client side, see TLSContext::PeerVerification.

Example for a server-side setup enforcing at least TLS1.3, requiring the peer to present a trusted certificate (pvVerifyPeer).

TLSContext tlscontext( PeerVerification::pvVerifyPeer,
                       TLSContext::TLSVersion::tls1_3,
                       false,                           // server-side does not need SNI
                       false );                         // server-side does not do SAN matching
tlscontext.loadPEMIdentity( "server.crt", "server.key", "passphrase" );

Parameters

peerverficiation	The TLSContext::PeerVerification method to use.
tlsversion	The TLS version to use. Use of default is less future code hassle.
enableSNI	Enable the Server Name Indication extension. Note that this exposes the target hostname
allowSANWildcards	Allow SAN wildcard matching under pvVerifyFQDN of TLSSocket connections as the hostname is sent unencrypted, facilitated all kinds of evil such as censorship. Use only when you must connect to a server that requires it.

See also: https://en.wikipedia.org/wiki/Server_Name_Indication

Definition at line 49 of file tlscontext.cpp.

References construct().

Here is the call graph for this function:

◆ TLSContext() [2/2]

dodo::network::TLSContext::TLSContext ( const YAML::Node & yaml )

Construct a TLSContext from a YAML node.

tlscontext:
  peer-verification: pvVerifyFQDN                    # mandatory
  tls-version: 1.3                                   # mandatory
  enable-sni: true                                   # mandatory
  allow-san-wildcards: true                          # mandatory
  trust:                                             # optional
    file: <path to PEM file>                         # at least one of file or path
    path: <path to directory with PEM files>         # at least one of file or path
  ciphers:                                           # mandatory
    - TLS_AES_256_GCM_SHA384                         # at least one entry
    - TLS_AES_128_GCM_SHA256

If the PEM format is used to provide keys and passphrase:

tlscontext:
  pem:
    private: <path to private key PEM>               # mandatory
    public: <path to public key PEM>                 # mandatory
    passphrase: <ENC[...]>                           # mandatory

If the PKCS12 format is used to provide keys and passphrase:

tlscontext:
  pkcs12:
    file: <path to PKCS12 file>                      # mandatory
    passphrase: <ENC[...]>                           # mandatory

Parameters

yaml	The YAML node to read from, which would be 'tlscontext' in the above examples.

Definition at line 57 of file tlscontext.cpp.

References dodo::common::Bytes::asString(), construct(), dodo::common::DataCrypt::decrypt(), loadPEMIdentity(), passphrase_, peerVerficiationFromString(), throw_Exception, tlsVersionFromString(), and dodo::common::YAML_read_key< bool >().

Here is the call graph for this function:

Member Function Documentation

◆ construct()

void dodo::network::TLSContext::construct	(	const PeerVerification &	peerverficiation,
		const TLSVersion &	tlsversion,
		bool	enableSNI,
		bool	allowSANWildcards
	)

private

Construct the TLSContext.

Parameters

peerverficiation	The TLSContext::PeerVerification method to use.
tlsversion	The TLS version to use. Use of default is less future code hassle.
enableSNI	Enable the Server Name Indication extension. Note that this exposes the target hostname
allowSANWildcards	Allow SAN wildcard matching under pvVerifyFQDN

Definition at line 75 of file tlscontext.cpp.

References allow_san_wildcards_, enable_sni_, dodo::common::getSSLErrors(), passphrase_, peerverficiation_, pem_passwd_cb(), pvVerifyNone, throw_ExceptionObject, tls1_1, tls1_2, tls1_3, tlsctx_, and tlsversion_.

Referenced by TLSContext().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getContext()

SSL_CTX* dodo::network::TLSContext::getContext ( ) const

inline

Return a pointer to the SSL_CTX.

Returns: a pointer to the SSL_CTX

Definition at line 215 of file tlscontext.hpp.

References tlsctx_.

◆ getPeerVerification()

PeerVerification dodo::network::TLSContext::getPeerVerification ( ) const

inline

Return the getPeerVerification mode.

Returns: the getPeerVerification.

Definition at line 221 of file tlscontext.hpp.

References peerverficiation_.

Referenced by dodo::network::TLSSocket::connect().

Here is the caller graph for this function:

◆ InitializeSSL()

void dodo::network::TLSContext::InitializeSSL ( )

staticprivate

Initialize the SSL library.

Definition at line 38 of file tlscontext.cpp.

◆ isAllowSANWildcards()

bool dodo::network::TLSContext::isAllowSANWildcards ( ) const

inline

If true, TLS will allow SAN wildcard matching.

Returns: True if wildcard matching on the SAN is allowed.

Definition at line 233 of file tlscontext.hpp.

References allow_san_wildcards_.

Referenced by dodo::network::TLSSocket::connect().

Here is the caller graph for this function:

◆ isSNIEnabled()

bool dodo::network::TLSContext::isSNIEnabled ( ) const

inline

Return true when SNI (server Name Information) is to be enabled by TLSSocket objects using this TLSContext.

Returns: true when SNI is enabled.

Definition at line 227 of file tlscontext.hpp.

References enable_sni_.

Referenced by dodo::network::TLSSocket::TLSSocket().

Here is the caller graph for this function:

◆ loadPEMIdentity()

void dodo::network::TLSContext::loadPEMIdentity	(	const std::string &	certfile,
		const std::string &	keyfile,
		const std::string &	passphrase
	)

Load a certificate and the corresponding private key for an identity.

Parameters

certfile	The certificate PEM file.
keyfile	The private key PEM file.
passphrase	The passphrase for the private key PEM file. If the private key is not protected by a passphrase its value is stored in this object nonetheless but unused.

Definition at line 126 of file tlscontext.cpp.

References dodo::common::getSSLErrors(), passphrase_, throw_ExceptionObject, and tlsctx_.

Referenced by TLSContext().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ loadPKCS12()

void dodo::network::TLSContext::loadPKCS12	(	const std::string &	p12file,
		const std::string &	p12passphrase
	)

Loads a private key, matching certificate and optional CA certificates (eg a truststore) from a PKCS12 file.

Parameters

p12file	The PKCS12 file to read from.
p12passphrase	The passphrase for the PKCS12 file.

Definition at line 142 of file tlscontext.cpp.

References dodo::common::getSSLErrors(), passphrase_, throw_ExceptionObject, and tlsctx_.

Here is the call graph for this function:

◆ peerVerficiationFromString()

TLSContext::PeerVerification dodo::network::TLSContext::peerVerficiationFromString ( const std::string & src )

static

Get a PeerVerfication enum from a string.

The comparison is case sensitive and must match the enum name ( "pvVerifyNone", "pvVerifyPeer", "pvVerifyFQDN" ). If the name does not translate, a common::Exception is thrown.

Parameters

src	The source string.

Returns: the PeerVerification.

Definition at line 195 of file tlscontext.cpp.

References pvVerifyFQDN, pvVerifyNone, pvVerifyPeer, and throw_Exception.

Referenced by TLSContext().

Here is the caller graph for this function:

◆ pem_passwd_cb()

int dodo::network::TLSContext::pem_passwd_cb	(	char *	buf,
		int	size,
		int	rwflag,
		void *	userdata
	)

staticprivate

Password callback, returns the passphrase set in the TLS context by the passphrase argument of loadCertificate or pkeypassphrase argument of the loadPKCS12 method.

Parameters

buf	The passphrase should be copied to here.
size	No more than size bytes should be copied into buf.
rwflag	0 = decryption 1 = encryption
userdata	Pass a pointer to the TLSContext object.

Returns: the character length of the passphrase string.

Definition at line 202 of file tlscontext.cpp.

References passphrase_.

Referenced by construct().

Here is the caller graph for this function:

◆ setCipherList()

void dodo::network::TLSContext::setCipherList ( const std::string & cipherlist )

Set a list of ciphers, separated by a colon, the TLSContext will accept.

There are differences between TLSVersion tough,

A few examples (note the hyphens and underscores)

TLS 1.3 TLS_AES_256_GCM_SHA384
TLS 1.2 DHE-RSA-AES256-GCM-SHA384
TLS 1.1 DHE-RSA-AES256-GCM-SHA384

See also: https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_cipher_list.html

A list of available ciphers is given by

$ openssl ciphers -tls1_2 -s

$ openssl ciphers -tls1_3 -s

Note that this call will not return a SystemError, but throws a dodo::common::Exception when the cipher list is invalid.

Parameters

cipherlist The cipherlist.

Exceptions

dodo::common::Exception

Definition at line 211 of file tlscontext.cpp.

References throw_ExceptionObject, tls1_3, tlsctx_, and tlsversion_.

◆ setOptions()

long dodo::network::TLSContext::setOptions ( long option )

Set SSL options.

Parameters

option The option or OR-ed options to apply.

Returns: The options applied.

See also: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_options.html

Definition at line 222 of file tlscontext.cpp.

References tlsctx_.

◆ setTrustPaths()

void dodo::network::TLSContext::setTrustPaths	(	const std::string &	cafile,
		const std::string &	capath
	)

Trust all certificates (PEM format) in the specified file and/or directory.

Parameters

cafile	A PEM file containing one or more certificates. If an empty string, unused.
capath	A directory containing certificate files. If an empty string, unused.

Definition at line 226 of file tlscontext.cpp.

References dodo::common::getSSLErrors(), throw_ExceptionObject, and tlsctx_.

Here is the call graph for this function:

◆ ShutdownSSL()

void dodo::network::TLSContext::ShutdownSSL ( )

staticprivate

Shutdown the SSL library.

Definition at line 44 of file tlscontext.cpp.

◆ tlsVersionFromString()

TLSContext::TLSVersion dodo::network::TLSContext::tlsVersionFromString ( const std::string & src )

static

Convert the src string to a TLSVersion or throw a common::Exception if that mapping fails.

TLSversion strings could be "1.1", "1.2" and "1.3".

Parameters

src	The source string.

Returns: The TLSVersion specified by the string.

Definition at line 237 of file tlscontext.cpp.

References throw_Exception, tls1_1, tls1_2, and tls1_3.

Referenced by TLSContext().

Here is the caller graph for this function:

Field Documentation

◆ allow_san_wildcards_

bool dodo::network::TLSContext::allow_san_wildcards_

private

Allow SAN names to match agains wildcards (eg foo.domain.org matches *.domain.org).

Definition at line 315 of file tlscontext.hpp.

Referenced by construct(), and isAllowSANWildcards().

◆ enable_clr_

bool dodo::network::TLSContext::enable_clr_

private

Enable / disable CRL (Certificate Revocation List) checking.

Definition at line 320 of file tlscontext.hpp.

◆ enable_sni_

bool dodo::network::TLSContext::enable_sni_

private

Enable / disable SNI on TLSSocket objects using this TLSContext.

Definition at line 310 of file tlscontext.hpp.

Referenced by construct(), and isSNIEnabled().

◆ passphrase_

std::string dodo::network::TLSContext::passphrase_

private

The passphrase to decrypt encrypted private keys (may be empty when the key is not encrypted).

Definition at line 305 of file tlscontext.hpp.

Referenced by construct(), loadPEMIdentity(), loadPKCS12(), pem_passwd_cb(), and TLSContext().

◆ peerverficiation_

PeerVerification dodo::network::TLSContext::peerverficiation_

private

The peer verification method used.

Definition at line 300 of file tlscontext.hpp.

Referenced by construct(), and getPeerVerification().

◆ tlsctx_

SSL_CTX* dodo::network::TLSContext::tlsctx_

private

The openssl SSL_CTX.

Definition at line 290 of file tlscontext.hpp.

Referenced by construct(), getContext(), loadPEMIdentity(), loadPKCS12(), setCipherList(), setOptions(), and setTrustPaths().

◆ tlsversion_

TLSVersion dodo::network::TLSContext::tlsversion_

private

The TLS version.

Definition at line 295 of file tlscontext.hpp.

Referenced by construct(), and setCipherList().

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

src/include/network/tlscontext.hpp
src/lib/network/tlscontext.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ PeerVerification

◆ TLSVersion

Constructor & Destructor Documentation

◆ TLSContext() [1/2]

◆ TLSContext() [2/2]

Member Function Documentation

◆ construct()

◆ getContext()

◆ getPeerVerification()

◆ InitializeSSL()

◆ isAllowSANWildcards()

◆ isSNIEnabled()

◆ loadPEMIdentity()

◆ loadPKCS12()

◆ peerVerficiationFromString()

◆ pem_passwd_cb()

◆ setCipherList()

◆ setOptions()

◆ setTrustPaths()

◆ ShutdownSSL()

◆ tlsVersionFromString()

Field Documentation

◆ allow_san_wildcards_

◆ enable_clr_

◆ enable_sni_

◆ passphrase_

◆ peerverficiation_

◆ tlsctx_

◆ tlsversion_