NAME

Crypt::MatrixSSL3 - Perl extension for SSL and TLS using MatrixSSL.org v3.3

SYNOPSIS

use Crypt::MatrixSSL3;

# 1. See the MatrixSSL documentation.
# 2. See scripts included in this package:
#     sample_ssl_client.pl
#     sample_ssl_server.pl
#     sample_functions.pl

DESCRIPTION

Crypt::MatrixSSL3 lets you use the MatrixSSL crypto library (see http://matrixssl.org/) from Perl. With this module, you will be able to easily write SSL and TLS client and server programs.

MatrixSSL includes everything you need, all in under 50KB.

You will need a "C" compiler to build this, unless you're getting the ".ppm" prebuilt Win32 version. Crypt::MatrixSSL3 builds cleanly on (at least) Windows, Linux, and Macintosh machines.

MatrixSSL is an Open Source (GNU Public License) product, and is also available commercially if you need freedom from GNU rules.

Everything you need is included here, but check the MatrixSSL.org web site to make sure you've got the latest version of the MatrixSSL "C" code if you like (it's in the directory "./matrixssl" of this package if you want to replace the included version from the MatrixSSL.org download site.)

EXPORTS

Constants and functions can be exported using different tags. Use tag ':all' to export everything.

By default (tag ':DEFAULT') only SSL_MAX_PLAINTEXT_LEN and return code constants (tag ':RC') will be exported.

:Version

SSL2_MAJ_VER
SSL3_MAJ_VER
SSL3_MIN_VER
TLS_1_1_MIN_VER
TLS_1_2_MIN_VER
TLS_MAJ_VER
TLS_MIN_VER
MATRIXSSL_VERSION
MATRIXSSL_VERSION_MAJOR
MATRIXSSL_VERSION_MINOR
MATRIXSSL_VERSION_PATCH
MATRIXSSL_VERSION_CODE

:Cipher

Used in matrixSslSetCipherSuiteEnabledStatus().

SSL_NULL_WITH_NULL_NULL
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_EMPTY_RENEGOTIATION_INFO_SCSV

Flag for matrixSslEncodeRehandshake():

SSL_OPTION_FULL_HANDSHAKE

:Alert

Alert level codes:

SSL_ALERT_LEVEL_FATAL
SSL_ALERT_LEVEL_WARNING

Alert description codes:

SSL_ALERT_ACCESS_DENIED
SSL_ALERT_BAD_CERTIFICATE
SSL_ALERT_BAD_RECORD_MAC
SSL_ALERT_CERTIFICATE_EXPIRED
SSL_ALERT_CERTIFICATE_REVOKED
SSL_ALERT_CERTIFICATE_UNKNOWN
SSL_ALERT_CLOSE_NOTIFY
SSL_ALERT_DECODE_ERROR
SSL_ALERT_DECOMPRESSION_FAILURE
SSL_ALERT_DECRYPTION_FAILED
SSL_ALERT_DECRYPT_ERROR
SSL_ALERT_HANDSHAKE_FAILURE
SSL_ALERT_ILLEGAL_PARAMETER
SSL_ALERT_INTERNAL_ERROR
SSL_ALERT_NONE
SSL_ALERT_NO_CERTIFICATE
SSL_ALERT_NO_RENEGOTIATION
SSL_ALERT_PROTOCOL_VERSION
SSL_ALERT_RECORD_OVERFLOW
SSL_ALERT_UNEXPECTED_MESSAGE
SSL_ALERT_UNKNOWN_CA
SSL_ALERT_UNSUPPORTED_CERTIFICATE
SSL_ALERT_UNSUPPORTED_EXTENSION

:Error

Error codes from different functions:

PS_FAILURE
MATRIXSSL_ERROR
PS_ARG_FAIL
PS_CERT_AUTH_FAIL
PS_LIMIT_FAIL
PS_MEM_FAIL
PS_PARSE_FAIL
PS_PLATFORM_FAIL
PS_PROTOCOL_FAIL
PS_UNSUPPORTED_FAIL

:RC

Return codes from different functions:

