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
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.
Resources
* MetaCPAN Search
* CPAN Ratings
* AnnoCPAN: Annotated CPAN documentation
* CPAN Testers Matrix
* CPANTS: A CPAN Testing Service (Kwalitee)
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!