/ 
Linux-Event-0.105
/ Linux::Event::TLS

NAME

Linux::Event::TLS - declare OpenSSL TLS policy for a Stream subclass

SYNOPSIS

package SecureServerStream;
use parent 'Linux::Event::Stream';
use Linux::Event::TLS
    cert_file         => '/etc/linux-event/server-cert.pem', # required inbound
    key_file          => '/etc/linux-event/server-key.pem',  # required inbound
    alpn              => ['echo/1'],                         # optional
    handshake_timeout => 10,                                 # default
    shutdown_timeout  => 5;                                  # default

sub on_data ($stream, $bytes) {
    $stream->write($bytes);
}

package SecureClientStream;
use parent 'Linux::Event::Stream';
use Linux::Event::TLS
    ca_file           => '/etc/ssl/certs/ca-certificates.crt', # optional
    verify            => 1,                                   # default
    alpn              => ['echo/1'],                          # optional
    handshake_timeout => 10,                                  # default
    shutdown_timeout  => 5;                                   # default

sub on_data ($stream, $bytes) {
    say $bytes;
}

DESCRIPTION

use Linux::Event::TLS marks the calling Linux::Event::Stream subclass as a TLS connection type. The acquisition path selects the handshake role: SecureClientStream->connect(host => 'example.com', port => 443) uses client TLS, while a Linux::Event::Listener that names SecureServerStream as its stream_class uses server TLS for every accepted connection.

There is no TLS Stream base class and no public client object. TLS remains an internal byte transport so protocol inheritance, framing, and transition_to remain independent of encryption. The declaration is validated once and stored with the subclass's cached descriptor. Every Stream instance receives fresh native OpenSSL connection state automatically.

The declaration must follow use parent 'Linux::Event::Stream'. It installs no methods and adds no per-I/O Perl dispatch.

ROLE SELECTION

Outbound connections

my $stream = SecureClientStream->connect(
    loop    => $loop,          # optional: start immediately
    host    => 'example.com',  # required for TCP
    port    => 443,            # required for TCP
    timeout => 10,             # default
);

Client certificate-chain and hostname verification are enabled by default. server_name defaults to the host passed to connect. Declare an explicit server_name only when verification must use a different identity. ca_file and ca_path optionally override OpenSSL's trust-source selection. verify => 0 disables verification and is intended only for explicitly controlled test or private environments.

Accepted connections

my $listener = Linux::Event::Listener->new(
    loop         => $loop,                 # optional: start immediately
    stream_class => 'SecureServerStream',  # required
    host         => '0.0.0.0',             # required for TCP
    port         => 8443,                  # required for TCP
);

An accepted TLS Stream requires cert_file and key_file in its class declaration. Listener preflights that server identity during construction and creates fresh server-side connection state for every accepted socket.

Adopted connected handles

The acquisition role is ambiguous when an application supplies an already connected fh. This advanced form therefore requires tls_role:

my $stream = SecureServerStream->new(
    loop     => $loop,    # optional
    fh       => $socket,  # required
    tls_role => 'server', # required for a TLS-declared adopted handle
);

tls_role accepts client or server. A client-role adopted handle also needs a declared server_name, because there is no connect host from which to derive it.

DECLARATION OPTIONS

cert_file and key_file form the required server credential pair. server_name, verify, ca_file, and ca_path configure client verification. alpn is an optional array reference used in either role. handshake_timeout and shutdown_timeout are non-negative seconds, default to 10 and 5, and are disabled by zero.

A declaration may contain both client and server settings when one Stream subclass is acquired in both roles. Role-specific values are selected only when that role is instantiated.

READINESS AND DATA

Stream continues to own buffering, framing, backpressure, established deadlines, and descriptor readiness. OpenSSL owns TLS protocol state, cryptography, verification, ALPN, and close notification. on_data and on_message receive plaintext, as does each message passed to on_messages. on_ready runs only after handshake and verification succeed.

$stream->end drains plaintext output and sends close_notify. $stream->close is immediate. A TLS Stream cannot be detached because its descriptor contains encrypted provider state. Clean peer close_notify uses ordinary Stream EOF handling; socket EOF without it is a typed tls read error. TLS socket writes use Linux MSG_NOSIGNAL and do not modify the process-wide SIGPIPE disposition.

STREAM TLS INFORMATION

$stream->selected_alpn, $stream->tls_protocol, $stream->tls_cipher, and $stream->tls_stats expose negotiated state and native counters without revealing the internal provider object.

REQUIREMENTS

Linux and OpenSSL 1.1.1 or newer, including development headers at build time.