[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Handle.pm

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.142 by root, Mon Jul 6 20:24:47 2009 UTC vs.
Revision 1.146 by root, Wed Jul 8 13:46:46 2009 UTC

 AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
 =cut
-our $VERSION = 4.452;
+our $VERSION = 4.8;
 =head1 SYNOPSIS
    use AnyEvent;
    use AnyEvent::Handle;
 A string used to identify the remote site - usually the DNS hostname
 (I<not> IDN!) used to create the connection, rarely the IP address.
 Apart from being useful in error messages, this string is also used in TLS
-peername verification (see C<verify_peername> in L<AnyEvent::TLS>).
+peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
+verification will be skipped when C<peername> is not specified or
+C<undef>.
 =item tls => "accept" | "connect" | Net::SSLeay::SSL object
 When this parameter is given, it enables TLS (SSL) mode, that means
 AnyEvent will start a TLS handshake as soon as the conenction has been
 Instead of an object, you can also specify a hash reference with C<< key
 => value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
 new TLS context object.
-=item on_starttls => $cb->($handle, $success)
+=item on_starttls => $cb->($handle, $success[, $error_message])
 This callback will be invoked when the TLS/SSL handshake has finished. If
 C<$success> is true, then the TLS handshake succeeded, otherwise it failed
 (C<on_stoptls> will not be called in this case).
 The session in C<< $handle->{tls} >> can still be examined in this
 callback, even when the handshake was not successful.
+TLS handshake failures will not cause C<on_error> to be invoked when this
+callback is in effect, instead, the error message will be passed to C<on_starttls>.
+Without this callback, handshake failures lead to C<on_error> being
+called, as normal.
+Note that you cannot call C<starttls> right again in this callback. If you
+need to do that, start an zero-second timer instead whose callback can
+then call C<< ->starttls >> again.
 =item on_stoptls => $cb->($handle)
 When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
 set, then it will be invoked after freeing the TLS session. If it is not,
    $self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
    $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
       if $self->{tls};
-   $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
+   $self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
    $self->start_read
       if $self->{on_read};
    $self->{fh} && $self
       Scalar::Util::weaken $self;
       my $cb = sub {
          my $len = syswrite $self->{fh}, $self->{wbuf};
-         if ($len >= 0) {
+         if (defined $len) {
             substr $self->{wbuf}, 0, $len, "";
             $self->{_activity} = AnyEvent->now;
             $self->{on_drain}($self)
    my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
    # reduce error string to look less scary
    $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
+   if ($self->{_on_starttls}) {
+      (delete $self->{_on_starttls})->($self, undef, $err);
+      &_freetls;
+   } else {
+      &_freetls;
-   $self->_error (&Errno::EPROTO, 1, $err);
+      $self->_error (&Errno::EPROTO, 1, $err);
+   }
 }
 # poll the write BIO and send the data if applicable
 # also decode read data if possible
 # this is basiclaly our TLS state machine
             && ($tmp != $ERROR_SYSCALL || $!);
    }
    while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
       unless (length $tmp) {
+         $self->{_on_starttls}
+            and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
          &_freetls;
          if ($self->{on_stoptls}) {
             $self->{on_stoptls}($self);
             return;
          } else {
             # let's treat SSL-eof as we treat normal EOF
       $self->_drain_wbuf;
    }
    $self->{_on_starttls}
       and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
-      and (delete $self->{_on_starttls})->($self, 1);
+      and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
 }
 =item $handle->starttls ($tls[, $tls_ctx])
 Instead of starting TLS negotiation immediately when the AnyEvent::Handle
    $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
    Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
    $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
-      if exists $self->{on_starttls};
+      if $self->{on_starttls};
    &_dotls; # need to trigger the initial handshake
    $self->start_read; # make sure we actually do read
 }
 sub _freetls {
    my ($self) = @_;
    return unless $self->{tls};
-   $self->{_on_starttls}
-      and (delete $self->{_on_starttls})->($self, undef);
    $self->{tls_ctx}->_put_session (delete $self->{tls});
-   delete @$self{qw(_rbio _wbio _tls_wbuf)};
+   delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
 }
 sub DESTROY {
    my ($self) = @_;
    $handle->on_drain (sub {
       warn "all data submitted to the kernel\n";
       undef $handle;
    });
+If you just want to queue some data and then signal EOF to the other side,
+consider using C<< ->push_shutdown >> instead.
+=item I want to contact a TLS/SSL server, I don't care about security.
+If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
+simply connect to it and then create the AnyEvent::Handle with the C<tls>
+parameter:
+   tcp_connect $host, $port, sub {
+      my ($fh) = @_;
+      my $handle = new AnyEvent::Handle
+         fh  => $fh,
+         tls => "connect",
+         on_error => sub { ... };
+      $handle->push_write (...);
+   };
+=item I want to contact a TLS/SSL server, I do care about security.
+Then you should additionally enable certificate verification, including
+peername verification, if the protocol you use supports it (see
+L<AnyEvent::TLS>, C<verify_peername>).
+E.g. for HTTPS:
+   tcp_connect $host, $port, sub {
+      my ($fh) = @_;
+       my $handle = new AnyEvent::Handle
+          fh       => $fh,
+          peername => $host,
+          tls      => "connect",
+          tls_ctx  => { verify => 1, verify_peername => "https" },
+          ...
+Note that you must specify the hostname you connected to (or whatever
+"peername" the protocol needs) as the C<peername> argument, otherwise no
+peername verification will be done.
+The above will use the system-dependent default set of trusted CA
+certificates. If you want to check against a specific CA, add the
+C<ca_file> (or C<ca_cert>) arguments to C<tls_ctx>:
+       tls_ctx  => {
+          verify          => 1,
+          verify_peername => "https",
+          ca_file         => "my-ca-cert.pem",
+       },
+=item I want to create a TLS/SSL server, how do I do that?
+Well, you first need to get a server certificate and key. You have
+three options: a) ask a CA (buy one, use cacert.org etc.) b) create a
+self-signed certificate (cheap. check the search engine of your choice,
+there are many tutorials on the net) or c) make your own CA (tinyca2 is a
+nice program for that purpose).
+Then create a file with your private key (in PEM format, see
+L<AnyEvent::TLS>), followed by the certificate (also in PEM format). The
+file should then look like this:
+   -----BEGIN RSA PRIVATE KEY-----
+   ...header data
+   ... lots of base64'y-stuff
+   -----END RSA PRIVATE KEY-----
+   -----BEGIN CERTIFICATE-----
+   ... lots of base64'y-stuff
+   -----END CERTIFICATE-----
+The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts.  Then
+specify this file as C<cert_file>:
+   tcp_server undef, $port, sub {
+      my ($fh) = @_;
+      my $handle = new AnyEvent::Handle
+         fh       => $fh,
+         tls      => "accept",
+         tls_ctx  => { cert_file => "my-server-keycert.pem" },
+         ...
+When you have intermediate CA certificates that your clients might not
+know about, just append them to the C<cert_file>.
 =back
 =head1 SUBCLASSING AnyEvent::Handle

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.142 by root, Mon Jul 6 20:24:47 2009 UTC vs. Revision 1.146 by root, Wed Jul 8 13:46:46 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.142 by root, Mon Jul 6 20:24:47 2009 UTC vs.
Revision 1.146 by root, Wed Jul 8 13:46:46 2009 UTC