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.129 by root, Mon Jun 29 11:04:09 2009 UTC vs.
Revision 1.148 by root, Fri Jul 10 22:35:28 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.42; 19our $VERSION = 4.82;
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. Note that you 138method or access the C<< $handle->{rbuf} >> member directly. Note that you
133must not enlarge or modify the read buffer, you can only remove data at 139must not enlarge or modify the read buffer, you can only remove data at
134the beginning from it. 140the beginning from it.
135 141
136When 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
137feed 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
237 243
238This 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
239yet. 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
240help. 246help.
241 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>). This
255verification will be skipped when C<peername> is not specified or
256C<undef>.
257
242=item tls => "accept" | "connect" | Net::SSLeay::SSL object 258=item tls => "accept" | "connect" | Net::SSLeay::SSL object
243 259
244When this parameter is given, it enables TLS (SSL) mode, that means 260When this parameter is given, it enables TLS (SSL) mode, that means
245AnyEvent will start a TLS handshake as soon as the conenction has been 261AnyEvent will start a TLS handshake as soon as the conenction has been
246established and will transparently encrypt/decrypt data afterwards. 262established and will transparently encrypt/decrypt data afterwards.
263
264All TLS protocol errors will be signalled as C<EPROTO>, with an
265appropriate error message.
247 266
248TLS mode requires Net::SSLeay to be installed (it will be loaded 267TLS mode requires Net::SSLeay to be installed (it will be loaded
249automatically when you try to create a TLS handle): this module doesn't 268automatically when you try to create a TLS handle): this module doesn't
250have a dependency on that module, so if your module requires it, you have 269have a dependency on that module, so if your module requires it, you have
251to add the dependency yourself. 270to add the dependency yourself.
255mode. 274mode.
256 275
257You can also provide your own TLS connection object, but you have 276You can also provide your own TLS connection object, but you have
258to make sure that you call either C<Net::SSLeay::set_connect_state> 277to make sure that you call either C<Net::SSLeay::set_connect_state>
259or C<Net::SSLeay::set_accept_state> on it before you pass it to 278or C<Net::SSLeay::set_accept_state> on it before you pass it to
260AnyEvent::Handle. 279AnyEvent::Handle. Also, this module will take ownership of this connection
280object.
281
282At some future point, AnyEvent::Handle might switch to another TLS
283implementation, then the option to use your own session object will go
284away.
261 285
262B<IMPORTANT:> since Net::SSLeay "objects" are really only integers, 286B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
263passing in the wrong integer will lead to certain crash. This most often 287passing in the wrong integer will lead to certain crash. This most often
264happens when one uses a stylish C<< tls => 1 >> and is surprised about the 288happens when one uses a stylish C<< tls => 1 >> and is surprised about the
265segmentation fault. 289segmentation fault.
266 290
267See the C<< ->starttls >> method for when need to start TLS negotiation later. 291See the C<< ->starttls >> method for when need to start TLS negotiation later.
268 292
269=item tls_ctx => $ssl_ctx 293=item tls_ctx => $anyevent_tls
270 294
271Use the given C<Net::SSLeay::CTX> object to create the new TLS connection 295Use the given C<AnyEvent::TLS> object to create the new TLS connection
272(unless a connection object was specified directly). If this parameter is 296(unless a connection object was specified directly). If this parameter is
273missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 297missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
298
299Instead of an object, you can also specify a hash reference with C<< key
300=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
301new TLS context object.
302
303=item on_starttls => $cb->($handle, $success[, $error_message])
304
305This callback will be invoked when the TLS/SSL handshake has finished. If
306C<$success> is true, then the TLS handshake succeeded, otherwise it failed
307(C<on_stoptls> will not be called in this case).
308
309The session in C<< $handle->{tls} >> can still be examined in this
310callback, even when the handshake was not successful.
311
312TLS handshake failures will not cause C<on_error> to be invoked when this
313callback is in effect, instead, the error message will be passed to C<on_starttls>.
314
315Without this callback, handshake failures lead to C<on_error> being
316called, as normal.
317
318Note that you cannot call C<starttls> right again in this callback. If you
319need to do that, start an zero-second timer instead whose callback can
320then call C<< ->starttls >> again.
321
322=item on_stoptls => $cb->($handle)
323
324When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
325set, then it will be invoked after freeing the TLS session. If it is not,
326then a TLS shutdown condition will be treated like a normal EOF condition
327on the handle.
328
329The session in C<< $handle->{tls} >> can still be examined in this
330callback.
331
332This callback will only be called on TLS shutdowns, not when the
333underlying handle signals EOF.
274 334
275=item json => JSON or JSON::XS object 335=item json => JSON or JSON::XS object
276 336
277This is the json coder object used by the C<json> read and write types. 337This is the json coder object used by the C<json> read and write types.
278 338
287 347
288=cut 348=cut
289 349
290sub new { 350sub new {
291 my $class = shift; 351 my $class = shift;
292
293 my $self = bless { @_ }, $class; 352 my $self = bless { @_ }, $class;
294 353
295 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 354 $self->{fh} or Carp::croak "mandatory argument fh is missing";
296 355
297 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 356 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
357
358 $self->{_activity} = AnyEvent->now;
359 $self->_timeout;
360
361 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
298 362
299 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 363 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
300 if $self->{tls}; 364 if $self->{tls};
301 365
302 $self->{_activity} = AnyEvent->now;
303 $self->_timeout;
304
305 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 366 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
306 $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
307 367
308 $self->start_read 368 $self->start_read
309 if $self->{on_read}; 369 if $self->{on_read};
310 370
311 $self 371 $self->{fh} && $self
312} 372}
313 373
314sub _shutdown { 374sub _shutdown {
315 my ($self) = @_; 375 my ($self) = @_;
316 376
317 delete @$self{qw(_tw _rw _ww fh rbuf wbuf on_read _queue)}; 377 delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};
378 $self->{_eof} = 1; # tell starttls et. al to stop trying
318 379
319 &_freetls; 380 &_freetls;
320} 381}
321 382
322sub _error { 383sub _error {
323 my ($self, $errno, $fatal) = @_; 384 my ($self, $errno, $fatal, $message) = @_;
324 385
325 $self->_shutdown 386 $self->_shutdown
326 if $fatal; 387 if $fatal;
327 388
328 $! = $errno; 389 $! = $errno;
390 $message ||= "$!";
329 391
330 if ($self->{on_error}) { 392 if ($self->{on_error}) {
331 $self->{on_error}($self, $fatal); 393 $self->{on_error}($self, $fatal, $message);
332 } elsif ($self->{fh}) { 394 } elsif ($self->{fh}) {
333 Carp::croak "AnyEvent::Handle uncaught error: $!"; 395 Carp::croak "AnyEvent::Handle uncaught error: $message";
334 } 396 }
335} 397}
336 398
337=item $fh = $handle->fh 399=item $fh = $handle->fh
338 400
397 459
398 eval { 460 eval {
399 local $SIG{__DIE__}; 461 local $SIG{__DIE__};
400 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1]; 462 setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
401 }; 463 };
464}
465
466=item $handle->on_starttls ($cb)
467
468Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
469
470=cut
471
472sub on_starttls {
473 $_[0]{on_starttls} = $_[1];
474}
475
476=item $handle->on_stoptls ($cb)
477
478Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
479
480=cut
481
482sub on_starttls {
483 $_[0]{on_stoptls} = $_[1];
402} 484}
403 485
404############################################################################# 486#############################################################################
405 487
406=item $handle->timeout ($seconds) 488=item $handle->timeout ($seconds)
505 Scalar::Util::weaken $self; 587 Scalar::Util::weaken $self;
506 588
507 my $cb = sub { 589 my $cb = sub {
508 my $len = syswrite $self->{fh}, $self->{wbuf}; 590 my $len = syswrite $self->{fh}, $self->{wbuf};
509 591
510 if ($len >= 0) { 592 if (defined $len) {
511 substr $self->{wbuf}, 0, $len, ""; 593 substr $self->{wbuf}, 0, $len, "";
512 594
513 $self->{_activity} = AnyEvent->now; 595 $self->{_activity} = AnyEvent->now;
514 596
515 $self->{on_drain}($self) 597 $self->{on_drain}($self)
650 732
651 pack "w/a*", Storable::nfreeze ($ref) 733 pack "w/a*", Storable::nfreeze ($ref)
652}; 734};
653 735
654=back 736=back
737
738=item $handle->push_shutdown
739
740Sometimes you know you want to close the socket after writing your data
741before it was actually written. One way to do that is to replace your
742C<on_drain> handler by a callback that shuts down the socket (and set
743C<low_water_mark> to C<0>). This method is a shorthand for just that, and
744replaces the C<on_drain> callback with:
745
746 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
747
748This simply shuts down the write side and signals an EOF condition to the
749the peer.
750
751You can rely on the normal read queue and C<on_eof> handling
752afterwards. This is the cleanest way to close a connection.
753
754=cut
755
756sub push_shutdown {
757 my ($self) = @_;
758
759 delete $self->{low_water_mark};
760 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
761}
655 762
656=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 763=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
657 764
658This function (not method) lets you add your own types to C<push_write>. 765This function (not method) lets you add your own types to C<push_write>.
659Whenever the given C<type> is used, C<push_write> will invoke the code 766Whenever the given C<type> is used, C<push_write> will invoke the code
807 914
808 if ($self->{_eof}) { 915 if ($self->{_eof}) {
809 if ($self->{on_eof}) { 916 if ($self->{on_eof}) {
810 $self->{on_eof}($self) 917 $self->{on_eof}($self)
811 } else { 918 } else {
812 $self->_error (0, 1); 919 $self->_error (0, 1, "Unexpected end-of-file");
813 } 920 }
814 } 921 }
815 922
816 # may need to restart read watcher 923 # may need to restart read watcher
817 unless ($self->{_rw}) { 924 unless ($self->{_rw}) {
1167=cut 1274=cut
1168 1275
1169register_read_type json => sub { 1276register_read_type json => sub {
1170 my ($self, $cb) = @_; 1277 my ($self, $cb) = @_;
1171 1278
1172 require JSON; 1279 my $json = $self->{json} ||=
1280 eval { require JSON::XS; JSON::XS->new->utf8 }
1281 || do { require JSON; JSON->new->utf8 };
1173 1282
1174 my $data; 1283 my $data;
1175 my $rbuf = \$self->{rbuf}; 1284 my $rbuf = \$self->{rbuf};
1176
1177 my $json = $self->{json} ||= JSON->new->utf8;
1178 1285
1179 sub { 1286 sub {
1180 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1287 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1181 1288
1182 if ($ref) { 1289 if ($ref) {
1326 } 1433 }
1327 }); 1434 });
1328 } 1435 }
1329} 1436}
1330 1437
1438our $ERROR_SYSCALL;
1439our $ERROR_WANT_READ;
1440
1441sub _tls_error {
1442 my ($self, $err) = @_;
1443
1444 return $self->_error ($!, 1)
1445 if $err == Net::SSLeay::ERROR_SYSCALL ();
1446
1447 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1448
1449 # reduce error string to look less scary
1450 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1451
1452 if ($self->{_on_starttls}) {
1453 (delete $self->{_on_starttls})->($self, undef, $err);
1454 &_freetls;
1455 } else {
1456 &_freetls;
1457 $self->_error (&Errno::EPROTO, 1, $err);
1458 }
1459}
1460
1331# poll the write BIO and send the data if applicable 1461# poll the write BIO and send the data if applicable
1462# also decode read data if possible
1463# this is basiclaly our TLS state machine
1464# more efficient implementations are possible with openssl,
1465# but not with the buggy and incomplete Net::SSLeay.
1332sub _dotls { 1466sub _dotls {
1333 my ($self) = @_; 1467 my ($self) = @_;
1334 1468
1335 my $tmp; 1469 my $tmp;
1336 1470
1337 if (length $self->{_tls_wbuf}) { 1471 if (length $self->{_tls_wbuf}) {
1338 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1472 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1339 substr $self->{_tls_wbuf}, 0, $tmp, ""; 1473 substr $self->{_tls_wbuf}, 0, $tmp, "";
1340 } 1474 }
1475
1476 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1477 return $self->_tls_error ($tmp)
1478 if $tmp != $ERROR_WANT_READ
1479 && ($tmp != $ERROR_SYSCALL || $!);
1341 } 1480 }
1342 1481
1343 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) { 1482 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1344 unless (length $tmp) { 1483 unless (length $tmp) {
1345 # let's treat SSL-eof as we treat normal EOF 1484 $self->{_on_starttls}
1346 delete $self->{_rw}; 1485 and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
1347 $self->{_eof} = 1;
1348 &_freetls; 1486 &_freetls;
1487
1488 if ($self->{on_stoptls}) {
1489 $self->{on_stoptls}($self);
1490 return;
1491 } else {
1492 # let's treat SSL-eof as we treat normal EOF
1493 delete $self->{_rw};
1494 $self->{_eof} = 1;
1495 }
1349 } 1496 }
1350 1497
1351 $self->{_tls_rbuf} .= $tmp; 1498 $self->{_tls_rbuf} .= $tmp;
1352 $self->_drain_rbuf unless $self->{_in_drain}; 1499 $self->_drain_rbuf unless $self->{_in_drain};
1353 $self->{tls} or return; # tls session might have gone away in callback 1500 $self->{tls} or return; # tls session might have gone away in callback
1354 } 1501 }
1355 1502
1356 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); 1503 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1357
1358 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1359 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1360 return $self->_error ($!, 1); 1504 return $self->_tls_error ($tmp)
1361 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) { 1505 if $tmp != $ERROR_WANT_READ
1362 return $self->_error (&Errno::EIO, 1); 1506 && ($tmp != $ERROR_SYSCALL || $!);
1363 }
1364
1365 # all other errors are fine for our purposes
1366 }
1367 1507
1368 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) { 1508 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1369 $self->{wbuf} .= $tmp; 1509 $self->{wbuf} .= $tmp;
1370 $self->_drain_wbuf; 1510 $self->_drain_wbuf;
1371 } 1511 }
1512
1513 $self->{_on_starttls}
1514 and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
1515 and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
1372} 1516}
1373 1517
1374=item $handle->starttls ($tls[, $tls_ctx]) 1518=item $handle->starttls ($tls[, $tls_ctx])
1375 1519
1376Instead of starting TLS negotiation immediately when the AnyEvent::Handle 1520Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1378C<starttls>. 1522C<starttls>.
1379 1523
1380The first argument is the same as the C<tls> constructor argument (either 1524The first argument is the same as the C<tls> constructor argument (either
1381C<"connect">, C<"accept"> or an existing Net::SSLeay object). 1525C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1382 1526
1383The second argument is the optional C<Net::SSLeay::CTX> object that is 1527The second argument is the optional C<AnyEvent::TLS> object that is used
1384used when AnyEvent::Handle has to create its own TLS connection object. 1528when AnyEvent::Handle has to create its own TLS connection object, or
1529a hash reference with C<< key => value >> pairs that will be used to
1530construct a new context.
1385 1531
1386The TLS connection object will end up in C<< $handle->{tls} >> after this 1532The TLS connection object will end up in C<< $handle->{tls} >>, the TLS
1387call and can be used or changed to your liking. Note that the handshake 1533context in C<< $handle->{tls_ctx} >> after this call and can be used or
1388might have already started when this function returns. 1534changed to your liking. Note that the handshake might have already started
1535when this function returns.
1389 1536
1390If it an error to start a TLS handshake more than once per 1537If it an error to start a TLS handshake more than once per
1391AnyEvent::Handle object (this is due to bugs in OpenSSL). 1538AnyEvent::Handle object (this is due to bugs in OpenSSL).
1392 1539
1393=cut 1540=cut
1394 1541
1542our %TLS_CACHE; #TODO not yet documented, should we?
1543
1395sub starttls { 1544sub starttls {
1396 my ($self, $ssl, $ctx) = @_; 1545 my ($self, $ssl, $ctx) = @_;
1397 1546
1398 require Net::SSLeay; 1547 require Net::SSLeay;
1399 1548
1400 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object" 1549 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1401 if $self->{tls}; 1550 if $self->{tls};
1551
1552 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1553 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1554
1555 $ctx ||= $self->{tls_ctx};
1556
1557 if ("HASH" eq ref $ctx) {
1558 require AnyEvent::TLS;
1559
1560 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
1561
1562 if ($ctx->{cache}) {
1563 my $key = $ctx+0;
1564 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1565 } else {
1566 $ctx = new AnyEvent::TLS %$ctx;
1567 }
1568 }
1402 1569
1403 if ($ssl eq "accept") { 1570 $self->{tls_ctx} = $ctx || TLS_CTX ();
1404 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1571 $self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
1405 Net::SSLeay::set_accept_state ($ssl);
1406 } elsif ($ssl eq "connect") {
1407 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1408 Net::SSLeay::set_connect_state ($ssl);
1409 }
1410
1411 $self->{tls} = $ssl;
1412 1572
1413 # basically, this is deep magic (because SSL_read should have the same issues) 1573 # basically, this is deep magic (because SSL_read should have the same issues)
1414 # but the openssl maintainers basically said: "trust us, it just works". 1574 # but the openssl maintainers basically said: "trust us, it just works".
1415 # (unfortunately, we have to hardcode constants because the abysmally misdesigned 1575 # (unfortunately, we have to hardcode constants because the abysmally misdesigned
1416 # and mismaintained ssleay-module doesn't even offer them). 1576 # and mismaintained ssleay-module doesn't even offer them).
1420 # 1580 #
1421 # note that we do not try to keep the length constant between writes as we are required to do. 1581 # note that we do not try to keep the length constant between writes as we are required to do.
1422 # we assume that most (but not all) of this insanity only applies to non-blocking cases, 1582 # we assume that most (but not all) of this insanity only applies to non-blocking cases,
1423 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to 1583 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1424 # have identity issues in that area. 1584 # have identity issues in that area.
1425 Net::SSLeay::CTX_set_mode ($self->{tls}, 1585# Net::SSLeay::CTX_set_mode ($ssl,
1426 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1586# (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1427 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1587# | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1588 Net::SSLeay::CTX_set_mode ($ssl, 1|2);
1428 1589
1429 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1590 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1430 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1591 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1431 1592
1432 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1593 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1594
1595 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1596 if $self->{on_starttls};
1433 1597
1434 &_dotls; # need to trigger the initial handshake 1598 &_dotls; # need to trigger the initial handshake
1435 $self->start_read; # make sure we actually do read 1599 $self->start_read; # make sure we actually do read
1436} 1600}
1437 1601
1450 if ($self->{tls}) { 1614 if ($self->{tls}) {
1451 Net::SSLeay::shutdown ($self->{tls}); 1615 Net::SSLeay::shutdown ($self->{tls});
1452 1616
1453 &_dotls; 1617 &_dotls;
1454 1618
1455 # we don't give a shit. no, we do, but we can't. no... 1619# # we don't give a shit. no, we do, but we can't. no...#d#
1456 # we, we... have to use openssl :/ 1620# # we, we... have to use openssl :/#d#
1457 &_freetls; 1621# &_freetls;#d#
1458 } 1622 }
1459} 1623}
1460 1624
1461sub _freetls { 1625sub _freetls {
1462 my ($self) = @_; 1626 my ($self) = @_;
1463 1627
1464 return unless $self->{tls}; 1628 return unless $self->{tls};
1465 1629
1466 Net::SSLeay::free (delete $self->{tls}); 1630 $self->{tls_ctx}->_put_session (delete $self->{tls});
1467 1631
1468 delete @$self{qw(_rbio _wbio _tls_wbuf)}; 1632 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1469} 1633}
1470 1634
1471sub DESTROY { 1635sub DESTROY {
1472 my ($self) = @_; 1636 my ($self) = @_;
1473 1637
1497} 1661}
1498 1662
1499=item $handle->destroy 1663=item $handle->destroy
1500 1664
1501Shuts down the handle object as much as possible - this call ensures that 1665Shuts down the handle object as much as possible - this call ensures that
1502no further callbacks will be invoked and resources will be freed as much 1666no further callbacks will be invoked and as many resources as possible
1503as possible. You must not call any methods on the object afterwards. 1667will be freed. You must not call any methods on the object afterwards.
1504 1668
1505Normally, you can just "forget" any references to an AnyEvent::Handle 1669Normally, you can just "forget" any references to an AnyEvent::Handle
1506object and it will simply shut down. This works in fatal error and EOF 1670object and it will simply shut down. This works in fatal error and EOF
1507callbacks, as well as code outside. It does I<NOT> work in a read or write 1671callbacks, as well as code outside. It does I<NOT> work in a read or write
1508callback, so when you want to destroy the AnyEvent::Handle object from 1672callback, so when you want to destroy the AnyEvent::Handle object from
1521 %$self = (); 1685 %$self = ();
1522} 1686}
1523 1687
1524=item AnyEvent::Handle::TLS_CTX 1688=item AnyEvent::Handle::TLS_CTX
1525 1689
1526This function creates and returns the Net::SSLeay::CTX object used by 1690This function creates and returns the AnyEvent::TLS object used by default
1527default for TLS mode. 1691for TLS mode.
1528 1692
1529The context is created like this: 1693The context is created by calling L<AnyEvent::TLS> without any arguments.
1530
1531 Net::SSLeay::load_error_strings;
1532 Net::SSLeay::SSLeay_add_ssl_algorithms;
1533 Net::SSLeay::randomize;
1534
1535 my $CTX = Net::SSLeay::CTX_new;
1536
1537 Net::SSLeay::CTX_set_options $CTX, Net::SSLeay::OP_ALL
1538 1694
1539=cut 1695=cut
1540 1696
1541our $TLS_CTX; 1697our $TLS_CTX;
1542 1698
1543sub TLS_CTX() { 1699sub TLS_CTX() {
1544 $TLS_CTX || do { 1700 $TLS_CTX ||= do {
1545 require Net::SSLeay; 1701 require AnyEvent::TLS;
1546 1702
1547 Net::SSLeay::load_error_strings (); 1703 new AnyEvent::TLS
1548 Net::SSLeay::SSLeay_add_ssl_algorithms ();
1549 Net::SSLeay::randomize ();
1550
1551 $TLS_CTX = Net::SSLeay::CTX_new ();
1552
1553 Net::SSLeay::CTX_set_options ($TLS_CTX, Net::SSLeay::OP_ALL ());
1554
1555 $TLS_CTX
1556 } 1704 }
1557} 1705}
1558 1706
1559=back 1707=back
1560 1708
1625 $handle->on_drain (sub { 1773 $handle->on_drain (sub {
1626 warn "all data submitted to the kernel\n"; 1774 warn "all data submitted to the kernel\n";
1627 undef $handle; 1775 undef $handle;
1628 }); 1776 });
1629 1777
1778If you just want to queue some data and then signal EOF to the other side,
1779consider using C<< ->push_shutdown >> instead.
1780
1781=item I want to contact a TLS/SSL server, I don't care about security.
1782
1783If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
1784simply connect to it and then create the AnyEvent::Handle with the C<tls>
1785parameter:
1786
1787 tcp_connect $host, $port, sub {
1788 my ($fh) = @_;
1789
1790 my $handle = new AnyEvent::Handle
1791 fh => $fh,
1792 tls => "connect",
1793 on_error => sub { ... };
1794
1795 $handle->push_write (...);
1796 };
1797
1798=item I want to contact a TLS/SSL server, I do care about security.
1799
1800Then you should additionally enable certificate verification, including
1801peername verification, if the protocol you use supports it (see
1802L<AnyEvent::TLS>, C<verify_peername>).
1803
1804E.g. for HTTPS:
1805
1806 tcp_connect $host, $port, sub {
1807 my ($fh) = @_;
1808
1809 my $handle = new AnyEvent::Handle
1810 fh => $fh,
1811 peername => $host,
1812 tls => "connect",
1813 tls_ctx => { verify => 1, verify_peername => "https" },
1814 ...
1815
1816Note that you must specify the hostname you connected to (or whatever
1817"peername" the protocol needs) as the C<peername> argument, otherwise no
1818peername verification will be done.
1819
1820The above will use the system-dependent default set of trusted CA
1821certificates. If you want to check against a specific CA, add the
1822C<ca_file> (or C<ca_cert>) arguments to C<tls_ctx>:
1823
1824 tls_ctx => {
1825 verify => 1,
1826 verify_peername => "https",
1827 ca_file => "my-ca-cert.pem",
1828 },
1829
1830=item I want to create a TLS/SSL server, how do I do that?
1831
1832Well, you first need to get a server certificate and key. You have
1833three options: a) ask a CA (buy one, use cacert.org etc.) b) create a
1834self-signed certificate (cheap. check the search engine of your choice,
1835there are many tutorials on the net) or c) make your own CA (tinyca2 is a
1836nice program for that purpose).
1837
1838Then create a file with your private key (in PEM format, see
1839L<AnyEvent::TLS>), followed by the certificate (also in PEM format). The
1840file should then look like this:
1841
1842 -----BEGIN RSA PRIVATE KEY-----
1843 ...header data
1844 ... lots of base64'y-stuff
1845 -----END RSA PRIVATE KEY-----
1846
1847 -----BEGIN CERTIFICATE-----
1848 ... lots of base64'y-stuff
1849 -----END CERTIFICATE-----
1850
1851The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts. Then
1852specify this file as C<cert_file>:
1853
1854 tcp_server undef, $port, sub {
1855 my ($fh) = @_;
1856
1857 my $handle = new AnyEvent::Handle
1858 fh => $fh,
1859 tls => "accept",
1860 tls_ctx => { cert_file => "my-server-keycert.pem" },
1861 ...
1862
1863When you have intermediate CA certificates that your clients might not
1864know about, just append them to the C<cert_file>.
1865
1630=back 1866=back
1631 1867
1632 1868
1633=head1 SUBCLASSING AnyEvent::Handle 1869=head1 SUBCLASSING AnyEvent::Handle
1634 1870

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines