ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Handle.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.112 by root, Wed Jan 21 06:01:35 2009 UTC vs.
Revision 1.142 by root, Mon Jul 6 20:24:47 2009 UTC

… …
14 14
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 16
17=cut 17=cut
18 18
19our $VERSION = 4.331; 19our $VERSION = 4.452;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
63 63
64=head1 METHODS 64=head1 METHODS
65 65
66=over 4 66=over 4
67 67
68=item B<new (%args)> 68=item $handle = B<new> AnyEvent::TLS fh => $filehandle, key => value...
69 69
70The constructor supports these arguments (all as key => value pairs). 70The constructor supports these arguments (all as C<< key => value >> pairs).
71 71
72=over 4 72=over 4
73 73
74=item fh => $filehandle [MANDATORY] 74=item fh => $filehandle [MANDATORY]
75 75
… …
95waiting for data. 95waiting for data.
96 96
97If an EOF condition has been detected but no C<on_eof> callback has been 97If an EOF condition has been detected but no C<on_eof> callback has been
98set, then a fatal error will be raised with C<$!> set to <0>. 98set, then a fatal error will be raised with C<$!> set to <0>.
99 99
100=item on_error => $cb->($handle, $fatal) 100=item on_error => $cb->($handle, $fatal, $message)
101 101
102This is the error callback, which is called when, well, some error 102This is the error callback, which is called when, well, some error
103occured, such as not being able to resolve the hostname, failure to 103occured, such as not being able to resolve the hostname, failure to
104connect or a read error. 104connect or a read error.
105 105
… …
107fatal errors the handle object will be shut down and will not be usable 107fatal errors the handle object will be shut down and will not be usable
108(but you are free to look at the current C<< ->rbuf >>). Examples of fatal 108(but you are free to look at the current C<< ->rbuf >>). Examples of fatal
109errors are an EOF condition with active (but unsatisifable) read watchers 109errors are an EOF condition with active (but unsatisifable) read watchers
110(C<EPIPE>) or I/O errors. 110(C<EPIPE>) or I/O errors.
111 111
112AnyEvent::Handle tries to find an appropriate error code for you to check
113against, but in some cases (TLS errors), this does not work well. It is
114recommended to always output the C<$message> argument in human-readable
115error messages (it's usually the same as C<"$!">).
116
112Non-fatal errors can be retried by simply returning, but it is recommended 117Non-fatal errors can be retried by simply returning, but it is recommended
113to simply ignore this parameter and instead abondon the handle object 118to simply ignore this parameter and instead abondon the handle object
114when this callback is invoked. Examples of non-fatal errors are timeouts 119when this callback is invoked. Examples of non-fatal errors are timeouts
115C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>). 120C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
116 121
117On callback entrance, the value of C<$!> contains the operating system 122On callback entrance, the value of C<$!> contains the operating system
118error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>). 123error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
124C<EPROTO>).
119 125
120While not mandatory, it is I<highly> recommended to set this callback, as 126While not mandatory, it is I<highly> recommended to set this callback, as
121you will not be notified of errors otherwise. The default simply calls 127you will not be notified of errors otherwise. The default simply calls
122C<croak>. 128C<croak>.
123 129
… …
127and no read request is in the queue (unlike read queue callbacks, this 133and no read request is in the queue (unlike read queue callbacks, this
128callback will only be called when at least one octet of data is in the 134callback will only be called when at least one octet of data is in the
129read buffer). 135read buffer).
130 136
131To access (and remove data from) the read buffer, use the C<< ->rbuf >> 137To access (and remove data from) the read buffer, use the C<< ->rbuf >>
132method or access the C<$handle->{rbuf}> member directly. 138method or access the C<< $handle->{rbuf} >> member directly. Note that you
139must not enlarge or modify the read buffer, you can only remove data at
140the beginning from it.
133 141
134When an EOF condition is detected then AnyEvent::Handle will first try to 142When an EOF condition is detected then AnyEvent::Handle will first try to
135feed all the remaining data to the queued callbacks and C<on_read> before 143feed all the remaining data to the queued callbacks and C<on_read> before
136calling the C<on_eof> callback. If no progress can be made, then a fatal 144calling the C<on_eof> callback. If no progress can be made, then a fatal
137error will be raised (with C<$!> set to C<EPIPE>). 145error will be raised (with C<$!> set to C<EPIPE>).
… …
235 243
236This will not work for partial TLS data that could not be encoded 244This will not work for partial TLS data that could not be encoded
237yet. This data will be lost. Calling the C<stoptls> method in time might 245yet. This data will be lost. Calling the C<stoptls> method in time might
238help. 246help.
239 247
248=item peername => $string
249
250A string used to identify the remote site - usually the DNS hostname
251(I<not> IDN!) used to create the connection, rarely the IP address.
252
253Apart from being useful in error messages, this string is also used in TLS
254peername verification (see C<verify_peername> in L<AnyEvent::TLS>).
255
240=item tls => "accept" | "connect" | Net::SSLeay::SSL object 256=item tls => "accept" | "connect" | Net::SSLeay::SSL object
241 257
242When this parameter is given, it enables TLS (SSL) mode, that means 258When this parameter is given, it enables TLS (SSL) mode, that means
243AnyEvent will start a TLS handshake as soon as the conenction has been 259AnyEvent will start a TLS handshake as soon as the conenction has been
244established and will transparently encrypt/decrypt data afterwards. 260established and will transparently encrypt/decrypt data afterwards.
261
262All TLS protocol errors will be signalled as C<EPROTO>, with an
263appropriate error message.
245 264
246TLS mode requires Net::SSLeay to be installed (it will be loaded 265TLS mode requires Net::SSLeay to be installed (it will be loaded
247automatically when you try to create a TLS handle): this module doesn't 266automatically when you try to create a TLS handle): this module doesn't
248have a dependency on that module, so if your module requires it, you have 267have a dependency on that module, so if your module requires it, you have
249to add the dependency yourself. 268to add the dependency yourself.
… …
253mode. 272mode.
254 273
255You can also provide your own TLS connection object, but you have 274You can also provide your own TLS connection object, but you have
256to make sure that you call either C<Net::SSLeay::set_connect_state> 275to make sure that you call either C<Net::SSLeay::set_connect_state>
257or C<Net::SSLeay::set_accept_state> on it before you pass it to 276or C<Net::SSLeay::set_accept_state> on it before you pass it to
258AnyEvent::Handle. 277AnyEvent::Handle. Also, this module will take ownership of this connection
278object.
279
280At some future point, AnyEvent::Handle might switch to another TLS
281implementation, then the option to use your own session object will go
282away.
259 283
260B<IMPORTANT:> since Net::SSLeay "objects" are really only integers, 284B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
261passing in the wrong integer will lead to certain crash. This most often 285passing in the wrong integer will lead to certain crash. This most often
262happens when one uses a stylish C<< tls => 1 >> and is surprised about the 286happens when one uses a stylish C<< tls => 1 >> and is surprised about the
263segmentation fault. 287segmentation fault.
264 288
265See the C<< ->starttls >> method for when need to start TLS negotiation later. 289See the C<< ->starttls >> method for when need to start TLS negotiation later.
266 290
267=item tls_ctx => $ssl_ctx 291=item tls_ctx => $anyevent_tls
268 292
269Use the given C<Net::SSLeay::CTX> object to create the new TLS connection 293Use the given C<AnyEvent::TLS> object to create the new TLS connection
270(unless a connection object was specified directly). If this parameter is 294(unless a connection object was specified directly). If this parameter is
271missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 295missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
296
297Instead of an object, you can also specify a hash reference with C<< key
298=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
299new TLS context object.
300
301=item on_starttls => $cb->($handle, $success)
302
303This callback will be invoked when the TLS/SSL handshake has finished. If
304C<$success> is true, then the TLS handshake succeeded, otherwise it failed
305(C<on_stoptls> will not be called in this case).
306
307The session in C<< $handle->{tls} >> can still be examined in this
308callback, even when the handshake was not successful.
309
310=item on_stoptls => $cb->($handle)
311
312When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
313set, then it will be invoked after freeing the TLS session. If it is not,
314then a TLS shutdown condition will be treated like a normal EOF condition
315on the handle.
316
317The session in C<< $handle->{tls} >> can still be examined in this
318callback.
319
320This callback will only be called on TLS shutdowns, not when the
321underlying handle signals EOF.
272 322
273=item json => JSON or JSON::XS object 323=item json => JSON or JSON::XS object
274 324
275This is the json coder object used by the C<json> read and write types. 325This is the json coder object used by the C<json> read and write types.
276 326
… …
285 335
286=cut 336=cut
287 337
288sub new { 338sub new {
289 my $class = shift; 339 my $class = shift;
290
291 my $self = bless { @_ }, $class; 340 my $self = bless { @_ }, $class;
292 341
293 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 342 $self->{fh} or Carp::croak "mandatory argument fh is missing";
294 343
295 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 344 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
345
346 $self->{_activity} = AnyEvent->now;
347 $self->_timeout;
348
349 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
296 350
297 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 351 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
298 if $self->{tls}; 352 if $self->{tls};
299 353
300 $self->{_activity} = AnyEvent->now;
301 $self->_timeout;
302
303 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 354 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
304 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
305 355
306 $self->start_read 356 $self->start_read
307 if $self->{on_read}; 357 if $self->{on_read};
308 358
309 $self 359 $self->{fh} && $self
310} 360}
311 361
312sub _shutdown { 362sub _shutdown {
313 my ($self) = @_; 363 my ($self) = @_;
314 364
315 delete $self->{_tw}; 365 delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};
316 delete $self->{_rw}; 366 $self->{_eof} = 1; # tell starttls et. al to stop trying
317 delete $self->{_ww};
318 delete $self->{fh};
319 367
320 &_freetls; 368 &_freetls;
321
322 delete $self->{on_read};
323 delete $self->{_queue};
324} 369}
325 370
326sub _error { 371sub _error {
327 my ($self, $errno, $fatal) = @_; 372 my ($self, $errno, $fatal, $message) = @_;
328 373
329 $self->_shutdown 374 $self->_shutdown
330 if $fatal; 375 if $fatal;
331 376
332 $! = $errno; 377 $! = $errno;
378 $message ||= "$!";
333 379
334 if ($self->{on_error}) { 380 if ($self->{on_error}) {
335 $self->{on_error}($self, $fatal); 381 $self->{on_error}($self, $fatal, $message);
336 } elsif ($self->{fh}) { 382 } elsif ($self->{fh}) {
337 Carp::croak "AnyEvent::Handle uncaught error: $!"; 383 Carp::croak "AnyEvent::Handle uncaught error: $message";
338 } 384 }
339} 385}
340 386
341=item $fh = $handle->fh 387=item $fh = $handle->fh
342 388
… …
401 447
402 eval { 448 eval {
403 local $SIG{__DIE__}; 449 local $SIG{__DIE__};
404 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]; 450 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
405 }; 451 };
452}
453
454=item $handle->on_starttls ($cb)
455
456Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
457
458=cut
459
460sub on_starttls {
461 $_[0]{on_starttls} = $_[1];
462}
463
464=item $handle->on_stoptls ($cb)
465
466Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
467
468=cut
469
470sub on_starttls {
471 $_[0]{on_stoptls} = $_[1];
406} 472}
407 473
408############################################################################# 474#############################################################################
409 475
410=item $handle->timeout ($seconds) 476=item $handle->timeout ($seconds)
… …
654 720
655 pack "w/a*", Storable::nfreeze ($ref) 721 pack "w/a*", Storable::nfreeze ($ref)
656}; 722};
657 723
658=back 724=back
725
726=item $handle->push_shutdown
727
728Sometimes you know you want to close the socket after writing your data
729before it was actually written. One way to do that is to replace your
730C<on_drain> handler by a callback that shuts down the socket (and set
731C<low_water_mark> to C<0>). This method is a shorthand for just that, and
732replaces the C<on_drain> callback with:
733
734 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
735
736This simply shuts down the write side and signals an EOF condition to the
737the peer.
738
739You can rely on the normal read queue and C<on_eof> handling
740afterwards. This is the cleanest way to close a connection.
741
742=cut
743
744sub push_shutdown {
745 my ($self) = @_;
746
747 delete $self->{low_water_mark};
748 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
749}
659 750
660=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 751=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
661 752
662This function (not method) lets you add your own types to C<push_write>. 753This function (not method) lets you add your own types to C<push_write>.
663Whenever the given C<type> is used, C<push_write> will invoke the code 754Whenever the given C<type> is used, C<push_write> will invoke the code
… …
767 ) { 858 ) {
768 $self->_error (&Errno::ENOSPC, 1), return; 859 $self->_error (&Errno::ENOSPC, 1), return;
769 } 860 }
770 861
771 while () { 862 while () {
863 # we need to use a separate tls read buffer, as we must not receive data while
864 # we are draining the buffer, and this can only happen with TLS.
865 $self->{rbuf} .= delete $self->{_tls_rbuf} if exists $self->{_tls_rbuf};
866
772 my $len = length $self->{rbuf}; 867 my $len = length $self->{rbuf};
773 868
774 if (my $cb = shift @{ $self->{_queue} }) { 869 if (my $cb = shift @{ $self->{_queue} }) {
775 unless ($cb->($self)) { 870 unless ($cb->($self)) {
776 if ($self->{_eof}) { 871 if ($self->{_eof}) {
… …
807 902
808 if ($self->{_eof}) { 903 if ($self->{_eof}) {
809 if ($self->{on_eof}) { 904 if ($self->{on_eof}) {
810 $self->{on_eof}($self) 905 $self->{on_eof}($self)
811 } else { 906 } else {
812 $self->_error (0, 1); 907 $self->_error (0, 1, "Unexpected end-of-file");
813 } 908 }
814 } 909 }
815 910
816 # may need to restart read watcher 911 # may need to restart read watcher
817 unless ($self->{_rw}) { 912 unless ($self->{_rw}) {
… …
837 932
838=item $handle->rbuf 933=item $handle->rbuf
839 934
840Returns the read buffer (as a modifiable lvalue). 935Returns the read buffer (as a modifiable lvalue).
841 936
842You can access the read buffer directly as the C<< ->{rbuf} >> member, if 937You can access the read buffer directly as the C<< ->{rbuf} >>
843you want. 938member, if you want. However, the only operation allowed on the
939read buffer (apart from looking at it) is removing data from its
940beginning. Otherwise modifying or appending to it is not allowed and will
941lead to hard-to-track-down bugs.
844 942
845NOTE: The read buffer should only be used or modified if the C<on_read>, 943NOTE: The read buffer should only be used or modified if the C<on_read>,
846C<push_read> or C<unshift_read> methods are used. The other read methods 944C<push_read> or C<unshift_read> methods are used. The other read methods
847automatically manage the read buffer. 945automatically manage the read buffer.
848 946
… …
1164=cut 1262=cut
1165 1263
1166register_read_type json => sub { 1264register_read_type json => sub {
1167 my ($self, $cb) = @_; 1265 my ($self, $cb) = @_;
1168 1266
1169 require JSON; 1267 my $json = $self->{json} ||=
1268 eval { require JSON::XS; JSON::XS->new->utf8 }
1269 || do { require JSON; JSON->new->utf8 };
1170 1270
1171 my $data; 1271 my $data;
1172 my $rbuf = \$self->{rbuf}; 1272 my $rbuf = \$self->{rbuf};
1173 1273
1174 my $json = $self->{json} ||= JSON->new->utf8;
1175
1176 sub { 1274 sub {
1177 eval {
1178 my $ref = $json->incr_parse ($self->{rbuf}); 1275 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1179 1276
1180 if ($ref) { 1277 if ($ref) {
1181 $self->{rbuf} = $json->incr_text; 1278 $self->{rbuf} = $json->incr_text;
1182 $json->incr_text = ""; 1279 $json->incr_text = "";
1183 $cb->($self, $ref); 1280 $cb->($self, $ref);
1184
1185 1
1186 } else {
1187 $self->{rbuf} = "";
1188 ()
1189 }
1190 1281
1191 1 1282 1
1192 } or do { 1283 } elsif ($@) {
1193 # error case 1284 # error case
1194 $json->incr_skip; 1285 $json->incr_skip;
1195 1286
1196 $self->{rbuf} = $json->incr_text; 1287 $self->{rbuf} = $json->incr_text;
1197 $json->incr_text = ""; 1288 $json->incr_text = "";
1198 1289
1199 $self->_error (&Errno::EBADMSG); 1290 $self->_error (&Errno::EBADMSG);
1291
1292 ()
1293 } else {
1294 $self->{rbuf} = "";
1295
1296 ()
1200 }; 1297 }
1201 } 1298 }
1202}; 1299};
1203 1300
1204=item storable => $cb->($handle, $ref) 1301=item storable => $cb->($handle, $ref)
1205 1302
… …
1324 } 1421 }
1325 }); 1422 });
1326 } 1423 }
1327} 1424}
1328 1425
1426our $ERROR_SYSCALL;
1427our $ERROR_WANT_READ;
1428
1429sub _tls_error {
1430 my ($self, $err) = @_;
1431
1432 return $self->_error ($!, 1)
1433 if $err == Net::SSLeay::ERROR_SYSCALL ();
1434
1435 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1436
1437 # reduce error string to look less scary
1438 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1439
1440 $self->_error (&Errno::EPROTO, 1, $err);
1441}
1442
1329# poll the write BIO and send the data if applicable 1443# poll the write BIO and send the data if applicable
1444# also decode read data if possible
1445# this is basiclaly our TLS state machine
1446# more efficient implementations are possible with openssl,
1447# but not with the buggy and incomplete Net::SSLeay.
1330sub _dotls { 1448sub _dotls {
1331 my ($self) = @_; 1449 my ($self) = @_;
1332 1450
1333 my $tmp; 1451 my $tmp;
1334 1452
1335 if (length $self->{_tls_wbuf}) { 1453 if (length $self->{_tls_wbuf}) {
1336 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1454 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1337 substr $self->{_tls_wbuf}, 0, $tmp, ""; 1455 substr $self->{_tls_wbuf}, 0, $tmp, "";
1338 } 1456 }
1457
1458 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1459 return $self->_tls_error ($tmp)
1460 if $tmp != $ERROR_WANT_READ
1461 && ($tmp != $ERROR_SYSCALL || $!);
1339 } 1462 }
1340 1463
1341 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) { 1464 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1342 unless (length $tmp) { 1465 unless (length $tmp) {
1343 # let's treat SSL-eof as we treat normal EOF
1344 delete $self->{_rw};
1345 $self->{_eof} = 1;
1346 &_freetls; 1466 &_freetls;
1467 if ($self->{on_stoptls}) {
1468 $self->{on_stoptls}($self);
1469 return;
1470 } else {
1471 # let's treat SSL-eof as we treat normal EOF
1472 delete $self->{_rw};
1473 $self->{_eof} = 1;
1474 }
1347 } 1475 }
1348 1476
1349 $self->{rbuf} .= $tmp; 1477 $self->{_tls_rbuf} .= $tmp;
1350 $self->_drain_rbuf unless $self->{_in_drain}; 1478 $self->_drain_rbuf unless $self->{_in_drain};
1351 $self->{tls} or return; # tls session might have gone away in callback 1479 $self->{tls} or return; # tls session might have gone away in callback
1352 } 1480 }
1353 1481
1354 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); 1482 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1355
1356 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1357 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1358 return $self->_error ($!, 1); 1483 return $self->_tls_error ($tmp)
1359 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) { 1484 if $tmp != $ERROR_WANT_READ
1360 return $self->_error (&Errno::EIO, 1); 1485 && ($tmp != $ERROR_SYSCALL || $!);
1361 }
1362
1363 # all other errors are fine for our purposes
1364 }
1365 1486
1366 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) { 1487 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1367 $self->{wbuf} .= $tmp; 1488 $self->{wbuf} .= $tmp;
1368 $self->_drain_wbuf; 1489 $self->_drain_wbuf;
1369 } 1490 }
1491
1492 $self->{_on_starttls}
1493 and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
1494 and (delete $self->{_on_starttls})->($self, 1);
1370} 1495}
1371 1496
1372=item $handle->starttls ($tls[, $tls_ctx]) 1497=item $handle->starttls ($tls[, $tls_ctx])
1373 1498
1374Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1499Instead of starting TLS negotiation immediately when the AnyEvent::Handle
… …
1376C<starttls>. 1501C<starttls>.
1377 1502
1378The first argument is the same as the C<tls> constructor argument (either 1503The first argument is the same as the C<tls> constructor argument (either
1379C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1504C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1380 1505
1381The second argument is the optional C<Net::SSLeay::CTX> object that is 1506The second argument is the optional C<AnyEvent::TLS> object that is used
1382used when AnyEvent::Handle has to create its own TLS connection object. 1507when AnyEvent::Handle has to create its own TLS connection object, or
1508a hash reference with C<< key => value >> pairs that will be used to
1509construct a new context.
1383 1510
1384The TLS connection object will end up in C<< $handle->{tls} >> after this 1511The TLS connection object will end up in C<< $handle->{tls} >>, the TLS
1385call and can be used or changed to your liking. Note that the handshake 1512context in C<< $handle->{tls_ctx} >> after this call and can be used or
1386might have already started when this function returns. 1513changed to your liking. Note that the handshake might have already started
1514when this function returns.
1387 1515
1388If it an error to start a TLS handshake more than once per 1516If it an error to start a TLS handshake more than once per
1389AnyEvent::Handle object (this is due to bugs in OpenSSL). 1517AnyEvent::Handle object (this is due to bugs in OpenSSL).
1390 1518
1391=cut 1519=cut
1392 1520
1521our %TLS_CACHE; #TODO not yet documented, should we?
1522
1393sub starttls { 1523sub starttls {
1394 my ($self, $ssl, $ctx) = @_; 1524 my ($self, $ssl, $ctx) = @_;
1395 1525
1396 require Net::SSLeay; 1526 require Net::SSLeay;
1397 1527
1398 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object" 1528 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1399 if $self->{tls}; 1529 if $self->{tls};
1530
1531 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1532 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1533
1534 $ctx ||= $self->{tls_ctx};
1535
1536 if ("HASH" eq ref $ctx) {
1537 require AnyEvent::TLS;
1538
1539 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
1540
1541 if ($ctx->{cache}) {
1542 my $key = $ctx+0;
1543 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1544 } else {
1545 $ctx = new AnyEvent::TLS %$ctx;
1546 }
1547 }
1400 1548
1401 if ($ssl eq "accept") { 1549 $self->{tls_ctx} = $ctx || TLS_CTX ();
1402 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1550 $self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
1403 Net::SSLeay::set_accept_state ($ssl);
1404 } elsif ($ssl eq "connect") {
1405 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1406 Net::SSLeay::set_connect_state ($ssl);
1407 }
1408
1409 $self->{tls} = $ssl;
1410 1551
1411 # basically, this is deep magic (because SSL_read should have the same issues) 1552 # basically, this is deep magic (because SSL_read should have the same issues)
1412 # but the openssl maintainers basically said: "trust us, it just works". 1553 # but the openssl maintainers basically said: "trust us, it just works".
1413 # (unfortunately, we have to hardcode constants because the abysmally misdesigned 1554 # (unfortunately, we have to hardcode constants because the abysmally misdesigned
1414 # and mismaintained ssleay-module doesn't even offer them). 1555 # and mismaintained ssleay-module doesn't even offer them).
… …
1418 # 1559 #
1419 # note that we do not try to keep the length constant between writes as we are required to do. 1560 # note that we do not try to keep the length constant between writes as we are required to do.
1420 # we assume that most (but not all) of this insanity only applies to non-blocking cases, 1561 # we assume that most (but not all) of this insanity only applies to non-blocking cases,
1421 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to 1562 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1422 # have identity issues in that area. 1563 # have identity issues in that area.
1423 Net::SSLeay::CTX_set_mode ($self->{tls}, 1564# Net::SSLeay::CTX_set_mode ($ssl,
1424 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1565# (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1425 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1566# | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1567 Net::SSLeay::CTX_set_mode ($ssl, 1|2);
1426 1568
1427 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1569 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1428 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1570 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1429 1571
1430 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1572 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1573
1574 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1575 if exists $self->{on_starttls};
1431 1576
1432 &_dotls; # need to trigger the initial handshake 1577 &_dotls; # need to trigger the initial handshake
1433 $self->start_read; # make sure we actually do read 1578 $self->start_read; # make sure we actually do read
1434} 1579}
1435 1580
… …
1448 if ($self->{tls}) { 1593 if ($self->{tls}) {
1449 Net::SSLeay::shutdown ($self->{tls}); 1594 Net::SSLeay::shutdown ($self->{tls});
1450 1595
1451 &_dotls; 1596 &_dotls;
1452 1597
1453 # we don't give a shit. no, we do, but we can't. no... 1598# # we don't give a shit. no, we do, but we can't. no...#d#
1454 # we, we... have to use openssl :/ 1599# # we, we... have to use openssl :/#d#
1455 &_freetls; 1600# &_freetls;#d#
1456 } 1601 }
1457} 1602}
1458 1603
1459sub _freetls { 1604sub _freetls {
1460 my ($self) = @_; 1605 my ($self) = @_;
1461 1606
1462 return unless $self->{tls}; 1607 return unless $self->{tls};
1463 1608
1464 Net::SSLeay::free (delete $self->{tls}); 1609 $self->{_on_starttls}
1610 and (delete $self->{_on_starttls})->($self, undef);
1611
1612 $self->{tls_ctx}->_put_session (delete $self->{tls});
1465 1613
1466 delete @$self{qw(_rbio _wbio _tls_wbuf)}; 1614 delete @$self{qw(_rbio _wbio _tls_wbuf)};
1467} 1615}
1468 1616
1469sub DESTROY { 1617sub DESTROY {
1470 my $self = shift; 1618 my ($self) = @_;
1471 1619
1472 &_freetls; 1620 &_freetls;
1473 1621
1474 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 1622 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1475 1623
… …
1495} 1643}
1496 1644
1497=item $handle->destroy 1645=item $handle->destroy
1498 1646
1499Shuts down the handle object as much as possible - this call ensures that 1647Shuts down the handle object as much as possible - this call ensures that
1500no further callbacks will be invoked and resources will be freed as much 1648no further callbacks will be invoked and as many resources as possible
1501as possible. You must not call any methods on the object afterwards. 1649will be freed. You must not call any methods on the object afterwards.
1502 1650
1503Normally, you can just "forget" any references to an AnyEvent::Handle 1651Normally, you can just "forget" any references to an AnyEvent::Handle
1504object and it will simply shut down. This works in fatal error and EOF 1652object and it will simply shut down. This works in fatal error and EOF
1505callbacks, as well as code outside. It does I<NOT> work in a read or write 1653callbacks, as well as code outside. It does I<NOT> work in a read or write
1506callback, so when you want to destroy the AnyEvent::Handle object from 1654callback, so when you want to destroy the AnyEvent::Handle object from
… …
1519 %$self = (); 1667 %$self = ();
1520} 1668}
1521 1669
1522=item AnyEvent::Handle::TLS_CTX 1670=item AnyEvent::Handle::TLS_CTX
1523 1671
1524This function creates and returns the Net::SSLeay::CTX object used by 1672This function creates and returns the AnyEvent::TLS object used by default
1525default for TLS mode. 1673for TLS mode.
1526 1674
1527The context is created like this: 1675The context is created by calling L<AnyEvent::TLS> without any arguments.
1528
1529 Net::SSLeay::load_error_strings;
1530 Net::SSLeay::SSLeay_add_ssl_algorithms;
1531 Net::SSLeay::randomize;
1532
1533 my $CTX = Net::SSLeay::CTX_new;
1534
1535 Net::SSLeay::CTX_set_options $CTX, Net::SSLeay::OP_ALL
1536 1676
1537=cut 1677=cut
1538 1678
1539our $TLS_CTX; 1679our $TLS_CTX;
1540 1680
1541sub TLS_CTX() { 1681sub TLS_CTX() {
1542 $TLS_CTX || do { 1682 $TLS_CTX ||= do {
1543 require Net::SSLeay; 1683 require AnyEvent::TLS;
1544 1684
1545 Net::SSLeay::load_error_strings (); 1685 new AnyEvent::TLS
1546 Net::SSLeay::SSLeay_add_ssl_algorithms ();
1547 Net::SSLeay::randomize ();
1548
1549 $TLS_CTX = Net::SSLeay::CTX_new ();
1550
1551 Net::SSLeay::CTX_set_options ($TLS_CTX, Net::SSLeay::OP_ALL ());
1552
1553 $TLS_CTX
1554 } 1686 }
1555} 1687}
1556 1688
1557=back 1689=back
1558 1690

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines