Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / pyopenssl / 72b8f0fb39f1029de628e2c64bc00178b51baa90 / . / doc / html / openssl-connection.html
blob: fed4d5203e8a84fa337dcc18ed809ad74c9280bd [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.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>
49<P>
50<EM><EM><EM>Connection objects have the following methods:
51</EM></EM></EM>
52<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]53<dl><dt><b><a name='l2h-138'><tt class='method'>accept</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]54<dd>
55Call the <tt class="method">accept</tt> method of the underlying socket and set up SSL on the
56returned socket, using the Context object supplied to this Connection object at
57creation. Returns a pair <code>(<var>conn</var>, <var>address</var>)</code>. where <var>conn</var>
58is the new Connection object created, and <var>address</var> is as returned by the
59socket's <tt class="method">accept</tt>.
60</dl>
61<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]62<dl><dt><b><a name='l2h-139'><tt class='method'>bind</tt></a></b>(<var>address</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]63<dd>
64Call the <tt class="method">bind</tt> method of the underlying socket.
65</dl>
66<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]67<dl><dt><b><a name='l2h-140'><tt class='method'>close</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]68<dd>
69Call the <tt class="method">close</tt> method of the underlying socket. Note: If you want
70correct SSL closure, you need to call the <tt class="method">shutdown</tt> method first.
71</dl>
72<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]73<dl><dt><b><a name='l2h-141'><tt class='method'>connect</tt></a></b>(<var>address</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]74<dd>
75Call the <tt class="method">connect</tt> method of the underlying socket and set up SSL on the
76socket, using the Context object supplied to this Connection object at
77creation.
78</dl>
79<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]80<dl><dt><b><a name='l2h-142'><tt class='method'>connect_ex</tt></a></b>(<var>address</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]81<dd>
82Call the <tt class="method">connect_ex</tt> method of the underlying socket and set up SSL on
83the socket, using the Context object supplied to this Connection object at
84creation. Note that if the <tt class="method">connect_ex</tt> method of the socket doesn't
85return 0, SSL won't be initialized.
86</dl>
87<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]88<dl><dt><b><a name='l2h-143'><tt class='method'>do_handshake</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]89<dd>
90Perform an SSL handshake (usually called after <tt class="method">renegotiate</tt> or one of
91<tt class="method">set_accept_state</tt> or <tt class="method">set_accept_state</tt>). This can raise the
92same exceptions as <tt class="method">send</tt> and <tt class="method">recv</tt>.
93</dl>
94<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]95<dl><dt><b><a name='l2h-144'><tt class='method'>fileno</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]96<dd>
97Retrieve the file descriptor number for the underlying socket.
98</dl>
99<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]100<dl><dt><b><a name='l2h-145'><tt class='method'>listen</tt></a></b>(<var>backlog</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]101<dd>
102Call the <tt class="method">listen</tt> method of the underlying socket.
103</dl>
104<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]105<dl><dt><b><a name='l2h-146'><tt class='method'>get_app_data</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]106<dd>
107Retrieve application data as set by <tt class="method">set_app_data</tt>.
108</dl>
109<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]110<dl><dt><b><a name='l2h-147'><tt class='method'>get_cipher_list</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]111<dd>
112Retrieve the list of ciphers used by the Connection object. WARNING: This API
113has changed. It used to take an optional parameter and just return a string,
114but not it returns the entire list in one go.
115</dl>
116<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]117<dl><dt><b><a name='l2h-148'><tt class='method'>get_context</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]118<dd>
119Retrieve the Context object associated with this Connection.
120</dl>
121<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]122<dl><dt><b><a name='l2h-149'><tt class='method'>get_peer_certificate</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]123<dd>
124Retrieve the other side's certificate (if any)
125</dl>
126<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]127<dl><dt><b><a name='l2h-150'><tt class='method'>getpeername</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]128<dd>
129Call the <tt class="method">getpeername</tt> method of the underlying socket.
130</dl>
131<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]132<dl><dt><b><a name='l2h-151'><tt class='method'>getsockname</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]133<dd>
134Call the <tt class="method">getsockname</tt> method of the underlying socket.
135</dl>
136<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]137<dl><dt><b><a name='l2h-152'><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 -0500[diff] [blame]138<dd>
139Call the <tt class="method">getsockopt</tt> method of the underlying socket.
140</dl>
141<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]142<dl><dt><b><a name='l2h-153'><tt class='method'>pending</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]143<dd>
144Retrieve the number of bytes that can be safely read from the SSL buffer.
145</dl>
146<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]147<dl><dt><b><a name='l2h-154'><tt class='method'>recv</tt></a></b>(<var>bufsize</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]148<dd>
149Receive data from the Connection. The return value is a string representing the
150data received. The maximum amount of data to be received at once, is specified
151by <var>bufsize</var>.
152</dl>
153<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]154<dl><dt><b><a name='l2h-155'><tt class='method'>renegotiate</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]155<dd>
156Renegotiate the SSL session. Call this if you wish to change cipher suites or
157anything like that.
158</dl>
159<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]160<dl><dt><b><a name='l2h-156'><tt class='method'>send</tt></a></b>(<var>string</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]161<dd>
162Send the <var>string</var> data to the Connection.
163</dl>
164<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]165<dl><dt><b><a name='l2h-157'><tt class='method'>sendall</tt></a></b>(<var>string</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]166<dd>
167Send all of the <var>string</var> data to the Connection. This calls <tt class="method">send</tt>
168repeatedly until all data is sent. If an error occurs, it's impossible to tell
169how much data has been sent.
170</dl>
171<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]172<dl><dt><b><a name='l2h-158'><tt class='method'>set_accept_state</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]173<dd>
174Set the connection to work in server mode. The handshake will be handled
175automatically by read/write.
176</dl>
177<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]178<dl><dt><b><a name='l2h-159'><tt class='method'>set_app_data</tt></a></b>(<var>data</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]179<dd>
180Associate <var>data</var> with this Connection object. <var>data</var> can be retrieved
181later using the <tt class="method">get_app_data</tt> method.
182</dl>
183<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]184<dl><dt><b><a name='l2h-160'><tt class='method'>set_connect_state</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]185<dd>
186Set the connection to work in client mode. The handshake will be handled
187automatically by read/write.
188</dl>
189<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]190<dl><dt><b><a name='l2h-161'><tt class='method'>setblocking</tt></a></b>(<var>flag</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]191<dd>
192Call the <tt class="method">setblocking</tt> method of the underlying socket.
193</dl>
194<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]195<dl><dt><b><a name='l2h-162'><tt class='method'>setsockopt</tt></a></b>(<var>level, optname, value</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]196<dd>
197Call the <tt class="method">setsockopt</tt> method of the underlying socket.
198</dl>
199<P>
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500[diff] [blame]200<dl><dt><b><a name='l2h-163'><tt class='method'>shutdown</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]201<dd>
202Send the shutdown message to the Connection. Returns true if the shutdown
203message exchange is completed and false otherwise (in which case you call
204<tt class="method">recv()</tt> or <tt class="method">send()</tt> when the connection becomes
205readable/writeable.
206</dl>
207<P>
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500[diff] [blame^]208<dl><dt><b><a name='l2h-164'><tt class='method'>get_shutdown</tt></a></b>()
209<dd>
210Get the shutdown state of the Connection. Returns a bitvector of either or
211both of <var>SENT_SHUTDOWN</var> and <var>RECEIVED_SHUTDOWN</var>.
212</dl>
213<P>
214<dl><dt><b><a name='l2h-165'><tt class='method'>set_shutdown</tt></a></b>(<var>state</var>)
215<dd>
216Set the shutdown state of the Connection. <var>state</var> is a bitvector of
217either or both of <var>SENT_SHUTDOWN</var> and <var>RECEIVED_SHUTDOWN</var>.
218</dl>
219<P>
220<dl><dt><b><a name='l2h-166'><tt class='method'>sock_shutdown</tt></a></b>(<var>how</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]221<dd>
222Call the <tt class="method">shutdown</tt> method of the underlying socket.
223</dl>
224<P>
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500[diff] [blame^]225<dl><dt><b><a name='l2h-167'><tt class='method'>state_string</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]226<dd>
227Retrieve a verbose string detailing the state of the Connection.
228</dl>
229<P>
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500[diff] [blame^]230<dl><dt><b><a name='l2h-168'><tt class='method'>want_read</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]231<dd>
232Checks if more data has to be read from the transport layer to complete an
233operation.
234</dl>
235<P>
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500[diff] [blame^]236<dl><dt><b><a name='l2h-169'><tt class='method'>want_write</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]237<dd>
238Checks if there is data to write to the transport layer to complete an
239operation.
240</dl>
241<P>
242
243<DIV CLASS="navigation">
244<p><hr>
245<table align="center" width="100%" cellpadding="0" cellspacing="2">
246<tr>
247<td><A href="openssl-context.html"><img src="previous.gif"
248border="0" height="32"
249 alt="Previous Page" width="32"></A></td>
250<td><A href="openssl-ssl.html"><img src="up.gif"
251border="0" height="32"
252 alt="Up One Level" width="32"></A></td>
253<td><A href="internals.html"><img src="next.gif"
254border="0" height="32"
255 alt="Next Page" width="32"></A></td>
256<td align="center" width="100%">Python OpenSSL Manual</td>
257<td><A href="contents.html"><img src="contents.gif"
258border="0" height="32"
259 alt="Contents" width="32"></A></td>
260<td><img src="blank.gif"
261 border="0" height="32"
262 alt="" width="32"></td>
263<td><img src="blank.gif"
264 border="0" height="32"
265 alt="" width="32"></td>
266</tr></table>
267<b class="navlabel">Previous:</b> <a class="sectref" href="openssl-context.html">3.3.1 Context objects</A>
268<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
269<b class="navlabel">Next:</b> <a class="sectref" href="internals.html">4 Internals</A>
270<hr>
271<span class="release-info">Release 0.6.</span>
272</DIV>
273<!--End of Navigation Panel-->
274
275</BODY>
276</HTML>