IO::Async::SSL - use SSL/TLS with IO::Async
IO::Async::SSL
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"; }, );
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.
SSL_connect
SSL_listen
IO::Socket::SSL
SSL_upgrade
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.
SSL_verify_mode
SSL_ca_*
SSL_VERIFY_NONE
The following extra methods are added to IO::Async::Loop.
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:
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.
IO::Async::Stream
If an IO::Async::Stream is passed it will have the reader and writer functions set on it suitable for SSL use, and will be returned as the result from the future.
reader
writer
If a plain socket handle is passed, that will be returned from the future instead.
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.
SSL_
The following legacy callback arguments are also supported, in case the returned future is not used:
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 )
A continuation that is invoked if IO::Socket::SSL detects an error while negotiating the upgrade.
$on_error->( $! )
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.
IO::Async::Loop::connect()
connect
socktype
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.
handle
When not returning a future, this method also supports the on_connected and on_stream continuations.
on_connected
on_stream
In addition, the following arguments are then required:
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.
IO::Async::SSLStream
IO::Async
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.
on_accept
on_socket
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.
IO::Async::Loop::listen()
listen
In addition, the following arguments are rquired:
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.
The following extra methods are added to IO::Async::Protocol::Stream.
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.
$loop->SSL_upgrade
transport
Paul Evans <leonerd@leonerd.org.uk>
To install IO::Async::SSL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Async::SSL
CPAN shell
perl -MCPAN -e shell install IO::Async::SSL
For more information on module installation, please visit the detailed CPAN module installation guide.