doc/html/openssl-ssl.html - platform/external/python/pyopenssl - Gitiles

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <title>3.3 SSL -- An interface to the SSL-specific parts of OpenSSL </title>
 <META NAME="description" CONTENT="3.3 SSL -- An interface to the SSL-specific parts of OpenSSL ">
 <META NAME="keywords" CONTENT="pyOpenSSL">
 <META NAME="resource-type" CONTENT="document">
 <META NAME="distribution" CONTENT="global">
 <link rel="STYLESHEET" href="pyOpenSSL.css">
 <LINK REL="previous" href="openssl-rand.html">
 <LINK REL="up" href="openssl.html">
 <LINK REL="next" href="openssl-context.html">
 </head>
 <body>
 <DIV CLASS="navigation">
 <table align="center" width="100%" cellpadding="0" cellspacing="2">
 <tr>
 <td><A href="openssl-rand.html"><img src="previous.gif"
   border="0" height="32"
   alt="Previous Page" width="32"></A></td>
 <td><A href="openssl.html"><img src="up.gif"
   border="0" height="32"
   alt="Up One Level" width="32"></A></td>
 <td><A href="openssl-context.html"><img src="next.gif"
   border="0" height="32"
   alt="Next Page" width="32"></A></td>
 <td align="center" width="100%">Python OpenSSL Manual</td>
 <td><A href="contents.html"><img src="contents.gif"
   border="0" height="32"
   alt="Contents" width="32"></A></td>
 <td><img src="blank.gif"
   border="0" height="32"
   alt="" width="32"></td>
 <td><img src="blank.gif"
   border="0" height="32"
   alt="" width="32"></td>
 </tr></table>
 <b class="navlabel">Previous:</b> <a class="sectref" href="openssl-rand.html">3.2 rand  </A>
 <b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL  </A>
 <b class="navlabel">Next:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
 <br><hr>
 </DIV>
 <!--End of Navigation Panel-->

 <H2><A NAME="SECTION000430000000000000000">&nbsp;</A>
 <BR>
 3.3 <tt class="module">SSL</tt> -- An interface to the SSL-specific parts of OpenSSL
 </H2>

 <P>


 <P>
 This module handles things specific to SSL. There are two objects defined:
 Context, Connection.

 <P>
 <dl><dt><b><a name='l2h-128'><tt>SSLv2_METHOD</tt></a></b>
 <dd>
 <dt><b><a name='l2h-142'><tt>SSLv3_METHOD</tt></a></b><dd>
 <dt><b><a name='l2h-143'><tt>SSLv23_METHOD</tt></a></b><dd>
 <dt><b><a name='l2h-144'><tt>TLSv1_METHOD</tt></a></b><dd>
 These constants represent the different SSL methods to use when creating a
 context object.
 </dl>

 <P>
 <dl><dt><b><a name='l2h-129'><tt>VERIFY_NONE</tt></a></b>
 <dd>
 <dt><b><a name='l2h-145'><tt>VERIFY_PEER</tt></a></b><dd>
 <dt><b><a name='l2h-146'><tt>VERIFY_FAIL_IF_NO_PEER_CERT</tt></a></b><dd>
 These constants represent the verification mode used by the Context
 object's <tt class="method">set_verify</tt> method.
 </dl>

 <P>
 <dl><dt><b><a name='l2h-130'><tt>FILETYPE_PEM</tt></a></b>
 <dd>
 <dt><b><a name='l2h-147'><tt>FILETYPE_ASN1</tt></a></b><dd>
 File type constants used with the <tt class="method">use_certificate_file</tt> and
 <tt class="method">use_privatekey_file</tt> methods of Context objects.
 </dl>

 <P>
 <dl><dt><b><a name='l2h-131'><tt>OP_SINGLE_DH_USE</tt></a></b>
 <dd>
 <dt><b><a name='l2h-148'><tt>OP_EPHEMERAL_RSA</tt></a></b><dd>
 <dt><b><a name='l2h-149'><tt>OP_NO_SSLv2</tt></a></b><dd>
 <dt><b><a name='l2h-150'><tt>OP_NO_SSLv3</tt></a></b><dd>
 <dt><b><a name='l2h-151'><tt>OP_NO_TLSv1</tt></a></b><dd>
 Constants used with <tt class="method">set_options</tt> of Context objects.
 <tt class="constant">OP_SINGLE_DH_USE</tt> means to always create a new key when using ephemeral
 Diffie-Hellman. <tt class="constant">OP_EPHEMERAL_RSA</tt> means to always use ephemeral RSA keys
 when doing RSA operations. <tt class="constant">OP_NO_SSLv2</tt>, <tt class="constant">OP_NO_SSLv3</tt> and
 <tt class="constant">OP_NO_TLSv1</tt> means to disable those specific protocols. This is
 interesting if you're using e.g. <tt class="constant">SSLv23_METHOD</tt> to get an SSLv2-compatible
 handshake, but don't want to use SSLv2.
 </dl>

 <P>
 <dl><dt><b><a name='l2h-132'><tt>ContextType</tt></a></b>
 <dd>
 See <tt class="class">Context</tt>.
 </dl>

 <P>
 <dl><dt><b>class <a name='l2h-133'><tt class='class'>Context</tt></a></b>(<var>method</var>)
 <dd>
 A class representing SSL contexts.  Contexts define the parameters of one or
 more SSL connections.

 <P>
 <var>method</var> should be <tt class="constant">SSLv2_METHOD</tt>, <tt class="constant">SSLv3_METHOD</tt>,
 <tt class="constant">SSLv23_METHOD</tt> or <tt class="constant">TLSv1_METHOD</tt>.
 </dl>

 <P>
 <dl><dt><b><a name='l2h-134'><tt>ConnectionType</tt></a></b>
 <dd>
 See <tt class="class">Connection</tt>.
 </dl>

 <P>
 <dl><dt><b>class <a name='l2h-135'><tt class='class'>Connection</tt></a></b>(<var>context, socket</var>)
 <dd>
 A class representing SSL connections.

 <P>
 <var>context</var> should be an instance of <tt class="class">Context</tt> and <var>socket</var>
 should be a socket <A NAME="tex2html4"
   HREF="#foot1231"><SUP>3</SUP></A> object.  <var>socket</var> may be
 <var>None</var>; in this case, the Connection is created with a memory BIO: see
 the <tt class="method">bio_read</tt>, <tt class="method">bio_write</tt>, and <tt class="method">bio_shutdown</tt>
 methods.
 </dl>

 <P>
 <dl><dt><b>exception <a name='l2h-136'><tt class='exception'>Error</tt></a></b>
 <dd>
 This exception is used as a base class for the other SSL-related
 exceptions, but may also be raised directly.

 <P>
 Whenever this exception is raised directly, it has a list of error messages
 from the OpenSSL error queue, where each item is a tuple <code>(<var>lib</var>,
 <var>function</var>, <var>reason</var>)</code>. Here <var>lib</var>, <var>function</var> and <var>reason</var>
 are all strings, describing where and what the problem is. See <span class='manpage'><i>err</i>(3)</span>
 for more information.
 </dl>

 <P>
 <dl><dt><b>exception <a name='l2h-137'><tt class='exception'>ZeroReturnError</tt></a></b>
 <dd>
 This exception matches the error return code <code>SSL_ERROR_ZERO_RETURN</code>, and
 is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this
 only occurs if a closure alert has occurred in the protocol, i.e. the
 connection has been closed cleanly. Note that this does not necessarily
 mean that the transport layer (e.g. a socket) has been closed.

 <P>
 It may seem a little strange that this is an exception, but it does match an
 <code>SSL_ERROR</code> code, and is very convenient.
 </dl>

 <P>
 <dl><dt><b>exception <a name='l2h-138'><tt class='exception'>WantReadError</tt></a></b>
 <dd>
 The operation did not complete; the same I/O method should be called again
 later, with the same arguments. Any I/O method can lead to this since new
 handshakes can occur at any time.

 <P>
 The wanted read is for <i>dirty</i> data sent over the network, not the
 <i>clean</i> data inside the tunnel.  For a socket based SSL connection,
 <i>read</i> means data coming at us over the network.  Until that read
 succeeds, the attempted <tt class="method">OpenSSL.SSL.Connection.recv</tt>,
 <tt class="method">OpenSSL.SSL.Connection.send</tt>, or
 <tt class="method">OpenSSL.SSL.Connection.do_handshake</tt> is prevented or incomplete. You
 probably want to <tt class="method">select()</tt> on the socket before trying again.
 </dl>

 <P>
 <dl><dt><b>exception <a name='l2h-139'><tt class='exception'>WantWriteError</tt></a></b>
 <dd>
 See <tt class="exception">WantReadError</tt>.  The socket send buffer may be too full to
 write more data.
 </dl>

 <P>
 <dl><dt><b>exception <a name='l2h-140'><tt class='exception'>WantX509LookupError</tt></a></b>
 <dd>
 The operation did not complete because an application callback has asked to be
 called again. The I/O method should be called again later, with the same
 arguments. Note: This won't occur in this version, as there are no such
 callbacks in this version.
 </dl>

 <P>
 <dl><dt><b>exception <a name='l2h-141'><tt class='exception'>SysCallError</tt></a></b>
 <dd>
 The <tt class="exception">SysCallError</tt> occurs when there's an I/O error and OpenSSL's
 error queue does not contain any information. This can mean two things: An
 error in the transport protocol, or an end of file that violates the protocol.
 The parameter to the exception is always a pair <code>(<var>errnum</var>,
 <var>errstr</var>)</code>.
 </dl>

 <P>
 <BR><HR><H4>Footnotes</H4>
 <DL>
 <DT><A NAME="foot1231">... socket</A><A
  href="openssl-ssl.html#tex2html4"><SUP>3</SUP></A></DT>
 <DD>Actually, all that is required is an object
 that <i>behaves</i> like a socket, you could even use files, even though
 it'd be tricky to get the handshakes right!

 </DD>
 </DL>
 <p><hr>
 <!--Table of Child-Links-->
 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>

 <UL CLASS="ChildLinks">
 <LI><A NAME="tex2html303"
   href="openssl-context.html">3.3.1 Context objects </A>
 <LI><A NAME="tex2html304"
   href="openssl-connection.html">3.3.2 Connection objects </A>
 </UL>
 <!--End of Table of Child-Links-->

 <DIV CLASS="navigation">
 <p><hr>
 <table align="center" width="100%" cellpadding="0" cellspacing="2">
 <tr>
 <td><A href="openssl-rand.html"><img src="previous.gif"
   border="0" height="32"
   alt="Previous Page" width="32"></A></td>
 <td><A href="openssl.html"><img src="up.gif"
   border="0" height="32"
   alt="Up One Level" width="32"></A></td>
 <td><A href="openssl-context.html"><img src="next.gif"
   border="0" height="32"
   alt="Next Page" width="32"></A></td>
 <td align="center" width="100%">Python OpenSSL Manual</td>
 <td><A href="contents.html"><img src="contents.gif"
   border="0" height="32"
   alt="Contents" width="32"></A></td>
 <td><img src="blank.gif"
   border="0" height="32"
   alt="" width="32"></td>
 <td><img src="blank.gif"
   border="0" height="32"
   alt="" width="32"></td>
 </tr></table>
 <b class="navlabel">Previous:</b> <a class="sectref" href="openssl-rand.html">3.2 rand  </A>
 <b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL  </A>
 <b class="navlabel">Next:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
 <hr>
 <span class="release-info">Release 0.11.</span>
 </DIV>
 <!--End of Navigation Panel-->

 </BODY>
 </HTML>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<title>3.3 SSL -- An interface to the SSL-specific parts of OpenSSL </title>
	<META NAME="description" CONTENT="3.3 SSL -- An interface to the SSL-specific parts of OpenSSL ">
	<META NAME="keywords" CONTENT="pyOpenSSL">
	<META NAME="resource-type" CONTENT="document">
	<META NAME="distribution" CONTENT="global">
	<link rel="STYLESHEET" href="pyOpenSSL.css">
	<LINK REL="previous" href="openssl-rand.html">
	<LINK REL="up" href="openssl.html">
	<LINK REL="next" href="openssl-context.html">
	</head>
	<body>
	<DIV CLASS="navigation">
	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	<tr>
	<td><A href="openssl-rand.html"><img src="previous.gif"
	border="0" height="32"
	alt="Previous Page" width="32"></A></td>
	<td><A href="openssl.html"><img src="up.gif"
	border="0" height="32"
	alt="Up One Level" width="32"></A></td>
	<td><A href="openssl-context.html"><img src="next.gif"
	border="0" height="32"
	alt="Next Page" width="32"></A></td>
	<td align="center" width="100%">Python OpenSSL Manual</td>
	<td><A href="contents.html"><img src="contents.gif"
	border="0" height="32"
	alt="Contents" width="32"></A></td>
	<td><img src="blank.gif"
	border="0" height="32"
	alt="" width="32"></td>
	<td><img src="blank.gif"
	border="0" height="32"
	alt="" width="32"></td>
	</tr></table>
	<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-rand.html">3.2 rand </A>
	<b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL </A>
	<b class="navlabel">Next:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
	<br><hr>
	</DIV>
	<!--End of Navigation Panel-->

	<H2><A NAME="SECTION000430000000000000000"> </A>
	<BR>
	3.3 <tt class="module">SSL</tt> -- An interface to the SSL-specific parts of OpenSSL
	</H2>

	<P>


	<P>
	This module handles things specific to SSL. There are two objects defined:
	Context, Connection.

	<P>
	<dl><dt><b><a name='l2h-128'><tt>SSLv2_METHOD</tt></a></b>
	<dd>
	<dt><b><a name='l2h-142'><tt>SSLv3_METHOD</tt></a></b><dd>
	<dt><b><a name='l2h-143'><tt>SSLv23_METHOD</tt></a></b><dd>
	<dt><b><a name='l2h-144'><tt>TLSv1_METHOD</tt></a></b><dd>
	These constants represent the different SSL methods to use when creating a
	context object.
	</dl>

	<P>
	<dl><dt><b><a name='l2h-129'><tt>VERIFY_NONE</tt></a></b>
	<dd>
	<dt><b><a name='l2h-145'><tt>VERIFY_PEER</tt></a></b><dd>
	<dt><b><a name='l2h-146'><tt>VERIFY_FAIL_IF_NO_PEER_CERT</tt></a></b><dd>
	These constants represent the verification mode used by the Context
	object's <tt class="method">set_verify</tt> method.
	</dl>

	<P>
	<dl><dt><b><a name='l2h-130'><tt>FILETYPE_PEM</tt></a></b>
	<dd>
	<dt><b><a name='l2h-147'><tt>FILETYPE_ASN1</tt></a></b><dd>
	File type constants used with the <tt class="method">use_certificate_file</tt> and
	<tt class="method">use_privatekey_file</tt> methods of Context objects.
	</dl>

	<P>
	<dl><dt><b><a name='l2h-131'><tt>OP_SINGLE_DH_USE</tt></a></b>
	<dd>
	<dt><b><a name='l2h-148'><tt>OP_EPHEMERAL_RSA</tt></a></b><dd>
	<dt><b><a name='l2h-149'><tt>OP_NO_SSLv2</tt></a></b><dd>
	<dt><b><a name='l2h-150'><tt>OP_NO_SSLv3</tt></a></b><dd>
	<dt><b><a name='l2h-151'><tt>OP_NO_TLSv1</tt></a></b><dd>
	Constants used with <tt class="method">set_options</tt> of Context objects.
	<tt class="constant">OP_SINGLE_DH_USE</tt> means to always create a new key when using ephemeral
	Diffie-Hellman. <tt class="constant">OP_EPHEMERAL_RSA</tt> means to always use ephemeral RSA keys
	when doing RSA operations. <tt class="constant">OP_NO_SSLv2</tt>, <tt class="constant">OP_NO_SSLv3</tt> and
	<tt class="constant">OP_NO_TLSv1</tt> means to disable those specific protocols. This is
	interesting if you're using e.g. <tt class="constant">SSLv23_METHOD</tt> to get an SSLv2-compatible
	handshake, but don't want to use SSLv2.
	</dl>

	<P>
	<dl><dt><b><a name='l2h-132'><tt>ContextType</tt></a></b>
	<dd>
	See <tt class="class">Context</tt>.
	</dl>

	<P>
	<dl><dt><b>class <a name='l2h-133'><tt class='class'>Context</tt></a></b>(<var>method</var>)
	<dd>
	A class representing SSL contexts. Contexts define the parameters of one or
	more SSL connections.

	<P>
	<var>method</var> should be <tt class="constant">SSLv2_METHOD</tt>, <tt class="constant">SSLv3_METHOD</tt>,
	<tt class="constant">SSLv23_METHOD</tt> or <tt class="constant">TLSv1_METHOD</tt>.
	</dl>

	<P>
	<dl><dt><b><a name='l2h-134'><tt>ConnectionType</tt></a></b>
	<dd>
	See <tt class="class">Connection</tt>.
	</dl>

	<P>
	<dl><dt><b>class <a name='l2h-135'><tt class='class'>Connection</tt></a></b>(<var>context, socket</var>)
	<dd>
	A class representing SSL connections.

	<P>
	<var>context</var> should be an instance of <tt class="class">Context</tt> and <var>socket</var>
	should be a socket <A NAME="tex2html4"
	HREF="#foot1231"><SUP>3</SUP></A> object. <var>socket</var> may be
	<var>None</var>; in this case, the Connection is created with a memory BIO: see
	the <tt class="method">bio_read</tt>, <tt class="method">bio_write</tt>, and <tt class="method">bio_shutdown</tt>
	methods.
	</dl>

	<P>
	<dl><dt><b>exception <a name='l2h-136'><tt class='exception'>Error</tt></a></b>
	<dd>
	This exception is used as a base class for the other SSL-related
	exceptions, but may also be raised directly.

	<P>
	Whenever this exception is raised directly, it has a list of error messages
	from the OpenSSL error queue, where each item is a tuple <code>(<var>lib</var>,
	<var>function</var>, <var>reason</var>)</code>. Here <var>lib</var>, <var>function</var> and <var>reason</var>
	are all strings, describing where and what the problem is. See <span class='manpage'><i>err</i>(3)</span>
	for more information.
	</dl>

	<P>
	<dl><dt><b>exception <a name='l2h-137'><tt class='exception'>ZeroReturnError</tt></a></b>
	<dd>
	This exception matches the error return code <code>SSL_ERROR_ZERO_RETURN</code>, and
	is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this
	only occurs if a closure alert has occurred in the protocol, i.e. the
	connection has been closed cleanly. Note that this does not necessarily
	mean that the transport layer (e.g. a socket) has been closed.

	<P>
	It may seem a little strange that this is an exception, but it does match an
	<code>SSL_ERROR</code> code, and is very convenient.
	</dl>

	<P>
	<dl><dt><b>exception <a name='l2h-138'><tt class='exception'>WantReadError</tt></a></b>
	<dd>
	The operation did not complete; the same I/O method should be called again
	later, with the same arguments. Any I/O method can lead to this since new
	handshakes can occur at any time.

	<P>
	The wanted read is for <i>dirty</i> data sent over the network, not the
	<i>clean</i> data inside the tunnel. For a socket based SSL connection,
	<i>read</i> means data coming at us over the network. Until that read
	succeeds, the attempted <tt class="method">OpenSSL.SSL.Connection.recv</tt>,
	<tt class="method">OpenSSL.SSL.Connection.send</tt>, or
	<tt class="method">OpenSSL.SSL.Connection.do_handshake</tt> is prevented or incomplete. You
	probably want to <tt class="method">select()</tt> on the socket before trying again.
	</dl>

	<P>
	<dl><dt><b>exception <a name='l2h-139'><tt class='exception'>WantWriteError</tt></a></b>
	<dd>
	See <tt class="exception">WantReadError</tt>. The socket send buffer may be too full to
	write more data.
	</dl>

	<P>
	<dl><dt><b>exception <a name='l2h-140'><tt class='exception'>WantX509LookupError</tt></a></b>
	<dd>
	The operation did not complete because an application callback has asked to be
	called again. The I/O method should be called again later, with the same
	arguments. Note: This won't occur in this version, as there are no such
	callbacks in this version.
	</dl>

	<P>
	<dl><dt><b>exception <a name='l2h-141'><tt class='exception'>SysCallError</tt></a></b>
	<dd>
	The <tt class="exception">SysCallError</tt> occurs when there's an I/O error and OpenSSL's
	error queue does not contain any information. This can mean two things: An
	error in the transport protocol, or an end of file that violates the protocol.
	The parameter to the exception is always a pair <code>(<var>errnum</var>,
	<var>errstr</var>)</code>.
	</dl>

	<P>
	<BR><HR><H4>Footnotes</H4>
	<DL>
	<DT><A NAME="foot1231">... socket</A><A
	href="openssl-ssl.html#tex2html4"><SUP>3</SUP></A></DT>
	<DD>Actually, all that is required is an object
	that <i>behaves</i> like a socket, you could even use files, even though
	it'd be tricky to get the handshakes right!

	</DD>
	</DL>
	<p><hr>
	<!--Table of Child-Links-->
	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>

	<UL CLASS="ChildLinks">
	<LI><A NAME="tex2html303"
	href="openssl-context.html">3.3.1 Context objects </A>
	<LI><A NAME="tex2html304"
	href="openssl-connection.html">3.3.2 Connection objects </A>
	</UL>
	<!--End of Table of Child-Links-->

	<DIV CLASS="navigation">
	<p><hr>
	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	<tr>
	<td><A href="openssl-rand.html"><img src="previous.gif"
	border="0" height="32"
	alt="Previous Page" width="32"></A></td>
	<td><A href="openssl.html"><img src="up.gif"
	border="0" height="32"
	alt="Up One Level" width="32"></A></td>
	<td><A href="openssl-context.html"><img src="next.gif"
	border="0" height="32"
	alt="Next Page" width="32"></A></td>
	<td align="center" width="100%">Python OpenSSL Manual</td>
	<td><A href="contents.html"><img src="contents.gif"
	border="0" height="32"
	alt="Contents" width="32"></A></td>
	<td><img src="blank.gif"
	border="0" height="32"
	alt="" width="32"></td>
	<td><img src="blank.gif"
	border="0" height="32"
	alt="" width="32"></td>
	</tr></table>
	<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-rand.html">3.2 rand </A>
	<b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL </A>
	<b class="navlabel">Next:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
	<hr>
	<span class="release-info">Release 0.11.</span>
	</DIV>
	<!--End of Navigation Panel-->

	</BODY>
	</HTML>