ot::ssl
class SSLContext  (abstract)

SSLContext is an abstract class which has a concrete implementation for each security provider. OpenTop 1.4 and above is provided with a default security provider which consists of a set of C++ classes which wrap the OpenSSL library. Note that the OpenSSL secutity provider is not enabled by default and must be explicitly enabled when building the OpenTop library.

When a security provider (such as OpenSSL) is available, OpenTop provides a default SSLContext instance which is suitable for most purposes. The default SSLContext can be obtained by calling the GetDefault() static method on this class. Note, however, that the SSL protocol requires configuration information such as X509 certificate locations and private keys and these details must be provided by the application before an instance of SSLContext can be used for secure communications.

Initializing the SSLContext

• explicitly by the use of the SSLContext::init() method, or
• implicitly by setting system properties before requesting a socket factory from a SSLContext.

Implicit initialization occurs automatically when explicit initialization has not been performed and the SSLContext is being asked for a socket factory. Implicit initialization involves the SSLContext initializing itself by reading the following system properties:-

Property Name	Default Value	Description	Notes for OpenSSL users
ssl.cafile	none	A PEM-encoded file containing one or more certificates for certification authorities (CAs) which the application will accept as trusted.	When individual certificate filenames are provided, the OpenSSL library attempts to read the files during initialization. Failure to read a file (due to a missing or badly formatted file) results in an IOException being thrown.
ssl.capath	none	The name of a directory containing individual certificate files for CAs which the application will accept as trusted.	OpenSSL requires the filenames within the directory to follow a specific naming convention comprising the MD5 hash of the certificate followed by the .0 extension. Certificate files within the directory are not read until they are required, for example at the point when a certificate is first received during a SSL handshake.
ssl.certfile	none	The name of a PEM-encoded certificate file providing an identity for the application. The application will usually also need to supply another file containing the private key from which the certificate was generated.
ssl.keyfile	none	The name of a PEM-encoded file containing the application's private key. This file may be encrypted with a password/passphrase.
ssl.password	none	The passphrase used to decrypt the private key for the application.	If this property is not set the OpenSSL library will prompt via the console when a password is required.

Since:

OpenTop 1.4

SSLContext

protected  SSLContext(Protocol protocol)

Protected constructor for use by SSL security providers.

GetDefault

static RefPtr< SSLContext > GetDefault()

Static method that returns the default SSLContext instance for the application. This method will not return null, but will throw an UnsupportedOperationException if OpenTop has been built without support for a built-in security provider and the application has not provided a default instance via SetDefault().

The instance generated by this method when there is no default currently registered will employ a reasonably secure version of the SSL/TLS protocol. In OpenTop version 1.4, the default instance is generated to support both the SSLv3 and TLS protocols.

Returns:

A RefPtr to the default SSLContext instance.

Exceptions:

UnsupportedOperationException - if OpenTop has been built without support for a built-in security provider such as OpenSSL, and the application has not provided a custom default.

See also:

SetDefault() , GetInstance() , HasDefault()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

GetInstance

static RefPtr< SSLContext > GetInstance(Protocol protocol)

Creates a new SSLContext that supports only the specified (set of) SSL/TLS protocol(s) when establishing SSL socket connections.

Returns:

A RefPtr to a new SSLContext.

Exceptions:

UnsupportedOperationException - if OpenTop has been built without support for a built-in security provider such as OpenSSL.

See also:

GetDefault() , SetInstance()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getProtocol

Protocol getProtocol() const

Returns an enum representing the SSL/TLS protocols that may be used by SSLSockets created from this SSLContext. SSLSockets are not created by this SSLContext directly, rather they are created from the SSL socket factories which are provided by this SSLContext.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getServerSocketFactory

virtual RefPtr< SSLServerSocketFactory > getServerSocketFactory() const=0

Returns a SSLServerSocketFactory for creating SSLServerSockets provided by the same security provider and employing the SSL/TLS protocol(s) and other characteristics set by this SSLContext.

Returns:

A RefPtr to a SSLServerSocketFactory.

Note:

If this SSLContext has not yet been initialized, this will cause an implicit initialization to take place.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getSocketFactory

virtual RefPtr< SSLSocketFactory > getSocketFactory() const=0

Returns a SSLSocketFactory for creating SSLSockets provided by the same security provider and employing the SSL/TLS protocol(s) and other characteristics set by this SSLContext.

Returns:

A RefPtr to a SSLSocketFactory.

Note:

If this SSLContext has not yet been initialized, this will cause an implicit initialization to take place.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

HasDefault

static bool HasDefault()

Static method that returns a Boolean flag indicating if a call to the GetDefault() method would return a SSLContext. The GetDefault() method will only return a valid instance if OpenTop has been built with support for a built-in security provider, or the application has provided a default instance using SetDefault().

Returns:

true if a call to GetDefault() would return a SSLContext instance; false if a call to GetDefault() would result in an UnsupportedOperationException.

See also:

GetDefault() , SetDefault()

init

virtual void init(const SSLInitParameters& param)=0

Provides initialization parameters for this SSLContext. If init() is not called before either getServerSocketFactory() or getSocketFactory() then an implicit initialization is performed using values derived from system properties.

Exceptions:

RuntimeException - if this SSLContext has already been initialized (which will happen implicitly when either one of the socket factories is requested).
SSLException - if the security provider is unable to process the parameters provided.

See also:

isInitialized()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

isInitialized

virtual bool isInitialized() const=0

Returns a boolean flag indicating if this SSLContext has been initialized.

Returns:

true if this SSLContext has been explicitly or implicitly initialized; false otherwise.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

SetDefault

static void SetDefault(SSLContext* pContext)

Static method that sets the default SSLContext instance. The default instance is used by OpenTop to provide the default SSL socket factories, which are themselves used by the OpenTop framework classes to provide secure network facilities such as HTTPS.

This method allows the application to change either the default security provider or the SSL/TLS protocol version used by the OpenTop framework classes.

To ensure that the passed object exists for as long as the application needs it, the provided SSLContext object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination. This absolves the application from having to manage the lifetime of the passed object.

SetDefault() may also be useful when the application needs to use a freshly initialized SSLContext and the current SSLContext has already been used.

The following example shows how the application can dictate the SSL/TLS protocol that will be used by the OpenTop framework classes when communicating via SSL:-

    int main(int argc, char* argv[])
    {
        SystemMonitor _monitor();   // ensures clean termination
        try
        {
            // Allow the use of SSL2 by employing a generic SSL/TLS SSLContext
            // (SSLv2 has security flaws so not recommended for secure applications!)
            RefPtr<SSLContext> rpContext = SSLContext::GetInstance(SSLContext::SSL_TLS);
            // perform initialization of our custom SSLContext here
            ...
            SSLContext::SetDefault(rpContext.get());
            ...
        }
        catch(Exception& e)
        {
            ...
        }
    }

Parameters:

pContext - a pointer to an instance of SSLContext. When this is null it has the effect of resetting the default instance, with the effect that the next call to GetDefault() will generate an instance if possible.

See also:

GetDefault()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.