Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / pyopenssl / 897bc2556fed43b76f6d1b14470c3e806df15af8 / . / doc / html / openssl-ssl.html
blob: 5aee0007b96bdbdb536124887adf7a6e8ceb9760 [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 SSL -- An interface to the SSL-specific parts of OpenSSL </title>
5<META NAME="description" CONTENT="3.3 SSL -- An interface to the SSL-specific parts of OpenSSL ">
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="previous" href="openssl-rand.html">
11<LINK REL="up" href="openssl.html">
12<LINK REL="next" href="openssl-context.html">
13</head>
14<body>
15<DIV CLASS="navigation">
16<table align="center" width="100%" cellpadding="0" cellspacing="2">
17<tr>
18<td><A href="openssl-rand.html"><img src="previous.gif"
19border="0" height="32"
20 alt="Previous Page" width="32"></A></td>
21<td><A href="openssl.html"><img src="up.gif"
22border="0" height="32"
23 alt="Up One Level" width="32"></A></td>
24<td><A href="openssl-context.html"><img src="next.gif"
25border="0" height="32"
26 alt="Next Page" width="32"></A></td>
27<td align="center" width="100%">Python OpenSSL Manual</td>
28<td><A href="contents.html"><img src="contents.gif"
29border="0" height="32"
30 alt="Contents" width="32"></A></td>
31<td><img src="blank.gif"
32 border="0" height="32"
33 alt="" width="32"></td>
34<td><img src="blank.gif"
35 border="0" height="32"
36 alt="" width="32"></td>
37</tr></table>
38<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-rand.html">3.2 rand </A>
39<b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL </A>
40<b class="navlabel">Next:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
41<br><hr>
42</DIV>
43<!--End of Navigation Panel-->
44<H2><A NAME="SECTION000430000000000000000">&nbsp;</A>
45<BR>
463.3 <tt class="module">SSL</tt> -- An interface to the SSL-specific parts of OpenSSL
47</H2>
48<P>
49<EM><EM><EM>
50</EM></EM></EM>
51<P>
52<EM><EM><EM>This module handles things specific to SSL. There are two objects defined:
53Context, Connection.
54</EM></EM></EM>
55<P>
56<dl><dt><b><a name='l2h-90'><tt>SSLv2_METHOD</tt></a></b>
57<dd>
58<dt><b><a name='l2h-104'><tt>SSLv3_METHOD</tt></a></b><dd>
59<dt><b><a name='l2h-105'><tt>SSLv23_METHOD</tt></a></b><dd>
60<dt><b><a name='l2h-106'><tt>TLSv1_METHOD</tt></a></b><dd>
61These constants represent the different SSL methods to use when creating a
62context object.
63</dl>
64<P>
65<dl><dt><b><a name='l2h-91'><tt>VERIFY_NONE</tt></a></b>
66<dd>
67<dt><b><a name='l2h-107'><tt>VERIFY_PEER</tt></a></b><dd>
68<dt><b><a name='l2h-108'><tt>VERIFY_FAIL_IF_NO_PEER_CERT</tt></a></b><dd>
69These constants represent the verification mode used by the Context
70object's <tt class="method">set_verify</tt> method.
71</dl>
72<P>
73<dl><dt><b><a name='l2h-92'><tt>FILETYPE_PEM</tt></a></b>
74<dd>
75<dt><b><a name='l2h-109'><tt>FILETYPE_ASN1</tt></a></b><dd>
76File type constants used with the <tt class="method">use_certificate_file</tt> and
77<tt class="method">use_privatekey_file</tt> methods of Context objects.
78</dl>
79<P>
80<dl><dt><b><a name='l2h-93'><tt>OP_SINGLE_DH_USE</tt></a></b>
81<dd>
82<dt><b><a name='l2h-110'><tt>OP_EPHEMERAL_RSA</tt></a></b><dd>
83<dt><b><a name='l2h-111'><tt>OP_NO_SSLv2</tt></a></b><dd>
84<dt><b><a name='l2h-112'><tt>OP_NO_SSLv3</tt></a></b><dd>
85<dt><b><a name='l2h-113'><tt>OP_NO_TLSv1</tt></a></b><dd>
86Constants used with <tt class="method">set_options</tt> of Context objects.
87<tt class="constant">OP_SINGLE_DH_USE</tt> means to always create a new key when using ephemeral
88Diffie-Hellman. <tt class="constant">OP_EPHEMERAL_RSA</tt> means to always use ephemeral RSA keys
89when doing RSA operations. <tt class="constant">OP_NO_SSLv2</tt>, <tt class="constant">OP_NO_SSLv3</tt> and
90<tt class="constant">OP_NO_TLSv1</tt> means to disable those specific protocols. This is
91interesting if you're using e.g. <tt class="constant">SSLv23_METHOD</tt> to get an SSLv2-compatible
92handshake, but don't want to use SSLv2.
93</dl>
94<P>
95<dl><dt><b><a name='l2h-94'><tt>ContextType</tt></a></b>
96<dd>
97A Python type object representing the Context object type.
98</dl>
99<P>
100<dl><dt><b><a name='l2h-95'><tt class='function'>Context</tt></a></b>(<var>method</var>)
101<dd>
102Factory function that creates a new Context object given an SSL method. The
103method should be <tt class="constant">SSLv2_METHOD</tt>, <tt class="constant">SSLv3_METHOD</tt>,
104<tt class="constant">SSLv23_METHOD</tt> or <tt class="constant">TLSv1_METHOD</tt>.
105</dl>
106<P>
107<dl><dt><b><a name='l2h-96'><tt>ConnectionType</tt></a></b>
108<dd>
109A Python type object representing the Connection object type.
110</dl>
111<P>
112<dl><dt><b><a name='l2h-97'><tt class='function'>Connection</tt></a></b>(<var>context, socket</var>)
113<dd>
114Factory fucnction that creates a new Connection object given an SSL context and
115a socket <A NAME="tex2html5"
116 HREF="#foot901"><SUP>4</SUP></A> object.
117</dl>
118<P>
119<dl><dt><b>exception <a name='l2h-98'><tt class='exception'>Error</tt></a></b>
120<dd>
121This exception is used as a base class for the other SSL-related
122exceptions, but may also be raised directly.
123</EM></EM></EM>
124<P>
125<EM><EM><EM>Whenever this exception is raised directly, it has a list of error messages
126from the OpenSSL error queue, where each item is a tuple <code>(<var>lib</var>,
127<var>function</var>, <var>reason</var>)</code>. Here <var>lib</var>, <var>function</var> and <var>reason</var>
128are all strings, describing where and what the problem is. See <span class='manpage'><i>err</i>(3)</span>
129for more information.
130</dl>
131<P>
132<dl><dt><b>exception <a name='l2h-99'><tt class='exception'>ZeroReturnError</tt></a></b>
133<dd>
134This exception matches the error return code <code>SSL_ERROR_ZERO_RETURN</code>, and
135is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this
136only occurs if a closure alert has occurred in the protocol, i.e. the
137connection has been closed cleanly. Note that this does not necessarily
138mean that the transport layer (e.g. a socket) has been closed.
139</EM></EM></EM>
140<P>
141<EM><EM><EM>It may seem a little strange that this is an exception, but it does match an
142<code>SSL_ERROR</code> code, and is very convenient.
143</dl>
144<P>
145<dl><dt><b>exception <a name='l2h-100'><tt class='exception'>WantReadError</tt></a></b>
146<dd>
147The operation did not complete; the same I/O method should be called again
148later, with the same arguments. Any I/O method can lead to this since new
149handshakes can occur at any time.
150</dl>
151<P>
152<dl><dt><b>exception <a name='l2h-101'><tt class='exception'>WantWriteError</tt></a></b>
153<dd>
154See <tt class="exception">WantReadError</tt>.
155</dl>
156<P>
157<dl><dt><b>exception <a name='l2h-102'><tt class='exception'>WantX509LookupError</tt></a></b>
158<dd>
159The operation did not complete because an application callback has asked to be
160called again. The I/O method should be called again later, with the same
161arguments. Note: This won't occur in this version, as there are no such
162callbacks in this version.
163</dl>
164<P>
165<dl><dt><b>exception <a name='l2h-103'><tt class='exception'>SysCallError</tt></a></b>
166<dd>
167The <tt class="exception">SysCallError</tt> occurs when there's an I/O error and OpenSSL's
168error queue does not contain any information. This can mean two things: An
169error in the transport protocol, or an end of file that violates the protocol.
170The parameter to the exception is always a pair <code>(<var>errnum</var>,
171<var>errstr</var>)</code>.
172</dl>
173<P>
174<BR><HR><H4>Footnotes</H4>
175<DL>
176<DT><A NAME="foot901">... socket</A><A
177 href="openssl-ssl.html#tex2html5"><SUP>4</SUP></A></DT>
178<DD>Actually, all that is required is an object that
179<i>behaves</i> like a socket, you could even use files, even though it'd be
180tricky to get the handshakes right!
181
182</DD>
183</DL>
184<p><hr>
185
186<!--Table of Child-Links-->
187<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
188
189<UL CLASS="ChildLinks">
190<LI><A NAME="tex2html263"
191 href="openssl-context.html">3.3.1 Context objects </A>
192<LI><A NAME="tex2html264"
193 href="openssl-connection.html">3.3.2 Connection objects </A>
194</UL>
195<!--End of Table of Child-Links-->
196
197<DIV CLASS="navigation">
198<p><hr>
199<table align="center" width="100%" cellpadding="0" cellspacing="2">
200<tr>
201<td><A href="openssl-rand.html"><img src="previous.gif"
202border="0" height="32"
203 alt="Previous Page" width="32"></A></td>
204<td><A href="openssl.html"><img src="up.gif"
205border="0" height="32"
206 alt="Up One Level" width="32"></A></td>
207<td><A href="openssl-context.html"><img src="next.gif"
208border="0" height="32"
209 alt="Next Page" width="32"></A></td>
210<td align="center" width="100%">Python OpenSSL Manual</td>
211<td><A href="contents.html"><img src="contents.gif"
212border="0" height="32"
213 alt="Contents" width="32"></A></td>
214<td><img src="blank.gif"
215 border="0" height="32"
216 alt="" width="32"></td>
217<td><img src="blank.gif"
218 border="0" height="32"
219 alt="" width="32"></td>
220</tr></table>
221<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-rand.html">3.2 rand </A>
222<b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL </A>
223<b class="navlabel">Next:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
224<hr>
225<span class="release-info">Release 0.6.</span>
226</DIV>
227<!--End of Navigation Panel-->
228
229</BODY>
230</HTML>