scottk/wlan-cloud-lib-poco
1
0
Fork 0
mirror of https://github.com/Telecominfraproject/wlan-cloud-lib-poco.git synced 2025-11-01 19:17:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Crypto/NetSSL improvements and doc fixes

Browse Source
This commit is contained in:
Guenter Obiltschnig
2010-08-18 10:18:50 +00:00
parent 86e5c7b615
commit 8a68e3675b
9 changed files with 131 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
NetSSL_OpenSSL/include/Poco/Net/SSLManager.h
View File

@@ -1,7 +1,7 @@
//
// SSLManager.h
//
// $Id: //poco/1.3/NetSSL_OpenSSL/include/Poco/Net/SSLManager.h#10 $
// $Id: //poco/1.3/NetSSL_OpenSSL/include/Poco/Net/SSLManager.h#12 $
//
// Library: NetSSL_OpenSSL
// Package: SSLCore
@@ -46,6 +46,7 @@
#include "Poco/Net/PrivateKeyFactoryMgr.h"
#include "Poco/Net/CertificateHandlerFactoryMgr.h"
#include "Poco/Net/InvalidCertificateHandler.h"
#include "Poco/Util/AbstractConfiguration.h"
#include "Poco/BasicEvent.h"
#include "Poco/SharedPtr.h"
#include "Poco/Mutex.h"
@@ -64,13 +65,24 @@ class Context;
class NetSSL_API SSLManager
/// SSLManager is a singleton for holding the default server/client
/// Context and PrivateKeyPassphraseHandler.
/// Context and handling callbacks for certificate verification errors
/// and private key passphrases.
///
/// 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).
/// 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:
@@ -128,8 +140,10 @@ class NetSSL_API SSLManager
/// - 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. Must be specified
/// for a server to enable session caching.
/// 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.
@@ -145,62 +159,65 @@ public:
typedef Poco::SharedPtr<InvalidCertificateHandler> InvalidCertificateHandlerPtr;
Poco::BasicEvent<VerificationErrorArgs> ServerVerificationError;
/// Fired whenever a certificate error is detected by the server during a handshake.
/// Fired whenever a certificate verification error is detected by the server during a handshake.
Poco::BasicEvent<VerificationErrorArgs> ClientVerificationError;
/// Fired whenever a certificate error is detected by the client during a handshake.
/// Fired whenever a certificate verification error is detected by the client during a handshake.
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.
///
/// Per default the SSLManager checks the application configuration file
/// (path openSSL.privateKeyPassphraseHandler.name)
/// for which default delegate it should register. If nothing is configured,
/// a KeyConsoleHandler is used.
static SSLManager& instance();
/// Returns the instance of the SSLManager singleton.
void initializeServer(PrivateKeyPassphraseHandlerPtr ptrPassphraseHandler, InvalidCertificateHandlerPtr ptrHandler, Context::Ptr ptrContext);
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.
///
/// Note: ALWAYS create the handlers before you create the context!
/// 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);
///
/// This method can only be called if no defaultContext is set yet.
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!
/// 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);
///
/// This method can only be called if no defaultContext is set yet.
Context::Ptr defaultServerContext();
/// Returns the default context used by the server. The first call to this method initializes the defaultContext
/// from an 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.
Context::Ptr defaultClientContext();
/// Returns the default context used by the client. The first call to this method initializes the defaultContext
/// 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.
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
/// from an application configuration.
InvalidCertificateHandlerPtr serverCertificateHandler();
/// Returns an initialized certificate handler (used by the server to verify client cert) which determines how invalid certificates are treated.
@@ -208,7 +225,7 @@ public:
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
/// from an application configuration.
InvalidCertificateHandlerPtr clientCertificateHandler();
/// Returns an initialized certificate handler (used by the client to verify server cert) which determines how invalid certificates are treated.
@@ -239,10 +256,15 @@ protected:
/// verification are handled. Return 0 to terminate the handshake,
/// or 1 to continue despite the error.
static int privateKeyPasswdCallback(char* pBuf, int size, int flag, void* userData);
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.
static Poco::Util::AbstractConfiguration& appConfig();
/// Returns the application configuration.
///
/// Throws a
private:
SSLManager();