blob: 93b72bc1e1776281fcbe998821060158412b0980 [file] [log] [blame]
Jean-Paul Calderone897bc252008-02-18 20:50:23 -05001<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<title>3.3.2 Connection objects </title>
5<META NAME="description" CONTENT="3.3.2 Connection 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="previous" href="openssl-context.html">
11<LINK REL="up" href="openssl-ssl.html">
12<LINK REL="next" href="internals.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-context.html"><img src="previous.gif"
19border="0" height="32"
20 alt="Previous Page" width="32"></A></td>
21<td><A href="openssl-ssl.html"><img src="up.gif"
22border="0" height="32"
23 alt="Up One Level" width="32"></A></td>
24<td><A href="internals.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-context.html">3.3.1 Context objects</A>
39<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
40<b class="navlabel">Next:</b> <a class="sectref" href="internals.html">4 Internals</A>
41<br><hr>
42</DIV>
43<!--End of Navigation Panel-->
44
45<H3><A NAME="SECTION000432000000000000000">&nbsp;</A>
46<BR>
473.3.2 Connection objects
48</H3>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050049
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050050<P>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050051Connection objects have the following methods:
52
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050053<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -040054<dl><dt><b><a name='l2h-145'><tt class='method'>accept</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050055<dd>
56Call the <tt class="method">accept</tt> method of the underlying socket and set up SSL on the
57returned socket, using the Context object supplied to this Connection object at
58creation. Returns a pair <code>(<var>conn</var>, <var>address</var>)</code>. where <var>conn</var>
59is the new Connection object created, and <var>address</var> is as returned by the
60socket's <tt class="method">accept</tt>.
61</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050062
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050063<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -040064<dl><dt><b><a name='l2h-146'><tt class='method'>bind</tt></a></b>(<var>address</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050065<dd>
66Call the <tt class="method">bind</tt> method of the underlying socket.
67</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050068
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050069<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -040070<dl><dt><b><a name='l2h-147'><tt class='method'>close</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050071<dd>
72Call the <tt class="method">close</tt> method of the underlying socket. Note: If you want
73correct SSL closure, you need to call the <tt class="method">shutdown</tt> method first.
74</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050075
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050076<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -040077<dl><dt><b><a name='l2h-148'><tt class='method'>connect</tt></a></b>(<var>address</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050078<dd>
79Call the <tt class="method">connect</tt> method of the underlying socket and set up SSL on the
80socket, using the Context object supplied to this Connection object at
81creation.
82</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050083
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050084<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -040085<dl><dt><b><a name='l2h-149'><tt class='method'>connect_ex</tt></a></b>(<var>address</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050086<dd>
87Call the <tt class="method">connect_ex</tt> method of the underlying socket and set up SSL on
88the socket, using the Context object supplied to this Connection object at
89creation. Note that if the <tt class="method">connect_ex</tt> method of the socket doesn't
90return 0, SSL won't be initialized.
91</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -050092
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050093<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -040094<dl><dt><b><a name='l2h-150'><tt class='method'>do_handshake</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -050095<dd>
96Perform an SSL handshake (usually called after <tt class="method">renegotiate</tt> or one of
97<tt class="method">set_accept_state</tt> or <tt class="method">set_accept_state</tt>). This can raise the
98same exceptions as <tt class="method">send</tt> and <tt class="method">recv</tt>.
99</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500100
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500101<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400102<dl><dt><b><a name='l2h-151'><tt class='method'>fileno</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500103<dd>
104Retrieve the file descriptor number for the underlying socket.
105</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500106
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500107<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400108<dl><dt><b><a name='l2h-152'><tt class='method'>listen</tt></a></b>(<var>backlog</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500109<dd>
110Call the <tt class="method">listen</tt> method of the underlying socket.
111</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500112
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500113<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400114<dl><dt><b><a name='l2h-153'><tt class='method'>get_app_data</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500115<dd>
116Retrieve application data as set by <tt class="method">set_app_data</tt>.
117</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500118
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500119<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400120<dl><dt><b><a name='l2h-154'><tt class='method'>get_cipher_list</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500121<dd>
122Retrieve the list of ciphers used by the Connection object. WARNING: This API
123has changed. It used to take an optional parameter and just return a string,
124but not it returns the entire list in one go.
125</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500126
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500127<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400128<dl><dt><b><a name='l2h-155'><tt class='method'>get_context</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500129<dd>
130Retrieve the Context object associated with this Connection.
131</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500132
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500133<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400134<dl><dt><b><a name='l2h-156'><tt class='method'>get_peer_certificate</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500135<dd>
136Retrieve the other side's certificate (if any)
137</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500138
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500139<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400140<dl><dt><b><a name='l2h-157'><tt class='method'>getpeername</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500141<dd>
142Call the <tt class="method">getpeername</tt> method of the underlying socket.
143</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500144
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500145<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400146<dl><dt><b><a name='l2h-158'><tt class='method'>getsockname</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500147<dd>
148Call the <tt class="method">getsockname</tt> method of the underlying socket.
149</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500150
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500151<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400152<dl><dt><b><a name='l2h-159'><tt class='method'>getsockopt</tt></a></b>(<var>level, optname</var><big>[</big><var>, buflen</var><big>]</big>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500153<dd>
154Call the <tt class="method">getsockopt</tt> method of the underlying socket.
155</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500156
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500157<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400158<dl><dt><b><a name='l2h-160'><tt class='method'>pending</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500159<dd>
Jean-Paul Calderoneb6f57be2008-03-06 21:22:16 -0500160Retrieve the number of bytes that can be safely read from the SSL buffer
161(<i>not</i> the underlying transport buffer).
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500162</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500163
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500164<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400165<dl><dt><b><a name='l2h-161'><tt class='method'>recv</tt></a></b>(<var>bufsize</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500166<dd>
167Receive data from the Connection. The return value is a string representing the
168data received. The maximum amount of data to be received at once, is specified
169by <var>bufsize</var>.
170</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500171
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500172<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400173<dl><dt><b><a name='l2h-162'><tt class='method'>renegotiate</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500174<dd>
175Renegotiate the SSL session. Call this if you wish to change cipher suites or
176anything like that.
177</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500178
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500179<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400180<dl><dt><b><a name='l2h-163'><tt class='method'>send</tt></a></b>(<var>string</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500181<dd>
182Send the <var>string</var> data to the Connection.
183</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500184
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500185<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400186<dl><dt><b><a name='l2h-164'><tt class='method'>sendall</tt></a></b>(<var>string</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500187<dd>
188Send all of the <var>string</var> data to the Connection. This calls <tt class="method">send</tt>
189repeatedly until all data is sent. If an error occurs, it's impossible to tell
190how much data has been sent.
191</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500192
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500193<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400194<dl><dt><b><a name='l2h-165'><tt class='method'>set_accept_state</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500195<dd>
196Set the connection to work in server mode. The handshake will be handled
197automatically by read/write.
198</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500199
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500200<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400201<dl><dt><b><a name='l2h-166'><tt class='method'>set_app_data</tt></a></b>(<var>data</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500202<dd>
203Associate <var>data</var> with this Connection object. <var>data</var> can be retrieved
204later using the <tt class="method">get_app_data</tt> method.
205</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500206
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500207<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400208<dl><dt><b><a name='l2h-167'><tt class='method'>set_connect_state</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500209<dd>
210Set the connection to work in client mode. The handshake will be handled
211automatically by read/write.
212</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500213
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500214<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400215<dl><dt><b><a name='l2h-168'><tt class='method'>setblocking</tt></a></b>(<var>flag</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500216<dd>
217Call the <tt class="method">setblocking</tt> method of the underlying socket.
218</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500219
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500220<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400221<dl><dt><b><a name='l2h-169'><tt class='method'>setsockopt</tt></a></b>(<var>level, optname, value</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500222<dd>
223Call the <tt class="method">setsockopt</tt> method of the underlying socket.
224</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500225
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500226<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400227<dl><dt><b><a name='l2h-170'><tt class='method'>shutdown</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500228<dd>
229Send the shutdown message to the Connection. Returns true if the shutdown
230message exchange is completed and false otherwise (in which case you call
231<tt class="method">recv()</tt> or <tt class="method">send()</tt> when the connection becomes
232readable/writeable.
233</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500234
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500235<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400236<dl><dt><b><a name='l2h-171'><tt class='method'>get_shutdown</tt></a></b>()
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500237<dd>
238Get the shutdown state of the Connection. Returns a bitvector of either or
239both of <var>SENT_SHUTDOWN</var> and <var>RECEIVED_SHUTDOWN</var>.
240</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500241
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500242<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400243<dl><dt><b><a name='l2h-172'><tt class='method'>set_shutdown</tt></a></b>(<var>state</var>)
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500244<dd>
245Set the shutdown state of the Connection. <var>state</var> is a bitvector of
246either or both of <var>SENT_SHUTDOWN</var> and <var>RECEIVED_SHUTDOWN</var>.
247</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500248
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500249<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400250<dl><dt><b><a name='l2h-173'><tt class='method'>sock_shutdown</tt></a></b>(<var>how</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500251<dd>
252Call the <tt class="method">shutdown</tt> method of the underlying socket.
253</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500254
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500255<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400256<dl><dt><b><a name='l2h-174'><tt class='method'>state_string</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500257<dd>
258Retrieve a verbose string detailing the state of the Connection.
259</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500260
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500261<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400262<dl><dt><b><a name='l2h-175'><tt class='method'>want_read</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500263<dd>
264Checks if more data has to be read from the transport layer to complete an
265operation.
266</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500267
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500268<P>
Jean-Paul Calderonec54cc182008-03-26 21:11:07 -0400269<dl><dt><b><a name='l2h-176'><tt class='method'>want_write</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500270<dd>
271Checks if there is data to write to the transport layer to complete an
272operation.
273</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500274
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500275<P>
276
277<DIV CLASS="navigation">
278<p><hr>
279<table align="center" width="100%" cellpadding="0" cellspacing="2">
280<tr>
281<td><A href="openssl-context.html"><img src="previous.gif"
282border="0" height="32"
283 alt="Previous Page" width="32"></A></td>
284<td><A href="openssl-ssl.html"><img src="up.gif"
285border="0" height="32"
286 alt="Up One Level" width="32"></A></td>
287<td><A href="internals.html"><img src="next.gif"
288border="0" height="32"
289 alt="Next Page" width="32"></A></td>
290<td align="center" width="100%">Python OpenSSL Manual</td>
291<td><A href="contents.html"><img src="contents.gif"
292border="0" height="32"
293 alt="Contents" width="32"></A></td>
294<td><img src="blank.gif"
295 border="0" height="32"
296 alt="" width="32"></td>
297<td><img src="blank.gif"
298 border="0" height="32"
299 alt="" width="32"></td>
300</tr></table>
301<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
302<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
303<b class="navlabel">Next:</b> <a class="sectref" href="internals.html">4 Internals</A>
304<hr>
Jean-Paul Calderoned2532d82008-03-25 15:20:39 -0400305<span class="release-info">Release 0.7a2.</span>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500306</DIV>
307<!--End of Navigation Panel-->
308
309</BODY>
310</HTML>