Crypt-MatrixSSL3

 view release on metacpan or  search on metacpan

MatrixSSL3.xs  view on Meta::CPAN

    }
#ifdef MATRIX_DEBUG
        warn("Returning SSL (default) server index: %d", server_index);
#endif
    RETVAL = server_index;

    OUTPUT:
    RETVAL


int sess_set_callbacks(ssl, server_index, ssl_id)
    Crypt_MatrixSSL3_Sess *ssl;
    int server_index = SvOK(ST(1)) ? SvIV(ST(1)) : -1;
    int ssl_id = SvOK(ST(2)) ? SvIV(ST(2)) : -1;
    p_SSL_data ssl_data = NULL;
    p_SSL_server ss = NULL;

    CODE:
    /* check if server_index points to a valid SSL server structure */
    if (server_index < 0)
        croak("Invalid SSL server index %d", server_index);

    if (server_index >= SSL_server_index)
        croak("Requested SSL server index out of range %d > %d", server_index, SSL_server_index - 1);

    /* just set the callback and we're done */
#ifdef MATRIX_DEBUG
    warn("Setting up SNI/ALPN callbacks for SSL server %d, ssl_id = %d, %p", server_index, ssl_id, SSL_servers[server_index]);
#endif

    /* set out SSL session custom data */
    ssl_data = (p_SSL_data) ssl->userPtr;

    ssl_data->ssl_id = ssl_id;
    ssl_data->server_index = server_index;

    /* get the SSL server strcuture */
    ss = SSL_servers[server_index];

README  view on Meta::CPAN

    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 $@;

README  view on Meta::CPAN

            \&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 )

README  view on Meta::CPAN

      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

README  view on Meta::CPAN

 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

README  view on Meta::CPAN

    
            # 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

lib/Crypt/MatrixSSL3.pm  view on Meta::CPAN

    set_ALPN_callback( \&ALPNCallback );

More information about L</ALPNCallback> in the L</CALLBACKS> section.

=head2 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.

=head1 CLASSES

Constructors for all classes will throw exception on error instead of
returning error as matrixSslNew*() functions do. Exception will be
thrown using C< 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 $@;

lib/Crypt/MatrixSSL3.pm  view on Meta::CPAN

        $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 L</certValidator> and L</extensionCback>
in the L</CALLBACKS> section.


=head2 Crypt::MatrixSSL3::Server

=head3 new

    $ssl = Crypt::MatrixSSL3::Server->new( $keys, \&certValidator );

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

lib/Crypt/MatrixSSL3.pm  view on Meta::CPAN

    $sv_params = {
        'ALPN' => ['protocol1', 'protocol2']
    }

If you specify the 'ALPN' parameter, you should also provide
an ALPN callback. More information about callback L</ALPNCallback>
in the L</CALLBACKS> section.

=back

=head3 set_callbacks

    $ssl->set_callbacks( $server_index, $ssl_id );

Parameters:

=over

=item $server_index

Server structure index returned by C<create_SSL_server()>

=item $ssl_id

lib/Crypt/MatrixSSL3.pm  view on Meta::CPAN

=head2 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

=head2 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.


=head1 HOWTO: Certificate Transparency

=head2 PREREQUISITES

lib/Crypt/MatrixSSL3.pm  view on Meta::CPAN

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


=head1 SEE ALSO