IO::Async::SSL(3pm)

💖 IO::Async::SSL — use SSL/TLS with IO::Async 💖

okay bestie, this is IO::Async::SSL, a 3pm User Contributed Perl Documentation page, and it's literally the glow-up your sockets have been waiting for. no cap.

---

✨ 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"; },
);

look at her go. ✨

---

🌸 DESCRIPTION 🌸

So. This module is the ✨upgrade✨ bestie — it extends the IO::Async classes you already know and love with extra methods, so you can do SSL or TLS-based connections using IO::Socket::SSL. It does not directly provide any methods or functions of its own. It's giving supporting cast, not main character. 🙈

Mainly though, it hands you SSL_connect and SSL_listen, which yield IO::Socket::SSL-upgraded socket handles or IO::Async::Stream instances, plus two forms of SSL_upgrade so you can take an existing TCP connection and glow it up into SSL. 💅

And as an extra lil convenience: if the SSL_verify_mode and SSL_ca_* options are omitted, the module will try to provide them by querying the result of IO::Socket::SSL's default_ca function. Otherwise, the module will print a warning and set SSL_VERIFY_NONE instead. so like, heads up. 👀

---

🦋 LOOP METHODS 🦋

The following extra methods get added to IO::Async::Loop. slay.

---

🎀 SSL_upgrade

( $stream or $socket ) = $loop->SSL_upgrade( %params )->get;

This one upgrades a given stream filehandle into an SSL-wrapped stream, and returns a future that'll yield the given stream object or socket. iconic.

It takes these parameters, bestie:

• handle => IO::Async::Stream | IO — the IO::Async::Stream object holding the IO handle of an already-established connection, which then acts as the transport for SSL; or the plain IO socket handle itself, your call.
  • If you pass an IO::Async::Stream, it'll get its reader and writer functions set on it all properly for SSL use, and it'll be returned as the result from the future. 💖
  • If you pass a plain socket handle, that's what comes back from the future instead.
• SSL_server => BOOL — if true, this says you're on the server side of the connection. 👑

Also, literally any parameter whose name starts with SSL_ gets passed to the IO::Socket::SSL constructor. periodt.

And the following legacy callback arguments are also supported, in case you're not using the returned future:

• on_upgraded => CODE — a continuation that gets invoked when the socket has been successfully upgraded to SSL. It'll 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 gets invoked if IO::Socket::SSL detects an error while negotiating the upgrade. 😭

 $on_error->( $! )

---

🌈 SSL_connect

$stream = $loop->SSL_connect( %params )->get;

This method does a non-blocking connection to a given address or set of addresses, upgrades the socket to SSL, then yields a IO::Async::Stream object once the SSL handshake is complete. it's giving full journey. 🫶

It takes all the same arguments as IO::Async::Loop::connect(). Any argument whose name starts with SSL_ gets passed on to the IO::Socket::SSL constructor rather than the Loop's connect method. And ngl, you don't need to pass the socktype option — 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. 💅

---

⭐ SSL_connect (void)

$loop->SSL_connect( %params,
   on_connected => sub { ... },
   on_stream => sub { ... },
);

When you're 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 gets 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, so she's already dressed for the occasion. ✨

---

💜 SSL_listen

$loop->SSL_listen( %params )->get;

This method sets up a listening socket using the addresses you give it, 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 — heads up, on_socket is not supported. 🙈

It takes all the same arguments as IO::Async::Loop::listen(). Any argument whose name starts with SSL_ gets passed on to the IO::Socket::SSL constructor rather than the Loop's listen method. And again, no need to pass socktype — SSL implies this will be stream. periodt.

In addition, the following arguments are required:

• on_ssl_error => CODE — a continuation that gets invoked if IO::Socket::SSL detects an SSL-based error once the actual stream socket is connected. 😭

Also, the underlying IO::Socket::SSL socket will need the server key and certificate for a server-mode socket. See its documentation for more details, bestie, go read it. 📖

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 get added to IO::Async::Protocol::Stream.

---

🍓 SSL_upgrade

$protocol->SSL_upgrade( %params )->get;

A shortcut to calling $loop->SSL_upgrade. This method will unconfigure the transport of the Protocol, upgrade its underlying filehandle to SSL, then reconfigure it again with SSL reader and writer functions on it. it's giving makeover montage. 💅

It takes the same arguments as $loop->SSL_upgrade, except that the handle argument is not required, because it's taken from the Protocol's transport. convenient, we love her. 🫶

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, bestie! 🎀 this one's from perl v5.36.0, dated 2023-09-29, and it's the IO::Async::SSL(3pm) page — now go forth and negotiate some SSL, you've got this. 💖✨🦋🌸💅