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:

Collaboration graph
[legend]
List of all members.
ACE_UNIMPLEMENTED_FUNC(void
operator=(const ACE_SSL_Context
&)) ACE_UNIMPLEMENTED_FUNC(ACE_SSL_Context(const ACE_SSL_Context
&)) private int 
mode_
 Cache the mode so we can answer fast.
ACE_SSL_Data_File private_key_
 The private key, certificate, and Diffie-Hellman paramters files.
ACE_SSL_Data_File certificate_
 Cache the mode so we can answer fast.
ACE_SSL_Data_File dh_params_
 Cache the mode so we can answer fast.
int default_verify_mode_
 The default verify mode.
int have_ca_
 count of successful CA load attempts
static int library_init_count_
static ACE_mutex_t * lock_

Public Types

enum  {
  INVALID_METHOD = -1, SSLv2_client = 1, SSLv2_server, SSLv2,
  SSLv3_client, SSLv3_server, SSLv3, SSLv23_client,
  SSLv23_server, SSLv23, TLSv1_client, TLSv1_server,
  TLSv1
}

Public Member Functions

 ACE_SSL_Context (void)
 Constructor.
 ~ACE_SSL_Context (void)
 Destructor.
int set_mode (int mode=ACE_SSL_Context::SSLv23)
int get_mode (void) const
SSL_CTX * context (void)
 Get the SSL context.
int private_key_type (void) const
 Get the file name and file format used for the private key.
const char * private_key_file_name (void) const
int private_key (const char *file_name, int type=SSL_FILETYPE_PEM)
 Set the private key file.
int verify_private_key (void)
 Verify that the private key is valid.
int certificate_type (void) const
 Get the file name and file format used for the certificate file.
const char * certificate_file_name (void) const
int certificate (const char *file_name, int type=SSL_FILETYPE_PEM)
 Set the certificate file.
int load_trusted_ca (const char *ca_file=0, const char *ca_dir=0)
int have_trusted_ca (void) const
void set_verify_peer (int strict=0, int once=1, int depth=0)
void default_verify_mode (int mode)
int default_verify_mode (void) const
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.

int random_seed (const char *seed)
int egd_file (const char *socket_file)
int seed_file (const char *seed_file, long bytes=-1)
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.

int dh_params (const char *file_name, int type=SSL_FILETYPE_PEM)
const char * dh_params_file_name () const
int dh_params_file_type () const

Static Public Member Functions

static ACE_SSL_Contextinstance (void)
static void report_error (unsigned long error_code)
 Print SSL error corresponding to the given error code.
static void report_error (void)
 Print the last SSL error for the current thread.

Private Member Functions

void check_context (void)
 Verify if the context has been initialized or not.
void ssl_library_init ()
 @ More to document
void ssl_library_fini ()

Friends

void ACE_SSL_locking_callback (int, int, const char *, int)

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
 

Enumerator:
INVALID_METHOD 
SSLv2_client 
SSLv2_server 
SSLv2 
SSLv3_client 
SSLv3_server 
SSLv3 
SSLv23_client 
SSLv23_server 
SSLv23 
TLSv1_client 
TLSv1_server 
TLSv1 


Constructor & Destructor Documentation

ACE_SSL_Context::ACE_SSL_Context void   ) 
 

Constructor.

ACE_SSL_Context::~ACE_SSL_Context void   ) 
 

Destructor.


Member Function Documentation

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

Set the certificate file.

ACE_INLINE const char * ACE_SSL_Context::certificate_file_name void   )  const
 

ACE_INLINE int ACE_SSL_Context::certificate_type void   )  const
 

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

ACE_INLINE void ACE_SSL_Context::check_context void   )  [private]
 

Verify if the context has been initialized or not.

ACE_INLINE SSL_CTX * ACE_SSL_Context::context void   ) 
 

Get the SSL context.

ACE_INLINE int ACE_SSL_Context::default_verify_mode void   )  const
 

ACE_INLINE void ACE_SSL_Context::default_verify_mode int  mode  ) 
 

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.

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.

ACE_INLINE const char * ACE_SSL_Context::dh_params_file_name  )  const
 

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.

ACE_INLINE int ACE_SSL_Context::dh_params_file_type  )  const
 

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.

int ACE_SSL_Context::egd_file const char *  socket_file  ) 
 

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

ACE_INLINE int ACE_SSL_Context::get_mode void   )  const
 

ACE_INLINE int ACE_SSL_Context::have_trusted_ca void   )  const
 

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

Returns:
>0 This value indicates the number of successful CA load attempts .

0 If all CA load attempts have failed.

ACE_SSL_Context * ACE_SSL_Context::instance void   )  [static]
 

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

int ACE_SSL_Context::load_trusted_ca const char *  ca_file = 0,
const char *  ca_dir = 0
 

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 dosn't make sense to keep a copy of the file and path name of the most recently added <ca_file> or <ca_path>.

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.

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.

ACE_INLINE const char * ACE_SSL_Context::private_key_file_name void   )  const
 

ACE_INLINE int ACE_SSL_Context::private_key_type void   )  const
 

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

int ACE_SSL_Context::random_seed const char *  seed  ) 
 

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

void ACE_SSL_Context::report_error void   )  [static]
 

Print the last SSL error for the current thread.

void ACE_SSL_Context::report_error unsigned long  error_code  )  [static]
 

Print SSL error corresponding to the given error code.

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

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.

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.

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

Todo:
Complete this documentation where elipses(...) are used
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.

void ACE_SSL_Context::ssl_library_fini  )  [private]
 

void ACE_SSL_Context::ssl_library_init  )  [private]
 

@ More to document

int ACE_SSL_Context::verify_private_key void   ) 
 

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.


Friends And Related Function Documentation

void ACE_SSL_locking_callback int  ,
int  ,
const char *  ,
int 
[friend]
 

Mutex locking/unlocking callback for OpenSSL multithread support.


Member Data Documentation

ACE_SSL_Data_File ACE_SSL_Context::certificate_ [private]
 

Cache the mode so we can answer fast.

int ACE_SSL_Context::default_verify_mode_ [private]
 

The default verify mode.

ACE_SSL_Data_File ACE_SSL_Context::dh_params_ [private]
 

Cache the mode so we can answer fast.

int ACE_SSL_Context::have_ca_ [private]
 

count of successful CA load attempts

int ACE_SSL_Context::library_init_count_ [static, private]
 

Reference count of the number of times the ACE_SSL_Context was initialized.

ACE_mutex_t* ACE_SSL_Context::lock_ [static, private]
 

Array of mutexes used internally by OpenSSL when the SSL application is multithreaded.

ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_SSL_Context &)) ACE_UNIMPLEMENTED_FUNC (ACE_SSL_Context ( const ACE_SSL_Context &)) private int ACE_SSL_Context::mode_ [private]
 

Cache the mode so we can answer fast.

ACE_SSL_Data_File ACE_SSL_Context::private_key_ [private]
 

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


The documentation for this class was generated from the following files:
Generated on Wed Nov 23 15:54:43 2005 for ACE_SSL by  doxygen 1.4.5