add documentation for Mojo::IOLoop::TLS

mojolicious · Jan 13, 2017 · 6a9a9fc · 6a9a9fc
1 parent 7b789aa
commit 6a9a9fc
Show file tree

Hide file tree

Showing 3 changed files with 154 additions and 3 deletions.
diff --git a/lib/Mojo/IOLoop/Client.pm b/lib/Mojo/IOLoop/Client.pm
@@ -153,7 +153,7 @@ sub _try_tls {
   # Start TLS handshake
   weaken $self;
   my $tls = Mojo::IOLoop::TLS->new(reactor => $reactor);
-  $tls->on(finish => sub { $self->_cleanup->emit(connect => pop) });
+  $tls->on(upgrade => sub { $self->_cleanup->emit(connect => pop) });
   $tls->on(error => sub { $self->emit(error => pop) });
   $tls->negotiate(%$args, handle => $handle);
 }

diff --git a/lib/Mojo/IOLoop/Server.pm b/lib/Mojo/IOLoop/Server.pm
@@ -96,7 +96,7 @@ sub _accept {
 
     # Start TLS handshake
     my $tls = Mojo::IOLoop::TLS->new(reactor => $self->reactor);
-    $tls->on(finish => sub { $self->emit(accept => pop) });
+    $tls->on(upgrade => sub { $self->emit(accept => pop) });
     $tls->on(error => sub { });
     $tls->negotiate(%$args, handle => $handle, server => 1);
   }

diff --git a/lib/Mojo/IOLoop/TLS.pm b/lib/Mojo/IOLoop/TLS.pm
@@ -69,7 +69,7 @@ sub negotiate {
 sub _tls {
   my ($self, $handle, $server) = @_;
 
-  return $self->emit(finish => delete $self->{handle})
+  return $self->emit(upgrade => delete $self->{handle})
     if $server ? $handle->accept_SSL : $handle->connect_SSL;
 
   # Switch between reading and writing
@@ -79,3 +79,154 @@ sub _tls {
 }
 
 1;
+
+=encoding utf8
+
+=head1 NAME
+
+Mojo::IOLoop::TLS - Non-blocking TLS handshake
+
+=head1 SYNOPSIS
+
+  use Mojo::IOLoop::TLS;
+
+  # Negotiate TLS
+  my $tls = Mojo::IOLoop::TLS->new;
+  $tls->on(upgrade => sub {
+    my ($tls, $new_handle) = @_;
+    ...
+  });
+  $tls->on(error => sub {
+    my ($tls, $err) = @_;
+    ...
+  });
+  $tls->negotiate(handle => $old_handle, server => 1);
+
+  # Start reactor if necessary
+  $tls->reactor->start unless $tls->reactor->is_running;
+
+=head1 DESCRIPTION
+
+L<Mojo::IOLoop::TLS> negotiates TLS for L<Mojo::IOLoop>.
+
+=head1 EVENTS
+
+L<Mojo::IOLoop::TLS> inherits all events from L<Mojo::EventEmitter> and can
+emit the following new ones.
+
+=head2 upgrade
+
+  $tls->on(connect => sub {
+    my ($tls, $handle) = @_;
+    ...
+  });
+
+Emitted once TLS has been negotiated.
+
+=head2 error
+
+  $tls->on(error => sub {
+    my ($tls, $err) = @_;
+    ...
+  });
+
+Emitted if an error occurs during negotiation, fatal if unhandled.
+
+=head1 ATTRIBUTES
+
+L<Mojo::IOLoop::TLS> implements the following attributes.
+
+=head2 reactor
+
+  my $reactor = $tls->reactor;
+  $tls        = $tls->reactor(Mojo::Reactor::Poll->new);
+
+Low-level event reactor, defaults to the C<reactor> attribute value of the
+global L<Mojo::IOLoop> singleton.
+
+=head1 METHODS
+
+L<Mojo::IOLoop::TLS> inherits all methods from L<Mojo::EventEmitter> and
+implements the following new ones.
+
+=head2 negotiate
+
+  $tls->negotiate(handle => $handle, server => 1);
+  $tls->negotiate({handle => $handle, server => 1});
+
+Negotiate TLS.
+
+These options are currently available:
+
+=over 2
+
+=item handle
+
+  handle => $handle
+
+L<IO::Socket::IP> object to negotiate TLS with.
+
+=item server
+
+  server => 1
+
+Negotiate TLS from the server-side, defaults to the client-side.
+
+=item tls_ca
+
+  tls_ca => '/etc/tls/ca.crt'
+
+Path to TLS certificate authority file. Also activates hostname verification on
+the client-side.
+
+=item tls_cert
+
+  tls_cert => '/etc/tls/server.crt'
+  tls_cert => {'mojolicious.org' => '/etc/tls/mojo.crt'}
+
+Path to the TLS cert file, defaults to a built-in test certificate on the
+server-side.
+
+=item tls_ciphers
+
+  tls_ciphers => 'AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL:!EDH'
+
+TLS cipher specification string. For more information about the format see
+L<https://www.openssl.org/docs/manmaster/apps/ciphers.html#CIPHER-STRINGS>.
+
+=item tls_key
+
+  tls_key => '/etc/tls/server.key'
+  tls_key => {'mojolicious.org' => '/etc/tls/mojo.key'}
+
+Path to the TLS key file, defaults to a built-in test key on the server-side.
+
+=item tls_verify
+
+  tls_verify => 0x00
+
+TLS verification mode, defaults to C<0x03> on the server-side and C<0x01> on the
+client-side if a certificate authority file has been provided, or C<0x00>.
+
+=item tls_version
+
+  tls_version => 'TLSv1_2'
+
+TLS protocol version.
+
+=back
+
+=head1 CONSTANTS
+
+L<Mojo::IOLoop::TLS> implements the following constants, which can be
+imported individually.
+
+=head2 HAS_TLS
+
+TLS is supported with L<IO::Socket::SSL>.
+
+=head1 SEE ALSO
+
+L<Mojolicious>, L<Mojolicious::Guides>, L<http://mojolicious.org>.
+
+=cut