NAME

Socket::Class::SSL::CTX - Shared context for Socket::Class::SSL

SYNOPSIS

  use Socket::Class::SSL;
  
  $ctx = Socket::Class::SSL::CTX->new( ... );
  
  $ssl = Socket::Class::SSL->new( 'use_ctx' => $ctx, ... );
  
  $ssl = Socket::Class::SSL->startssl( $sock, 'use_ctx' => $ctx, ... );

DESCRIPTION

The module creates shared ssl context for improved performance.

Functions in alphabetical order

check_private_key, enable_compatibility, new, set_certificate, set_cipher_list, set_client_ca, set_private_key, set_ssl_method, set_verify_locations,

EXAMPLES

SSL Server using fork

thanks to J. Nick Koston

  use Socket::Class::SSL;
  
  %ssl_args = (
      'private_key' => '/path/to/server.key.pem',
      'certificate' => '/path/to/server.crt.pem',
      'cipher_list' => 'ALL:!ADH:+HIGH:+MEDIUM:-LOW:-SSLv2:-EXP'
  );
  
  # create shared context
  $ssl_ctx = Socket::Class::SSL::CTX->new(
      'server' => 1,
      %ssl_args
  ) or die $@;
  
  # create listen socket
  $server = Socket::Class->new (
      'listen'     => 45,
      'proto'      => 'tcp',
      'local_port' => 10001,
      'reuseaddr'  => 1,
  );
  
  while( 1 ) {
      # test readability
      $server->select( 1, undef, undef, 5 ) or next;
      # accept client
      $socket = $server->accept() or next;
      if( fork() ) {
          # whats going on here?
          $socket->close();
      }
      else {
          # start ssl
          $ssl_socket = Socket::Class::SSL->startssl(
              $socket,
              'server'  => 1,
              'use_ctx' => $ssl_ctx,
              %ssl_args
          ) or die "Could not start ssl: $@";
          # speak to the client
          $ssl_socket->write( "SSL SERVER CONNETED OK\n" );
          # ...
          exit();
      }
  }

METHODS

new ( [%arg] )

Additional arguments for the constructor.

  certificate    Path to certificate file in PEM format
  private_key    Path to private key file in PEM format
  client_ca      Path to PEM formatted file with CA certificates
                 to send to the client
  ca_file        A file of CA certificates in PEM format
  ca_path        A directory containing CA certificates in PEM format
  ssl_method     One of "SSLv2", "SSLv23", "SSLv3" or "TLSv1"
                 default method is SSLv23
  cipher_list    A string representing a list of availables ciphers
                 The format is described at
                 http://www.openssl.org/docs/apps/ciphers.html
  server         Create server context on true value. False by default.

Detailed information about the arguments are documented in the functions below.

set_certificate ( $certificate )

Adds a certificate chain. The certificates must be in PEM format and must be sorted starting with the subject`s certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA.

Parameters

$certificate: Path to certificate file in PEM format.

Return Values

Returns a TRUE value on success or UNDEF on failure.

set_private_key ( $private_key ): Adds a private key to the socket. To change a certificate, private key pair the new certificate needs to be set before setting the private key.
Parameters

$private_key: Path to private key file in PEM format.

Return Values

Returns a TRUE value on success or UNDEF on failure.

check_private_key ()

Verifies that the private key agrees with the corresponding public key in the certificate.

Returns a TRUE value on success or UNDEF on failure.

The most likely causes of errors:

The private key file does not match the corresponding public key in the certificate.
A certificate file was not loaded.
A key file was not loaded.

set_client_ca ( $client_ca ): Reads a file of PEM formatted certificates and sets the list of CA names sent to the client when requesting a client certificate
Parameters

$client_ca: Path to PEM formatted file with CA certificates to send to the client.

Return Values

Returns a true value on success or undef on failure.

Note

The CAs listed do not become trusted (list only contains the names, not the complete certificates); use set_verify_locations() to additionally load them for verification.

These function is only useful for TLS/SSL servers.

set_verify_locations ( $ca_file, $ca_path )

Specifies the locations at which CA certificates for verification purposes are located.

When building its own certificate chain, an OpenSSL client/server will try to fill in missing certificates from $ca_file/$ca_path, if the certificate chain was not explicitly specified.

Parameters

$ca_file

If $ca_file is defined, it points to a file of CA certificates in PEM format. The file can contain several CA certificates identified by

 -----BEGIN CERTIFICATE-----
 ... (CA certificate in base64 encoding) ...
 -----END CERTIFICATE-----

sequences. Before, between, and after the certificates text is allowed which can be used e.g. for descriptions of the certificates.

$ca_path

If $ca_path is defined, it points to a directory containing CA certificates in PEM format. Each file contains one CA certificate. The files are looked up by the CA subject name hash value, which must be available. If more than one CA certificate with the same name hash value exists, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the order of the extension numbers, regardless of other properties of the certificates.

When looking up CA certificates, the OpenSSL library will search the certificates in $ca_file first, then those in $ca_path. Certificate matching is done based on the subject name, the key identifier (if present), and the serial number as taken from the certificate to be verified. If these data do not match, the next certificate will be tried. The verification process will be performed on the first matching certificate. In case of failure no other certificates with the same parameters are searched.

Return Values

Returns a true value on success or undef on failure.

Note

In server mode, when requesting a client certificate, the server must send the list of CAs to accept client certificates. This list is not influenced by the contents of $ca_file or $ca_path and must explicitly be set using the set_client_ca() function.

enable_compatibility (): Enables all bug workarounds available with the OpenSSL library.
See <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html> for a list.
set_ssl_method ( $name ): Sets the ssl method.
Parameters

$name: One of "SSLv2", "SSLv23", "SSLv3" or "TLSv1"

Return Values

Returns a true value on success or undef on failure.

set_cipher_list ( $str ): Sets the list of available ciphers using the control string $str.
Parameters

$str: The cipher list consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used.
See <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT> for details.

Return Values

Returns a true value on success or undef on failure.

AUTHORS

Christian Mueller, <http://www.alien-heads.org/>

COPYRIGHT AND LICENSE

This module is part of the Socket::Class::SSL module and stays under the same copyright and license agreements.