POE::Filter::SSL(3pm)

📦

version 0.41 · 6 versions

💖 POE::Filter::SSL(3pm) 💖

okay bestie, this is the manual page for POE::Filter::SSL, from the User Contributed Perl Documentation, and it's lowkey one of the cutest little modules you'll ever meet. let's get into it 🫶

✨ NAME ✨

POE::Filter::SSL — The easiest and flexiblest way to SSL in POE!

periodt. that's the whole name section, she said what she said 💅

🎀 VERSION 🎀

Version 0.41

🌸 DESCRIPTION 🌸

bestie listen. this module lets you secure connections of POE::Wheel::ReadWrite with OpenSSL, and it does it through a POE::Filter object. and aside from the whole SSLing thing? it behaves exactly like POE::Filter::Stream. iconic behaviour honestly.

POE::Filter::SSL can be added, switched and removed during runtime, which is huge — like, if you wanna initiate SSL on an already established connection, you absolutely can (there's a whole example for it in SYNOPSIS, the "SSL on an established connection" one, go look 👀). you can also combine POE::Filter::SSL with other filters, so for example you can have a HTTPS server chilling with POE::Filter::HTTPD (that's the HTTPS-Server example in SYNOPSIS, she's there).

POE::Filter::SSL is based on Net::SSLeay, but it got two XS functions which Net::SSLeay is missing. so it's Net::SSLeay plus a lil extra ✨

🌈 Features

Full non-blocking processing
No use of sockets at all
Server and client mode
Optional client certificate verification
Allows one to accept connections with invalid or missing client certificate and return custom error data
CRL check of client certificates
Retrieve client certificate details (subject name, issuer name, certificate serial)

🦋 Upcoming Features

Direct cipher encryption without SSL or TLS protocol, for example with static AES encryption

⭐ SYNOPSIS ⭐

by default POE::Filter::SSL acts as a SSL server. so to use it in client mode you just have to set the client option of new(). that's it. that's the whole trick.

💜 TCP-Client

#!perl

use warnings;
use strict;

use POE qw(Component::Client::TCP Filter::SSL);

POE::Component::Client::TCP->new(
  RemoteAddress => "yahoo.com",
  RemotePort    => 443,
  Filter        => [ "POE::Filter::SSL", client => 1 ],
  Connected     => sub {
    $_[HEAP]{server}->put("HEAD /\r\n\r\n");
  },
  ServerInput   => sub {
    print "from server: ".$_[ARG0]."\n";
  },
);

POE::Kernel->run();
exit;

💖 TCP-Server

#!perl

use warnings;
use strict;

use POE qw(Component::Server::TCP);

POE::Component::Server::TCP->new(
  Port => 443,
  ClientFilter => [ "POE::Filter::SSL", crt => 'server.crt', key => 'server.key' ],
  ClientConnected => sub {
    print "got a connection from $_[HEAP]{remote_ip}\n";
    $_[HEAP]{client}->put("Smile from the server!\r\n");
  },
  Alias => "tcp",
  ClientInput => sub {
    my ($kernel, $session, $heap) = @_[KERNEL, SESSION, HEAP];
    $_[HEAP]{client}->put("You sent:\r\n".$_[ARG0]);
    $_[KERNEL]->yield("shutdown");
  },
);

POE::Kernel->run;
exit;

🌸 HTTPS-Server

use POE::Filter::SSL::PreFilter
use POE::Filter::SSL;
use POE::Component::Server::HTTP;
use HTTP::Status;
my $aliases = POE::Component::Server::HTTP->new(
  Port => 443,
  ContentHandler => {
    '/' => \&handler,
    '/dir/' => sub { return; },
    '/file' => sub { return; }
  },
  Headers => { Server => 'My Server' },
  PreFilter => POE::Filter::SSL->new(
    crt    => 'server.crt',
    key    => 'server.key',
    cacrt  => 'ca.crt'
  )
);

sub handler {
  my ($request, $response) = @_;
  $response->code(RC_OK);
  $response->content("Hi, you fetched ". $request->uri);
  return RC_OK;
}

POE::Kernel->run();
POE::Kernel->call($aliases->{httpd}, "shutdown");
# next line isn't really needed
POE::Kernel->call($aliases->{tcp}, "shutdown");

🧚 SSL on an established connection

💅 Advanced Example

okay this one is a baddie. this example is an IMAP-Relay which forwards the connections to a IMAP server by username. it allows one the unencrypted transfer on port 143, with the option of SSL on the established connection (STARTTLS). and on port 993 it allows one to do direct SSL.

Tested with Thunderbird version 3.0.5. 👑

#!perl

use warnings;
use strict;

use POE qw(Component::Server::TCP Component::Client::TCP Filter::SSL Filter::Stream);

my $defaultImapServer = "not.existing.de";
my $usernameToImapServer = {
  user1 => 'mailserver1.domain.de',
  user2 => 'mailserver2.domain.de',
  # ...
};

POE::Component::Server::TCP->new(
  Port => 143,
  ClientFilter => "POE::Filter::Stream",
  ClientDisconnected => \&disconnect,
  ClientConnected => \&connected,
  ClientInput => \&handleInput,
  InlineStates => {
    send_stuff => \&send_stuff,
    _child => \&child
  }
);

POE::Component::Server::TCP->new(
  Port => 993,
  ClientFilter => [ "POE::Filter::SSL", crt => 'server.crt', key => 'server.key' ],
  ClientConnected => \&connected,
  ClientDisconnected => \&disconnect,
  ClientInput => \&handleInput,
  InlineStates => {
    send_stuff => \&send_stuff,
    _child => \&child
  }
);

sub disconnect {
  my ($kernel, $session, $heap) = @_[KERNEL, SESSION, HEAP];
  logevent('server got disconnect', $session);
  $kernel->post($heap->{client_id} => "shutdown");
}

sub connected {
  my ($kernel, $session, $heap) = @_[KERNEL, SESSION, HEAP];
  logevent("got a connection from ".$heap->{remote_ip}, $session);
  $heap->{client}->put("* OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION STARTTLS] IMAP Relay v0.1 ready.\r\n");
}

sub send_stuff {
  my ($heap, $stuff, $session) = @_[HEAP, ARG0, SESSION];
  logevent("-> ".length($stuff)." Bytes", $session);
  (defined($heap->{client})) && (ref($heap->{client}) eq "POE::Wheel::ReadWrite") &&
  $heap->{client}->put($stuff);
}

sub child {
  my ($heap, $child_op, $child) = @_[HEAP, ARG0, ARG1];
  if ($child_op eq "create") {
    $heap->{client_id} = $child->ID;
  }
}

sub handleInput {
  my ($kernel, $session, $heap, $input) = @_[KERNEL, SESSION, HEAP, ARG0];
  if($heap->{forwarding}) {
    return $kernel->yield("shutdown") unless (defined($heap->{client_id}));
    $kernel->post($heap->{client_id} => send_stuff => $input);
  } elsif ($input =~ /^(\d+)\s+STARTTLS[\r\n]+/i) {
    $_[HEAP]{client}->put($1." OK Begin SSL/TLS negotiation now.\r\n");
    logevent("SSLing now...", $session);
    $_[HEAP]{client}->set_filter(POE::Filter::SSL->new(crt => 'server.crt', key => 'server.key'));
  } elsif ($input =~ /^(\d+)\s+CAPABILITY[\r\n]+/i) {
    $_[HEAP]{client}->put("* CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION STARTTLS\r\n");
    $_[HEAP]{client}->put($1." OK CAPABILITY completed\r\n");
  } elsif ($input =~ /^(\d+)\s+login\s+\"(\S+)\"\s+\"(\S+)\"[\r\n]+/i) {
    my $username = $2;
    my $pass = $3;
    logevent("login of user ".$username, $session);
    spawn_client_side($username, $input);
    $heap->{forwarding}++;
  } else {
    logevent("unknown command before login, disconnecting.", $session);
    return $kernel->yield("shutdown");
  }
}

sub spawn_client_side {
  my $username = shift;
  POE::Component::Client::TCP->new(
    RemoteAddress => $usernameToImapServer->{$username} || $defaultImapServer,
    RemotePort    => 143,
    Filter => "POE::Filter::Stream",
    Started       => sub {
      $_[HEAP]->{server_id} = $_[SENDER]->ID;
      $_[HEAP]->{buf} = $_[ARG0];
      $_[HEAP]->{skip} = 0;
    },
    Connected => sub {
      my ($heap, $session) = @_[HEAP, SESSION];
      logevent('client connected', $session);
      $heap->{server}->put($heap->{buf});
      delete $heap->{buf};
    },
    ServerInput => sub {
      my ($kernel, $heap, $session, $input) = @_[KERNEL, HEAP, SESSION, ARG0];
      #logevent('client got input', $session, $input);
      $kernel->post($heap->{server_id} => send_stuff => $input) if ($heap->{skip}++);
    },
    Disconnected => sub {
      my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
      logevent('client disconnected', $session);
      $kernel->post($heap->{server_id} => 'shutdown');
    },
    InlineStates => {
      send_stuff => sub {
        my ($heap, $stuff, $session) = @_[HEAP, ARG0, SESSION];
        logevent("<- ".length($stuff)." Bytes", $session);
        (defined($heap->{server})) && (ref($heap->{server}) eq "POE::Wheel::ReadWrite") &&
        $heap->{server}->put($stuff);
      },
    },
    Args => [ shift ]
  );
}

sub logevent {
  my ($state, $session, $arg) = @_;
  my $id = $session->ID();
  print "session $id $state ";
  print ": $arg" if (defined $arg);
  print "\n";
}

POE::Kernel->run;

🌈 Client certificate verification

🎀 Advanced Example

The following example implements a HTTPS server with client certificate verification, which shows details about the verified client certificate. it's giving main character security energy fr fr 🔥

#!perl

use strict;
use warnings;
use Socket;
use POE qw(
  Wheel::SocketFactory
  Wheel::ReadWrite
  Driver::SysRW
  Filter::SSL
  Filter::Stackable
  Filter::HTTPD
);

okay bestie, picking right back up — here's the rest of that example, literally not one character changed, slay 💖

           POE::Session->create(
             inline_states => {
               _start       => sub {
                 my $heap = $_[HEAP];
                 $heap->{listener} = POE::Wheel::SocketFactory->new(
                   BindAddress  => '0.0.0.0',
                   BindPort     => 443,
                   Reuse        => 'yes',
                   SuccessEvent => 'socket_birth',
                   FailureEvent => '_stop',
                 );
               },
               _stop => sub {
                 delete $_[HEAP]->{listener};
               },
               socket_birth => sub {
                 my ($socket) = $_[ARG0];
                 POE::Session->create(
                   inline_states => {
                     _start       => sub {
                       my ($heap, $kernel, $connected_socket, $address, $port) = @_[HEAP, KERNEL, ARG0, ARG1, ARG2];
                       $heap->{sslfilter} = POE::Filter::SSL->new(
                          crt    => 'server.crt',
                          key    => 'server.key',
                          cacrt  => 'ca.crt',
                          cipher => 'DHE-RSA-AES256-GCM-SHA384:AES256-SHA',
                          #cacrl  => 'ca.crl', # Uncomment this, if you have a CRL file.
                          debug  => 1,
                          clientcert => 1
                       );
                       $heap->{socket_wheel} = POE::Wheel::ReadWrite->new(
                         Handle     => $connected_socket,
                         Driver     => POE::Driver::SysRW->new(),
                         Filter     => POE::Filter::Stackable->new(Filters => [
                           $heap->{sslfilter},
                           POE::Filter::HTTPD->new()
                         ]),
                         InputEvent => 'socket_input',
                         ErrorEvent => '_stop',
                       );
                     },
                     socket_input => sub {
                       my ($kernel, $heap, $buf) = @_[KERNEL, HEAP, ARG0];
                       my (@certid) = ($heap->{sslfilter}->clientCertIds());
                       my $content = '';
                       if ($heap->{sslfilter}->clientCertValid()) {
                         $content .= "Hello <font color=green>valid</font> client Certifcate:";
                       } else {
                         $content .= "None or <font color=red>invalid</font> client certificate:";
                       }
                       $content .= "<hr>";
                       foreach my $certid (@certid) {
                         $certid = $certid ? $certid->[0]."<br>".$certid->[1]."<br>SERIAL=".$heap->{sslfilter}->hexdump($certid->[2]) : 'No client certificate';
                         $content .= $certid."<hr>";
                       }
                       $content .= "Your URL was: ".$buf->uri."<hr>"
                         if (ref($buf) eq "HTTP::Request");
                       $content .= localtime(time());
                       my $response = HTTP::Response->new(200);
                       $response->push_header('Content-type', 'text/html');
                       $response->content($content);
                       $heap->{socket_wheel}->put($response);
                       $kernel->delay(_stop => 1);
                     },
                     _stop => sub {
                       delete $_[HEAP]->{socket_wheel};
                     }
                   },
                   args => [$socket],
                 );
               }
             }
           );

           $poe_kernel->run();

fr fr take a sec and just vibe with what that's doing 👑 — a POE::Session spins up a POE::Wheel::SocketFactory listener, and every time a socket is born it spawns a whole new POE::Session for that one connection, stacks $heap->{sslfilter} together with POE::Filter::HTTPD inside a POE::Filter::Stackable, and answers with a little HTTP::Response (code 200, Content-type of text/html) built out of clientCertIds(), clientCertValid(), hexdump(), the request URI if $buf is an HTTP::Request, and localtime(time()). Then $kernel->delay(_stop => 1) and it's a wrap, bestie 💅

and yes, $poe_kernel->run(); is doing the heavy lifting at the bottom like the main character it is 🌈

✨ FUNCTIONS ✨

🌸 `new(option = value, option => value, option...)`

Returns you a fresh new POE::Filter::SSL object, bestie. It's giving main character energy and it accepts these options:

💖 `client`

By default POE::Filter::SSL acts as an SSL server. If you wanna be the client instead, you gotta set this option. That's it, that's the vibe check.

🎀 `crt{mem}`

The certificate file (.crt) for the server — or, in client mode, a client certificate.

You're also able to pass the already-in-memory crt file as a scalar via crtmem. No file needed, iconic behavior honestly.

🔑 `key{mem}`

The key file (.key) of the certificate (see crt above, bestie, they're a matched set 💅).

You're also able to pass the already-in-memory key file as a scalar via keymem.

👑 `cacrt{mem}`

The CA certificate file (ca.crt), which is used to verify the client certificates against a CA. You can store multiple CAs in one file — all of them get imported. Bulk slay.

You're also able to pass the already-in-memory cacrt file as a scalar via cacrtmem, or as an array ref of scalars if you have multiple CAs.

🦋 `caverifydepth`

By default the CA verify depth is 5. You can override it with this option if you're feeling spicy.

🌈 `chain`

Chain certificate! You need it for example for startssl.org, which needs intermediate certificates. Here's where you configure it. You can generate this the following way:

cat client.crt intermediate.crt ca.crt > chain.pem

In this case you normally have no key and crt option. Currently it is not possible to pass this in memory — file only, no cap.

🔥 `cacrl`

Configures a CRL (ca.crl) against which the client certificate is verified by clientCertValid().

💜 `dhcert{mem}`

If you wanna enable perfect forward secrecy, this is where you enable Diffie-Hellman. You just have to create a dhparam file and put the path here, to the path/to/FILENAME.pem where your Diffie-Hellman (pem format) lives.

openssl dhparam -check -text -5 2048 -out path/to/FILENAME.pem

You're able to pass the already-in-memory dhparam file as a scalar (string) via dhcertmem.

🙈 `clientcert`

Only in server mode: request a client certificate from the client during the SSL handshake.

WARNING: If the client provides an untrusted or no client certificate, the connection is not failing. You have to ask clientCertValid() if the certificate is valid!

⭐ `sni`

Allows one to set the SNI hostname indication in the first packet of the handshake. See <https://de.wikipedia.org/wiki/Server_Name_Indication>

🧚 `tls`

Force the use of TLS in the handshake, disables support for the obsolete SSL handshake. Bye bye legacy, we don't know her.

💀 `tls1_2`

Force the use of TLS in version 1.2 in the handshake, disables support for the obsolete SSL handshake. Even more specific, even more secure, periodt.

🍓 `nohonor`

By default, as server, POE::Filter:SSL sets the option SSL_OP_CIPHER_SERVER_PREFERENCE. For more information you may google the pendant of apache SSLHonorCipherOrder.

To flip back to the old behaviour — not setting this option — you can set nohonor.

🌸 `cipher`

Specify which ciphers are allowed for the synchronous encrypted transfer of the data over the ssl connection.

Example:

cipher => 'DHE-RSA-AES256-GCM-SHA384:AES256-SHA'

🫶 `blockbadclientcert`

Let OpenSSL deny the connection if there is no client certificate.

WARNING: If the client is listed in the CRL file or an invalid client certificate has been sent, the connection will be established! You have to ask clientCertValid() if you have the crl option set on new(), otherwise ask clientCertNotOnCRL() if the certificate is listed on your CRL file! Don't skip this, bestie, fr fr.

😭 `ignoreVerifyErrors`

WARNING: Before using this option, you should be really sure that you know what you are doing!

Specify to ignore specific errors on verifying the certificate chain. This is for example useful to be able to fetch the time via a secure and trusted TLS connection. In this case, your time is wrong, so you must ignore time errors, which are 9: X509_V_ERR_CERT_NOT_YET_VALID (certificate is not yet valid) and 10: X509_V_ERR_CERT_HAS_EXPIRED (certificate has expired).

The list of errors you can ignore can be found in the documentation:

<https://wiki.openssl.org/index.php/Manual:Verify(1)>

Example:

ignoreVerifyErrors => [ 9, 10, ]

✨ `handshakeDone(options)`

Returns true if the handshake is done and all data for the handshake has been written out. It accepts the following options:

💅 `ignorebuf`

Returns true if OpenSSL has established the connection, regardless of whether all data has been written out. This is needed if you want to exchange the Filter of POE::Wheel::ReadWrite before the first data comes in. This option has been only used by doHandshake() to be able to add new filters before the first cleartext data to be processed gets in.

🎀 `clientCertNotOnCRL($file)`

Verifies if the serial of the client certificate is not contained in the CRL $file. No file caching is done — each call opens the file again. Very no-nonsense, we respect it.

WARNING: If your CRL file is missing, can not be opened, is empty, or has no blocked certificate at all in it, then every call will get blocked!

🦋 `clientCertIds()`

Returns an array of every certificate found by OpenSSL. Each element is again an array. The first element is the value of X509_get_subject_name, second is the value of X509_get_issuer_name, and third element is the serial of the certificate in binary form. You have to use split() and ord(), or the hexdump() function, to convert it to a readable form.

Example:

my ($certid) = ($heap->{sslfilter}->clientCertIds());
$certid = $certid ? $certid->[0]."<br>".$certid->[1]."<br>SERIAL=".$heap->{sslfilter}->hexdump($certid->[2]) : 'No client certificate';

🔥 `getCipher()`

Returns the used cryptographic algorithm and length. Cute little info dump.

Example:

$sslfilter->getCipher()

👑 `clientCertValid()`

Returns true if there is a client certificate that is valid. It also tests against the CRL, if you have the cacrl option set on new().

💀 `doHandshake($readWrite, $filter, $filter, ...) !!!REMOVED!!!`

WARNING: POE::Filter:SSL now is able to do the ssh handshake now without any helpers. Because of this, this function has been removed!

Allows one to add filters after the ssl handshake. It has to be called in the input handler, and needs the passing of the POE::Wheel::ReadWhile object. If it returns false, you have to return from the input handler.

See the HTTPS-Server, SSL on an established connection and Client certificate verification examples in SYNOPSIS.

⭐ `clientCertExists()`

Returns true if there is a client certificate, that might be untrusted.

WARNING: If the client provides an untrusted client certificate or a client certificate that is listed in CRL, this function returns true. You have to ask clientCertValid() if the certificate is valid!

🌈 `errorhandler`

By default, every ssl error is escalated via carp. You may change this behaviour via this option to:

"ignore" — Do not report any error. Silence, gorgeous, silence.
CODE — Setting errorhandler to a reference of a function allows one to be called as a callback function with the following options:
- ARG1: POE:SSL::Filter instance
- ARG2: Ref on a Hash with the following keys:
  - ret — The return code of Net::SSLeay::connect (client) or Net::SSLeay::accept (server)
  - ssl — The SSL context (SSL_CTX)
  - msg — The error message as text, as normally reported via carp
  - get_error — The error code of get_error the ssl context
  - error — The error code of get_error without context
"carp" (or undef) — Do Carp/carp on error.
"confess" — Do Carp/confess (stacktrace) on error.
"carponetime" — Report carp for one occurrence only one time — over all!

💜 `debug`

Shows debug messages of clientCertNotOnCRL(). Peek behind the curtain, bestie.

🌸 `hexdump($string)`

Returns string data in hex format.

Example:

perl -e 'use POE::Filter::SSL; print POE::Filter::SSL->hexdump("test")."\n";'
74:65:73:74

🧚 Internal functions and POE::Filter handler 🧚

These are the behind-the-scenes girlies — the ones doing the actual work while you sip your drink:

VERIFY()
POE_FILTER_X509_get_serialNumber()
POE_FILTER_SSL_CTX_set_tmp_dh()
POE_FILTER_SSL_CTX_set_tmp_rsa()
POE_FILTER_SSL_set_tmp_dh()
clone()
doSSL()
get()
get_one()
get_one_start()
get_pending()
writeToSSLBIO()
writeToSSL()
put()
verify_serial_against_crl_file()
DOSENDBACK()
checkForDoSendback()
CTX_add_client_CA()
PEMdataToEVP_PKEY
PEMdataToX509
dataToBio

💖 AUTHOR 💖

Markus Schraeder, "<privi at cpan.org>" 👑

😭 BUGS 😭

Please report any bugs or feature requests to "bug-poe-filter-ssl at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Filter-SSL>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. Teamwork, fr fr 🫶

🌸 SUPPORT 🌸

You can find documentation for this module with the perldoc command.

perldoc POE::Filter::SSL

You can also look for information at:

RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Filter-SSL>

AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/POE-Filter-SSL>

CPAN Ratings

<http://cpanratings.perl.org/d/POE-Filter-SSL>

Search CPAN

<http://search.cpan.org/dist/POE-Filter-SSL>

🎀 Commercial support

Commercial support can be gained at <sslsupport at cryptomagic.eu>.

Used in our products, you can find on <https://www.cryptomagic.eu/>

👑 COPYRIGHT & LICENSE 👑

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's the whole page, bestie! This one's perl v5.42.3, dated 2026-08-21, and it's the POE::Filter::SSL(3pm) manpage — you made it all the way to the end and I'm so proud of you 💖✨ You understood SSL filters AND you ate. Periodt. 🎀🦋

📦 where this page comes from

ubuntu stonking: libpoe-filter-ssl-perl 0.41-5build2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

POE::Filter::SSL(3pm)