view release on metacpan or  search on metacpan

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

*get_keysize            = \&keysize;
*get_secret_keysize     = \&secret_keysize;
*get_issuer             = \&issuer;
*get_cipher             = \&cipher;

*syswrite = \&write;
*sysread = \&read;

1;
__END__

=head1 NAME

Net::NSS::SSL - SSL sockets using NSS

=head1 SYNOPSIS

=head1 INTERFACE

=head2 CLASS METHODS

=head3 Creating sockets

The prefered way of creating sockets is by using the C<new> constructor. This creates this socket, 
sets the desired options, imports it into SSL layer and connects to the peer host, or binds and sets up 
a listening socket, in the correct order. If you need more control it's possible to create a new socket 
using C<create_socket> which in turn must be SSL enabled by calling C<import_into_ssl_layer> before 
connecting or listening.

=over 4

=item new ( $address : string, %args ) : Net::NSS::SSL

=item new ( %args ) : Net::NSS::SSL

Creates a new socket, sets it up correctly, imports it into NSS SSL layer and optionally if it's a 
client-side socket connect to the remote host.

=over 4

=item PeerAddr : string

The peer to connect to in form of C<<host>>, C<<host>:<port>> or C<<host>:<service>> where host is either an IP number or a hostname, port 
a integer in the range 1-65535. If a service is specified such as C<http> or C<ftp>, its port number is looked up using C<getservbyname> with 
the proto C<tcp>.

=item PeerPort : string | integer

The numerical port or a service name to connect to. If I<PeerAddr> is specified it may take precedence over this. 

=item PeerHost : string

The host to connect to as either an IP number or a hostname. If I<PeerAddr> is specified is may take precedence over this.

=item Connect : boolean

If true then create the socket, import it into SSL, set the specfied options but don't connect. Defaults to false if omitted.

=item KeepAlive : boolean

Periodically test whether connection is still alive. Default to false if omitted.

=item Blocking : boolean

Blocking or non-blocking I/O. Default to 1 if omitted or what the class method C<blocking> returns if such exists.

=item SSL_PKCS11_PinArg : scalar

Sets the PKCS11 pin arg that is sent along to various funcions for the socket. 

See also: L<Net::NSS::SSL/set_pkcs11_pin_arg>

=item SSL_ClientCertHook : coderef | string

Sets the client certificte hook for the socket. If ommited defaults I<$DefaultClientCertHook> if one is defined.

See also: L<Net::NSS::SSL/set_client_certificate_hook>. 

=item SSL_ClientCertHookArg : scalar

Sets the client certificate hook argument for the socket. If ommited defaults to I<$DefaultClientCertHookArg> if defined.

=item SSL_CertVerifyHook : coderef | string

Sets the hook that is called to verify the certificate. If ommited defaults to I<$DefaultVerifyCertHook> if one is defined.

See also: L<Net::NSS::SSL/set_verify_certificate_hook>.

=item SSL_EnableOptions : arrayref

A list of options to enable where the items are either numeric or a constant name from C<Crypt::NSS::SSL::Constants>.

=item SSL_DisableOptions : arrayref

A list of options to enable where the items are either numeric or a constant name from C<Crypt::NSS::SSL::Constants>.

=item SSL_URL : string

Sets the host/URL that the server certificate will be verified against. If ommited defaults to I<$DefaultURL> if defined, 
otherwise uses I<PeerHost>.

=back

=item create_socket ( $type : string ) : Net::NSS::SSL

Creates a new socket of the I<TYPE> C<tcp> or C<udp>. Does not set any socket options nor imports it into 
the SSL layer. You probablly want to use C<new> instead of this method.

=item import_into_ssl_layer ( )

Imports the socket into NSS SSL layer if not already done. The constructor C<new> does this automatically for 
you.

=back

=head2 INSTANCE METHODS

=head3 Connecting to a host

This is done for you if you use C<new>.

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

Conencts to the host, I<$host>, on the given I<$port>. The optional argument I<$timeout> sets how many seconds 
connect has to complete the connection setup. If ommited C<PR_INTERVAL_NO_TIMEOUT> is used.

=back

=head3 Listening and accepting incoming connections

You don't need to bind and listen if you use C<new> to create your socket.

=over 4

=item bind ( $host : string, $port : integer ) 

Binds an the socket to a network address, ie host + port.

=item listen ( )
=item listen ( $queue_length : integer ) 

Listens for connections on the socket. The optional argument I<$queue_length> is the maximum length of the queue of 
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 )