ACE_SSL_Context Class Reference

A wrapper for the OpenSSL SSL_CTX related functions. More...

#include <SSL_Context.h>

Collaboration diagram for ACE_SSL_Context:

Public Types
enum	{ INVALID_METHOD = -1 , SSLv23_client , SSLv23_server , SSLv23 }

Public Member Functions
	ACE_SSL_Context ()
	Constructor.
	~ACE_SSL_Context ()
	Destructor.
int	set_mode (int mode=ACE_SSL_Context::SSLv23)
int	get_mode () const
SSL_CTX *	context ()
	Get the SSL context.
int	private_key_type () const
	Get the file name and file format used for the private key.
const char *	private_key_file_name () const
int	private_key (const char *file_name, int type=SSL_FILETYPE_PEM)
	Set the private key file.
int	verify_private_key ()
	Verify that the private key is valid.
int	certificate_type () const
	Get the file name and file format used for the certificate file.
const char *	certificate_file_name () const
int	certificate (const char *file_name, int type=SSL_FILETYPE_PEM)
	Set the certificate file.
int	certificate (X509 *cert)
	Load certificate from memory rather than a file.
int	certificate_chain (const char *file_name, int type=SSL_FILETYPE_PEM)
int	filter_versions (const char *filter)
	Parse the string and filter crypto versions accordingly.
bool	check_host (const ACE_INET_Addr &host, SSL *peerssl)
	verify the peer cert matches the host
int	load_trusted_ca (const char *ca_file=0, const char *ca_dir=0, bool use_env_defaults=true)
int	have_trusted_ca () const
void	set_verify_peer (int strict=0, int once=1, int depth=0)
void	default_verify_mode (int mode)
int	default_verify_mode () const
void	default_verify_callback (extern_C_CallBackVerify_t)
extern_C_CallBackVerify_t	default_verify_callback () const

Static Public Member Functions
static ACE_SSL_Context *	instance ()
static void	close ()
	Explicitly delete the Singleton context.
OpenSSL Random Number Generator Seed Related Methods
These are methods that can be used to seed OpenSSL's pseudo-random number generator. These methods can be called more than once.
static int	random_seed (const char *seed)
static int	egd_file (const char *socket_file)
static int	seed_file (const char *seed_file, long bytes=-1)
static void	report_error (unsigned long error_code)
	Print SSL error corresponding to the given error code.
static void	report_error ()
	Print the last SSL error for the current thread.

Diffie-Hellman (DH) Parameters
When using DSS-based certificates, Diffie-Hellman keys need to be exchanged. These must be provided in the form of DH key generation parameters loaded in, or as fixed keys hardcoded into the code itself. ACE_SSL supports loaded parameters.
SSL_CTX *	context_
	The SSL_CTX structure.
int	mode_
	Cache the mode so we can answer fast.
ACE_SSL_Data_File	private_key_
	The private key, certificate, and Diffie-Hellman parameters files.
ACE_SSL_Data_File	certificate_
	The SSL_CTX structure.
ACE_SSL_Data_File	dh_params_
	The SSL_CTX structure.
int	default_verify_mode_
	The default verify mode.
extern_C_CallBackVerify_t	default_verify_callback_
	The default verify callback.
int	have_ca_
	count of successful CA load attempts
int	dh_params (const char *file_name, int type=SSL_FILETYPE_PEM)
const char *	dh_params_file_name () const
	The SSL_CTX structure.
int	dh_params_file_type () const
	The SSL_CTX structure.
void	check_context ()
	Verify if the context has been initialized or not.
void	ssl_library_init ()
	@ More to document
void	ssl_library_fini ()
	The SSL_CTX structure.
	ACE_SSL_Context (const ACE_SSL_Context &)=delete
	The SSL_CTX structure.
ACE_SSL_Context &	operator= (const ACE_SSL_Context &)=delete
	The SSL_CTX structure.

Detailed Description

A wrapper for the OpenSSL SSL_CTX related functions.

This class provides a wrapper for the SSL_CTX data structure. Since most applications have a single SSL_CTX structure, this class can be used as a singleton.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
INVALID_METHOD
SSLv23_client
SSLv23_server
SSLv23

Constructor & Destructor Documentation

ACE_SSL_Context() [1/2]

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_SSL_Context::ACE_SSL_Context

(

)

Constructor.

~ACE_SSL_Context()

ACE_SSL_Context::~ACE_SSL_Context

(

)

Destructor.

ACE_SSL_Context() [2/2]

ACE_SSL_Context::ACE_SSL_Context ( const ACE_SSL_Context & )

privatedelete

The SSL_CTX structure.

Member Function Documentation

certificate() [1/2]

int ACE_SSL_Context::certificate	(	const char *	file_name,
		int	type = SSL_FILETYPE_PEM )

Set the certificate file.

certificate() [2/2]

int ACE_SSL_Context::certificate

(

X509 *

cert

)

Load certificate from memory rather than a file.

certificate_chain()

