Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / pyopenssl / f7f0fb4f10329ff1205b50a4cc9d6bea5f84c7ae / . / doc / html / openssl-context.html
blob: 011688c0f251610f0537d94e3f89b7f2e5e15162 [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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]55<dl><dt><b><a name='l2h-121'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]63<dl><dt><b><a name='l2h-122'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]69<dl><dt><b><a name='l2h-123'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]77<dl><dt><b><a name='l2h-124'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]84<dl><dt><b><a name='l2h-125'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]91<dl><dt><b><a name='l2h-126'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]97<dl><dt><b><a name='l2h-127'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]104<dl><dt><b><a name='l2h-128'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]111<dl><dt><b><a name='l2h-129'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]117<dl><dt><b><a name='l2h-130'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]124<dl><dt><b><a name='l2h-131'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]131<dl><dt><b><a name='l2h-132'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]142<dl><dt><b><a name='l2h-133'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]149<dl><dt><b><a name='l2h-134'><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
Jean-Paul Calderone1eeb29e2008-10-19 11:50:53 -0400[diff] [blame]152when a private key with a passphrase is loaded. <var>callback</var> must accept
153three positional arguments. First, an integer giving the maximum length of
154the passphrase it may return. If the returned passphrase is longer than
155this, it will be truncated. Second, a boolean value which will be true if
156the user should be prompted for the passphrase twice and the callback should
157verify that the two values supplied are equal. Third, the value given as the
158<var>userdata</var> parameter to <tt class="method">set_passwd_cb</tt>. If an error occurs,
159<var>callback</var> should return a false value (e.g. an empty string).
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]163<dl><dt><b><a name='l2h-135'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]172<dl><dt><b><a name='l2h-136'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]181<dl><dt><b><a name='l2h-137'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]196<dl><dt><b><a name='l2h-138'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]203<dl><dt><b><a name='l2h-139'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]209<dl><dt><b><a name='l2h-140'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]216<dl><dt><b><a name='l2h-141'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]222<dl><dt><b><a name='l2h-142'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]228<dl><dt><b><a name='l2h-143'><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 Calderonec54cc182008-03-26 21:11:07 -0400[diff] [blame]236<dl><dt><b><a name='l2h-144'><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 Calderonef7f0fb42008-10-19 11:55:13 -0400[diff] [blame^]273<span class="release-info">Release 0.8.</span>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]274</DIV>
275<!--End of Navigation Panel-->
276
277</BODY>
278</HTML>