Sloop::Socket::TLS

DESCRIPTION

Implements low level I/O functionality -- sloop does not use the usual perl IO::Socket classes. This class is separate from Sloop::Connection, etc., so that it may be interchanged with Sloop::Socket::Standard.

REQUIRES

GnuTLS version 3.1.4 or higher.

SYNOPSIS

There is only one API subroutine, the non-OO Sloop::Socket::TLS::init(). This is normally run in the Sloop::Server constructor using arguments from the 'secure' hash, if present. However, if you wish to use a secure mode Sloop::Other with an insecure Sloop::Server, you must do it yourself before you call $sloop->connectOther(). If you wish to use a secure Other together with a secure Server, you must supply all the necessary arguments to the Sloop::Server constructor. This subroutine may only be called once per process. All subsequent calls will fail.

The return value is:

0 Success.

1 Ignored because it has been called already.

2 No err_log_fd specified.

3 Minimum GnuTLS version (3.1.4) not available.

<0 A GnuTLS error. These can be found in the GnuTLS documentation (http://gnutls.org/manual/html_node/Error-codes.html), but a string version is reported via the log.

The function takes one argument, a hash ref:

 Sloop::Socket::TLS::init ({
     certificateChain => scalar
     privKey => scalar
     password => scalar
     err_log_fd => integer
     logLevel => integer
     trustFile => scalar
     priority => scalar
 });

Notice unlike most sloop functions, the parameters are inside an actual {hash ref}, not in a list. Which arguments are required depends on the context of use.

certificateChain

A certificate or chain of certificates, in PEM form (e.g., a slurped file), used to validate the server. You need this and the corresponding private key (see below) in order to run a Sloop::Server in secure mode. You do not need it to use a Sloop::Other.

privKey

A scalar containing the private key corresponding to the 'certificateChain', above. This is not held in memory after the call.

password

Scalar containing the password for the private key, if required. This is not held in memory after the call.

logLevel

This is passed on to gnutls_global_set_log_level(): "The level is an integer between 0 and 9. Higher values mean more verbosity. The default value is 0."

err_log_fd

This is required if you call the function directly. For example:

 my $logger = Sloop::Logger->new();
 Sloop::TLS::init ({
     err_log_fd => fileno($logger->{logs}->[LOG_ERR])
 })

That's not simply the same as LOG_ERR, in the concept of file descriptors is foreign. If you do this via the Sloop::Server 'secure' hash, you don't have to supply this; the server Logger will be used.

trustFile

A path to a file containing trusted X509 certificates in PEM format. This is required to validate Sloop::Other connections unless you set that object's 'trustLevel' to Sloop::Other::Secure::TRUST_ALL. This isn't used for any other purpose, so you can just include certs for servers you intend to make Other connections to. If you aren't making any, don't worry about this.

priority

This is passed as the second argument to gnutls_priority_init(), defining what ciphers are allowed in order of preference. The default used by Sloop::Server is:

 NORMAL:%PARTIAL_RENEGOTIATION

The nature of the string is partially described in the man page, and more thoroughly in the GnuTLS guide:

http://gnutls.org/manual/html_node/Priority-Strings.html

Note this is not applied to Sloop::Other connections, which set it on a per object basis (see Sloop::Other::Secure).