/ 
IO-Stream-MatrixSSL-v2.0.2
River stage zero No dependents
/ IO::Stream::MatrixSSL

NAME

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

VERSION

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

SYNOPSIS

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

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

# SSL client
IO::Stream->new({
    ...
    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;
}

DESCRIPTION

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

INTERFACE

IO::Stream::MatrixSSL::Client

new

$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.

crt
key
pass

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).

trusted_CA

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.

cb

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:

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

stream

$stream = $plugin_ssl_client->stream();

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

IO::Stream::MatrixSSL::Server

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

MIGRATION

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.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/powerman/perl-IO-Stream-MatrixSSL/issues. 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.

https://github.com/powerman/perl-IO-Stream-MatrixSSL

git clone https://github.com/powerman/perl-IO-Stream-MatrixSSL.git

Resources

AUTHOR

Alex Efros <powerman@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2008- by Alex Efros <powerman@cpan.org>.

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!