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

  use Crypt::MatrixSSL;

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

Crypt::MatrixSSL 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::MatrixSSL 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.)

See MatrixSSL documentations about these functions. This documentation will describe only differences between original C interface provided by MatrixSSL and Perl interface provided by this module (see below).

 matrixSslOpen()
 matrixSslClose()
 matrixSslReadKeys()
 matrixSslReadKeysMem()
 matrixSslFreeKeys()
 matrixSslNewSession()
 matrixSslDeleteSession()
 matrixSslDecode()
 matrixSslEncode()
 matrixSslEncodeClosureAlert()
 matrixSslEncodeClientHello()
 matrixSslEncodeHelloRequest()
 matrixSslSetSessionOption()
 matrixSslHandshakeIsComplete()
 matrixSslGetSessionId()
 matrixSslFreeSessionId()
 matrixSslSetCertValidator()
 matrixSslGetAnonStatus()
 matrixSslAssignNewKeys()
 matrixSslSetResumptionFlag()
 matrixSslGetResumptionFlag()

Return code in user validation callback:

 $SSL_ALLOW_ANON_CONNECTION

Max size for message in matrixSslEncode():

 $SSL_MAX_PLAINTEXT_LEN

Flags for matrixSslNewSession():

 $SSL_FLAGS_SERVER
 $SSL_FLAGS_CLIENT_AUTH

Options for matrixSslSetSessionOption():

 $SSL_OPTION_DELETE_SESSION

matrixSslDecode() return values:

 $SSL_SUCCESS
 $SSL_ERROR
 $SSL_FULL
 $SSL_PARTIAL
 $SSL_SEND_RESPONSE
 $SSL_PROCESS_DATA
 $SSL_ALERT
 $SSL_FILE_NOT_FOUND
 $SSL_MEM_ERROR

matrixSslDecode() alertLevel:

 $SSL_ALERT_LEVEL_WARNING
 $SSL_ALERT_LEVEL_FATAL

matrixSslDecode() alertDescription:

 $SSL_ALERT_CLOSE_NOTIFY
 $SSL_ALERT_UNEXPECTED_MESSAGE
 $SSL_ALERT_BAD_RECORD_MAC
 $SSL_ALERT_DECOMPRESSION_FAILURE
 $SSL_ALERT_HANDSHAKE_FAILURE
 $SSL_ALERT_NO_CERTIFICATE
 $SSL_ALERT_BAD_CERTIFICATE
 $SSL_ALERT_UNSUPPORTED_CERTIFICATE
 $SSL_ALERT_CERTIFICATE_REVOKED
 $SSL_ALERT_CERTIFICATE_EXPIRED
 $SSL_ALERT_CERTIFICATE_UNKNOWN
 $SSL_ALERT_ILLEGAL_PARAMETER

 %SSL_alertLevel
 %SSL_alertDescription

matrixSslDecode( $ssl, $inBuf, $outBuf, $error, $alertLevel, $alertDescription )

$inBuf and $outBuf are usual string scalars, not (sslBuf_t *) as in C interface.

After succesfull decoding one packet, matrixSslDecode() will cut decoded packet from $inBuf's beginning.

Reply SSL packets or application data will be appended to $outBuf, if any.

To convert error/alert codes into text use exported hashes:

 $SSL_alertDescription{ $error }
 $SSL_alertLevel{ $alertLevel }
 $SSL_alertDescription{ $alertDescription }

matrixSslEncode( $ssl, $inBuf, $outBuf )

matrixSslEncodeClosureAlert( $ssl, $outBuf )

matrixSslEncodeClientHello( $ssl, $outBuf, $cipherSuite )

matrixSslEncodeHelloRequest( $ssl, $outBuf )

$outBuf in all matrixSslEncode* functions is usual string scalar, not (sslBuf_t *) as in C interface.

Encoded SSL packet will be appended to $outBuf.

If you need to matrixSslEncode() huge $inBuf, then you should split $inBuf into strings with size <= $SSL_MAX_PLAINTEXT_LEN and call matrixSslEncode() for each of these strings. If you don't do this matrixSslEncode() will return one of these errors: $SSL_ERROR, $SSL_FULL or matrixSslDecode() on other side will return $SSL_ERROR.

matrixSslSetCertValidator( $ssl, \&cb, $cb_arg )

While interface of this function is same as in C, there some important notes about perl callback \&cb. Perl callback will be called with two scalar params: $certInfo and $cb_arg - just like in C.

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

 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,
                },

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.

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

C. N. Drake, <christopher@pobox.com> Alex Efros

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

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

Copyright (C) 2005 by C. N. Drake.

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.