PS_SUCCESS
MATRIXSSL_SUCCESS
MATRIXSSL_APP_DATA
MATRIXSSL_HANDSHAKE_COMPLETE
MATRIXSSL_RECEIVED_ALERT
MATRIXSSL_REQUEST_CLOSE
MATRIXSSL_REQUEST_RECV
MATRIXSSL_REQUEST_SEND

:Limit

Max amount of disabled ciphers in matrixSslSetCipherSuiteEnabledStatus():

SSL_MAX_DISABLED_CIPHERS

Max size for message in matrixSslEncodeToOutdata():

SSL_MAX_PLAINTEXT_LEN

:Validate

Return code in user validation callback:

SSL_ALLOW_ANON_CONNECTION

:Bool

Booleans used in matrixSslSetCipherSuiteEnabledStatus() and {authStatus}:

PS_TRUE
PS_FALSE

:Func

set_cipher_suite_enabled_status
get_ssl_alert
get_ssl_error

FUNCTIONS

Some MatrixSSL functions are not accessible from Perl.

These functions will be called automatically before creating first object of any class (::Keys, ::SessID, ::Client, ::Server or ::HelloExt) and after last object will be destroyed.

matrixSslOpen
matrixSslClose

These functions implement optimization which is useless in Perl:

matrixSslGetWritebuf
matrixSslEncodeWritebuf

set_cipher_suite_enabled_status( $cipherId, $status )

matrixSslSetCipherSuiteEnabledStatus( NULL, $cipherId, $status )

If this function will be used, matrixSslClose() will be never called.

get_ssl_alert( $ptBuf )

Unpack alert level and description from $ptBuf returned by $ssl->received_data() or $ssl->processed_data().

Return ($level, $descr) in list context, and $descr in scalar context. Both $level and $descr are dualvars (code in numeric context and text in string context).

get_ssl_error( $rc )

Return dualvar for this error code (same as $rc in numeric context and text error name in string context).

CLASSES

Constructors for all classes will throw exception on error instead of returning error as matrixSslNew*() functions do. Exception will be thrown using croak($return_code) , so to get $return_code from $@ you should convert it back to number:

eval { $client = Crypt::MatrixSSL3::Client->new(...) };
$return_code = 0+$@ if $@;

Crypt::MatrixSSL3::Keys

new()

matrixSslNewKeys( $keys )

Return new object $keys. Throw exception if matrixSslNewKeys() doesn't return PS_SUCCESS. When this object will be destroyed will call:

matrixSslDeleteKeys( $keys )

$keys->load_rsa( $certFile, $privFile, $privPass, $trustedCAcertFiles )

matrixSslLoadRsaKeys( $keys, $certFile,
   $privFile, $privPass, $trustedCAcertFiles )

$keys->load_rsa_mem( $cert, $priv, $trustedCA )

matrixSslLoadRsaKeysMem( $keys, $cert, length $cert,
   $priv, length $priv, $trustedCA, length $trustedCA )

$keys->load_pkcs12( $p12File, $importPass, $macPass, $flags )

matrixSslLoadPkcs12( $keys, $p12File, $importPass, length $importPass,
   $macPass, length $macPass, $flags )

Crypt::MatrixSSL3::SessID

new()

Return new object $sessid representing (sslSessionId_t*) type. Throw exception if failed to allocate memory. When this object will be destroyed will free memory, so you should keep this object while there are exist Client/Server session which uses this $sessid.

$sessid->init()

matrixSslInitSessionId($sessid);

Crypt::MatrixSSL3::Client

new( $keys, $sessionId, $cipherSuite, \&certValidator, $extensions, \&extensionCback )

matrixSslNewClientSession( $ssl, $keys, $sessionId, $cipherSuite,
   \&certValidator, $extensions, \&extensionCback )

Return new object $ssl. Throw exception if matrixSslNewClientSession() doesn't return MATRIXSSL_REQUEST_SEND. When this object will be destroyed will call:

matrixSslDeleteSession( $ssl )

More information about callbacks &certValidator and &extensionCback in next section.

Crypt::MatrixSSL3::Server

new( $keys, \&certValidator )

matrixSslNewServerSession( $ssl, $keys, \&certValidator )

Return new object $ssl. Throw exception if matrixSslNewServerSession() doesn't return PS_SUCCESS. When this object will be destroyed will call:

matrixSslDeleteSession( $ssl )

More information about callback &certValidator in next section.

Crypt::MatrixSSL3::Client and Crypt::MatrixSSL3::Server

$ssl->get_outdata( $outBuf )

Unlike C API, it doesn't set $outBuf to memory location inside MatrixSSL, but instead it append buffer returned by C API to the end of $outBuf.

matrixSslGetOutdata( $ssl, $tmpBuf )
$outBuf .= $tmpBuf

$ssl->sent_data( $bytes )

matrixSslSentData( $ssl, $bytes )

$ssl->get_readbuf( $ssl, $inBuf )

Unlike C API, it doesn't set $inBuf to memory location inside MatrixSSL, but instead it copy data from beginning of $inBuf into buffer returned by C API and cut copied data from beginning of $inBuf (it may copy less bytes than $inBuf contain if size of buffer provided by MatrixSSL will be smaller).

$n = matrixSslGetReadbuf( $ssl, $buf )
$n = min($n, length $inBuf)
$buf = substr($inBuf, 0, $n, q{})

$ssl->received_data( $bytes, $ptBuf )

matrixSslReceivedData( $ssl, $bytes, $ptBuf, $ptLen )

$ssl->processed_data( $ptBuf )

matrixSslProcessedData( $ssl, $ptBuf, $ptLen )

In case matrixSslReceivedData() or matrixSslProcessedData() will return MATRIXSSL_RECEIVED_ALERT, you can get alert level and description from $ptBuf:

my ($level, $descr) = get_ssl_alert($ptBuf);

$ssl->encode_to_outdata( $outBuf )

matrixSslEncodeToOutdata( $ssl, $outBuf, length $outBuf )

$ssl->encode_closure_alert( )

matrixSslEncodeClosureAlert( $ssl )

$ssl->encode_rehandshake( $keys, \&certValidator, $sessionOption, $cipherSpec )

matrixSslEncodeRehandshake( $ssl, $keys, \&certValidator,
   $sessionOption, $cipherSpec )

More information about callback &certValidator in next section.

$ssl->set_cipher_suite_enabled_status( $cipherId, $status )

matrixSslSetCipherSuiteEnabledStatus( $ssl, $cipherId, $status )

$ssl->get_anon_status( $anon )

matrixSslGetAnonStatus( $ssl, $anon )

Crypt::MatrixSSL3::HelloExt

new( )

matrixSslNewHelloExtension>( $extension )

Return new object $extension. Throw exception if matrixSslNewHelloExtension() doesn't return PS_SUCCESS. When this object will be destroyed will call:

matrixSslDeleteHelloExtension( $extension )

$extension->load( $ext, $extType )

matrixSslLoadHelloExtension( $extension, $ext, length $ext, $extType )

CALLBACKS

&certValidator

Will be called with two scalar params: $certInfo and $alert (unlike C callback which also have $ssl param).

Param $certInfo instead of (psX509Cert_t *) will contain reference to array with certificates. Each certificate will be hash in this format:

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,
               },
authStatus     => $authStatus,

This callback must return single scalar with integer value (as described in MatrixSSL documentation). If callback die(), then warning will be printed, and execution will continue assuming callback returned -1.

&extensionCback

Will be called with two scalar params: $type and $data (unlike C callback which also have $ssl and length($data) params).

AUTHORS

C. N. Drake, <christopher@pobox.com>
Alex Efros  <powerman-asdf@ya.ru>

COPYRIGHT AND LICENSE

MatrixSSL is distrubed under the GNU Public License:- http://www.gnu.org/copyleft/gpl.html

Crypt::MatrixSSL3 uses MatrixSSL, and so inherits the same License.

Copyright (C) 2005,2012 by C. N. Drake.
Copyright (C) 2012 by Alex Efros.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.

To install Crypt::MatrixSSL3, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Crypt::MatrixSSL3

CPAN shell

perl -MCPAN -e shell
install Crypt::MatrixSSL3

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)