view release on metacpan or  search on metacpan

lib/Net/NSS/SSL.pm  view on Meta::CPAN

pending connections. Defaults to 10.

=item configure_as_server ( $certificate : Crypt::NSS::Certificate, $private_key : Crypt::NSS::PrivateKey )

Configures a listening socket with the information needed to handshake as a SSL server. 

=item accept ( ) : Net::NSS::SSL
=item accept ( $timeout : integer ) : Net::NSS::SSL

Accepts a connection on the socket and returns the new socket used to communicate with the connected client. The 
optional argument I<$timeout> specified determined how long the connection setup might take. If ommited C<PR_INTERVAL_NO_TIMEOUT> is used.

This method blocks the calling thread until either a new connection is successfully accepted or an error occurs. 

=back

=head3 Handshaking

=over 4

=item reset_handshake ( $as_server : boolean )

Tells the the SSL library to start over with the handshake at the next I/O operation. This is not necessary for sockets 
that are already SSL:ed. The argument I<$as_server> tells whether the socket should handshake as server or client.

=back

=head3 Socket settings and security options

=over 4

=item set_option ( $option : string | integer, $value : scalar )

=item get_option ( $option : string | integer ) : scalar

Gets and sets socket options. The following options are valid:

=over 4

=item KeepAlive : boolean

Periodically test whether connection is still alive.

=item NoDelay : boolean

Disable Nagle algorithm. Don't delay send to coalesce packets.

=item Blocking : boolean

Do blocking or non-blocking (network) I/O.

=back

This method also works with SSL options if passed a numeric argument as exported by C<Crypt::NSS::Constants qw(:ssl)> and 
passing either C<SSL_OPTION_ENABLED> or C<SSL_OPTION_DISABLED> as the value.

=item set_pkcs11_pin_arg ( $arg : scalar  )

=item get_pkcs11_pin_arg ( ) : scalar

Sets or gets the argument that is passed along to pkcs11 callbacks for the given socket. I<$arg> can be any Perl scalar 
but in most cases you'll just want this to be a string. 

The default password callback (L<Crypt::NSS::PKCS11/set_password_hook>), returns this value.

=item set_URL ( $host : string )

=item get_URL ( ) : string

Set or get the domain name of the host we connect to (or actually what the CN in the servers certificate says). This 
is used in handshaking and if not matching the handshake will fail.

=item set_verify_certificate_hook ( $hook : coderef | string )

Sets a custom hook to verify an incoming certificate. The hook is passed the C<Net::NSS::SSL>-object that the 
hook is registered on, a boolean indicating whether signature should be checked and a boolean indicating if 
the certificate should be verified as a server (if true) or as a client (if false). The hook can obtain the 
certificate to be verified by calling C<peer_certificate> on the passed C<Net::NSS::SSL>-object.

To indicate that verification was ok the hook must return C<SEC_SUCCESS>, or C<SEC_FAILURE> if not. Both constants 
are exported by requesting the tag C<:sec> from C<Crypt::NSS::Constants>.

If not set, NSS uses a default hook that does the right thing in most cases. If you've replaced this with 
your own reverting to the built-in can be done by passing C<undef> to this method.

Example:

  sub my_verify_certificate_hook {
      my ($self, $check_signature, $is_server) = @_;
      
      my $cert = $self->peer_certificate():
      
      return SEC_SUCCESS;
  }

If you pass C<built-in-ignore> as the name we use a hook that never verifies the cert.

=item set_bad_certificate_hook ( $hook : coderef | string )

Sets a custom hook that is called when certficate authentication (the callback specified above) fails. 

=item set_client_certificate_hook ( $hook : coderef | string )

=item set_client_certificate_hook ( $hook : coderef | string, $arg : scalar )

Sets a custom hook that is called when a server requests a certificate for authentication. The hook is passed 
the C<Net::NSS::SSL>-object that is the subject of the authentication request and an array reference containing 
the names of the CAs the server accepts and optionally the nickname (or data) specified. The hook must return 
a 2-element list containing: 1) A C<Crypt::NSS::Certificate>-object representing the authentication certificate 
and 2) a C<Crypt::NSS::PrivateKey>-object representing the certificates private key.

By default no hook is set and one must be provided if your client application is to support client authentication. 

NSS provides a built-in hook that should be sufficient in most cases - if I<$arg> is set to a string it uses that 
as a nickname find the right cert and key otherwise it scans the database for a match. To use the built-in hook 
pass C<"built-in"> as the hook argument.

If you're using C<new> to construct the socket you can declare your callback using the key C<ClientAuthHook>.

=back