~myers-1/pyopenssl/npn

« back to all changes in this revision

Viewing changes to doc/html/openssl-connection.html

  • Committer: Jean-Paul Calderone
  • Date: 2010-01-25 22:55:30 UTC
  • mfrom: (126 trunk)
  • mto: This revision was merged to the branch mainline in revision 129.
  • Revision ID: exarkun@divmod.com-20100125225530-5e9nsb6bzoesoz42
merge trunk and resolve simple conflict

Show diffs side-by-side

added added

removed removed

Lines of Context:
16
16
<table align="center" width="100%" cellpadding="0" cellspacing="2">
17
17
<tr>
18
18
<td><A href="openssl-context.html"><img src="previous.gif"
19
 
border="0" height="32"
 
19
  border="0" height="32"
20
20
  alt="Previous Page" width="32"></A></td>
21
21
<td><A href="openssl-ssl.html"><img src="up.gif"
22
 
border="0" height="32"
 
22
  border="0" height="32"
23
23
  alt="Up One Level" width="32"></A></td>
24
24
<td><A href="internals.html"><img src="next.gif"
25
 
border="0" height="32"
 
25
  border="0" height="32"
26
26
  alt="Next Page" width="32"></A></td>
27
27
<td align="center" width="100%">Python OpenSSL Manual</td>
28
28
<td><A href="contents.html"><img src="contents.gif"
29
 
border="0" height="32"
 
29
  border="0" height="32"
30
30
  alt="Contents" width="32"></A></td>
31
31
<td><img src="blank.gif"
32
32
  border="0" height="32"
51
51
Connection objects have the following methods:
52
52
 
53
53
<P>
54
 
<dl><dt><b><a name='l2h-149'><tt class='method'>accept</tt></a></b>()
 
54
<dl><dt><b><a name='l2h-160'><tt class='method'>accept</tt></a></b>()
55
55
<dd>
56
56
Call the <tt class="method">accept</tt> method of the underlying socket and set up SSL on the
57
57
returned socket, using the Context object supplied to this Connection object at
61
61
</dl>
62
62
 
63
63
<P>
64
 
<dl><dt><b><a name='l2h-150'><tt class='method'>bind</tt></a></b>(<var>address</var>)
 
64
<dl><dt><b><a name='l2h-161'><tt class='method'>bind</tt></a></b>(<var>address</var>)
65
65
<dd>
66
66
Call the <tt class="method">bind</tt> method of the underlying socket.
67
67
</dl>
68
68
 
69
69
<P>
70
 
<dl><dt><b><a name='l2h-151'><tt class='method'>close</tt></a></b>()
 
70
<dl><dt><b><a name='l2h-162'><tt class='method'>close</tt></a></b>()
71
71
<dd>
72
72
Call the <tt class="method">close</tt> method of the underlying socket. Note: If you want
73
73
correct SSL closure, you need to call the <tt class="method">shutdown</tt> method first.
74
74
</dl>
75
75
 
76
76
<P>
77
 
<dl><dt><b><a name='l2h-152'><tt class='method'>connect</tt></a></b>(<var>address</var>)
 
77
<dl><dt><b><a name='l2h-163'><tt class='method'>connect</tt></a></b>(<var>address</var>)
78
78
<dd>
79
79
Call the <tt class="method">connect</tt> method of the underlying socket and set up SSL on the
80
80
socket, using the Context object supplied to this Connection object at
82
82
</dl>
83
83
 
84
84
<P>
85
 
<dl><dt><b><a name='l2h-153'><tt class='method'>connect_ex</tt></a></b>(<var>address</var>)
 
85
<dl><dt><b><a name='l2h-164'><tt class='method'>connect_ex</tt></a></b>(<var>address</var>)
86
86
<dd>
87
87
Call the <tt class="method">connect_ex</tt> method of the underlying socket and set up SSL on
88
88
the socket, using the Context object supplied to this Connection object at
91
91
</dl>
92
92
 
93
93
<P>
94
 
<dl><dt><b><a name='l2h-154'><tt class='method'>do_handshake</tt></a></b>()
 
94
<dl><dt><b><a name='l2h-165'><tt class='method'>do_handshake</tt></a></b>()
95
95
<dd>
96
96
Perform an SSL handshake (usually called after <tt class="method">renegotiate</tt> or one of
97
97
<tt class="method">set_accept_state</tt> or <tt class="method">set_accept_state</tt>). This can raise the
99
99
</dl>
100
100
 
101
101
<P>
102
 
<dl><dt><b><a name='l2h-155'><tt class='method'>fileno</tt></a></b>()
 
102
<dl><dt><b><a name='l2h-166'><tt class='method'>fileno</tt></a></b>()
103
103
<dd>
104
104
Retrieve the file descriptor number for the underlying socket.
105
105
</dl>
106
106
 
107
107
<P>
108
 
<dl><dt><b><a name='l2h-156'><tt class='method'>listen</tt></a></b>(<var>backlog</var>)
 
108
<dl><dt><b><a name='l2h-167'><tt class='method'>listen</tt></a></b>(<var>backlog</var>)
109
109
<dd>
110
110
Call the <tt class="method">listen</tt> method of the underlying socket.
111
111
</dl>
112
112
 
113
113
<P>
114
 
<dl><dt><b><a name='l2h-157'><tt class='method'>get_app_data</tt></a></b>()
 
114
<dl><dt><b><a name='l2h-168'><tt class='method'>get_app_data</tt></a></b>()
115
115
<dd>
116
116
Retrieve application data as set by <tt class="method">set_app_data</tt>.
117
117
</dl>
118
118
 
119
119
<P>
120
 
<dl><dt><b><a name='l2h-158'><tt class='method'>get_cipher_list</tt></a></b>()
 
120
<dl><dt><b><a name='l2h-169'><tt class='method'>get_cipher_list</tt></a></b>()
121
121
<dd>
122
122
Retrieve the list of ciphers used by the Connection object. WARNING: This API
123
123
has changed. It used to take an optional parameter and just return a string,
125
125
</dl>
126
126
 
127
127
<P>
128
 
<dl><dt><b><a name='l2h-159'><tt class='method'>get_context</tt></a></b>()
 
128
<dl><dt><b><a name='l2h-170'><tt class='method'>get_client_ca_list</tt></a></b>()
 
129
<dd>
 
130
Retrieve the list of preferred client certificate issuers sent by the server
 
131
as <tt class="class">OpenSSL.crypto.X509Name</tt> objects.
 
132
 
 
133
<P>
 
134
If this is a client <tt class="class">Connection</tt>, the list will be empty until the
 
135
connection with the server is established.
 
136
 
 
137
<P>
 
138
If this is a server <tt class="class">Connection</tt>, return the list of certificate
 
139
authorities that will be sent or has been sent to the client, as controlled
 
140
by this <tt class="class">Connection</tt>'s <tt class="class">Context</tt>.
 
141
 
 
142
<P>
 
143
 
 
144
<span class='versionnote'>New in version 0.10.</span>
 
145
 
 
146
</dl>
 
147
 
 
148
<P>
 
149
<dl><dt><b><a name='l2h-171'><tt class='method'>get_context</tt></a></b>()
129
150
<dd>
130
151
Retrieve the Context object associated with this Connection.
131
152
</dl>
132
153
 
133
154
<P>
134
 
<dl><dt><b><a name='l2h-160'><tt class='method'>get_peer_certificate</tt></a></b>()
 
155
<dl><dt><b><a name='l2h-172'><tt class='method'>get_peer_certificate</tt></a></b>()
135
156
<dd>
136
157
Retrieve the other side's certificate (if any)
137
158
</dl>
138
159
 
139
160
<P>
140
 
<dl><dt><b><a name='l2h-161'><tt class='method'>getpeername</tt></a></b>()
 
161
<dl><dt><b><a name='l2h-173'><tt class='method'>getpeername</tt></a></b>()
141
162
<dd>
142
163
Call the <tt class="method">getpeername</tt> method of the underlying socket.
143
164
</dl>
144
165
 
145
166
<P>
146
 
<dl><dt><b><a name='l2h-162'><tt class='method'>getsockname</tt></a></b>()
 
167
<dl><dt><b><a name='l2h-174'><tt class='method'>getsockname</tt></a></b>()
147
168
<dd>
148
169
Call the <tt class="method">getsockname</tt> method of the underlying socket.
149
170
</dl>
150
171
 
151
172
<P>
152
 
<dl><dt><b><a name='l2h-163'><tt class='method'>getsockopt</tt></a></b>(<var>level, optname</var><big>[</big><var>, buflen</var><big>]</big>)
 
173
<dl><dt><b><a name='l2h-175'><tt class='method'>getsockopt</tt></a></b>(<var>level, optname</var><big>[</big><var>, buflen</var><big>]</big>)
153
174
<dd>
154
175
Call the <tt class="method">getsockopt</tt> method of the underlying socket.
155
176
</dl>
156
177
 
157
178
<P>
158
 
<dl><dt><b><a name='l2h-164'><tt class='method'>pending</tt></a></b>()
 
179
<dl><dt><b><a name='l2h-176'><tt class='method'>pending</tt></a></b>()
159
180
<dd>
160
181
Retrieve the number of bytes that can be safely read from the SSL buffer
161
182
(<i>not</i> the underlying transport buffer).
162
183
</dl>
163
184
 
164
185
<P>
165
 
<dl><dt><b><a name='l2h-165'><tt class='method'>recv</tt></a></b>(<var>bufsize</var>)
 
186
<dl><dt><b><a name='l2h-177'><tt class='method'>recv</tt></a></b>(<var>bufsize</var>)
166
187
<dd>
167
188
Receive data from the Connection. The return value is a string representing the
168
189
data received. The maximum amount of data to be received at once, is specified
170
191
</dl>
171
192
 
172
193
<P>
173
 
<dl><dt><b><a name='l2h-166'><tt class='method'>renegotiate</tt></a></b>()
 
194
<dl><dt><b><a name='l2h-178'><tt class='method'>bio_write</tt></a></b>(<var>bytes</var>)
 
195
<dd>
 
196
If the Connection was created with a memory BIO, this method can be used to add
 
197
bytes to the read end of that memory BIO.  The Connection can then read the
 
198
bytes (for example, in response to a call to <tt class="method">recv</tt>).
 
199
</dl>
 
200
 
 
201
<P>
 
202
<dl><dt><b><a name='l2h-179'><tt class='method'>renegotiate</tt></a></b>()
174
203
<dd>
175
204
Renegotiate the SSL session. Call this if you wish to change cipher suites or
176
205
anything like that.
177
206
</dl>
178
207
 
179
208
<P>
180
 
<dl><dt><b><a name='l2h-167'><tt class='method'>send</tt></a></b>(<var>string</var>)
 
209
<dl><dt><b><a name='l2h-180'><tt class='method'>send</tt></a></b>(<var>string</var>)
181
210
<dd>
182
211
Send the <var>string</var> data to the Connection.
183
212
</dl>
184
213
 
185
214
<P>
186
 
<dl><dt><b><a name='l2h-168'><tt class='method'>sendall</tt></a></b>(<var>string</var>)
 
215
<dl><dt><b><a name='l2h-181'><tt class='method'>bio_read</tt></a></b>(<var>bufsize</var>)
 
216
<dd>
 
217
If the Connection was created with a memory BIO, this method can be used to
 
218
read bytes from the write end of that memory BIO.  Many Connection methods will
 
219
add bytes which must be read in this manner or the buffer will eventually fill
 
220
up and the Connection will be able to take no further actions.
 
221
</dl>
 
222
 
 
223
<P>
 
224
<dl><dt><b><a name='l2h-182'><tt class='method'>sendall</tt></a></b>(<var>string</var>)
187
225
<dd>
188
226
Send all of the <var>string</var> data to the Connection. This calls <tt class="method">send</tt>
189
227
repeatedly until all data is sent. If an error occurs, it's impossible to tell
191
229
</dl>
192
230
 
193
231
<P>
194
 
<dl><dt><b><a name='l2h-169'><tt class='method'>set_accept_state</tt></a></b>()
 
232
<dl><dt><b><a name='l2h-183'><tt class='method'>set_accept_state</tt></a></b>()
195
233
<dd>
196
234
Set the connection to work in server mode. The handshake will be handled
197
235
automatically by read/write.
198
236
</dl>
199
237
 
200
238
<P>
201
 
<dl><dt><b><a name='l2h-170'><tt class='method'>set_app_data</tt></a></b>(<var>data</var>)
 
239
<dl><dt><b><a name='l2h-184'><tt class='method'>set_app_data</tt></a></b>(<var>data</var>)
202
240
<dd>
203
241
Associate <var>data</var> with this Connection object. <var>data</var> can be retrieved
204
242
later using the <tt class="method">get_app_data</tt> method.
205
243
</dl>
206
244
 
207
245
<P>
208
 
<dl><dt><b><a name='l2h-171'><tt class='method'>set_connect_state</tt></a></b>()
 
246
<dl><dt><b><a name='l2h-185'><tt class='method'>set_connect_state</tt></a></b>()
209
247
<dd>
210
248
Set the connection to work in client mode. The handshake will be handled
211
249
automatically by read/write.
212
250
</dl>
213
251
 
214
252
<P>
215
 
<dl><dt><b><a name='l2h-172'><tt class='method'>setblocking</tt></a></b>(<var>flag</var>)
 
253
<dl><dt><b><a name='l2h-186'><tt class='method'>setblocking</tt></a></b>(<var>flag</var>)
216
254
<dd>
217
255
Call the <tt class="method">setblocking</tt> method of the underlying socket.
218
256
</dl>
219
257
 
220
258
<P>
221
 
<dl><dt><b><a name='l2h-173'><tt class='method'>setsockopt</tt></a></b>(<var>level, optname, value</var>)
 
259
<dl><dt><b><a name='l2h-187'><tt class='method'>setsockopt</tt></a></b>(<var>level, optname, value</var>)
222
260
<dd>
223
261
Call the <tt class="method">setsockopt</tt> method of the underlying socket.
224
262
</dl>
225
263
 
226
264
<P>
227
 
<dl><dt><b><a name='l2h-174'><tt class='method'>shutdown</tt></a></b>()
 
265
<dl><dt><b><a name='l2h-188'><tt class='method'>shutdown</tt></a></b>()
228
266
<dd>
229
267
Send the shutdown message to the Connection. Returns true if the shutdown
230
268
message exchange is completed and false otherwise (in which case you call
233
271
</dl>
234
272
 
235
273
<P>
236
 
<dl><dt><b><a name='l2h-175'><tt class='method'>get_shutdown</tt></a></b>()
 
274
<dl><dt><b><a name='l2h-189'><tt class='method'>get_shutdown</tt></a></b>()
237
275
<dd>
238
276
Get the shutdown state of the Connection.  Returns a bitvector of either or
239
277
both of <var>SENT_SHUTDOWN</var> and <var>RECEIVED_SHUTDOWN</var>.
240
278
</dl>
241
279
 
242
280
<P>
243
 
<dl><dt><b><a name='l2h-176'><tt class='method'>set_shutdown</tt></a></b>(<var>state</var>)
 
281
<dl><dt><b><a name='l2h-190'><tt class='method'>set_shutdown</tt></a></b>(<var>state</var>)
244
282
<dd>
245
283
Set the shutdown state of the Connection.  <var>state</var> is a bitvector of
246
284
either or both of <var>SENT_SHUTDOWN</var> and <var>RECEIVED_SHUTDOWN</var>.
247
285
</dl>
248
286
 
249
287
<P>
250
 
<dl><dt><b><a name='l2h-177'><tt class='method'>sock_shutdown</tt></a></b>(<var>how</var>)
 
288
<dl><dt><b><a name='l2h-191'><tt class='method'>sock_shutdown</tt></a></b>(<var>how</var>)
251
289
<dd>
252
290
Call the <tt class="method">shutdown</tt> method of the underlying socket.
253
291
</dl>
254
292
 
255
293
<P>
256
 
<dl><dt><b><a name='l2h-178'><tt class='method'>state_string</tt></a></b>()
 
294
<dl><dt><b><a name='l2h-192'><tt class='method'>bio_shutdown</tt></a></b>()
 
295
<dd>
 
296
If the Connection was created with a memory BIO, this method can be used to
 
297
indicate that ``end of file'' has been reached on the read end of that memory
 
298
BIO.
 
299
</dl>
 
300
 
 
301
<P>
 
302
<dl><dt><b><a name='l2h-193'><tt class='method'>state_string</tt></a></b>()
257
303
<dd>
258
304
Retrieve a verbose string detailing the state of the Connection.
259
305
</dl>
260
306
 
261
307
<P>
262
 
<dl><dt><b><a name='l2h-179'><tt class='method'>want_read</tt></a></b>()
 
308
<dl><dt><b><a name='l2h-194'><tt class='method'>client_random</tt></a></b>()
 
309
<dd>
 
310
Retrieve the random value used with the client hello message.
 
311
</dl>
 
312
 
 
313
<P>
 
314
<dl><dt><b><a name='l2h-195'><tt class='method'>server_random</tt></a></b>()
 
315
<dd>
 
316
Retrieve the random value used with the server hello message.
 
317
</dl>
 
318
 
 
319
<P>
 
320
<dl><dt><b><a name='l2h-196'><tt class='method'>master_key</tt></a></b>()
 
321
<dd>
 
322
Retrieve the value of the master key for this session.
 
323
</dl>
 
324
 
 
325
<P>
 
326
<dl><dt><b><a name='l2h-197'><tt class='method'>want_read</tt></a></b>()
263
327
<dd>
264
328
Checks if more data has to be read from the transport layer to complete an
265
329
operation.
266
330
</dl>
267
331
 
268
332
<P>
269
 
<dl><dt><b><a name='l2h-180'><tt class='method'>want_write</tt></a></b>()
 
333
<dl><dt><b><a name='l2h-198'><tt class='method'>want_write</tt></a></b>()
270
334
<dd>
271
335
Checks if there is data to write to the transport layer to complete an
272
336
operation.
279
343
<table align="center" width="100%" cellpadding="0" cellspacing="2">
280
344
<tr>
281
345
<td><A href="openssl-context.html"><img src="previous.gif"
282
 
border="0" height="32"
 
346
  border="0" height="32"
283
347
  alt="Previous Page" width="32"></A></td>
284
348
<td><A href="openssl-ssl.html"><img src="up.gif"
285
 
border="0" height="32"
 
349
  border="0" height="32"
286
350
  alt="Up One Level" width="32"></A></td>
287
351
<td><A href="internals.html"><img src="next.gif"
288
 
border="0" height="32"
 
352
  border="0" height="32"
289
353
  alt="Next Page" width="32"></A></td>
290
354
<td align="center" width="100%">Python OpenSSL Manual</td>
291
355
<td><A href="contents.html"><img src="contents.gif"
292
 
border="0" height="32"
 
356
  border="0" height="32"
293
357
  alt="Contents" width="32"></A></td>
294
358
<td><img src="blank.gif"
295
359
  border="0" height="32"
302
366
<b class="navlabel">Up:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL  </A>
303
367
<b class="navlabel">Next:</b> <a class="sectref" href="internals.html">4 Internals</A>
304
368
<hr>
305
 
<span class="release-info">Release 0.9.</span>
 
369
<span class="release-info">Release 0.10.</span>
306
370
</DIV>
307
371
<!--End of Navigation Panel-->
308
372