int ACE_SSL_Context::certificate_chain	(	const char *	file_name,
		int	type = SSL_FILETYPE_PEM )

Loads certificate chain file_name into ctx. Certificates must be sorted starting with the subject's certificate (actual client or server certificate), followed by ordered intermediate CA certificates. E.g. Let's Encrypt's intermediate certificate chain.

certificate_file_name()

ACE_INLINE const char * ACE_SSL_Context::certificate_file_name

(

)

const

certificate_type()

ACE_INLINE int ACE_SSL_Context::certificate_type

(

)

const

Get the file name and file format used for the certificate file.

check_context()

ACE_INLINE void ACE_SSL_Context::check_context ( )

private

Verify if the context has been initialized or not.

check_host()

bool ACE_SSL_Context::check_host	(	const ACE_INET_Addr &	host,
		SSL *	peerssl )

verify the peer cert matches the host

close()

void ACE_SSL_Context::close ( )

static

Explicitly delete the Singleton context.

context()

ACE_INLINE SSL_CTX * ACE_SSL_Context::context

(

)

Get the SSL context.

default_verify_callback() [1/2]

ACE_INLINE extern_C_CallBackVerify_t ACE_SSL_Context::default_verify_callback

(

)

const

default_verify_callback() [2/2]

ACE_INLINE void ACE_SSL_Context::default_verify_callback

(

extern_C_CallBackVerify_t

callback

)

Set and query the default verify callback for this context, it is inherited by all the ACE_SSL objects created using the context. It can be overriden on a per-ACE_SSL object.

default_verify_mode() [1/2]

ACE_INLINE int ACE_SSL_Context::default_verify_mode

(

)

const

default_verify_mode() [2/2]

ACE_INLINE void ACE_SSL_Context::default_verify_mode

(

int

mode

)

TODO: a implementation that will lookup the CTX table for the list of files and paths etc. Query the location of trusted certification authority certificates. Set and query the default verify mode for this context, it is inherited by all the ACE_SSL objects created using the context. It can be overriden on a per-ACE_SSL object.

dh_params()

int ACE_SSL_Context::dh_params	(	const char *	file_name,
		int	type = SSL_FILETYPE_PEM )

Load Diffie-Hellman parameters from file_name. The specified file can be a standalone file containing only DH parameters (e.g., as created by openssl dhparam), or it can be a certificate which has a PEM-encoded set of DH params concatenated on to i.

dh_params_file_name()

ACE_INLINE const char * ACE_SSL_Context::dh_params_file_name

(

)

const

The SSL_CTX structure.

dh_params_file_type()

ACE_INLINE int ACE_SSL_Context::dh_params_file_type

(

)

const

The SSL_CTX structure.

egd_file()

int ACE_SSL_Context::egd_file ( const char * socket_file )

static

Set the Entropy Gathering Daemon (EGD) UNIX domain socket file to read random seed values from.

filter_versions()

int ACE_SSL_Context::filter_versions

(

const char *

filter

)

Parse the string and filter crypto versions accordingly.

get_mode()

ACE_INLINE int ACE_SSL_Context::get_mode

(

)

const

have_trusted_ca()

ACE_INLINE int ACE_SSL_Context::have_trusted_ca

(

)

const

Test whether any CA locations have been successfully loaded and return the number of successful attempts.

Return values

>0	The number of successful CA load attempts.
0	If all CA load attempts have failed.

instance()

ACE_SSL_Context * ACE_SSL_Context::instance ( )

static

The Singleton context, the SSL components use the singleton if nothing else is available.

load_trusted_ca()

int ACE_SSL_Context::load_trusted_ca	(	const char *	ca_file = 0,
		const char *	ca_dir = 0,
		bool	use_env_defaults = true )

Load the location of the trusted certification authority certificates. Note that CA certificates are stored in PEM format as a sequence of certificates in ca_file or as a set of individual certificates in ca_dir (or both).

Note this method is called by set_mode() to load the default environment settings for ca_file and ca_dir, if any. This allows for automatic service configuration (and backward compatibility with previous versions).

Note that the underlying SSL function will add valid file and directory names to the load location lists maintained as part of the SSL_CTX table. It therefore doesn't make sense to keep a copy of the file and path name of the most recently added ca_file or ca_path.

Parameters

