Class Poco::Net::SSLManager (original) (raw)
Library: NetSSL_OpenSSL
Package: SSLCore
Header: Poco/Net/SSLManager.h
Description
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 initialization 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 initialization 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:
mycert.key mycert.crt rootcert.pem none|relaxed|strict|once 1..9 true|false ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH true|false KeyFileHandler test ConsoleCertificateHandler true|false someString 0..n 0..n true|false true|false true|false true|false true|false sslv2,sslv3,tlsv1,tlsv1_1,tlsv1_2,tlsv1_3 dh.pem prime256v1 falseFollowing 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 whether 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").
- preferServerCiphers (bool): When choosing a cipher, use the server's preferences instead of the client preferences. When not called, the SSL server will always follow the clients preferences. When called, the SSL/TLS server will choose following its own preferences.
- 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.
- requireTLSv1 (boolean): Require a TLSv1 connection.
- requireTLSv1_1 (boolean): Require a TLSv1.1 connection.
- requireTLSv1_2 (boolean): Require a TLSv1.2 connection.
- requireTLSv1_3 (boolean): Require a TLSv1.3 connection
- disableProtocols (string): A comma-separated list of protocols that should be disabled. Valid protocol names are sslv2, sslv3, tlsv1, tlsv1_1, tlsv1_2, tlsv1_3.
- dhParamsFile (string): Specifies a file containing Diffie-Hellman parameters. If not specified or empty, the default parameters are used.
- ecdhCurve (string): Specifies the name of the curve to use for ECDH, based on the curve names specified in RFC 4492. Defaults to "prime256v1".
- fips: Enable or disable OpenSSL FIPS mode. Only supported if the OpenSSL version that this library is built against supports FIPS mode.
Please see the Context class documentation regarding TLSv1.3 support.
Member Summary
Member Functions: appConfig, certificateHandlerFactoryMgr, clientCertificateHandler, clientPassphraseHandler, contextIndex, defaultClientContext, defaultServerContext, initializeClient, initializeServer, instance, isFIPSEnabled, privateKeyFactoryMgr, privateKeyPassphraseCallback, serverCertificateHandler, serverPassphraseHandler, shutdown, socketIndex, verifyClientCallback, verifyOCSPResponseCallback, verifyServerCallback
Types Aliases
InvalidCertificateHandlerPtr
using InvalidCertificateHandlerPtr = Poco::SharedPtr < InvalidCertificateHandler >;
PrivateKeyPassphraseHandlerPtr
using PrivateKeyPassphraseHandlerPtr = Poco::SharedPtr < PrivateKeyPassphraseHandler >;
Constructors
Destructor
~SSLManager 
~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.
Unless initializeClient() has been called, the first call to this method initializes the default Context from the application configuration.
defaultServerContext
Context::Ptr defaultServerContext();
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.
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.
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 pConsoleHandler = new KeyConsoleHandler; SharedPtr 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);
initializeServer
void initializeServer(
PrivateKeyPassphraseHandlerPtr ptrPassphraseHandler,
InvalidCertificateHandlerPtr ptrCertificateHandler,
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.
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 pConsoleHandler = new KeyConsoleHandler; SharedPtr 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);
instance 
static SSLManager & instance();
Returns the instance of the SSLManager singleton.
isFIPSEnabled
static bool isFIPSEnabled();
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.
shutdown
void shutdown();
appConfig
static Poco::Util::AbstractConfiguration & appConfig();
Returns the application configuration.
Throws a InvalidStateException if not application instance is available.
contextIndex
int contextIndex() const;
Returns the index for SSL_CTX_set_ex_data() and SSL_CTX_get_ex_data() to store the Context* in the underlying SSL_CTX.
privateKeyPassphraseCallback
static int privateKeyPassphraseCallback(
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.
socketIndex
int socketIndex() const;
Returns the index for SSL_set_ex_data() and SSL_get_ex_data() to store the SecureSocketImpl* in the underlying SSL.
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.
verifyOCSPResponseCallback
static int verifyOCSPResponseCallback(
SSL * pSSL,
void * arg
);
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;
Fired whenever a certificate verification error is detected by the client during a handshake.
PrivateKeyPassphraseRequired
Poco::BasicEvent < std::string > PrivateKeyPassphraseRequired;
Fired when a encrypted certificate is loaded. Not setting the password in the event parameter will result in a failure to load the certificate.
ServerVerificationError
Poco::BasicEvent < VerificationErrorArgs > ServerVerificationError;
Fired whenever a certificate verification error is detected by the server during a handshake.