blob: c42e56f34f92b7e2b829710133f14cffcce2f610 [file] [log] [blame]
Jean-Paul Calderone897bc252008-02-18 20:50:23 -05001<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<title>3.3.1 Context objects </title>
5<META NAME="description" CONTENT="3.3.1 Context objects ">
6<META NAME="keywords" CONTENT="pyOpenSSL">
7<META NAME="resource-type" CONTENT="document">
8<META NAME="distribution" CONTENT="global">
9<link rel="STYLESHEET" href="pyOpenSSL.css">
10<LINK REL="next" href="openssl-connection.html">
11<LINK REL="previous" href="openssl-ssl.html">
12<LINK REL="up" href="openssl-ssl.html">
13<LINK REL="next" href="openssl-connection.html">
14</head>
15<body>
16<DIV CLASS="navigation">
17<table align="center" width="100%" cellpadding="0" cellspacing="2">
18<tr>
19<td><A href="openssl-ssl.html"><img src="previous.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -050020 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050021 alt="Previous Page" width="32"></A></td>
22<td><A href="openssl-ssl.html"><img src="up.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -050023 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050024 alt="Up One Level" width="32"></A></td>
25<td><A href="openssl-connection.html"><img src="next.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -050026 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050027 alt="Next Page" width="32"></A></td>
28<td align="center" width="100%">Python OpenSSL Manual</td>
29<td><A href="contents.html"><img src="contents.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -050030 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050031 alt="Contents" width="32"></A></td>
32<td><img src="blank.gif"
33 border="0" height="32"
34 alt="" width="32"></td>
35<td><img src="blank.gif"
36 border="0" height="32"
37 alt="" width="32"></td>
38</tr></table>
39<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
40<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
41<b class="navlabel">Next:</b> <a class="sectref" href="openssl-connection.html">3.3.2 Connection objects</A>
42<br><hr>
43</DIV>
44<!--End of Navigation Panel-->
45
46<H3><A NAME="SECTION000431000000000000000">&nbsp;</A>
47<BR>
483.3.1 Context objects
49</H3>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050050
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050051<P>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050052Context objects have the following methods:
53
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050054<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040055<dl><dt><b><a name='l2h-152'><tt class='method'>check_privatekey</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050056<dd>
57Check if the private key (loaded with <tt class="method">use_privatekey<big>[</big>_file<big>]</big></tt>)
58matches the certificate (loaded with <tt class="method">use_certificate<big>[</big>_file<big>]</big></tt>).
Jean-Paul Calderonef05fbbe2008-03-06 21:52:35 -050059Returns <code>None</code> if they match, raises <tt class="exception">Error</tt> otherwise.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050060</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050061
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050062<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040063<dl><dt><b><a name='l2h-153'><tt class='method'>get_app_data</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050064<dd>
65Retrieve application data as set by <tt class="method">set_app_data</tt>.
66</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050067
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050068<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040069<dl><dt><b><a name='l2h-154'><tt class='method'>get_cert_store</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050070<dd>
71Retrieve the certificate store (a X509Store object) that the context uses.
72This can be used to add "trusted" certificates without using the.
73<tt class="method">load_verify_locations()</tt> method.
74</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050075
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050076<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040077<dl><dt><b><a name='l2h-155'><tt class='method'>get_timeout</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050078<dd>
79Retrieve session timeout, as set by <tt class="method">set_timeout</tt>. The default is 300
80seconds.
81</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050082
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050083<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040084<dl><dt><b><a name='l2h-156'><tt class='method'>get_verify_depth</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050085<dd>
86Retrieve the Context object's verify depth, as set by
87<tt class="method">set_verify_depth</tt>.
88</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050089
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050090<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040091<dl><dt><b><a name='l2h-157'><tt class='method'>get_verify_mode</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050092<dd>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -050093Retrieve the Context object's verify mode, as set by <tt class="method">set_verify</tt>.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050094</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050095
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050096<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -040097<dl><dt><b><a name='l2h-158'><tt class='method'>load_client_ca</tt></a></b>(<var>pemfile</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050098<dd>
99Read a file with PEM-formatted certificates that will be sent to the client
100when requesting a client certificate.
101</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500102
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500103<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400104<dl><dt><b><a name='l2h-159'><tt class='method'>set_client_ca_list</tt></a></b>(<var>certificate_authorities</var>)
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500105<dd>
106Replace the current list of preferred certificate signers that would be
107sent to the client when requesting a client certificate with the
108<var>certificate_authorities</var> sequence of <tt class="class">OpenSSL.crypto.X509Name</tt>s.
109
110<P>
111
112<span class='versionnote'>New in version 0.10.</span>
113
114</dl>
115
116<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400117<dl><dt><b><a name='l2h-160'><tt class='method'>add_client_ca</tt></a></b>(<var>certificate_authority</var>)
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500118<dd>
119Extract a <tt class="class">OpenSSL.crypto.X509Name</tt> from the <var>certificate_authority</var>
120<tt class="class">OpenSSL.crypto.X509</tt> certificate and add it to the list of preferred
121certificate signers sent to the client when requesting a client certificate.
122
123<P>
124
125<span class='versionnote'>New in version 0.10.</span>
126
127</dl>
128
129<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400130<dl><dt><b><a name='l2h-161'><tt class='method'>load_verify_locations</tt></a></b>(<var>pemfile, capath</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500131<dd>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500132Specify where CA certificates for verification purposes are located. These
133are trusted certificates. Note that the certificates have to be in PEM
134format. If capath is passed, it must be a directory prepared using the
135<code>c_rehash</code> tool included with OpenSSL. Either, but not both, of
136<var>pemfile</var> or <var>capath</var> may be <code>None</code>.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500137</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500138
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500139<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400140<dl><dt><b><a name='l2h-162'><tt class='method'>set_default_verify_paths</tt></a></b>()
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500141<dd>
142Specify that the platform provided CA certificates are to be used for
143verification purposes. This method may not work properly on OS X.
144</dl>
145
146<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400147<dl><dt><b><a name='l2h-163'><tt class='method'>load_tmp_dh</tt></a></b>(<var>dhfile</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500148<dd>
149Load parameters for Ephemeral Diffie-Hellman from <var>dhfile</var>.
150</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500151
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500152<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400153<dl><dt><b><a name='l2h-164'><tt class='method'>set_app_data</tt></a></b>(<var>data</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500154<dd>
155Associate <var>data</var> with this Context object. <var>data</var> can be retrieved
156later using the <tt class="method">get_app_data</tt> method.
157</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500158
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500159<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400160<dl><dt><b><a name='l2h-165'><tt class='method'>set_cipher_list</tt></a></b>(<var>ciphers</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500161<dd>
162Set the list of ciphers to be used in this context. See the OpenSSL manual for
163more information (e.g. ciphers(1))
164</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500165
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500166<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400167<dl><dt><b><a name='l2h-166'><tt class='method'>set_info_callback</tt></a></b>(<var>callback</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500168<dd>
169Set the information callback to <var>callback</var>. This function will be called
170from time to time during SSL handshakes.
Jean-Paul Calderone420bf212008-02-19 21:19:30 -0500171<var>callback</var> should take three arguments: a Connection object and two
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500172integers. The first integer specifies where in the SSL handshake the function
173was called, and the other the return code from a (possibly failed) internal
174function call.
175</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500176
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500177<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400178<dl><dt><b><a name='l2h-167'><tt class='method'>set_options</tt></a></b>(<var>options</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500179<dd>
180Add SSL options. Options you have set before are not cleared!
Jean-Paul Calderone420bf212008-02-19 21:19:30 -0500181This method should be used with the <tt class="constant">OP_*</tt> constants.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500182</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500183
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500184<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400185<dl><dt><b><a name='l2h-168'><tt class='method'>set_passwd_cb</tt></a></b>(<var>callback</var><big>[</big><var>, userdata</var><big>]</big>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500186<dd>
187Set the passphrase callback to <var>callback</var>. This function will be called
Jean-Paul Calderone1eeb29e2008-10-19 11:50:53 -0400188when a private key with a passphrase is loaded. <var>callback</var> must accept
189three positional arguments. First, an integer giving the maximum length of
190the passphrase it may return. If the returned passphrase is longer than
191this, it will be truncated. Second, a boolean value which will be true if
192the user should be prompted for the passphrase twice and the callback should
193verify that the two values supplied are equal. Third, the value given as the
194<var>userdata</var> parameter to <tt class="method">set_passwd_cb</tt>. If an error occurs,
195<var>callback</var> should return a false value (e.g. an empty string).
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500196</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500197
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500198<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400199<dl><dt><b><a name='l2h-169'><tt class='method'>set_session_id</tt></a></b>(<var>name</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500200<dd>
201Set the context <var>name</var> within which a session can be reused for this
202Context object. This is needed when doing session resumption, because there is
203no way for a stored session to know which Context object it is associated with.
204<var>name</var> may be any binary data.
205</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500206
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500207<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400208<dl><dt><b><a name='l2h-170'><tt class='method'>set_timeout</tt></a></b>(<var>timeout</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500209<dd>
210Set the timeout for newly created sessions for this Context object to
211<var>timeout</var>. <var>timeout</var> must be given in (whole) seconds. The default
212value is 300 seconds. See the OpenSSL manual for more information (e.g.
213SSL_CTX_set_timeout(3)).
214</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500215
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500216<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400217<dl><dt><b><a name='l2h-171'><tt class='method'>set_verify</tt></a></b>(<var>mode, callback</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500218<dd>
219Set the verification flags for this Context object to <var>mode</var> and specify
220that <var>callback</var> should be used for verification callbacks. <var>mode</var>
221should be one of <tt class="constant">VERIFY_NONE</tt> and <tt class="constant">VERIFY_PEER</tt>. If
222<tt class="constant">VERIFY_PEER</tt> is used, <var>mode</var> can be OR:ed with
223<tt class="constant">VERIFY_FAIL_IF_NO_PEER_CERT</tt> and <tt class="constant">VERIFY_CLIENT_ONCE</tt> to
224further control the behaviour.
Jean-Paul Calderone420bf212008-02-19 21:19:30 -0500225<var>callback</var> should take five arguments: A Connection object, an X509 object,
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500226and three integer variables, which are in turn potential error number, error
227depth and return code. <var>callback</var> should return true if verification passes
228and false otherwise.
229</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500230
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500231<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400232<dl><dt><b><a name='l2h-172'><tt class='method'>set_verify_depth</tt></a></b>(<var>depth</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500233<dd>
234Set the maximum depth for the certificate chain verification that shall be
235allowed for this Context object.
236</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500237
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500238<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400239<dl><dt><b><a name='l2h-173'><tt class='method'>use_certificate</tt></a></b>(<var>cert</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500240<dd>
241Use the certificate <var>cert</var> which has to be a X509 object.
242</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500243
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500244<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400245<dl><dt><b><a name='l2h-174'><tt class='method'>add_extra_chain_cert</tt></a></b>(<var>cert</var>)
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500246<dd>
247Adds the certificate <var>cert</var>, which has to be a X509 object, to the
248certificate chain presented together with the certificate.
249</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500250
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500251<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400252<dl><dt><b><a name='l2h-175'><tt class='method'>use_certificate_chain_file</tt></a></b>(<var>file</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500253<dd>
254Load a certificate chain from <var>file</var> which must be PEM encoded.
255</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500256
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500257<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400258<dl><dt><b><a name='l2h-176'><tt class='method'>use_privatekey</tt></a></b>(<var>pkey</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500259<dd>
260Use the private key <var>pkey</var> which has to be a PKey object.
261</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500262
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500263<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400264<dl><dt><b><a name='l2h-177'><tt class='method'>use_certificate_file</tt></a></b>(<var>file</var><big>[</big><var>, format</var><big>]</big>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500265<dd>
266Load the first certificate found in <var>file</var>. The certificate must be in the
267format specified by <var>format</var>, which is either <tt class="constant">FILETYPE_PEM</tt> or
268<tt class="constant">FILETYPE_ASN1</tt>. The default is <tt class="constant">FILETYPE_PEM</tt>.
269</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500270
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500271<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400272<dl><dt><b><a name='l2h-178'><tt class='method'>use_privatekey_file</tt></a></b>(<var>file</var><big>[</big><var>, format</var><big>]</big>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500273<dd>
274Load the first private key found in <var>file</var>. The private key must be in the
275format specified by <var>format</var>, which is either <tt class="constant">FILETYPE_PEM</tt> or
276<tt class="constant">FILETYPE_ASN1</tt>. The default is <tt class="constant">FILETYPE_PEM</tt>.
277</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500278
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500279<P>
280
281<DIV CLASS="navigation">
282<p><hr>
283<table align="center" width="100%" cellpadding="0" cellspacing="2">
284<tr>
285<td><A href="openssl-ssl.html"><img src="previous.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500286 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500287 alt="Previous Page" width="32"></A></td>
288<td><A href="openssl-ssl.html"><img src="up.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500289 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500290 alt="Up One Level" width="32"></A></td>
291<td><A href="openssl-connection.html"><img src="next.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500292 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500293 alt="Next Page" width="32"></A></td>
294<td align="center" width="100%">Python OpenSSL Manual</td>
295<td><A href="contents.html"><img src="contents.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500296 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500297 alt="Contents" width="32"></A></td>
298<td><img src="blank.gif"
299 border="0" height="32"
300 alt="" width="32"></td>
301<td><img src="blank.gif"
302 border="0" height="32"
303 alt="" width="32"></td>
304</tr></table>
305<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
306<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
307<b class="navlabel">Next:</b> <a class="sectref" href="openssl-connection.html">3.3.2 Connection objects</A>
308<hr>
Jean-Paul Calderone26ebc9e2011-04-11 19:57:10 -0400309<span class="release-info">Release 0.12.</span>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500310</DIV>
311<!--End of Navigation Panel-->
312
313</BODY>
314</HTML>