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