Chris Drake > Crypt-MatrixSSL3-3.3.0.1 > Crypt::MatrixSSL3

Download:
Crypt-MatrixSSL3-3.3.0.1.tgz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 3.3.0.1   Source  

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

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.

SEE ALSO ^

http://www.MatrixSSL.org - the download from this site includes simple yet comprehensive documentation in PDF format.

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.

syntax highlighting: