/ 
Linux-Event-0.115
/ Linux::Event::TLS

NAME

Linux::Event::TLS - OpenSSL transport for Linux::Event stream sockets

DESCRIPTION

TLS is transport policy for Linux::Event::IO::Sock::Stream. It does not change framing, buffering, backpressure, or callback semantics.

For servers, normal application code configures TLS in the Listener's generated Stream recipe and does not need to use Linux::Event::TLS directly:

my $listener = Linux::Event::IO::Sock::Listener->new(
    loop => $loop,
    host => '0.0.0.0',
    port => 443,
    stream => {
        tls => {
            cert_file => '/etc/app/server.crt',
            key_file  => '/etc/app/server.key',
            alpn      => ['h2', 'http/1.1'],
        },
        on_data => sub ($stream, $bytes) { ... },
    },
);

The Listener validates the TLS recipe and builds one reusable OpenSSL SSL_CTX. Every accepted connection creates only fresh per-connection SSL state and binds it to the accepted file descriptor. The shared context uses OpenSSL reference counting, so established TLS Streams remain valid even if the Listener closes.

A Stream subclass may provide ordinary tls_defaults() policy without becoming a special TLS class:

package SecureConnection;
use parent 'Linux::Event::IO::Sock::Stream';

sub tls_defaults ($class) {
    return (
        alpn              => ['echo/1'],
        handshake_timeout => 10,
        shutdown_timeout  => 5,
    );
}

sub on_data ($self, $bytes) { ... }

Listener stream => { tls => {...} } values override those defaults. tls_defaults() does not activate TLS by itself: an accepted connection is TLS only when its Listener recipe contains a tls key. Certificate and key paths are normally deployment values in that Listener recipe. A Listener without a tls recipe generates plain Streams and allocates no TLS state even when the Stream class defines tls_defaults().

SERVER TLS OPTIONS

Listener server TLS accepts cert_file, key_file, alpn, handshake_timeout, and shutdown_timeout. The certificate and key are required together. Handshake and shutdown timeouts default to 10 and 5 seconds; zero disables the corresponding timeout.

on_ready runs only after the handshake succeeds. Application data callbacks receive plaintext. selected_alpn, tls_protocol, tls_cipher, and tls_stats on the Stream report the established transport.

CLIENT AND DIRECT TRANSPORT API

Linux::Event::TLS->client(...) and Linux::Event::TLS->server(...) remain available when an application wants to construct a transport object directly. Existing subclass declarations with use Linux::Event::TLS ... also remain supported for explicit class-level acquisition policy, including outbound client verification.

Client verification is enabled by default. server_name is required by the direct client constructor; ca_file and ca_path optionally override trust roots. alpn, handshake_timeout, and shutdown_timeout work in both roles.

TRANSPORT MODEL

OpenSSL owns handshake state, cryptography, verification, ALPN, retry direction, and TLS close notification. Linux::Event's ordered-byte engine owns readiness, plaintext buffering, framing, backpressure, protocol transitions, and established Stream deadlines.

TLS uses the native transport ABI directly. It does not install a per-I/O Perl callback layer.