View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Alex Efros > IO-Stream-MatrixSSL > IO::Stream::MatrixSSL



Annotate this POD


View/Report Bugs
Module Version: v2.0.2   Source  


IO::Stream::MatrixSSL - Crypt::MatrixSSL plugin for IO::Stream


This document describes IO::Stream::MatrixSSL version v2.0.2


    use IO::Stream;
    use IO::Stream::MatrixSSL;

    # SSL server
        plugin => [
            ssl     => IO::Stream::MatrixSSL::Server->new({
                crt     => 'mysrv.crt',
                key     => 'mysrv.key',

    # SSL client
        plugin => [
            ssl     => IO::Stream::MatrixSSL::Client->new({
                cb      => \&validate,
    sub validate {
        my ($ssl, $certs) = @_;
        my $stream = $ssl->stream();
        # check cert, for ex.: $certs->[0]{subject}{commonName}
        return 0;


This module is plugin for IO::Stream which allow you to use SSL (on both client and server streams).




    $plugin_ssl_client = IO::Stream::MatrixSSL::Client->new();

    $plugin_ssl_client = IO::Stream::MatrixSSL::Client->new({
        crt         => '/path/to/client.crt',
        key         => '/path/to/client.key',
        pass        => 's3cret',
        trusted_CA  => '/path/to/ca-bundle.crt',
        cb          => \&validate,

Create and returns new IO::Stream plugin object.


Authenticate client on server using client's certificate. (You'll need Crypt::MatrixSSL3 compiled with support for client authentication.)

crt and key should contain file names of client's certificate and private key (in PEM format), pass should contain password (as string) for private key.

You can provide multiple file names with client's certificates in crt separated by ;.

All optional (crt and key should be either both provided or both omitted, pass should be provided only if key file protected by password).


This should be name of file (or files) with allowed CA certificates, required to check RSA signature of server certificate. Crypt::MatrixSSL3 provides such a file, so chances are you doesn't need to change default {trusted_CA} value ($Crypt::MatrixSSL3::CA_CERTIFICATES) if you just wanna connect to public https servers.

There may be many files listed in {trusted_CA}, separated by ;. Each file can contain many CA certificates.


This should be CODE ref to your callback, which will check server certificate. Callback will be called with two parameters: IO::Stream::MatrixSSL::Client (or IO::Stream::MatrixSSL::Server - if you're validating client's certificate) object and HASH ref with certificate details (see "SYNOPSIS" for example).

Callback should return a number >=0 if this certificate is acceptable, and we can continue with SSL handshake, or number <0 if this certificate isn't acceptable and we should interrupt this connection and return error to IO::Stream user callback. If this function will throw exception, it will be handled just as return(-1).

Hash with certificate details will looks this way:

    verified       => $verified,
    notBefore      => $notBefore,
    notAfter       => $notAfter,
    subjectAltName => {
        dns             => $dns,
        uri             => $uri,
        email           => $email,
    subject        => {
        country         => $country,
        state           => $state,
        locality        => $locality,
        organization    => $organization,
        orgUnit         => $orgUnit,
        commonName      => $commonName,
    issuer         => {
        country         => $country,
        state           => $state,
        locality        => $locality,
        organization    => $organization,
        orgUnit         => $orgUnit,
        commonName      => $commonName,

where all values are just strings except these:

        Status of cetrificate RSA signature check:
        -1  signature is wrong
         1  signature is correct
        Time period when certificate is active, in format
        YYYYMMDDHHMMSSZ     (for ex.: 20061231235959Z)


    $stream = $plugin_ssl_client->stream();

Returns IO::Stream object related to this plugin object.


Same as above for IO::Stream::MatrixSSL::Client.


MatrixSSL often makes incompatible API changes, and so does Crypt::MatrixSSL3. Sometimes because of this IO::Stream::MatrixSSL also change API in incompatible way, and below explained how to migrate your code.

1.1.2 to 2.0.0

Parameters for validation callback was changed:

    sub validate {
        ### WAS
        my ($certs, $ssl, $stream) = ($_[0], @{ $_[1] });

        ### NOW
        my ($ssl, $certs) = @_;
        my $stream = $ssl->stream();


Some error messages was changed too.


Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests.

    git clone



Alex Efros <>


This software is Copyright (c) 2008- by Alex Efros <>.

This is free software, licensed under:

  The GNU General Public License version 2

instead of less restrictive MIT only because…

MatrixSSL is distributed under the GNU General Public License…

Crypt::MatrixSSL3 uses MatrixSSL, and so inherits the same license…

IO::Stream::MatrixSSL uses Crypt::MatrixSSL3, and so inherits the same license.

GPL is a virus, avoid it whenever possible!

syntax highlighting: