Class Poco::Net::SSLManager
Author: Applied Informatics Software Engineering GmbH and Contributors
Date: 2009-11-24

# Poco::Net

# class SSLManager

Library: NetSSL_OpenSSL
Package: SSLCore
Header: Poco/Net/SSLManager.h

## Description

SSLManager is a singleton for holding the default server/client Context and PrivateKeyPassphraseHandler.

Either initialize via Poco::Util::Application or via the initialize methods of the singleton. Note that the latter initialization must happen very early during program startup before somebody calls defaultClientContext()/defaultServerContext() or any of the passPhraseHandler methods (which tries to auto-initialize the context and passphrase handler based on an Poco::Util::Application configuration).

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>relaxed</verificationMode>
            <verificationDepth>9</verificationDepth>
            <loadDefaultCAFile>true</loadDefaultCAFile>
            <cypherList>ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH</cypherList>
            <privateKeyPassphraseHandler>
                <name>KeyFileHandler</name>
                <options>
                    <password>test</password>
                </options>
            </privateKeyPassphraseHandler>
            <invalidCertificateHandler>
                 <name>ConsoleCertificateHandler</name>
                 <options>
                 </options>
            </invalidCertificateHandler>
            <cacheSessions>true</cacheSessions>
          </server|client>
       </openSSL>
    </AppConfig>

## Member Summary

Member Functions: certificateHandlerFactoryMgr, clientCertificateHandler, clientPassPhraseHandler, defaultClientContext, defaultServerContext, initializeClient, initializeServer, instance, privateKeyFactoryMgr, privateKeyPasswdCallback, serverCertificateHandler, serverPassPhraseHandler, verifyClientCallback, verifyServerCallback

## Types

### InvalidCertificateHandlerPtr

typedef Poco::SharedPtr < InvalidCertificateHandler > InvalidCertificateHandlerPtr;

### PrivateKeyPassphraseHandlerPtr

typedef Poco::SharedPtr < PrivateKeyPassphraseHandler > PrivateKeyPassphraseHandlerPtr;

## Constructors

## Destructor

### ~SSLManager

~SSLManager();

Destroys the SSLManager.

## Member Functions

### certificateHandlerFactoryMgr

CertificateHandlerFactoryMgr & certificateHandlerFactoryMgr();

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

### clientCertificateHandler

InvalidCertificateHandlerPtr clientCertificateHandler();

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.

### clientPassPhraseHandler

PrivateKeyPassphraseHandlerPtr clientPassPhraseHandler();

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

### defaultClientContext

Context::Ptr defaultClientContext();

Returns the default context used by the client. The first call to this method initializes the defaultContext from an application configuration.

### defaultServerContext

Context::Ptr defaultServerContext();

Returns the default context used by the server. The first call to this method initializes the defaultContext from an application configuration.

### initializeClient

void initializeClient(
PrivateKeyPassphraseHandlerPtr ptrPassPhraseHandler,
InvalidCertificateHandlerPtr ptrHandler,
Context::Ptr ptrContext
);

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.

Note: ALWAYS create the handlers before you create the context!

Valid initialization code would be:

    SharedPtr<PrivateKeyPassphraseHandler> ptrConsole = new KeyConsoleHandler();
    SharedPtr<InvalidCertificateHandler> ptrCert = new ConsoleCertificateHandler();
    Context::Ptr ptrContext = new Context("any.pem", "rootcert.pem", Context::Relaxed, 9, false, "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH");

This method can only be called if no defaultContext is set yet.

### initializeServer

void initializeServer(
PrivateKeyPassphraseHandlerPtr ptrPassPhraseHandler,
InvalidCertificateHandlerPtr ptrHandler,
Context::Ptr ptrContext
);

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.

Note: ALWAYS create the handlers before you create the context!

Valid initialization code would be:

    SharedPtr<PrivateKeyPassphraseHandler> ptrConsole = new KeyConsoleHandler();
    SharedPtr<InvalidCertificateHandler> ptrCert = new ConsoleCertificateHandler();
    Context::Ptr ptrContext = new Context("any.pem", "rootcert.pem", Context::Relaxed, 9, false, "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH");

This method can only be called if no defaultContext is set yet.

### instance

static SSLManager & instance();

Returns the instance of the SSLManager singleton.

### privateKeyFactoryMgr

PrivateKeyFactoryMgr & privateKeyFactoryMgr();

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

### serverCertificateHandler

InvalidCertificateHandlerPtr serverCertificateHandler();

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.

### serverPassPhraseHandler

PrivateKeyPassphraseHandlerPtr serverPassPhraseHandler();

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

### privateKeyPasswdCallback

static int privateKeyPasswdCallback(
char * pBuf,
int size,
int flag,
void * userData
);

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.

### verifyClientCallback

static int verifyClientCallback(
int ok,
X509_STORE_CTX * pStore
);

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.

### verifyServerCallback

static int verifyServerCallback(
int ok,
X509_STORE_CTX * pStore
);

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.

## Variables

### CFG_CLIENT_PREFIX

static const std::string CFG_CLIENT_PREFIX;

### CFG_SERVER_PREFIX

static const std::string CFG_SERVER_PREFIX;

### ClientVerificationError

Poco::BasicEvent < VerificationErrorArgs > ClientVerificationError;

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

### PrivateKeyPassPhrase

Poco::BasicEvent < std::string > PrivateKeyPassPhrase;

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

Per default the SSLManager checks the configuration.xml file (path openSSL.privateKeyPassphraseHandler.name) for which default delegate it should register. If nothing is configured, a KeyConsoleHandler is used.

### ServerVerificationError

Poco::BasicEvent < VerificationErrorArgs > ServerVerificationError;

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