Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / pyopenssl / ec48cd56e0b0bada9b5556a2c759f3f6fef5c9d1 / . / doc / html / openssl-context.html
blob: 3d155bfc9036b7a3894609afa6a66b43f8e25194 [file] [log] [blame]
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]1<!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"
20border="0" height="32"
21 alt="Previous Page" width="32"></A></td>
22<td><A href="openssl-ssl.html"><img src="up.gif"
23border="0" height="32"
24 alt="Up One Level" width="32"></A></td>
25<td><A href="openssl-connection.html"><img src="next.gif"
26border="0" height="32"
27 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"
30border="0" height="32"
31 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 -0500[diff] [blame]50
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]51<P>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]52Context objects have the following methods:
53
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]54<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]55<dl><dt><b><a name='l2h-124'><tt class='method'>check_privatekey</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]56<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 -0500[diff] [blame]59Returns <code>None</code> if they match, raises <tt class="exception">Error</tt> otherwise.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]60</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]61
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]62<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]63<dl><dt><b><a name='l2h-125'><tt class='method'>get_app_data</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]64<dd>
65Retrieve application data as set by <tt class="method">set_app_data</tt>.
66</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]67
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]68<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]69<dl><dt><b><a name='l2h-126'><tt class='method'>get_cert_store</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]70<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 -0500[diff] [blame]75
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]76<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]77<dl><dt><b><a name='l2h-127'><tt class='method'>get_timeout</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]78<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 -0500[diff] [blame]82
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]83<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]84<dl><dt><b><a name='l2h-128'><tt class='method'>get_verify_depth</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]85<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 -0500[diff] [blame]89
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]90<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]91<dl><dt><b><a name='l2h-129'><tt class='method'>get_verify_mode</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]92<dd>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]93Retrieve the Context object's verify mode, as set by <tt class="method">set_verify</tt>.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]94</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]95
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]96<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]97<dl><dt><b><a name='l2h-130'><tt class='method'>load_client_ca</tt></a></b>(<var>pemfile</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]98<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 -0500[diff] [blame]102
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]103<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]104<dl><dt><b><a name='l2h-131'><tt class='method'>load_verify_locations</tt></a></b>(<var>pemfile, capath</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]105<dd>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]106Specify where CA certificates for verification purposes are located. These
107are trusted certificates. Note that the certificates have to be in PEM
108format. If capath is passed, it must be a directory prepared using the
109<code>c_rehash</code> tool included with OpenSSL. Either, but not both, of
110<var>pemfile</var> or <var>capath</var> may be <code>None</code>.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]111</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]112
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]113<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]114<dl><dt><b><a name='l2h-132'><tt class='method'>set_default_verify_paths</tt></a></b>()
115<dd>
116Specify that the platform provided CA certificates are to be used for
117verification purposes. This method may not work properly on OS X.
118</dl>
119
120<P>
121<dl><dt><b><a name='l2h-133'><tt class='method'>load_tmp_dh</tt></a></b>(<var>dhfile</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]122<dd>
123Load parameters for Ephemeral Diffie-Hellman from <var>dhfile</var>.
124</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]125
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]126<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]127<dl><dt><b><a name='l2h-134'><tt class='method'>set_app_data</tt></a></b>(<var>data</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]128<dd>
129Associate <var>data</var> with this Context object. <var>data</var> can be retrieved
130later using the <tt class="method">get_app_data</tt> method.
131</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]132
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]133<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]134<dl><dt><b><a name='l2h-135'><tt class='method'>set_cipher_list</tt></a></b>(<var>ciphers</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]135<dd>
136Set the list of ciphers to be used in this context. See the OpenSSL manual for
137more information (e.g. ciphers(1))
138</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]139
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]140<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]141<dl><dt><b><a name='l2h-136'><tt class='method'>set_info_callback</tt></a></b>(<var>callback</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]142<dd>
143Set the information callback to <var>callback</var>. This function will be called
144from time to time during SSL handshakes.
Jean-Paul Calderone420bf212008-02-19 21:19:30 -0500[diff] [blame]145<var>callback</var> should take three arguments: a Connection object and two
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]146integers. The first integer specifies where in the SSL handshake the function
147was called, and the other the return code from a (possibly failed) internal
148function call.
149</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]150
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]151<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]152<dl><dt><b><a name='l2h-137'><tt class='method'>set_options</tt></a></b>(<var>options</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]153<dd>
154Add SSL options. Options you have set before are not cleared!
Jean-Paul Calderone420bf212008-02-19 21:19:30 -0500[diff] [blame]155This method should be used with the <tt class="constant">OP_*</tt> constants.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]156</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]157
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]158<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]159<dl><dt><b><a name='l2h-138'><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 -0500[diff] [blame]160<dd>
161Set the passphrase callback to <var>callback</var>. This function will be called
Jean-Paul Calderone1eeb29e2008-10-19 11:50:53 -0400[diff] [blame]162when a private key with a passphrase is loaded. <var>callback</var> must accept
163three positional arguments. First, an integer giving the maximum length of
164the passphrase it may return. If the returned passphrase is longer than
165this, it will be truncated. Second, a boolean value which will be true if
166the user should be prompted for the passphrase twice and the callback should
167verify that the two values supplied are equal. Third, the value given as the
168<var>userdata</var> parameter to <tt class="method">set_passwd_cb</tt>. If an error occurs,
169<var>callback</var> should return a false value (e.g. an empty string).
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]170</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]171
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]172<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]173<dl><dt><b><a name='l2h-139'><tt class='method'>set_session_id</tt></a></b>(<var>name</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]174<dd>
175Set the context <var>name</var> within which a session can be reused for this
176Context object. This is needed when doing session resumption, because there is
177no way for a stored session to know which Context object it is associated with.
178<var>name</var> may be any binary data.
179</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]180
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]181<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]182<dl><dt><b><a name='l2h-140'><tt class='method'>set_timeout</tt></a></b>(<var>timeout</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]183<dd>
184Set the timeout for newly created sessions for this Context object to
185<var>timeout</var>. <var>timeout</var> must be given in (whole) seconds. The default
186value is 300 seconds. See the OpenSSL manual for more information (e.g.
187SSL_CTX_set_timeout(3)).
188</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]189
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]190<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]191<dl><dt><b><a name='l2h-141'><tt class='method'>set_verify</tt></a></b>(<var>mode, callback</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]192<dd>
193Set the verification flags for this Context object to <var>mode</var> and specify
194that <var>callback</var> should be used for verification callbacks. <var>mode</var>
195should be one of <tt class="constant">VERIFY_NONE</tt> and <tt class="constant">VERIFY_PEER</tt>. If
196<tt class="constant">VERIFY_PEER</tt> is used, <var>mode</var> can be OR:ed with
197<tt class="constant">VERIFY_FAIL_IF_NO_PEER_CERT</tt> and <tt class="constant">VERIFY_CLIENT_ONCE</tt> to
198further control the behaviour.
Jean-Paul Calderone420bf212008-02-19 21:19:30 -0500[diff] [blame]199<var>callback</var> should take five arguments: A Connection object, an X509 object,
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]200and three integer variables, which are in turn potential error number, error
201depth and return code. <var>callback</var> should return true if verification passes
202and false otherwise.
203</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]204
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]205<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]206<dl><dt><b><a name='l2h-142'><tt class='method'>set_verify_depth</tt></a></b>(<var>depth</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]207<dd>
208Set the maximum depth for the certificate chain verification that shall be
209allowed for this Context object.
210</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]211
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]212<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]213<dl><dt><b><a name='l2h-143'><tt class='method'>use_certificate</tt></a></b>(<var>cert</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]214<dd>
215Use the certificate <var>cert</var> which has to be a X509 object.
216</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]217
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]218<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]219<dl><dt><b><a name='l2h-144'><tt class='method'>add_extra_chain_cert</tt></a></b>(<var>cert</var>)
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]220<dd>
221Adds the certificate <var>cert</var>, which has to be a X509 object, to the
222certificate chain presented together with the certificate.
223</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]224
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]225<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]226<dl><dt><b><a name='l2h-145'><tt class='method'>use_certificate_chain_file</tt></a></b>(<var>file</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]227<dd>
228Load a certificate chain from <var>file</var> which must be PEM encoded.
229</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]230
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]231<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]232<dl><dt><b><a name='l2h-146'><tt class='method'>use_privatekey</tt></a></b>(<var>pkey</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]233<dd>
234Use the private key <var>pkey</var> which has to be a PKey object.
235</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]236
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]237<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]238<dl><dt><b><a name='l2h-147'><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 -0500[diff] [blame]239<dd>
240Load the first certificate found in <var>file</var>. The certificate must be in the
241format specified by <var>format</var>, which is either <tt class="constant">FILETYPE_PEM</tt> or
242<tt class="constant">FILETYPE_ASN1</tt>. The default is <tt class="constant">FILETYPE_PEM</tt>.
243</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]244
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]245<P>
Jean-Paul Calderone6c1d4f92009-03-07 09:10:30 -0500[diff] [blame]246<dl><dt><b><a name='l2h-148'><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 -0500[diff] [blame]247<dd>
248Load the first private key found in <var>file</var>. The private key must be in the
249format specified by <var>format</var>, which is either <tt class="constant">FILETYPE_PEM</tt> or
250<tt class="constant">FILETYPE_ASN1</tt>. The default is <tt class="constant">FILETYPE_PEM</tt>.
251</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]252
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]253<P>
254
255<DIV CLASS="navigation">
256<p><hr>
257<table align="center" width="100%" cellpadding="0" cellspacing="2">
258<tr>
259<td><A href="openssl-ssl.html"><img src="previous.gif"
260border="0" height="32"
261 alt="Previous Page" width="32"></A></td>
262<td><A href="openssl-ssl.html"><img src="up.gif"
263border="0" height="32"
264 alt="Up One Level" width="32"></A></td>
265<td><A href="openssl-connection.html"><img src="next.gif"
266border="0" height="32"
267 alt="Next Page" width="32"></A></td>
268<td align="center" width="100%">Python OpenSSL Manual</td>
269<td><A href="contents.html"><img src="contents.gif"
270border="0" height="32"
271 alt="Contents" width="32"></A></td>
272<td><img src="blank.gif"
273 border="0" height="32"
274 alt="" width="32"></td>
275<td><img src="blank.gif"
276 border="0" height="32"
277 alt="" width="32"></td>
278</tr></table>
279<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
280<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
281<b class="navlabel">Next:</b> <a class="sectref" href="openssl-connection.html">3.3.2 Connection objects</A>
282<hr>
Jean-Paul Calderonef7f0fb42008-10-19 11:55:13 -0400[diff] [blame]283<span class="release-info">Release 0.8.</span>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]284</DIV>
285<!--End of Navigation Panel-->
286
287</BODY>
288</HTML>