NAME
    "IO::Async::SSL" - Use SSL/TLS with IO::Async

SYNOPSIS
     use IO::Async::Loop;
     use IO::Async::SSL;
     use IO::Async::SLStream;

     my $loop = IO::Async::Loop->new();

     $loop->SSL_connect(
        host     => "www.example.com",
        service  => "https",

        on_connected => sub {
           my ( $sock ) = @_;

           my $stream = IO::Async::SSLStream->new(
              handle => $sock,
              on_read => sub {
                 ...
              },
           );

           $loop->add( $stream );
       
           ...
        },

        on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
        on_connect_error => sub { print STDERR "Cannot connect\n"; },
        on_ssl_error     => sub { print STDERR "Cannot negotiate SSL - $_[-1]\n"; },
     );

DESCRIPTION
    This module extends IO::Async::Loop to allow the use of SSL or TLS-based
    connections using IO::Socket::SSL. It provides two extension methods on
    the "IO::Async::Loop" class, which extend "connect" and "listen", to
    yield "IO::Socket::SSL"-upgraded socket handles. These socket handles
    must then be wrapped in instances of IO::Async::SSLStream.

METHODS
  $loop->SSL_connect( %params )
    This method performs a non-blocking connection to a given address or set
    of addresses, upgrades the socket to SSL, then invokes the
    "on_connected" continuation when the SSL-wrapped socket is ready for use
    by the application.

    It takes all the same arguments as "IO::Async::Loop::connect()". Any
    argument whose name starts "SSL_" will be passed on to the
    IO::Socket::SSL constructor rather than the Loop's "connect" method. It
    is not required to pass the "socktype" option, as SSL implies this will
    be "stream".

    In addition, the following arguments are required:

    on_ssl_error => CODE
            A continuation that is invoked if "IO::Socket::SSL" detects an
            SSL-based error once the actual stream socket is connected.

  $loop->SSL_listen( %params )
    This method sets up a listening socket using the addresses given, and
    will invoke the "on_accept" callback each time a new connection is
    accepted on the socket and the initial SSL negotiation has been
    completed.

    It takes all the same arguments as "IO::Async::Loop::listen()". Any
    argument whose name starts "SSL_" will be passed on to the
    IO::Socket::SSL constructor rather than the Loop's "listen" method. It
    is not required to pass the "socktype" option, as SSL implies this will
    be "stream".

    In addition, the following arguments are rquired:

    on_ssl_error => CODE
            A continuation that is invoked if "IO::Socket::SSL" detects an
            SSL-based error once the actual stream socket is connected.

    The underlying IO::Socket::SSL socket will also require the server key
    and certificate for a server-mode socket. See its documentation for more
    details.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

