-
-
23 May 2022 09:14:24 UTC
- Distribution: IO-Async-SSL
- Module version: 0.23
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (6)
- Testers (283 / 49 / 0)
- Kwalitee
Bus factor: 1- % Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (29KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Future
- IO::Async::Handle
- IO::Async::Loop
- IO::Async::Protocol::Stream
- IO::Async::Stream
- IO::Socket::SSL
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
IO::Async::SSL
- use SSL/TLS with IO::AsyncSYNOPSIS
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
andSSL_listen
, which yieldIO::Socket::SSL
-upgraded socket handles or IO::Async::Stream instances, and two forms ofSSL_upgrade
to upgrade an existing TCP connection to use SSL.As an additional convenience, if the
SSL_verify_mode
andSSL_ca_*
options are omitted, the module will attempt to provide them by quering the result of IO::Socket::SSL'sdefault_ca
function. Otherwise, the module will print a warning and setSSL_VERIFY_NONE
instead.LOOP METHODS
The following extra methods are added to IO::Async::Loop.
SSL_upgrade
( $stream or $socket ) = $loop->SSL_upgrade( %params )->get;
This method upgrades a given stream filehandle into an SSL-wrapped stream, returning a future which will yield the given stream object or socket.
Takes the following parameters:
- handle => IO::Async::Stream | IO
-
The
IO::Async::Stream
object containing the IO handle of an already-established connection to act as the transport for SSL; or the plain IO socket handle itself.If an
IO::Async::Stream
is passed it will have thereader
andwriter
functions set on it suitable for SSL use, and will be returned as the result from the future.If a plain socket handle is passed, that will be returned from the future instead.
- 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 theIO::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 will have appropriate SSL-compatible reader/writer functions attached.$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_connect
$stream = $loop->SSL_connect( %params )->get;
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 startsSSL_
will be passed on to the IO::Socket::SSL constructor rather than the Loop'sconnect
method. It is not required to pass thesocktype
option, as SSL implies this will bestream
.This method can also upgrade an existing
IO::Async::Stream
or subclass instance given as thehandle
argument, by setting thereader
andwriter
functions.SSL_connect (void)
$loop->SSL_connect( %params, on_connected => sub { ... }, on_stream => sub { ... }, );
When not returning a future, this method also supports the
on_connected
andon_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 aIO::Socket::SSL
, which must be wrapped inIO::Async::SSLStream
to be used byIO::Async
. Theon_stream
continuation will already yield such an instance.SSL_listen
$loop->SSL_listen( %params )->get;
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
oron_stream
continuation;on_socket
is not supported.It takes all the same arguments as
IO::Async::Loop::listen()
. Any argument whose name startsSSL_
will be passed on to the IO::Socket::SSL constructor rather than the Loop'slisten
method. It is not required to pass thesocktype
option, as SSL implies this will bestream
.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 aIO::Socket::SSL
, which must be wrapped inIO::Async::SSLStream
to be used byIO::Async
. Theon_stream
continuation will already yield such an instance.STREAM PROTOCOL METHODS
The following extra methods are added to IO::Async::Protocol::Stream.
SSL_upgrade
$protocol->SSL_upgrade( %params )->get;
A shortcut to calling
$loop->SSL_upgrade
. This method will unconfigure thetransport
of the Protocol, upgrade its underlying filehandle to SSL, then reconfigure it again with SSL reader and writer functions on it. It takes the same arguments as$loop->SSL_upgrade
, except that thehandle
argument is not required as it's taken from the Protocol'stransport
.AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
Module Install Instructions
To install IO::Async::SSL, copy and paste the appropriate command in to your terminal.
cpanm IO::Async::SSL
perl -MCPAN -e shell install IO::Async::SSL
For more information on module installation, please visit the detailed CPAN module installation guide.