---
name: "IO::Async::SSL"
section: "3pm"
platform: "linux"
package: "libio-async-ssl-perl"
version: "0.25-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/IO::Async::SSL"
---

# IO::Async::SSL(3pm)

use SSL/TLS with IO::Async

## 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::Stream 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 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.

## 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 the `"reader"` and `"writer"` 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 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 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 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.

### 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"` 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.

### 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"` 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.

### 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 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\>