|
|
| |
CTX(3) |
User Contributed Perl Documentation |
CTX(3) |
Socket::Class::SSL::CTX - Shared context for Socket::Class::SSL
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, ... );
The module creates shared ssl context for improved performance.
check_private_key, enable_compatibility, new,
set_certificate, set_cipher_list, set_client_ca, set_private_key,
set_ssl_method, set_verify_locations,
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();
}
}
- 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.
The Socket::Class::SSL manpage
OpenSSL, <http://www.openssl.org/>
Christian Mueller, <http://www.alien-heads.org/>
This module is part of the Socket::Class::SSL module and stays under the same
copyright and license agreements.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |