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.109 by root, Wed Jan 14 02:03:43 2009 UTC vs.
Revision 1.143 by root, Mon Jul 6 21:02:34 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[, $error_message])
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
310TLS handshake failures will not cause C<on_error> to be invoked when this
311callback is in effect, instead, the error message will be passed to C<on_starttls>.
312
313Without this callback, handshake failures lead to C<on_error> being
314called, as normal.
315
316Note that you cannot call C<starttls> right again in this callback. If you
317need to do that, start an zero-second timer instead whose callback can
318then call C<< ->starttls >> again.
319
320=item on_stoptls => $cb->($handle)
321
322When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
323set, then it will be invoked after freeing the TLS session. If it is not,
324then a TLS shutdown condition will be treated like a normal EOF condition
325on the handle.
326
327The session in C<< $handle->{tls} >> can still be examined in this
328callback.
329
330This callback will only be called on TLS shutdowns, not when the
331underlying handle signals EOF.
272 332
273=item json => JSON or JSON::XS object 333=item json => JSON or JSON::XS object
274 334
275This is the json coder object used by the C<json> read and write types. 335This is the json coder object used by the C<json> read and write types.
276 336
285 345
286=cut 346=cut
287 347
288sub new { 348sub new {
289 my $class = shift; 349 my $class = shift;
290
291 my $self = bless { @_ }, $class; 350 my $self = bless { @_ }, $class;
292 351
293 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 352 $self->{fh} or Carp::croak "mandatory argument fh is missing";
294 353
295 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 354 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
355
356 $self->{_activity} = AnyEvent->now;
357 $self->_timeout;
358
359 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
296 360
297 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 361 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
298 if $self->{tls}; 362 if $self->{tls};
299 363
300 $self->{_activity} = AnyEvent->now;
301 $self->_timeout;
302
303 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 364 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
304 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
305 365
306 $self->start_read 366 $self->start_read
307 if $self->{on_read}; 367 if $self->{on_read};
308 368
309 $self 369 $self->{fh} && $self
310} 370}
311 371
312sub _shutdown { 372sub _shutdown {
313 my ($self) = @_; 373 my ($self) = @_;
314 374
315 delete $self->{_tw}; 375 delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};
316 delete $self->{_rw}; 376 $self->{_eof} = 1; # tell starttls et. al to stop trying
317 delete $self->{_ww};
318 delete $self->{fh};
319 377
320 &_freetls; 378 &_freetls;
321
322 delete $self->{on_read};
323 delete $self->{_queue};
324} 379}
325 380
326sub _error { 381sub _error {
327 my ($self, $errno, $fatal) = @_; 382 my ($self, $errno, $fatal, $message) = @_;
328 383
329 $self->_shutdown 384 $self->_shutdown
330 if $fatal; 385 if $fatal;
331 386
332 $! = $errno; 387 $! = $errno;
388 $message ||= "$!";
333 389
334 if ($self->{on_error}) { 390 if ($self->{on_error}) {
335 $self->{on_error}($self, $fatal); 391 $self->{on_error}($self, $fatal, $message);
336 } elsif ($self->{fh}) { 392 } elsif ($self->{fh}) {
337 Carp::croak "AnyEvent::Handle uncaught error: $!"; 393 Carp::croak "AnyEvent::Handle uncaught error: $message";
338 } 394 }
339} 395}
340 396
341=item $fh = $handle->fh 397=item $fh = $handle->fh
342 398
401 457
402 eval { 458 eval {
403 local $SIG{__DIE__}; 459 local $SIG{__DIE__};
404 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]; 460 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
405 }; 461 };
462}
463
464=item $handle->on_starttls ($cb)
465
466Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
467
468=cut
469
470sub on_starttls {
471 $_[0]{on_starttls} = $_[1];
472}
473
474=item $handle->on_stoptls ($cb)
475
476Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
477
478=cut
479
480sub on_starttls {
481 $_[0]{on_stoptls} = $_[1];
406} 482}
407 483
408############################################################################# 484#############################################################################
409 485
410=item $handle->timeout ($seconds) 486=item $handle->timeout ($seconds)
654 730
655 pack "w/a*", Storable::nfreeze ($ref) 731 pack "w/a*", Storable::nfreeze ($ref)
656}; 732};
657 733
658=back 734=back
735
736=item $handle->push_shutdown
737
738Sometimes you know you want to close the socket after writing your data
739before it was actually written. One way to do that is to replace your
740C<on_drain> handler by a callback that shuts down the socket (and set
741C<low_water_mark> to C<0>). This method is a shorthand for just that, and
742replaces the C<on_drain> callback with:
743
744 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
745
746This simply shuts down the write side and signals an EOF condition to the
747the peer.
748
749You can rely on the normal read queue and C<on_eof> handling
750afterwards. This is the cleanest way to close a connection.
751
752=cut
753
754sub push_shutdown {
755 my ($self) = @_;
756
757 delete $self->{low_water_mark};
758 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
759}
659 760
660=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 761=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
661 762
662This function (not method) lets you add your own types to C<push_write>. 763This 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 764Whenever the given C<type> is used, C<push_write> will invoke the code
767 ) { 868 ) {
768 $self->_error (&Errno::ENOSPC, 1), return; 869 $self->_error (&Errno::ENOSPC, 1), return;
769 } 870 }
770 871
771 while () { 872 while () {
873 # we need to use a separate tls read buffer, as we must not receive data while
874 # we are draining the buffer, and this can only happen with TLS.
875 $self->{rbuf} .= delete $self->{_tls_rbuf} if exists $self->{_tls_rbuf};
876
772 my $len = length $self->{rbuf}; 877 my $len = length $self->{rbuf};
773 878
774 if (my $cb = shift @{ $self->{_queue} }) { 879 if (my $cb = shift @{ $self->{_queue} }) {
775 unless ($cb->($self)) { 880 unless ($cb->($self)) {
776 if ($self->{_eof}) { 881 if ($self->{_eof}) {
807 912
808 if ($self->{_eof}) { 913 if ($self->{_eof}) {
809 if ($self->{on_eof}) { 914 if ($self->{on_eof}) {
810 $self->{on_eof}($self) 915 $self->{on_eof}($self)
811 } else { 916 } else {
812 $self->_error (0, 1); 917 $self->_error (0, 1, "Unexpected end-of-file");
813 } 918 }
814 } 919 }
815 920
816 # may need to restart read watcher 921 # may need to restart read watcher
817 unless ($self->{_rw}) { 922 unless ($self->{_rw}) {
837 942
838=item $handle->rbuf 943=item $handle->rbuf
839 944
840Returns the read buffer (as a modifiable lvalue). 945Returns the read buffer (as a modifiable lvalue).
841 946
842You can access the read buffer directly as the C<< ->{rbuf} >> member, if 947You can access the read buffer directly as the C<< ->{rbuf} >>
843you want. 948member, if you want. However, the only operation allowed on the
949read buffer (apart from looking at it) is removing data from its
950beginning. Otherwise modifying or appending to it is not allowed and will
951lead to hard-to-track-down bugs.
844 952
845NOTE: The read buffer should only be used or modified if the C<on_read>, 953NOTE: 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 954C<push_read> or C<unshift_read> methods are used. The other read methods
847automatically manage the read buffer. 955automatically manage the read buffer.
848 956
1144 } 1252 }
1145}; 1253};
1146 1254
1147=item json => $cb->($handle, $hash_or_arrayref) 1255=item json => $cb->($handle, $hash_or_arrayref)
1148 1256
1149Reads a JSON object or array, decodes it and passes it to the callback. 1257Reads a JSON object or array, decodes it and passes it to the
1258callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1150 1259
1151If a C<json> object was passed to the constructor, then that will be used 1260If a C<json> object was passed to the constructor, then that will be used
1152for the final decode, otherwise it will create a JSON coder expecting UTF-8. 1261for the final decode, otherwise it will create a JSON coder expecting UTF-8.
1153 1262
1154This read type uses the incremental parser available with JSON version 1263This read type uses the incremental parser available with JSON version
1163=cut 1272=cut
1164 1273
1165register_read_type json => sub { 1274register_read_type json => sub {
1166 my ($self, $cb) = @_; 1275 my ($self, $cb) = @_;
1167 1276
1168 require JSON; 1277 my $json = $self->{json} ||=
1278 eval { require JSON::XS; JSON::XS->new->utf8 }
1279 || do { require JSON; JSON->new->utf8 };
1169 1280
1170 my $data; 1281 my $data;
1171 my $rbuf = \$self->{rbuf}; 1282 my $rbuf = \$self->{rbuf};
1172 1283
1173 my $json = $self->{json} ||= JSON->new->utf8;
1174
1175 sub { 1284 sub {
1176 my $ref = $json->incr_parse ($self->{rbuf}); 1285 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1177 1286
1178 if ($ref) { 1287 if ($ref) {
1179 $self->{rbuf} = $json->incr_text; 1288 $self->{rbuf} = $json->incr_text;
1180 $json->incr_text = ""; 1289 $json->incr_text = "";
1181 $cb->($self, $ref); 1290 $cb->($self, $ref);
1182 1291
1183 1 1292 1
1293 } elsif ($@) {
1294 # error case
1295 $json->incr_skip;
1296
1297 $self->{rbuf} = $json->incr_text;
1298 $json->incr_text = "";
1299
1300 $self->_error (&Errno::EBADMSG);
1301
1302 ()
1184 } else { 1303 } else {
1185 $self->{rbuf} = ""; 1304 $self->{rbuf} = "";
1305
1186 () 1306 ()
1187 } 1307 }
1188 } 1308 }
1189}; 1309};
1190 1310
1311 } 1431 }
1312 }); 1432 });
1313 } 1433 }
1314} 1434}
1315 1435
1436our $ERROR_SYSCALL;
1437our $ERROR_WANT_READ;
1438
1439sub _tls_error {
1440 my ($self, $err) = @_;
1441
1442 return $self->_error ($!, 1)
1443 if $err == Net::SSLeay::ERROR_SYSCALL ();
1444
1445 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1446
1447 # reduce error string to look less scary
1448 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1449
1450 if ($self->{_on_starttls}) {
1451 (delete $self->{_on_starttls})->($self, undef, $err);
1452 &_freetls;
1453 } else {
1454 &_freetls;
1455 $self->_error (&Errno::EPROTO, 1, $err);
1456 }
1457}
1458
1316# poll the write BIO and send the data if applicable 1459# poll the write BIO and send the data if applicable
1460# also decode read data if possible
1461# this is basiclaly our TLS state machine
1462# more efficient implementations are possible with openssl,
1463# but not with the buggy and incomplete Net::SSLeay.
1317sub _dotls { 1464sub _dotls {
1318 my ($self) = @_; 1465 my ($self) = @_;
1319 1466
1320 my $tmp; 1467 my $tmp;
1321 1468
1322 if (length $self->{_tls_wbuf}) { 1469 if (length $self->{_tls_wbuf}) {
1323 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1470 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1324 substr $self->{_tls_wbuf}, 0, $tmp, ""; 1471 substr $self->{_tls_wbuf}, 0, $tmp, "";
1325 } 1472 }
1473
1474 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1475 return $self->_tls_error ($tmp)
1476 if $tmp != $ERROR_WANT_READ
1477 && ($tmp != $ERROR_SYSCALL || $!);
1326 } 1478 }
1327 1479
1328 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) { 1480 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1329 unless (length $tmp) { 1481 unless (length $tmp) {
1330 # let's treat SSL-eof as we treat normal EOF 1482 $self->{_on_starttls}
1331 delete $self->{_rw}; 1483 and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
1332 $self->{_eof} = 1;
1333 &_freetls; 1484 &_freetls;
1485
1486 if ($self->{on_stoptls}) {
1487 $self->{on_stoptls}($self);
1488 return;
1489 } else {
1490 # let's treat SSL-eof as we treat normal EOF
1491 delete $self->{_rw};
1492 $self->{_eof} = 1;
1493 }
1334 } 1494 }
1335 1495
1336 $self->{rbuf} .= $tmp; 1496 $self->{_tls_rbuf} .= $tmp;
1337 $self->_drain_rbuf unless $self->{_in_drain}; 1497 $self->_drain_rbuf unless $self->{_in_drain};
1338 $self->{tls} or return; # tls session might have gone away in callback 1498 $self->{tls} or return; # tls session might have gone away in callback
1339 } 1499 }
1340 1500
1341 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); 1501 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1342
1343 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1344 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1345 return $self->_error ($!, 1); 1502 return $self->_tls_error ($tmp)
1346 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) { 1503 if $tmp != $ERROR_WANT_READ
1347 return $self->_error (&Errno::EIO, 1); 1504 && ($tmp != $ERROR_SYSCALL || $!);
1348 }
1349
1350 # all other errors are fine for our purposes
1351 }
1352 1505
1353 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) { 1506 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1354 $self->{wbuf} .= $tmp; 1507 $self->{wbuf} .= $tmp;
1355 $self->_drain_wbuf; 1508 $self->_drain_wbuf;
1356 } 1509 }
1510
1511 $self->{_on_starttls}
1512 and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
1513 and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
1357} 1514}
1358 1515
1359=item $handle->starttls ($tls[, $tls_ctx]) 1516=item $handle->starttls ($tls[, $tls_ctx])
1360 1517
1361Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1518Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1363C<starttls>. 1520C<starttls>.
1364 1521
1365The first argument is the same as the C<tls> constructor argument (either 1522The first argument is the same as the C<tls> constructor argument (either
1366C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1523C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1367 1524
1368The second argument is the optional C<Net::SSLeay::CTX> object that is 1525The second argument is the optional C<AnyEvent::TLS> object that is used
1369used when AnyEvent::Handle has to create its own TLS connection object. 1526when AnyEvent::Handle has to create its own TLS connection object, or
1527a hash reference with C<< key => value >> pairs that will be used to
1528construct a new context.
1370 1529
1371The TLS connection object will end up in C<< $handle->{tls} >> after this 1530The TLS connection object will end up in C<< $handle->{tls} >>, the TLS
1372call and can be used or changed to your liking. Note that the handshake 1531context in C<< $handle->{tls_ctx} >> after this call and can be used or
1373might have already started when this function returns. 1532changed to your liking. Note that the handshake might have already started
1533when this function returns.
1374 1534
1375If it an error to start a TLS handshake more than once per 1535If it an error to start a TLS handshake more than once per
1376AnyEvent::Handle object (this is due to bugs in OpenSSL). 1536AnyEvent::Handle object (this is due to bugs in OpenSSL).
1377 1537
1378=cut 1538=cut
1379 1539
1540our %TLS_CACHE; #TODO not yet documented, should we?
1541
1380sub starttls { 1542sub starttls {
1381 my ($self, $ssl, $ctx) = @_; 1543 my ($self, $ssl, $ctx) = @_;
1382 1544
1383 require Net::SSLeay; 1545 require Net::SSLeay;
1384 1546
1385 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object" 1547 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1386 if $self->{tls}; 1548 if $self->{tls};
1549
1550 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1551 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1552
1553 $ctx ||= $self->{tls_ctx};
1554
1555 if ("HASH" eq ref $ctx) {
1556 require AnyEvent::TLS;
1557
1558 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
1559
1560 if ($ctx->{cache}) {
1561 my $key = $ctx+0;
1562 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1563 } else {
1564 $ctx = new AnyEvent::TLS %$ctx;
1565 }
1566 }
1387 1567
1388 if ($ssl eq "accept") { 1568 $self->{tls_ctx} = $ctx || TLS_CTX ();
1389 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1569 $self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
1390 Net::SSLeay::set_accept_state ($ssl);
1391 } elsif ($ssl eq "connect") {
1392 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1393 Net::SSLeay::set_connect_state ($ssl);
1394 }
1395
1396 $self->{tls} = $ssl;
1397 1570
1398 # basically, this is deep magic (because SSL_read should have the same issues) 1571 # basically, this is deep magic (because SSL_read should have the same issues)
1399 # but the openssl maintainers basically said: "trust us, it just works". 1572 # but the openssl maintainers basically said: "trust us, it just works".
1400 # (unfortunately, we have to hardcode constants because the abysmally misdesigned 1573 # (unfortunately, we have to hardcode constants because the abysmally misdesigned
1401 # and mismaintained ssleay-module doesn't even offer them). 1574 # and mismaintained ssleay-module doesn't even offer them).
1405 # 1578 #
1406 # note that we do not try to keep the length constant between writes as we are required to do. 1579 # note that we do not try to keep the length constant between writes as we are required to do.
1407 # we assume that most (but not all) of this insanity only applies to non-blocking cases, 1580 # we assume that most (but not all) of this insanity only applies to non-blocking cases,
1408 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to 1581 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1409 # have identity issues in that area. 1582 # have identity issues in that area.
1410 Net::SSLeay::CTX_set_mode ($self->{tls}, 1583# Net::SSLeay::CTX_set_mode ($ssl,
1411 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1584# (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1412 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1585# | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1586 Net::SSLeay::CTX_set_mode ($ssl, 1|2);
1413 1587
1414 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1588 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1415 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1589 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1416 1590
1417 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1591 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1592
1593 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1594 if $self->{on_starttls};
1418 1595
1419 &_dotls; # need to trigger the initial handshake 1596 &_dotls; # need to trigger the initial handshake
1420 $self->start_read; # make sure we actually do read 1597 $self->start_read; # make sure we actually do read
1421} 1598}
1422 1599
1435 if ($self->{tls}) { 1612 if ($self->{tls}) {
1436 Net::SSLeay::shutdown ($self->{tls}); 1613 Net::SSLeay::shutdown ($self->{tls});
1437 1614
1438 &_dotls; 1615 &_dotls;
1439 1616
1440 # we don't give a shit. no, we do, but we can't. no... 1617# # we don't give a shit. no, we do, but we can't. no...#d#
1441 # we, we... have to use openssl :/ 1618# # we, we... have to use openssl :/#d#
1442 &_freetls; 1619# &_freetls;#d#
1443 } 1620 }
1444} 1621}
1445 1622
1446sub _freetls { 1623sub _freetls {
1447 my ($self) = @_; 1624 my ($self) = @_;
1448 1625
1449 return unless $self->{tls}; 1626 return unless $self->{tls};
1450 1627
1451 Net::SSLeay::free (delete $self->{tls}); 1628 $self->{tls_ctx}->_put_session (delete $self->{tls});
1452 1629
1453 delete @$self{qw(_rbio _wbio _tls_wbuf)}; 1630 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1454} 1631}
1455 1632
1456sub DESTROY { 1633sub DESTROY {
1457 my $self = shift; 1634 my ($self) = @_;
1458 1635
1459 &_freetls; 1636 &_freetls;
1460 1637
1461 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 1638 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1462 1639
1482} 1659}
1483 1660
1484=item $handle->destroy 1661=item $handle->destroy
1485 1662
1486Shuts down the handle object as much as possible - this call ensures that 1663Shuts down the handle object as much as possible - this call ensures that
1487no further callbacks will be invoked and resources will be freed as much 1664no further callbacks will be invoked and as many resources as possible
1488as possible. You must not call any methods on the object afterwards. 1665will be freed. You must not call any methods on the object afterwards.
1489 1666
1490Normally, you can just "forget" any references to an AnyEvent::Handle 1667Normally, you can just "forget" any references to an AnyEvent::Handle
1491object and it will simply shut down. This works in fatal error and EOF 1668object and it will simply shut down. This works in fatal error and EOF
1492callbacks, as well as code outside. It does I<NOT> work in a read or write 1669callbacks, as well as code outside. It does I<NOT> work in a read or write
1493callback, so when you want to destroy the AnyEvent::Handle object from 1670callback, so when you want to destroy the AnyEvent::Handle object from
1506 %$self = (); 1683 %$self = ();
1507} 1684}
1508 1685
1509=item AnyEvent::Handle::TLS_CTX 1686=item AnyEvent::Handle::TLS_CTX
1510 1687
1511This function creates and returns the Net::SSLeay::CTX object used by 1688This function creates and returns the AnyEvent::TLS object used by default
1512default for TLS mode. 1689for TLS mode.
1513 1690
1514The context is created like this: 1691The context is created by calling L<AnyEvent::TLS> without any arguments.
1515
1516 Net::SSLeay::load_error_strings;
1517 Net::SSLeay::SSLeay_add_ssl_algorithms;
1518 Net::SSLeay::randomize;
1519
1520 my $CTX = Net::SSLeay::CTX_new;
1521
1522 Net::SSLeay::CTX_set_options $CTX, Net::SSLeay::OP_ALL
1523 1692
1524=cut 1693=cut
1525 1694
1526our $TLS_CTX; 1695our $TLS_CTX;
1527 1696
1528sub TLS_CTX() { 1697sub TLS_CTX() {
1529 $TLS_CTX || do { 1698 $TLS_CTX ||= do {
1530 require Net::SSLeay; 1699 require AnyEvent::TLS;
1531 1700
1532 Net::SSLeay::load_error_strings (); 1701 new AnyEvent::TLS
1533 Net::SSLeay::SSLeay_add_ssl_algorithms ();
1534 Net::SSLeay::randomize ();
1535
1536 $TLS_CTX = Net::SSLeay::CTX_new ();
1537
1538 Net::SSLeay::CTX_set_options ($TLS_CTX, Net::SSLeay::OP_ALL ());
1539
1540 $TLS_CTX
1541 } 1702 }
1542} 1703}
1543 1704
1544=back 1705=back
1545 1706
1610 $handle->on_drain (sub { 1771 $handle->on_drain (sub {
1611 warn "all data submitted to the kernel\n"; 1772 warn "all data submitted to the kernel\n";
1612 undef $handle; 1773 undef $handle;
1613 }); 1774 });
1614 1775
1776If you just want to queue some data and then signal EOF to the other side,
1777consider using C<< ->push_shutdown >> instead.
1778
1779=item I want to contact a TLS/SSL server, I don't care about security.
1780
1781If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
1782simply connect to it and then create the AnyEvent::Handle with the C<tls>
1783parameter:
1784
1785 my $handle = new AnyEvent::Handle
1786 fh => $fh,
1787 tls => "connect",
1788 on_error => sub { ... };
1789
1790 $handle->push_write (...);
1791
1792=item I want to contact a TLS/SSL server, I do care about security.
1793
1794Then you #x##TODO#
1795
1796
1797
1615=back 1798=back
1616 1799
1617 1800
1618=head1 SUBCLASSING AnyEvent::Handle 1801=head1 SUBCLASSING AnyEvent::Handle
1619 1802

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines