SSLManager is a singleton for holding the default server/client Context and handling callbacks for certificate verification errors and private key passphrases.

Proper initialization of SSLManager is critical.

SSLManager can be initialized manually, by calling initializeServer() and/or initializeClient(), or intialization can be automatic. In the latter case, a Poco::Util::Application instance must be available and the required configuration properties must be set (see below).

Note that manual intialization must happen very early in the application, before defaultClientContext() or defaultServerContext() are called.

If defaultClientContext() and defaultServerContext() are never called in an application, initialization of SSLManager can be omitted. However, in this case, delegates for the ServerVerificationError, ClientVerificationError and PrivateKeyPassphraseRequired events must be registered.

An exemplary documentation which sets either the server or client default context and creates a PrivateKeyPassphraseHandler that reads the password from the XML file looks like this:

<AppConfig>
   <openSSL>
      <server|client>
        <privateKeyFile>mycert.key</privateKeyFile>
        <certificateFile>mycert.crt</certificateFile>
        <caConfig>rootcert.pem</caConfig>
        <verificationMode>none|relaxed|strict|once</verificationMode>
        <verificationDepth>1..9</verificationDepth>
        <loadDefaultCAFile>true|false</loadDefaultCAFile>
        <cipherList>ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH</cipherList>
        <privateKeyPassphraseHandler>
            <name>KeyFileHandler</name>
            <options>
                <password>test</password>
            </options>
        </privateKeyPassphraseHandler>
        <invalidCertificateHandler>
             <name>ConsoleCertificateHandler</name>
        </invalidCertificateHandler>
        <cacheSessions>true|false</cacheSessions>
        <sessionIdContext>someString</sessionIdContext> <!-- server only -->
        <sessionCacheSize>0..n</sessionCacheSize>       <!-- server only -->
        <sessionTimeout>0..n</sessionTimeout>           <!-- server only -->
        <extendedVerification>true|false</extendedVerification>
      </server|client>
      <fips>false</fips>
   </openSSL>
</AppConfig>

Following is a list of supported configuration properties. Property names must always be prefixed with openSSL.server or openSSL.client. Some properties are only supported for servers.

• privateKeyFile (string): The path to the file containing the private key for the certificate in PEM format (or containing both the private key and the certificate).
• certificateFile (string): The Path to the file containing the server's or client's certificate in PEM format. Can be omitted if the the file given in privateKeyFile contains the certificate as well.
• caConfig (string): The path to the file or directory containing the trusted root certificates.
• verificationMode (string): Specifies whether and how peer certificates are validated (see the Context class for details). Valid values are none, relaxed, strict, once.
• verificationDepth (integer, 1-9): Sets the upper limit for verification chain sizes. Verification will fail if a certificate chain larger than this is encountered.
• loadDefaultCAFile (boolean): Specifies wheter the builtin CA certificates from OpenSSL are used.
• cipherList (string): Specifies the supported ciphers in OpenSSL notation (e.g. "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH").
• privateKeyPassphraseHandler.name (string): The name of the class (subclass of PrivateKeyPassphraseHandler) used for obtaining the passphrase for accessing the private key.
• privateKeyPassphraseHandler.options.password (string): The password to be used by KeyFileHandler.
• invalidCertificateHandler.name: The name of the class (subclass of CertificateHandler) used for confirming invalid certificates.
• cacheSessions (boolean): Enables or disables session caching.
• sessionIdContext (string): contains the application's unique session ID context, which becomes part of each session identifier generated by the server. Can be an arbitrary sequence of bytes with a maximum length of SSL_MAX_SSL_SESSION_ID_LENGTH. Should be specified for a server to enable session caching. Should be specified even if session caching is disabled to avoid problems with clients that request session caching (e.g. Firefox 3.6). If not specified, defaults to ${application.name}.
• sessionCacheSize (integer): Sets the maximum size of the server session cache, in number of sessions. The default size (according to OpenSSL documentation) is 1024*20, which may be too large for many applications, especially on embedded platforms with limited memory. Specifying a size of 0 will set an unlimited cache size.
• sessionTimeout (integer): Sets the timeout (in seconds) of cached sessions on the server.
• extendedVerification (boolean): Enable or disable the automatic post-connection extended certificate verification.
• fips: Enable or disable OpenSSL FIPS mode. Only supported if the OpenSSL version that this library is built against supports FIPS mode.

Destroys the SSLManager.

Returns the CertificateHandlerFactoryMgr which stores the factories for the different registered certificate handlers.

Returns an initialized certificate handler (used by the client to verify server cert) which determines how invalid certificates are treated. If none is set, it will try to auto-initialize one from an application configuration.

Returns the configured passphrase handler of the client. If none is set, the method will create a default one from an application configuration.

Returns the default Context used by the client.

Unless initializeClient() has been called, the first call to this method initializes the default Context from the application configuration.

Returns the default Context used by the server.

Unless initializeServer() has been called, the first call to this method initializes the default Context from the application configuration.

Initializes the client side of the SSLManager with a default passphrase handler, a default invalid certificate handler and a default context. If this method is never called the SSLmanager will try to initialize its members from an application configuration.

PtrPassphraseHandler and ptrCertificateHandler can be 0. However, in this case, event delegates must be registered with the ClientVerificationError and PrivateKeyPassphraseRequired events.

Note: Always create the handlers (or register the corresponding event delegates) before creating the Context, as during creation of the Context the passphrase for the private key might be needed.

Valid initialization code would be:

SharedPtr<PrivateKeyPassphraseHandler> pConsoleHandler = new KeyConsoleHandler;
SharedPtr<InvalidCertificateHandler> pInvalidCertHandler = new ConsoleCertificateHandler;
Context::Ptr pContext = new Context(Context::CLIENT_USE, "", "", "rootcert.pem", Context::VERIFY_RELAXED, 9, false, "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH");
SSLManager::instance().initializeClient(pConsoleHandler, pInvalidCertHandler, pContext);

Initializes the server side of the SSLManager with a default passphrase handler, a default invalid certificate handler and a default context. If this method is never called the SSLmanager will try to initialize its members from an application configuration.

PtrPassphraseHandler and ptrCertificateHandler can be 0. However, in this case, event delegates must be registered with the ServerVerificationError and PrivateKeyPassphraseRequired events.

Note: Always create the handlers (or register the corresponding event delegates) before creating the Context, as during creation of the Context the passphrase for the private key might be needed.

Valid initialization code would be:

SharedPtr<PrivateKeyPassphraseHandler> pConsoleHandler = new KeyConsoleHandler;
SharedPtr<InvalidCertificateHandler> pInvalidCertHandler = new ConsoleCertificateHandler;
Context::Ptr pContext = new Context(Context::SERVER_USE, "any.pem", "any.pem", "rootcert.pem", Context::VERIFY_RELAXED, 9, false, "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH");
SSLManager::instance().initializeServer(pConsoleHandler, pInvalidCertHandler, pContext);

Returns the instance of the SSLManager singleton.

Returns the private key factory manager which stores the factories for the different registered passphrase handlers for private keys.

Returns an initialized certificate handler (used by the server to verify client cert) which determines how invalid certificates are treated. If none is set, it will try to auto-initialize one from an application configuration.

Returns the configured passphrase handler of the server. If none is set, the method will create a default one from an application configuration.

Shuts down the SSLManager and releases the default Context objects. After a call to shutdown(), the SSLManager can no longer be used.

Normally, it's not necessary to call this method directly, as this will be called either by uninitializeSSL(), or when the SSLManager instance is destroyed.

Returns the application configuration.

Throws a

Method is invoked by OpenSSL to retrieve a passwd for an encrypted certificate. The request is delegated to the PrivatekeyPassword event. This method returns the length of the password.

The return value of this method defines how errors in verification are handled. Return 0 to terminate the handshake, or 1 to continue despite the error.

The return value of this method defines how errors in verification are handled. Return 0 to terminate the handshake, or 1 to continue despite the error.

Fired whenever a certificate verification error is detected by the client during a handshake.

Fired when a encrypted certificate is loaded. Not setting the password in the event parameter will result in a failure to load the certificate.

Fired whenever a certificate verification error is detected by the server during a handshake.