1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Class Poco::Net::SSLManager</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="namespace"><a href="Poco.Net.html" class="namespace">Poco::Net</a></h1>
<h1 class="symbol">class SSLManager</h1>
</div>
<div class="body">
<p>
<b>Library:</b> NetSSL_OpenSSL<br />
<b>Package:</b> SSLCore<br />
<b>Header:</b> Poco/Net/SSLManager.h</p>
<h2>Description</h2>
<div class="description">
<p><a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a> is a singleton for holding the default server/client <a href="Poco.Net.Context.html" title="class Poco::Net::Context">Context</a> and <a href="Poco.Net.PrivateKeyPassphraseHandler.html" title="class Poco::Net::PrivateKeyPassphraseHandler">PrivateKeyPassphraseHandler</a>. </p>
<p>Either initialize via <a href="Poco.Util.Application.html" title="class Poco::Util::Application">Poco::Util::Application</a> or via the initialize methods of the singleton. Note that the latter initialization must happen very early during program startup before somebody calls <a href="Poco.Net.SSLManager.html#15953" title="Poco::Net::SSLManager::defaultClientContext()">defaultClientContext</a>()/<a href="Poco.Net.SSLManager.html#15952" title="Poco::Net::SSLManager::defaultServerContext()">defaultServerContext</a>() or any of the passPhraseHandler methods (which tries to auto-initialize the context and passphrase handler based on an <a href="Poco.Util.Application.html" title="class Poco::Util::Application">Poco::Util::Application</a> configuration). </p>
<p>An exemplary documentation which sets either the server or client default context and creates a <a href="Poco.Net.PrivateKeyPassphraseHandler.html" title="class Poco::Net::PrivateKeyPassphraseHandler">PrivateKeyPassphraseHandler</a> that reads the password from the <a href="Poco.XML.html" title="namespace Poco::XML">XML</a> file looks like this: </p>
<p></p>
<pre><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>
</pre>
</div>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.Net.SSLManager.html#15959" title="Poco::Net::SSLManager::certificateHandlerFactoryMgr()">certificateHandlerFactoryMgr</a>, <a href="Poco.Net.SSLManager.html#15957" title="Poco::Net::SSLManager::clientCertificateHandler()">clientCertificateHandler</a>, <a href="Poco.Net.SSLManager.html#15956" title="Poco::Net::SSLManager::clientPassPhraseHandler()">clientPassPhraseHandler</a>, <a href="Poco.Net.SSLManager.html#15953" title="Poco::Net::SSLManager::defaultClientContext()">defaultClientContext</a>, <a href="Poco.Net.SSLManager.html#15952" title="Poco::Net::SSLManager::defaultServerContext()">defaultServerContext</a>, <a href="Poco.Net.SSLManager.html#15948" title="Poco::Net::SSLManager::initializeClient()">initializeClient</a>, <a href="Poco.Net.SSLManager.html#15944" title="Poco::Net::SSLManager::initializeServer()">initializeServer</a>, <a href="Poco.Net.SSLManager.html#15943" title="Poco::Net::SSLManager::instance()">instance</a>, <a href="Poco.Net.SSLManager.html#15958" title="Poco::Net::SSLManager::privateKeyFactoryMgr()">privateKeyFactoryMgr</a>, <a href="Poco.Net.SSLManager.html#15968" title="Poco::Net::SSLManager::privateKeyPasswdCallback()">privateKeyPasswdCallback</a>, <a href="Poco.Net.SSLManager.html#15955" title="Poco::Net::SSLManager::serverCertificateHandler()">serverCertificateHandler</a>, <a href="Poco.Net.SSLManager.html#15954" title="Poco::Net::SSLManager::serverPassPhraseHandler()">serverPassPhraseHandler</a>, <a href="Poco.Net.SSLManager.html#15962" title="Poco::Net::SSLManager::verifyClientCallback()">verifyClientCallback</a>, <a href="Poco.Net.SSLManager.html#15965" title="Poco::Net::SSLManager::verifyServerCallback()">verifyServerCallback</a></p>
<h2>Types</h2>
<h3><a name="15939">InvalidCertificateHandlerPtr</a></h3>
<p class="decl">typedef <a href="Poco.SharedPtr.html" title="class Poco::SharedPtr">Poco::SharedPtr</a> < <a href="Poco.Net.InvalidCertificateHandler.html" title="class Poco::Net::InvalidCertificateHandler">InvalidCertificateHandler</a> > <a href="Poco.Net.SSLManager.html#15939" title="Poco::Net::SSLManager::InvalidCertificateHandlerPtr">InvalidCertificateHandlerPtr</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="15938">PrivateKeyPassphraseHandlerPtr</a></h3>
<p class="decl">typedef <a href="Poco.SharedPtr.html" title="class Poco::SharedPtr">Poco::SharedPtr</a> < <a href="Poco.Net.PrivateKeyPassphraseHandler.html" title="class Poco::Net::PrivateKeyPassphraseHandler">PrivateKeyPassphraseHandler</a> > <a href="Poco.Net.SSLManager.html#15938" title="Poco::Net::SSLManager::PrivateKeyPassphraseHandlerPtr">PrivateKeyPassphraseHandlerPtr</a>;</p>
<div class="description">
<p></p>
</div>
<h2>Constructors</h2>
<h2>Destructor</h2>
<h3><a name="15974">~SSLManager</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">~<a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a>();</p>
<div class="description">
<p>Destroys the <a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a>. </p>
</div>
<h2>Member Functions</h2>
<h3><a name="15959">certificateHandlerFactoryMgr</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.Net.CertificateHandlerFactoryMgr.html" title="class Poco::Net::CertificateHandlerFactoryMgr">CertificateHandlerFactoryMgr</a> & certificateHandlerFactoryMgr();</p>
<div class="description">
<p>Returns the <a href="Poco.Net.CertificateHandlerFactoryMgr.html" title="class Poco::Net::CertificateHandlerFactoryMgr">CertificateHandlerFactoryMgr</a> which stores the factories for the different registered certificate handlers. </p>
</div>
<h3><a name="15957">clientCertificateHandler</a></h3>
<p class="decl"><a href="Poco.Net.SSLManager.html#15939" title="Poco::Net::SSLManager::InvalidCertificateHandlerPtr">InvalidCertificateHandlerPtr</a> clientCertificateHandler();</p>
<div class="description">
<p>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. </p>
</div>
<h3><a name="15956">clientPassPhraseHandler</a></h3>
<p class="decl"><a href="Poco.Net.SSLManager.html#15938" title="Poco::Net::SSLManager::PrivateKeyPassphraseHandlerPtr">PrivateKeyPassphraseHandlerPtr</a> clientPassPhraseHandler();</p>
<div class="description">
<p>Returns the configured passphrase handler of the client. If none is set, the method will create a default one from an application configuration </p>
</div>
<h3><a name="15953">defaultClientContext</a></h3>
<p class="decl"><a href="Poco.Net.Context.html#15711" title="Poco::Net::Context::Ptr">Context::Ptr</a> defaultClientContext();</p>
<div class="description">
<p>Returns the default context used by the client. The first call to this method initializes the defaultContext from an application configuration. </p>
</div>
<h3><a name="15952">defaultServerContext</a></h3>
<p class="decl"><a href="Poco.Net.Context.html#15711" title="Poco::Net::Context::Ptr">Context::Ptr</a> defaultServerContext();</p>
<div class="description">
<p>Returns the default context used by the server. The first call to this method initializes the defaultContext from an application configuration. </p>
</div>
<h3><a name="15948">initializeClient</a></h3>
<p class="decl">void initializeClient(<br /> <a href="Poco.Net.SSLManager.html#15938" title="Poco::Net::SSLManager::PrivateKeyPassphraseHandlerPtr">PrivateKeyPassphraseHandlerPtr</a> ptrPassPhraseHandler,<br /> <a href="Poco.Net.SSLManager.html#15939" title="Poco::Net::SSLManager::InvalidCertificateHandlerPtr">InvalidCertificateHandlerPtr</a> ptrHandler,<br /> <a href="Poco.Net.Context.html#15711" title="Poco::Net::Context::Ptr">Context::Ptr</a> ptrContext<br />);</p>
<div class="description">
<p>Initializes the client side of the <a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a> 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. </p>
<p>Note: ALWAYS create the handlers before you create the context! </p>
<p>Valid initialization code would be: </p>
<pre>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");
</pre>
<p>This method can only be called if no defaultContext is set yet. </p>
</div>
<h3><a name="15944">initializeServer</a></h3>
<p class="decl">void initializeServer(<br /> <a href="Poco.Net.SSLManager.html#15938" title="Poco::Net::SSLManager::PrivateKeyPassphraseHandlerPtr">PrivateKeyPassphraseHandlerPtr</a> ptrPassPhraseHandler,<br /> <a href="Poco.Net.SSLManager.html#15939" title="Poco::Net::SSLManager::InvalidCertificateHandlerPtr">InvalidCertificateHandlerPtr</a> ptrHandler,<br /> <a href="Poco.Net.Context.html#15711" title="Poco::Net::Context::Ptr">Context::Ptr</a> ptrContext<br />);</p>
<div class="description">
<p>Initializes the server side of the <a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a> 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. </p>
<p>Note: ALWAYS create the handlers before you create the context! </p>
<p>Valid initialization code would be: </p>
<pre>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");
</pre>
<p>This method can only be called if no defaultContext is set yet. </p>
</div>
<h3><a name="15943">instance</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static <a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a> & instance();</p>
<div class="description">
<p>Returns the instance of the <a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a> singleton. </p>
</div>
<h3><a name="15958">privateKeyFactoryMgr</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.Net.PrivateKeyFactoryMgr.html" title="class Poco::Net::PrivateKeyFactoryMgr">PrivateKeyFactoryMgr</a> & privateKeyFactoryMgr();</p>
<div class="description">
<p>Returns the private key factory manager which stores the factories for the different registered passphrase handlers for private keys. </p>
</div>
<h3><a name="15955">serverCertificateHandler</a></h3>
<p class="decl"><a href="Poco.Net.SSLManager.html#15939" title="Poco::Net::SSLManager::InvalidCertificateHandlerPtr">InvalidCertificateHandlerPtr</a> serverCertificateHandler();</p>
<div class="description">
<p>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. </p>
</div>
<h3><a name="15954">serverPassPhraseHandler</a></h3>
<p class="decl"><a href="Poco.Net.SSLManager.html#15938" title="Poco::Net::SSLManager::PrivateKeyPassphraseHandlerPtr">PrivateKeyPassphraseHandlerPtr</a> serverPassPhraseHandler();</p>
<div class="description">
<p>Returns the configured passphrase handler of the server. If none is set, the method will create a default one from an application configuration </p>
</div>
<h3><a name="15968">privateKeyPasswdCallback</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static int privateKeyPasswdCallback(<br /> char * pBuf,<br /> int size,<br /> int flag,<br /> void * userData<br />);</p>
<div class="description">
<p>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. </p>
</div>
<h3><a name="15962">verifyClientCallback</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static int verifyClientCallback(<br /> int ok,<br /> X509_STORE_CTX * pStore<br />);</p>
<div class="description">
<p>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. </p>
</div>
<h3><a name="15965">verifyServerCallback</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static int verifyServerCallback(<br /> int ok,<br /> X509_STORE_CTX * pStore<br />);</p>
<div class="description">
<p>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. </p>
</div>
<h2>Variables</h2>
<h3><a name="15961">CFG_CLIENT_PREFIX</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.Net.SSLManager.html#15961" title="Poco::Net::SSLManager::CFG_CLIENT_PREFIX">CFG_CLIENT_PREFIX</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="15960">CFG_SERVER_PREFIX</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static const std::string <a href="Poco.Net.SSLManager.html#15960" title="Poco::Net::SSLManager::CFG_SERVER_PREFIX">CFG_SERVER_PREFIX</a>;</p>
<div class="description">
<p></p>
</div>
<h3><a name="15941">ClientVerificationError</a></h3>
<p class="decl"><a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">Poco::BasicEvent</a> < <a href="Poco.Net.VerificationErrorArgs.html" title="class Poco::Net::VerificationErrorArgs">VerificationErrorArgs</a> > <a href="Poco.Net.SSLManager.html#15941" title="Poco::Net::SSLManager::ClientVerificationError">ClientVerificationError</a>;</p>
<div class="description">
<p>Thrown whenever a certificate error is detected by the client during a handshake. </p>
</div>
<h3><a name="15942">PrivateKeyPassPhrase</a></h3>
<p class="decl"><a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">Poco::BasicEvent</a> < std::string > <a href="Poco.Net.SSLManager.html#15942" title="Poco::Net::SSLManager::PrivateKeyPassPhrase">PrivateKeyPassPhrase</a>;</p>
<div class="description">
<p>Thrown when a encrypted certificate is loaded. Not setting the password in the event parameter will result in a failure to load the certificate. </p>
<p>Per default the <a href="Poco.Net.SSLManager.html" title="class Poco::Net::SSLManager">SSLManager</a> checks the configuration.xml file (path openSSL.privateKeyPassphraseHandler.name) for which default delegate it should register. If nothing is configured, a <a href="Poco.Net.KeyConsoleHandler.html" title="class Poco::Net::KeyConsoleHandler">KeyConsoleHandler</a> is used. </p>
</div>
<h3><a name="15940">ServerVerificationError</a></h3>
<p class="decl"><a href="Poco.BasicEvent.html" title="class Poco::BasicEvent">Poco::BasicEvent</a> < <a href="Poco.Net.VerificationErrorArgs.html" title="class Poco::Net::VerificationErrorArgs">VerificationErrorArgs</a> > <a href="Poco.Net.SSLManager.html#15940" title="Poco::Net::SSLManager::ServerVerificationError">ServerVerificationError</a>;</p>
<div class="description">
<p>Thrown whenever a certificate error is detected by the server during a handshake. </p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</div>
</body>
</html>
|