[in]	ca_file	CA file pathname. Passed to SSL_CTX_load_verify_locations() if not 0. If 0, behavior depends on the value of use_env_defaults.
[in]	ca_dir	CA directory pathname. Passed to SSL_CTX_load_verify_locations() if not 0. If 0, behavior depends on the value of use_env_defaults.
[in]	use_env_defaults	If false, the specified ca_file argument is passed to SSL_CTX_load_verify_locations(), regardless of its value. If true (the default), additional defaults can be applied to either ca_file, ca_dir, or both. The following additional defaults are applied when the ca_file argument is 0: The SSL_CERT_FILE environment variable will be queried for a file name to use as the ca_file argument. The environment variable name to query can be changed by supplying a ACE_SSL_CERT_FILE_ENV configuration item when building ACE. If there is no SSL_CERT_FILE in the current environment, the file specified by the ACE_DEFAULT_SSL_CERT_FILE ACE configuration item will be used. The default value is "cert.pem" on Windows and "/etc/ssl/cert.pem" on all other platforms. The following additional defaults are applied when the ca_dir argument is 0: The SSL_CERT_DIR environment variable will be queried for a file name to use as the ca_dir argument. The environment variable name to query can be changed by supplying a ACE_SSL_CERT_DIR_ENV configuration item when building ACE. If there is no SSL_CERT_DIR in the current environment, the directory specified by the ACE_DEFAULT_SSL_CERT_DIR ACE configuration item will be used. The default value is "certs" on Windows and "/etc/ssl/certs" on all other platforms.

Returns

0 for success or -1 on error.

See also

OpenSSL manual SSL_CTX_load_verify_locations(3) for a detailed description of the CA file and directory requirements and processing.

operator=()

ACE_SSL_Context & ACE_SSL_Context::operator= ( const ACE_SSL_Context & )

privatedelete

The SSL_CTX structure.

private_key()

int ACE_SSL_Context::private_key	(	const char *	file_name,
		int	type = SSL_FILETYPE_PEM )

Set the private key file.

Note

This method should only be called after a certificate has been set since key verification is performed against the certificate, among other things.

private_key_file_name()

ACE_INLINE const char * ACE_SSL_Context::private_key_file_name

(

)

const

private_key_type()

ACE_INLINE int ACE_SSL_Context::private_key_type

(

)

const

Get the file name and file format used for the private key.

random_seed()

int ACE_SSL_Context::random_seed ( const char * seed )

static

Seed the underlying random number generator. This value should have at least 128 bits of entropy.

report_error() [1/2]

void ACE_SSL_Context::report_error ( )

static

Print the last SSL error for the current thread.

report_error() [2/2]

void ACE_SSL_Context::report_error ( unsigned long error_code )

static

Print SSL error corresponding to the given error code.

seed_file()

int ACE_SSL_Context::seed_file ( const char * seed_file, long bytes = -1 )

static

Set the file that contains the random seed value state, and the amount of bytes to read. "-1" bytes causes the entire file to be read.

set_mode()

int ACE_SSL_Context::set_mode

(

int

mode = ACE_SSL_Context::SSLv23

)

Set the CTX mode. The mode can be set only once, afterwards the function has no effect and returns -1. Once the mode is set the underlying SSL_CTX is initialized and the class can be used. If the mode is not set, then the class automatically initializes itself to the default mode.

set_verify_peer()

void ACE_SSL_Context::set_verify_peer	(	int	strict = 0,
		int	once = 1,
		int	depth = 0 )

Todo

Complete this documentation where elipses(...) are used

@doc Use this method when certificate chain verification is required. The default server behaviour is SSL_VERIFY_NONE i.e. client certicates are requested for verified. This method can be used to configure server to request client certificates and perform the certificate verification. If <strict> is set true the client connection is rejected when certificate verification fails. Otherwise the session is accepted with a warning, which is the default behaviour. If <once> is set true (default), certificates are requested only once per session. The last parameter <depth> can be used to set the verification depth.

Note for verification to work correctly there should be a valid CA name list set using load_trusted_ca().

See also

OpenSSL documentation of SSL_CTX_set_verify(3) for details of the verification process.

OpenSSL documentation ... set_verify_depth(3) ...

Note that this method overrides the use of the default_verify_mode() method.

ssl_library_fini()

void ACE_SSL_Context::ssl_library_fini ( )

private

The SSL_CTX structure.

ssl_library_init()

void ACE_SSL_Context::ssl_library_init ( )

private

@ More to document

verify_private_key()

int ACE_SSL_Context::verify_private_key

(

)

Verify that the private key is valid.

Note

This method should only be called after a certificate has been set since key verification is performed against the certificate, among other things.

Member Data Documentation

certificate_

ACE_SSL_Data_File ACE_SSL_Context::certificate_

private

The SSL_CTX structure.

context_

SSL_CTX* ACE_SSL_Context::context_

private

The SSL_CTX structure.

default_verify_callback_

extern_C_CallBackVerify_t ACE_SSL_Context::default_verify_callback_

private

The default verify callback.

default_verify_mode_

int ACE_SSL_Context::default_verify_mode_

private

The default verify mode.

dh_params_

ACE_SSL_Data_File ACE_SSL_Context::dh_params_

private

The SSL_CTX structure.

have_ca_

int ACE_SSL_Context::have_ca_

private

count of successful CA load attempts

mode_

int ACE_SSL_Context::mode_

private

Cache the mode so we can answer fast.

private_key_

ACE_SSL_Data_File ACE_SSL_Context::private_key_

private

The private key, certificate, and Diffie-Hellman parameters files.

---

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

• SSL_Context.h
• SSL_Context.cpp
• SSL_Context.inl