=head1 NAME

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


=head1 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, ... );

=head1 DESCRIPTION

The module creates shared ssl context for improved performance.

=head2 Functions in alphabetical order

=over

L<check_private_key|Socket::Class::SSL::CTX/check_private_key>,
L<enable_compatibility|Socket::Class::SSL::CTX/enable_compatibility>,
L<new|Socket::Class::SSL::CTX/new>,
L<set_certificate|Socket::Class::SSL::CTX/set_certificate>,
L<set_cipher_list|Socket::Class::SSL::CTX/set_cipher_list>,
L<set_client_ca|Socket::Class::SSL::CTX/set_client_ca>,
L<set_private_key|Socket::Class::SSL::CTX/set_private_key>,
L<set_ssl_method|Socket::Class::SSL::CTX/set_ssl_method>,
L<set_verify_locations|Socket::Class::SSL::CTX/set_verify_locations>,

=back

=head1 EXAMPLES

=head2 SSL Server using fork

I<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();
      }
  }

=head1 METHODS

=over

=item B<new ( [%arg] )>

Additional arguments for the constructor.

=for formatter none

  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.

=for formatter perl

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

=item B<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.

B<Parameters>

=over

=item I<$certificate>

Path to certificate file in PEM format.

=back

B<Return Values>

Returns a TRUE value on success or UNDEF on failure.

=item B<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.

B<Parameters>

=over

=item I<$private_key>

Path to private key file in PEM format.

=back

B<Return Values>

Returns a TRUE value on success or UNDEF on failure.

=item B<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: 

=over

=item * The private key file does not match the corresponding public key
in the certificate. 

=item * A certificate file was not loaded. 

=item * A key file was not loaded. 

=back

=item B<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

B<Parameters>

=over

=item I<$client_ca>

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

=back

B<Return Values>

Returns a true value on success or undef on failure.

B<Note>

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

These function is only useful for TLS/SSL servers.

=item B<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 I<$ca_file>/I<$ca_path>, if the
certificate chain was not explicitly specified.

B<Parameters>

=over

=item I<$ca_file>

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

=for formatter none

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

=for formatter perl

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

=item I<$ca_path>

If I<$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.

=back

When looking up CA certificates, the OpenSSL library will search the
certificates in I<$ca_file> first, then those in $I<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.

B<Return Values>

Returns a true value on success or undef on failure.

B<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 I<$ca_file> or I<$ca_path>
and must explicitly be set using the I<set_client_ca()> function. 

=item B<enable_compatibility ()>

Enables all bug workarounds available with the OpenSSL library.

See L<http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html> for a list.

=item B<set_ssl_method ( $name )>

Sets the ssl method.

B<Parameters>

=over

=item I<$name>

One of "SSLv2", "SSLv23", "SSLv3" or "TLSv1"

=back

B<Return Values>

Returns a true value on success or undef on failure.

=item B<set_cipher_list ( $str )>

Sets the list of available ciphers using the control string I<$str>.

B<Parameters>

=over

=item I<$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 L<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>
for details.

=back

B<Return Values>

Returns a true value on success or undef on failure.

=back

=head1 SEE ALSO

The L<Socket::Class::SSL> manpage

OpenSSL, L<http://www.openssl.org/>

=head1 AUTHORS

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

=head1 COPYRIGHT AND LICENSE

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

=cut