IO::Stream::MatrixSSL - Crypt::MatrixSSL plugin for IO::Stream
This document describes IO::Stream::MatrixSSL version 1.1.1
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 ($certs, $ssl, $stream) = ($_[0], @{ $_[1] }); # 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).
Create and return new IO::Stream plugin object.
There two optional parameters:
This should be CODE ref to your callback, which should check server certificate. Callback will be called with two parameters: HASH ref with certificate details, and ARRAY ref with two elements: IO::Stream::MatrixSSL::Client object and IO::Stream object (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)
This should be name of file (or files) with allowed CA certificates, required to check RSA signature of server certificate. This module installed with such file, so chances are you doesn't need to change default {trusted_CA} value if you just wanna connect to https servers.
There may be many files listed in {trusted_CA}, separated by ";". Each file can contain many CA certificates.
There at least two required parameters: {crt} and {key}. If {key} is encrypted, then one more parameter required: {pass}.
This should be name of file (or files) with server certificate (or chain of certicates). See above {trusted_CA} about format of this parameter.
This should be name of file with private key file for server certicate (file should be in PEM format).
If file with private key is encrypted, you should provide password for decrypting it in this parameter.
matrixSslReadKeys: wrong {trusted_CA}?
File with trusted CA certificates can't be read. If you provide own file, there some problem with it. If you doesn't provided own file, then probably this module was installed incorrectly - there should be default file with trusted CA certificates (taken from Mozilla) installed with module.
matrixSslNewSession: wrong {_ssl_session}?
This error shouldn't happens, it mean there some bug in this module, or Crypt::MatrixSSL, or MatrixSSL itself.
matrixSslEncodeClientHello
{crt} and {key} required
You can't create SSL server without certificate and key files.
matrixSslReadKeys: wrong {crt}, {key} or {pass}?
Certificate and key files you provided can't be read by MatrixSSL, or may be you used wrong password for key file.
matrixSslNewSession
IO::Stream::MatrixSSL requires no configuration files or environment variables.
IO::Stream, Crypt::MatrixSSL 1.83, File::ShareDir.
None reported.
No bugs have been reported.
Please report any bugs or feature requests to author, or bug-ev-stream-matrixssl@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-ev-stream-matrixssl@rt.cpan.org
Alex Efros <powerman-asdf@ya.ru>
<powerman-asdf@ya.ru>
Copyright (c) 2008, Alex Efros <powerman-asdf@ya.ru>. All rights reserved.
MatrixSSL is distrubed under the GNU Public License.
Crypt::MatrixSSL uses MatrixSSL, and so inherits the same license.
IO::Stream::MatrixSSL uses Crypt::MatrixSSL, and so inherits the same license.
... GPL is a virus, avoid it whenever possible!
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install IO::Stream::MatrixSSL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Stream::MatrixSSL
CPAN shell
perl -MCPAN -e shell install IO::Stream::MatrixSSL
For more information on module installation, please visit the detailed CPAN module installation guide.