Crypt-MatrixSSL3
view release on metacpan or search on metacpan
Used to refresh an already loaded CT extension data buffer for a
virtual host.
Parameters:
$server_index and $index
Are the same as refresh_OCSP_staple above.
$SCT_params
* Perl scalar contains a file name with prepared extension data.
* Perl array reference with file names of SCT binary structures
that the function will use to create the extension data.
Returns the number of files loaded (if this is 0 there was an error
loading one of the files).
refresh_ALPN_data
$num_protocols = refresh_ALPN_data( $server_index, $index, $protocols );
Used to refresh the application protocols for a default server or for a
virtual host.
Parameters:
$server_index and $index
Are the same as refresh_OCSP_staple above.
$protocols
* Perl array reference containing the new protocols.
Returns the number of protocols you supplied (if this is 0 there was
an error loading one of the files).
Returns the number of files loaded in order to build extension data.
set_VHIndex_callback
set_VHIndex_callback( \&VHIndexCallback );
More information about "VHIndexCallback" in the "CALLBACKS" section.
set_ALPN_callback
set_ALPN_callback( \&ALPNCallback );
More information about "ALPNCallback" in the "CALLBACKS" section.
create_SSL_server
$server_index = create_SSL_server();
Tells the XS module to allocate a new server structure. The returned
index must be saved and then used one time to initialize the server
structure and then each time a new client connection is accepted in
order to set SNI/ALPN callbacks.
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(...) };
$rc = 0+$@ if $@;
Crypt::MatrixSSL3::Keys
new
$keys = 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 )
load_rsa
$rc = $keys->load_rsa( $certFile,
$privFile, $privPass, $trustedCAcertFiles );
matrixSslLoadRsaKeys( $keys, $certFile,
$privFile, $privPass, $trustedCAcertFiles )
load_rsa_mem
$rc = $keys->load_rsa_mem( $cert, $priv, $trustedCA );
matrixSslLoadRsaKeysMem( $keys, $cert, length $cert,
$priv, length $priv, $trustedCA, length $trustedCA )
load_ecc
$rc = $keys->load_ecc( $certFile,
$privFile, $privPass, $trustedCAcertFiles );
matrixSslLoadEcKeys( $keys, $certFile,
$privFile, $privPass, $trustedCAcertFiles )
load_rsa_mem
$rc = $keys->load_ecc_mem( $cert, $priv, $trustedCA );
matrixSslLoadEcKeysMem( $keys, $cert, length $cert,
$priv, length $priv, $trustedCA, length $trustedCA )
load_pkcs12
$rc = $keys->load_pkcs12( $p12File, $importPass, $macPass, $flags );
matrixSslLoadPkcs12( $keys, $p12File, $importPass, length $importPass,
$macPass, length $macPass, $flags )
load_session_ticket_keys
$rc = $keys->load_session_ticket_keys( $name, $symkey, $hashkey );
matrixSslLoadSessionTicketKeys ( $keys, $name, $symkey, length $symkey,
$haskkey, length $hashkey )
load_OCSP_response
$rc = $keys->load_OCSP_response( $OCSP_file );
matrixSslLoadOCSPResponse ( $keys, $OCSPResponse, $OCSPResponseLen )
load_SCT_response
$rc = $keys->load_SCT_response( $SCT_params );
matrixSslLoadSCTResponse ( $keys, $SCTResponse, $SCTResponseLen )
Server side.
Crypt::MatrixSSL3::SessID
new
$sessID = 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 still Client/Server session which use this $sessID.
clear
$sessID->clear();
matrixSslClearSessionId($sessID)
Crypt::MatrixSSL3::Client
new
$ssl = Crypt::MatrixSSL3::Client->new(
$keys, $sessID, \@cipherSuites,
\&certValidator, $expectedName,
$extensions, \&extensionCback,
);
matrixSslNewClientSession( $ssl,
$keys, $sessID, \@cipherSuites,
\&certValidator, $expectedName,
$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 the "CALLBACKS" section.
Crypt::MatrixSSL3::Server
new
$ssl = 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 the "CALLBACKS"
section.
init_SNI
$ssl->init_SNI( $sserver_index, $sni_params );
This function should be called only once when the server is
initialized.
Parameters:
$server_index
Server structure index returned by create_SSL_server()
$sni_params [{...},...] or undef
This is a reference to an array that contains one or more array
references:
$sni_params = [ # virtual hosts support - when a client sends a TLS SNI extension, the settings below will apply
# based on the requested hostname
# virtual host 0 (also referred in the code as SNI entry 0)
{
'hostname' => 'hostname', # regular expression for matching the hostname
'cert' => '/path/to/certificate;/path/to/CA-chain', # KEY - certificate (the CA-chain is optional)
'key' => '/path/to/private_key', # KEY - private key
'DH_param' => /path/to/DH_params', # KEY - file containing the DH parameter used with DH ciphers
'session_ticket_keys' => { # session tickets setup
'id' => '1234567890123456', # KEY - TLS session tickets - 16 bytes unique identifier
'encrypt_key' => '12345678901234567890123456789012', # KEY - TLS session tickets - 128/256 bit encryption key
'hash_key' => '12345678901234567890123456789012', # KEY - TLS session tickets - 256 bit hash key
},
'OCSP_staple' => '/path/to/OCSP_staple.der', # SESSION - file containing a OCSP staple that gets sent when a client
# send a TLS status request extension
'SCT_params' => [ # SESSION - Certificate Transparency SCT files used to build the
# 'signed_certificate_timestamp' TLS extension data buffer
'/path/to/SCT1.sct',
'/path/to/SCT2.sct',
...
],
# instead of the Certificate Transparency SCT files you can specify a scalar with a single file that contains multiple SCT files
# note that this file is not just a concatenation of the SCT files, but a ready-to-use 'signed_certificate_timestamp' TLS extension data buffer
# see ct-submit.pl for more info
#'SCT_params' => '/path/to/CT_extension_data_buffer',
'ALPN' => ['protocol1', 'protocol2'] # SESSION - server supported protocols
},
# virtual host 1
...
]
set_server_params
$ssl->set_server_params( $server_index, $sv_params );
Used to set the server supported protocols used when a client send a
TLS ALPN extension.
Note that this function call only affects the default server. Virtual
hosts are managed by using the $ssl->init_SNI(...).
See $ssl->init_SNI(...) for usage.
Parameters:
$server_index
Server structure index returned by create_SSL_server()
$sv_params {...} or undef
This is a reference to a hash with the following structure (all keys
are optional):
$sv_params = {
'ALPN' => ['protocol1', 'protocol2']
}
If you specify the 'ALPN' parameter, you should also provide an ALPN
callback. More information about callback "ALPNCallback" in the
"CALLBACKS" section.
set_callbacks
$ssl->set_callbacks( $server_index, $ssl_id );
Parameters:
$server_index
Server structure index returned by create_SSL_server()
$ssl_id
A 32 bit integer that uniquely identifies this session. This
parameter will be sent back when MatrixSSL calls the SNI callback
defined in the XS module when a client sends a SNI extension. If the
XS module is able to match the requested client hostname it will call
the Perl callback set with set_VHIndex_callback.
Crypt::MatrixSSL3::Client and Crypt::MatrixSSL3::Server
get_outdata
$rc = $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
Throw exception if matrixSslGetOutdata() returns < 0.
sent_data
$rc = $ssl->sent_data( $bytes );
matrixSslSentData( $ssl, $bytes )
received_data
$rc = $ssl->received_data( $inBuf, $ptBuf );
$n = matrixSslGetReadbuf( $ssl, $buf )
$n = min($n, length $inBuf)
$buf = substr($inBuf, 0, $n, q{})
matrixSslReceivedData( $ssl, $n, $ptBuf, $ptLen )
Combines two calls: matrixSslGetReadbuf() and matrixSslReceivedData().
It copy data from beginning of $inBuf into buffer returned by
matrixSslGetReadbuf() 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). Then it calls matrixSslReceivedData() to
get $rc and may fill $ptBuf with received alert or application data.
It is safe to call it with empty $inBuf, but this isn't a good idea
performance-wise.
Throw exception if matrixSslGetReadbuf() returns <= 0.
processed_data
$rc = $ssl->processed_data( $ptBuf );
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.
ALPNCallback
Will be called when a client sends an ALPN extension and a successful
application protocol has been negotiated. If the server doesn't
implement any of the client's protocols the XS module will send an
appropriate response and the client will receive a
SSL_ALERT_NO_APP_PROTOCOL alert.
Will be called with 2 parameters:
$ssl_id - this is the $ssl_id used in the $ssl->set_callbacks(...) call
$app_proto - scalar with the negociated protocol name
VHIndexCallback
Will be called whenever we have a successful match against the hostname
specified by the client in its SNI extension. This will inform the Perl
code which virtual host the current SSL session belongs to.
Will be called with 3 parameters:
$ssl_id - this is the $ssl_id used in the $ssl->set_callbacks(...) call
$index - a 0-based int specifying which virtual host matchd the client requested hostname
$match - a scalar containing the hostname sent in the client's SNI TLS extension
Doesn't return anything.
HOWTO: Certificate Transparency
PREREQUISITES
For generating Certificate Transparency files you will need the
following:
Certificates
* Server certificate (server.crt)
* Issuer certificate (issuer.crt)
* Certificate Authority chain (server-CA.crt) - this includes any
number of intermediate certificate and optionally ends with the root
certificate.
USING THE ct-submit.pl TOOL
Generate one file containing SCTs from all CT log servers
ct-submit.pl --pem server.crt --pem issuer.crt --pem server-CA.pem \
--extbuf /path/to/CT.sct
The resulted file can be used in your script like:
# set or refresh CT response for a SSL session (default server)
$sv_keys->load_SCT_response('/path/to/CT.sct');
Generate multiple SCT files containing binary representation of the
responses received from the log servers
ct-submit.pl --pem server.crt --pem issuer.crt --pem server-CA.pem \
--individual /path/to/sct/
This will create in the /path/to/stc/ folder the following files
(considering that the requests to the log servers were successful):
aviator.sct # https://ct.googleapis.com/aviator
certly.sct # https://log.certly.io
pilot.sct # https://ct.googleapis.com/pilot
rocketeer.sct # https://ct.googleapis.com/rocketeer
digicert.sct # https://ct1.digicert-ct.com/log - disabled by default -
# accepts certificates only from select CAs
izenpe.sct # https://ct.izenpe.com - disabled by default -
# accepts certificates only from select CAs
One or more files can be used in your script like:
# set or refresh CT response for a SSL session (default server)
# note that even if you're using a single file (which will be wrong
# according to the RFC because at least 2 SCTs from different server logs
# must be sent), you still need to provide an array reference with one element
$sv_keys->load_SCT_response([
'/path/to/sct/aviator.sct',
$server_sock = ...
# initialize default server keys - these will be shared by all server sessions
my $sv_keys = Crypt::MatrixSSL3::Keys->new();
# load key material (certificate, private key, etc)
$sv_keys->load_rsa(...);
# load OCSP response
$sv_keys->load_OCSP_response(...);
# load SCT response
$sv_keys->load_SCT_response(...);
...
# we assume when a client connects an accept_client sub will be called
sub accept_client {
# accept client socket
my $client_sock = accept($server_sock, ...);
# create server session reusing the keys
my $cssl = Crypt::MatrixSSL3::Server->new($sv_keys, undef);
# create a unique SSL session ID
# for example this can be the fileno of the client socket
my $ssl_id = fileno($client_sock);
# check if the server parameters are initialized
if ($server_index == -1) {
# tell the XS module to allocate a new SSL server structure
$server_index = Crypt::MatrixSSL3::create_SSL_server();
# set supported protocols for the default server.
$ssl->set_server_params($server_index, {
'ALPN' => [...]
});
# initialize virtual hosts:
# - allocates a SNI_entry structure for each virtual host and:
# - creates new server keys
# - sets up OCSP staple buffer (server keys - if needed)
# - sets up SCT buffer (server keys - if needed)
# - stores server implemented protocols if provided
$ssl->init_SNI($server_index, [
# see MatrixSSL.pm - init_SNI function
]);
}
# setup SNI/ALPN callback
# sets up the matrixSSL SNI callback that will get called if the client sends a SNI TLS extension
# in its CLIENT_HELLO message. When the XS SNI callback is called if any of the hostnames defined
# for each virtual host matches againt the client requested hostname, the &VHIndexCallback setup
# above will be called with the $ssl_id of the session and the 0-based index of the virtual host
# the client sent its request
# sets up the matrixSSL ALPN callback that will get called when the client sends an ALPN extension
# the &ALPNCallback is called with the provided $ssl_id and the selected protocol
$cssl->set_callbacks($server_index, $sll_id);
# further initialization stuff after accepting the client
...
}
# secure communication with the client
...
SEE ALSO
http://www.MatrixSSL.org - the download from this site includes simple
yet comprehensive documentation in PDF format.
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at
https://github.com/powerman/perl-Crypt-MatrixSSL3/issues. You will be
notified automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for
public review and contribution under the terms of the license. Feel
free to fork the repository and submit pull requests.
https://github.com/powerman/perl-Crypt-MatrixSSL3
git clone https://github.com/powerman/perl-Crypt-MatrixSSL3.git
Resources
* MetaCPAN Search
https://metacpan.org/search?q=Crypt-MatrixSSL3
* CPAN Ratings
http://cpanratings.perl.org/dist/Crypt-MatrixSSL3
* AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Crypt-MatrixSSL3
* CPAN Testers Matrix
http://matrix.cpantesters.org/?dist=Crypt-MatrixSSL3
* CPANTS: A CPAN Testing Service (Kwalitee)
http://cpants.cpanauthors.org/dist/Crypt-MatrixSSL3
AUTHORS
C. N. Drake <christopher@pobox.com>
Alex Efros <powerman@cpan.org>
COPYRIGHT AND LICENSE
( run in 1.836 second using v1.01-cache-2.11-cpan-cdf2f3d4e48 )