view release on metacpan or  search on metacpan

xs/sc_ssl/CTX.pod  view on Meta::CPAN

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