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