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

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

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

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

        on_stream => sub {
           my ( $stream ) = @_;

           $stream->configure(
              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 existing IO::Async classes with extra methods to
    allow the use of SSL or TLS-based connections using IO::Socket::SSL. It
    does not directly provide any methods or functions of its own.

    Primarily, it provides "SSL_connect" and "SSL_listen", which yield
    "IO::Socket::SSL"-upgraded socket handles or IO::Async::SSLStream
    instances, and two forms of "SSL_upgrade" to upgrade an existing TCP
    connection to use SSL.

LOOP METHODS
    The following extra methods are added to IO::Async::Loop.

  $loop->SSL_upgrade( %params )
    This method upgrades a given stream filehandle into an SSL-wrapped
    stream, and will invoke the "on_upgraded" continuation when the handle
    is ready.

    Takes the following parameters:

    handle => IO
            The IO handle of an already-established connection to act as the
            transport for SSL.

    on_upgraded => CODE
            A continuation that is invoked when the socket has been
            successfully upgraded to SSL. It will be passed an instance of
            an "IO::Socket::SSL", which must be wrapped in an instance of
            IO::Async::SSLStream.

             $on_upgraded->( $sslsocket )

    on_error => CODE
            A continuation that is invoked if "IO::Socket::SSL" detects an
            error while negotiating the upgrade.

             $on_error->( $! )

    SSL_server => BOOL
            If true, indicates this is the server side of the connection.

    In addition, any parameter whose name starts "SSL_" will be passed to
    the "IO::Socket::SSL" constructor.

  $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 continuation
    when the SSL handshake is complete. This can be either the
    "on_connected" or "on_stream" continuation; "on_socket" is not
    supported.

    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.

    If the "on_connected" continuation is used, the socket handle it yields
    will be a "IO::Socket::SSL", which must be wrapped in
    "IO::Async::SSLStream" to be used by "IO::Async". The "on_stream"
    continuation will already yield such an instance.

  $loop->SSL_listen( %params )
    This method sets up a listening socket using the addresses given, and
    will invoke the callback each time a new connection is accepted on the
    socket and the SSL handshake has been completed. This can be either the
    "on_accepted" or "on_stream" continuation; "on_socket" is not supported.

    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.

    If the "on_accepted" continuation is used, the socket handle it yields
    will be a "IO::Socket::SSL", which must be wrapped in
    "IO::Async::SSLStream" to be used by "IO::Async". The "on_stream"
    continuation will already yield such an instance.

STREAM PROTOCOL METHODS
    The following extra methods are added to IO::Async::Protocol::Stream.

  $protocol->SSL_upgrade( %params )
    A shortcut to calling "$loop->SSL_upgrade". This method will unconfigure
    the "transport" of the Protocol, upgrade it to SSL, then reconfigure it
    again newly wrapped in a "IO::Async::SSLStream" instance. It takes the
    same arguments as "$loop->SSL_upgrade", except that the "handle"
    argument is not required as it's taken from the Protocol's "transport".

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

