/ 
Crypt-NSS-0.01_04
River stage zero No dependents
/ Net::NSS::SSL

NAME

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

SYNOPSIS

INTERFACE

CLASS METHODS

Creating sockets

The prefered way of creating sockets is by using the 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 create_socket which in turn must be SSL enabled by calling import_into_ssl_layer before connecting or listening.

new ( ADDR, %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.

create_socket ( TYPE ) : Net::NSS::SSL

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

INSTANCE METHODS

Connecting to a host

set_URL ( URL | HOST )
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 handshake will fail.

connect ( HOST, PORT, [ TIMEOUT ] )

Conencts to the host HOST on the given PORT. The optional argument TIMEOUT sets how many seconds connect has to complete the connection setup. If ommited PR_INTERVAL_NO_TIMEOUT is used.

Listening and accepting incoming connections

bind ( HOST, PORT )

Binds an network address (HOST + PORT) to the socket.

listen ( [ QUEUE_LENGTH ] )

Listens for connections on the socket. The optional argument QUEUE_LENGTH is the maximum length of the queue of pending connections. Defaults to 10.

accept ( [ TIMEOUT ] ) : Net::NSS::SSL

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

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

Socket settings and security options

set_option ( OPTION, VALUE )
get_option ( OPTION ) : VALUE

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

KeepAlive ( 1 | 0 )

Periodically test whether connection is still alive.

NoDelay ( 1 | 0 )

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

Blocking ( 1 | 0 )

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

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

close ( )

Closes the socket.

import_into_ssl_layer ( )

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

set_pkcs11_pin_arg ( ARG )

Sets the argument that is passed along to pkcs11 callbacks for the given socket. ARG can be any Perl scalar.

set_verify_certificate_hook ( CODE )

Sets a custom hook to verify an incoming certificate. The hook is passed the 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 peer_certificate on the passed Net::NSS::SSL-object.

To indicate that verification was ok the hook must return SEC_SUCCESS, or SEC_FAILURE if not. Both constants are exported by requesting the tag :sec from 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 undef to this method.

Example:

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

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

set_client_certificate_auth_hook ( CODE [, NICKNAME | DATA] )

Sets a custom hook that is called when a server requests a certificate for authentication. The hook is passed the 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 Crypt::NSS::Certificate-object representing the authentication certificate and 2)

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 a nickname is set it uses that to find the right cert and key otherwise it scans the database for a match. To use the built-in hook pass "built-in" as the code argument.

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

peer_certificate ( ) : Crypt::NSS::Certificate

Returns the certificate recived from the remote end of the connection. If we're a client that means we get the servers certificate and if we're the server we get the clients authentication certificate (if used).

keysize () : INTEGER

Returns the length (in bits) of the key used in the session.

secret_keysize ( ) : INTEGER

Returns the length (in bits) of the secret part in the key used in the session. Also known as effective key size.

issuer ( ) : STRING

Returns the distinguished name of issuer for the certificate on the other side. Returns no certificate if no certificate is used.

cipher ( ) : STRING

Returns the name of the cipher used in the session.

subject ( ) : STRING

Returns the distinguished name of the certificate on the other side.

pending ( ) : INTEGER

Returns the number of bytes of data available for read.

peerhost ( ) : STRING

Returns the host of the remote side.

peerport ( ) : INTEGER

Returns the port on the remote side.

remove_from_session_cache ( )

Removes the socket from the session cache.

Reading and writing

read ( BUFFER [, CHUNK_SIZE] ) : INTEGER

Reads data the scalar passed as BUFFER 8192 bytes at the time or CHUNK_SIZE if specified. Returns the actual number of bytes read or 0 if we've reached EOF. This method is blocking.

write ( DATA ) : INTEGER