Alex Efros > IO-Stream-MatrixSSL-1.1.1 > IO::Stream::MatrixSSL

Download:
IO-Stream-MatrixSSL-1.1.1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.1.1   Source   Latest Release: IO-Stream-MatrixSSL-1.1.2

NAME ^

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

VERSION ^

This document describes IO::Stream::MatrixSSL version 1.1.1

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 ($certs, $ssl, $stream) = ($_[0], @{ $_[1] });
        # 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(\%opt)

Create and return new IO::Stream plugin object.

There two optional parameters:

cb

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

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.

IO::Stream::MatrixSSL::Server->new(\%opt)

Create and return new IO::Stream plugin object.

There at least two required parameters: {crt} and {key}. If {key} is encrypted, then one more parameter required: {pass}.

crt

This should be name of file (or files) with server certificate (or chain of certicates). See above {trusted_CA} about format of this parameter.

key

This should be name of file with private key file for server certicate (file should be in PEM format).

pass

If file with private key is encrypted, you should provide password for decrypting it in this parameter.

DIAGNOSTICS ^

IO::Stream::MatrixSSL::Client

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

This error shouldn't happens, it mean there some bug in this module, or Crypt::MatrixSSL, or MatrixSSL itself.

IO::Stream::MatrixSSL::Server

{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

This error shouldn't happens, it mean there some bug in this module, or Crypt::MatrixSSL, or MatrixSSL itself.

CONFIGURATION AND ENVIRONMENT ^

IO::Stream::MatrixSSL requires no configuration files or environment variables.

DEPENDENCIES ^

IO::Stream, Crypt::MatrixSSL 1.83, File::ShareDir.

INCOMPATIBILITIES ^

None reported.

BUGS AND LIMITATIONS ^

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.

AUTHOR ^

Alex Efros <powerman-asdf@ya.ru>

LICENSE AND COPYRIGHT ^

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!

DISCLAIMER OF WARRANTY ^

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.

syntax highlighting: