NAME
Linux::Event::TLS - declare OpenSSL TLS policy for stream-socket subclasses
SYNOPSIS
package SecureServerConnection;
use parent 'Linux::Event::IO::Sock::Stream';
use Linux::Event::TLS
cert_file => '/etc/linux-event/server-cert.pem',
key_file => '/etc/linux-event/server-key.pem',
alpn => ['echo/1'],
handshake_timeout => 10,
shutdown_timeout => 5;
sub on_data ($self, $bytes) {
$self->write($bytes);
}
package SecureClientConnection;
use parent 'Linux::Event::IO::Sock::Stream';
use Linux::Event::TLS
ca_file => '/etc/ssl/certs/ca-certificates.crt',
verify => 1,
alpn => ['echo/1'],
handshake_timeout => 10,
shutdown_timeout => 5;
sub on_data ($self, $bytes) {
say $bytes;
}DESCRIPTION
use Linux::Event::TLS marks the calling Linux::Event::IO::Sock::Stream subclass as a TLS connection type. TLS is transport policy on a connected SOCK_STREAM; it is not a second public socket hierarchy and it is not a framer.
The acquisition path determines the TLS role. An outbound SecureClientConnection->connect(...) uses client semantics. A Linux::Event::IO::Sock::Listener that names SecureServerConnection as its stream_class creates a fresh server-side TLS transport for every accepted connection.
The declaration is resolved once with the concrete subclass descriptor. It installs no per-I/O Perl callback layer. Buffering, framing, backpressure, protocol transitions, and established deadlines continue to use the ordinary ordered-byte engine around plaintext application data.
The declaration must follow use parent 'Linux::Event::IO::Sock::Stream' or another subclass that already inherits that public leaf.
ROLE SELECTION
Outbound connections
my $connection = SecureClientConnection->connect(
loop => $loop,
host => 'example.com',
port => 443,
timeout => 10,
);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 trust-source selection.
verify => 0 disables peer verification and should be used only when an application intentionally accepts that security model.
Accepted connections
my $listener = Linux::Event::IO::Sock::Listener->new(
loop => $loop,
stream_class => 'SecureServerConnection',
host => '0.0.0.0',
port => 8443,
);An accepted TLS stream-socket class requires cert_file and key_file in its declaration. The listener validates server identity before accepting traffic and each accepted connection receives independent OpenSSL state.
Adopted connected handles
When an application supplies an already connected SOCK_STREAM handle, the TLS acquisition role is ambiguous. A TLS-declared adopted handle therefore requires tls_role:
my $connection = SecureServerConnection->new(
loop => $loop,
fh => $socket,
tls_role => 'server',
);tls_role accepts client or server. A client-role adopted handle also needs a declared server_name because there is no outbound connect host from which to derive one.
DECLARATION OPTIONS
cert_file and key_file form the 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.
One stream-socket subclass may contain both client and server settings when the same application protocol is acquired in both roles. Only the settings relevant to the selected role are used for a particular connection.
READINESS AND DATA
The ordered-byte engine owns descriptor readiness, buffering, framing, backpressure, and established deadlines. OpenSSL owns handshake state, cryptography, certificate verification, ALPN, retry direction, and TLS close notification.
on_data, on_message, and on_messages receive plaintext. on_ready runs only after the handshake and required verification complete.
$connection->end drains accepted plaintext output and performs TLS shutdown. $connection->close is immediate. A TLS connection cannot be detached because its descriptor is coupled to live encrypted transport state.
A clean peer close_notify becomes the ordinary readable EOF lifecycle. Underlying socket EOF without required TLS close semantics is reported as a typed TLS read failure. TLS writes use Linux MSG_NOSIGNAL and do not modify the process-wide SIGPIPE disposition.
TLS INFORMATION
$connection->selected_alpn, $connection->tls_protocol, $connection->tls_cipher, and $connection->tls_stats expose negotiated state and native counters without exposing the private provider object.
PERFORMANCE
TLS is integrated through the private native byte-transport boundary. The ordinary plain socket path retains its specialized direct syscall behavior; adding TLS support to the distribution does not add a Perl dispatch layer to plain stream-socket I/O.
Framing remains above the transport and therefore sees plaintext. Protocol transition_to changes framing/callback policy without recreating the socket or TLS provider.
REQUIREMENTS
Linux and OpenSSL 1.1.1 or newer, including development headers at build time.