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.

    As an additional convenience, if the `SSL_verify_mode' and `SSL_ca_*'
    options are omitted, the module will attempt to provide them. If the
    /etc/ssl/certs directory exists, it will be used. Failing that, if
    Mozilla::CA can be loaded, that will be used. Otherwise, the module will
    print a warning and set `SSL_VERIFY_NONE' instead.

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

  $loop->SSL_upgrade( %params ) ==> $sslsocket
    This method upgrades a given stream filehandle into an SSL-wrapped
    stream, returning a future which will yield an upgraded
    `IO::Socket::SSL'.

    Takes the following parameters:

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

    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.

    The following legacy callback arguments are also supported, in case the
    returned future is not used:

    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->( $! )

  $loop->SSL_connect( %params ) ==> $stream
    This method performs a non-blocking connection to a given address or set
    of addresses, upgrades the socket to SSL, then yields a
    `IO::Async::Stream' object when the SSL handshake is complete.

    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'.

    This method can also upgrade an existing `IO::Async::Stream' or subclass
    instance given as the `handle' argument, by setting the `reader' and
    `writer' functions.

  $loop->SSL_connect( %params )
    When not returning a future, this method also supports the
    `on_connected' and `on_stream' continuations.

    In addition, the following arguments are then 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_accept' 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_accept' 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>