Cross-Platform C++

ot::ssl
class SSLContext(abstract)

#include "ot/ssl/SSLContext.h"

ot::SynchronizedObject ot::ManagedObject An abstract interface class providing the root entry-point for applications to initialize and control a SSL implementation. A SSLContext essentially represents a configured encryption engine which can act as a source for both client and server SSLSockets. An instance of SSLContext is configured to understand a specific (set of) SSL/TLS protocol(s) together with additional information such as locations of PKI certificates and private keys.

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

There are two ways to initialize a SSLContext:- Explicit initialization involves calling the init() member function before the SSLContext is used to construct a socket factory. Subsequent calls to init() on the same instance will fail with a RuntimeException. The init() function takes a single argument of type SSLInitParameters, which is a structure containing commonly needed information such as certificate and key file locations.

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



Constructor/Destructor Summary
SSLContext(Protocol protocol)
Protected constructor for use by SSL security providers.

Method Summary
staticRefPtr< SSLContext > GetDefault()
Static method that returns the default SSLContext instance for the application.
staticRefPtr< SSLContext > GetInstance(Protocol protocol)
Creates a new SSLContext that supports only the specified (set of) SSL/TLS protocol(s) when establishing SSL socket connections.
Protocol getProtocol()const
Returns an enum representing the SSL/TLS protocols that may be used by SSLSockets created from this SSLContext.
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.
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.
staticbool HasDefault()
Static method that returns a Boolean flag indicating if a call to the GetDefault() method would return a SSLContext.
virtual void init(const SSLInitParameters& param)=0
Provides initialization parameters for this SSLContext.
virtual bool isInitialized()const=0
Returns a boolean flag indicating if this SSLContext has been initialized.
staticvoid SetDefault(SSLContext* pContext)
Static method that sets the default SSLContext instance.

Methods inherited from class ot::ManagedObject
addRef(), getRefCount(), onFinalRelease(), operator=(const ManagedObject&), release()

Methods inherited from class ot::SynchronizedObject
lock(), unlock()

Enumerations

enumProtocol{ SSL, /* Generic SSL including SSLv2 and SSLv3 */
SSLv2, /* SSLv2 only */
SSLv3, /* SSLv3 only */
SSLv3_TLS, /* SSLv3 and TLSv1 */
SSL_TLS, /* Generic SSL/TLS including SSLv2, SSLv3 and TLSv1 */
TLS, /* Generic TLS including TLSv1 */
TLSv1} /* TLSv1 only */


Constructor/Destructor Detail

SSLContext

protected SSLContext(Protocol protocol)
Protected constructor for use by SSL security providers.


Method Detail

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

ProtocolgetProtocol()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 boolHasDefault()
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 voidinit(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 boolisInitialized()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 voidSetDefault(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.


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright 2000-2005 ElCel Technology Trademark Acknowledgements