2897 lines
104 KiB
HTML
2897 lines
104 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of IO::Socket::SSL</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>IO::Socket::SSL</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-14<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
IO::Socket::SSL - SSL sockets with IO::Socket interface
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use strict;
|
|
use IO::Socket::SSL;
|
|
|
|
# simple client
|
|
my $cl = IO::Socket::SSL->new('<A HREF="http://www.google.com">www.google.com</A>:443');
|
|
print $cl "GET / HTTP/1.0\r\n\r\n";
|
|
print <$cl>;
|
|
|
|
# simple server
|
|
my $srv = IO::Socket::SSL->new(
|
|
LocalAddr => '0.0.0.0:1234',
|
|
Listen => 10,
|
|
SSL_cert_file => 'server-cert.pem',
|
|
SSL_key_file => 'server-key.pem',
|
|
);
|
|
$srv->accept;
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
IO::Socket::SSL makes using <FONT SIZE="-1">SSL/TLS</FONT> much easier by wrapping the necessary
|
|
functionality into the familiar IO::Socket interface and providing secure
|
|
defaults whenever possible.
|
|
This way, existing applications can be made SSL-aware without much effort, at
|
|
least if you do blocking I/O and don't use select or poll.
|
|
<P>
|
|
|
|
But, under the hood, <FONT SIZE="-1">SSL</FONT> is a complex beast.
|
|
So there are lots of methods to make it do what you need if the default
|
|
behavior is not adequate.
|
|
Because it is easy to inadvertently introduce critical security bugs or just
|
|
hard to debug problems, I would recommend studying the following
|
|
documentation carefully.
|
|
<P>
|
|
|
|
The documentation consists of the following parts:
|
|
<DL COMPACT>
|
|
<DT id="1">•<DD>
|
|
``Essential Information About <FONT SIZE="-1">SSL/TLS''</FONT>
|
|
<DT id="2">•<DD>
|
|
``Basic <FONT SIZE="-1">SSL</FONT> Client''
|
|
<DT id="3">•<DD>
|
|
``Basic <FONT SIZE="-1">SSL</FONT> Server''
|
|
<DT id="4">•<DD>
|
|
``Common Usage Errors''
|
|
<DT id="5">•<DD>
|
|
``Common Problems with <FONT SIZE="-1">SSL''</FONT>
|
|
<DT id="6">•<DD>
|
|
``Using Non-Blocking Sockets''
|
|
<DT id="7">•<DD>
|
|
``Advanced Usage''
|
|
<DT id="8">•<DD>
|
|
``Integration Into Own Modules''
|
|
<DT id="9">•<DD>
|
|
``Description Of Methods''
|
|
</DL>
|
|
<P>
|
|
|
|
Additional documentation can be found in
|
|
<DL COMPACT>
|
|
<DT id="10">•<DD>
|
|
IO::Socket::SSL::Intercept - Doing Man-In-The-Middle with <FONT SIZE="-1">SSL</FONT>
|
|
<DT id="11">•<DD>
|
|
IO::Socket::SSL::Utils - Useful functions for certificates etc
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>Essential Information About SSL/TLS</H2>
|
|
|
|
|
|
|
|
<FONT SIZE="-1">SSL</FONT> (Secure Socket Layer) or its successor <FONT SIZE="-1">TLS</FONT> (Transport Layer Security) are
|
|
protocols to facilitate end-to-end security. These protocols are used when
|
|
accessing web sites (https), delivering or retrieving email, and in lots of other
|
|
use cases.
|
|
In the following documentation we will refer to both <FONT SIZE="-1">SSL</FONT> and <FONT SIZE="-1">TLS</FONT> as simply '<FONT SIZE="-1">SSL</FONT>'.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">SSL</FONT> enables end-to-end security by providing two essential functions:
|
|
<DL COMPACT>
|
|
<DT id="12">Encryption<DD>
|
|
|
|
|
|
This part encrypts the data for transit between the communicating parties, so
|
|
that nobody in between can read them. It also provides tamper resistance so that
|
|
nobody in between can manipulate the data.
|
|
<DT id="13">Identification<DD>
|
|
|
|
|
|
This part makes sure that you talk to the right peer.
|
|
If the identification is done incorrectly it is easy to mount man-in-the-middle
|
|
attacks, e.g. if Alice wants to talk to Bob it would be possible for Mallory to
|
|
put itself in the middle, so that Alice talks to Mallory and Mallory to Bob.
|
|
All the data would still be encrypted, but not end-to-end between Alice and Bob,
|
|
but only between Alice and Mallory and then between Mallory and Bob.
|
|
Thus Mallory would be able to read and modify all traffic between Alice and Bob.
|
|
</DL>
|
|
<P>
|
|
|
|
Identification is the part which is the hardest to understand and the easiest
|
|
to get wrong.
|
|
<P>
|
|
|
|
With <FONT SIZE="-1">SSL,</FONT> the Identification is usually done with <B>certificates</B> inside a <B></B><FONT SIZE="-1"><B>PKI</B></FONT><B></B>
|
|
(Public Key Infrastructure).
|
|
These Certificates are comparable to an identity card, which contains
|
|
information about the owner of the card. The card then is somehow <B>signed</B> by
|
|
the <B>issuer</B> of the card, the <B></B><FONT SIZE="-1"><B>CA</B></FONT><B></B> (Certificate Agency).
|
|
<P>
|
|
|
|
To verify the identity of the peer the following must be done inside <FONT SIZE="-1">SSL:</FONT>
|
|
<DL COMPACT>
|
|
<DT id="14">•<DD>
|
|
Get the certificate from the peer.
|
|
If the peer does not present a certificate we cannot verify it.
|
|
<DT id="15">•<DD>
|
|
Check if we trust the certificate, e.g. make sure it's not a forgery.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
We believe that a certificate is not a fake if we either know the certificate
|
|
already or if we <B>trust</B> the issuer (the <FONT SIZE="-1">CA</FONT>) and can verify the issuers
|
|
signature on the certificate.
|
|
In reality there is often a hierarchy of certificate agencies and we only
|
|
directly trust the root of this hierarchy.
|
|
In this case the peer not only sends his own certificate, but also all
|
|
<B>intermediate certificates</B>.
|
|
Verification will be done by building a <B>trust path</B> from the trusted root up
|
|
to the peers certificate and checking in each step if the we can verify the
|
|
issuer's signature.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This step often causes problems because the client does not know the necessary
|
|
trusted root certificates. These are usually stored in a system dependent
|
|
<FONT SIZE="-1">CA</FONT> store, but often the browsers have their own <FONT SIZE="-1">CA</FONT> store.
|
|
<DT id="16">•<DD>
|
|
Check if the certificate is still valid.
|
|
Each certificate has a lifetime and should not be used after that time because
|
|
it might be compromised or the underlying cryptography got broken in the mean
|
|
time.
|
|
<DT id="17">•<DD>
|
|
Check if the subject of the certificate matches the peer.
|
|
This is like comparing the picture on the identity card against the person
|
|
representing the identity card.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When connecting to a server this is usually done by comparing the hostname used
|
|
for connecting against the names represented in the certificate.
|
|
A certificate might contain multiple names or wildcards, so that it can be used
|
|
for multiple hosts (e.g. *.example.com and *.example.org).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Although nobody sane would accept an identity card where the picture does not
|
|
match the person we see, it is a common implementation error with <FONT SIZE="-1">SSL</FONT> to omit
|
|
this check or get it wrong.
|
|
<DT id="18">•<DD>
|
|
Check if the certificate was revoked by the issuer.
|
|
This might be the case if the certificate was compromised somehow and now
|
|
somebody else might use it to claim the wrong identity.
|
|
Such revocations happened a lot after the heartbleed attack.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For <FONT SIZE="-1">SSL</FONT> there are two ways to verify a revocation, <FONT SIZE="-1">CRL</FONT> and <FONT SIZE="-1">OCSP.</FONT>
|
|
With CRLs (Certificate Revocation List) the <FONT SIZE="-1">CA</FONT> provides a list of serial numbers
|
|
for revoked certificates. The client somehow has to download the list
|
|
(which can be huge) and keep it up to date.
|
|
With <FONT SIZE="-1">OCSP</FONT> (Online Certificate Status Protocol) the client can check a single
|
|
certificate directly by asking the issuer.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Revocation is the hardest part of the verification and none of today's browsers
|
|
get it fully correct. But, they are still better than most other implementations
|
|
which don't implement revocation checks or leave the hard parts to the
|
|
developer.
|
|
</DL>
|
|
<P>
|
|
|
|
When accessing a web site with <FONT SIZE="-1">SSL</FONT> or delivering mail in a secure way the
|
|
identity is usually only checked one way, e.g. the client wants to make sure it
|
|
talks to the right server, but the server usually does not care which client it
|
|
talks to.
|
|
But, sometimes the server wants to identify the client too and will request a
|
|
certificate from the client which the server must verify in a similar way.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>Basic SSL Client</H2>
|
|
|
|
|
|
|
|
A basic <FONT SIZE="-1">SSL</FONT> client is simple:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $client = IO::Socket::SSL->new('<A HREF="http://www.example.com">www.example.com</A>:443')
|
|
or die "error=$!, ssl_error=$SSL_ERROR";
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This will take the OpenSSL default <FONT SIZE="-1">CA</FONT> store as the store for the trusted <FONT SIZE="-1">CA.</FONT>
|
|
This usually works on <FONT SIZE="-1">UNIX</FONT> systems.
|
|
If there are no certificates in the store it will try use Mozilla::CA which
|
|
provides the default CAs of Firefox.
|
|
<P>
|
|
|
|
In the default settings, IO::Socket::SSL will use a safer cipher set and <FONT SIZE="-1">SSL</FONT>
|
|
version, do a proper hostname check against the certificate, and use <FONT SIZE="-1">SNI</FONT> (server
|
|
name indication) to send the hostname inside the <FONT SIZE="-1">SSL</FONT> handshake. This is
|
|
necessary to work with servers which have different certificates behind the
|
|
same <FONT SIZE="-1">IP</FONT> address.
|
|
It will also check the revocation of the certificate with <FONT SIZE="-1">OCSP,</FONT> but currently
|
|
only if the server provides <FONT SIZE="-1">OCSP</FONT> stapling (for deeper checks see
|
|
<TT>"ocsp_resolver"</TT> method).
|
|
<P>
|
|
|
|
Lots of options can be used to change ciphers, <FONT SIZE="-1">SSL</FONT> version, location of <FONT SIZE="-1">CA</FONT> and
|
|
much more. See documentation of methods for details.
|
|
<P>
|
|
|
|
With protocols like <FONT SIZE="-1">SMTP</FONT> it is necessary to upgrade an existing socket to <FONT SIZE="-1">SSL.</FONT>
|
|
This can be done like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $client = IO::Socket::INET->new('mx.example.com:25') or die $!;
|
|
# .. read greeting from server
|
|
# .. send EHLO and read response
|
|
# .. send STARTTLS command and read response
|
|
# .. if response was successful we can upgrade the socket to SSL now:
|
|
IO::Socket::SSL->start_SSL($client,
|
|
# explicitly set hostname we should use for SNI
|
|
SSL_hostname => 'mx.example.com'
|
|
) or die $SSL_ERROR;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
A more complete example for a simple <FONT SIZE="-1">HTTP</FONT> client:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $client = IO::Socket::SSL->new(
|
|
# where to connect
|
|
PeerHost => "<A HREF="http://www.example.com">www.example.com</A>",
|
|
PeerPort => "https",
|
|
|
|
# certificate verification - VERIFY_PEER is default
|
|
SSL_verify_mode => SSL_VERIFY_PEER,
|
|
|
|
# location of CA store
|
|
# need only be given if default store should not be used
|
|
SSL_ca_path => '/etc/ssl/certs', # typical CA path on Linux
|
|
SSL_ca_file => '/etc/ssl/cert.pem', # typical CA file on BSD
|
|
|
|
# or just use default path on system:
|
|
IO::Socket::SSL::default_ca(), # either explicitly
|
|
# or implicitly by not giving SSL_ca_*
|
|
|
|
# easy hostname verification
|
|
# It will use PeerHost as default name a verification
|
|
# scheme as default, which is safe enough for most purposes.
|
|
SSL_verifycn_name => 'foo.bar',
|
|
SSL_verifycn_scheme => 'http',
|
|
|
|
# SNI support - defaults to PeerHost
|
|
SSL_hostname => 'foo.bar',
|
|
|
|
) or die "failed connect or ssl handshake: $!,$SSL_ERROR";
|
|
|
|
# send and receive over SSL connection
|
|
print $client "GET / HTTP/1.0\r\n\r\n";
|
|
print <$client>;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
And to do revocation checks with <FONT SIZE="-1">OCSP</FONT> (only available with OpenSSL 1.0.0 or
|
|
higher and Net::SSLeay 1.59 or higher):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
# default will try OCSP stapling and check only leaf certificate
|
|
my $client = IO::Socket::SSL->new($dst);
|
|
|
|
# better yet: require checking of full chain
|
|
my $client = IO::Socket::SSL->new(
|
|
PeerAddr => $dst,
|
|
SSL_ocsp_mode => SSL_OCSP_FULL_CHAIN,
|
|
);
|
|
|
|
# even better: make OCSP errors fatal
|
|
# (this will probably fail with lots of sites because of bad OCSP setups)
|
|
# also use common OCSP response cache
|
|
my $ocsp_cache = IO::Socket::SSL::OCSP_Cache->new;
|
|
my $client = IO::Socket::SSL->new(
|
|
PeerAddr => $dst,
|
|
SSL_ocsp_mode => SSL_OCSP_FULL_CHAIN|SSL_OCSP_FAIL_HARD,
|
|
SSL_ocsp_cache => $ocsp_cache,
|
|
);
|
|
|
|
# disable OCSP stapling in case server has problems with it
|
|
my $client = IO::Socket::SSL->new(
|
|
PeerAddr => $dst,
|
|
SSL_ocsp_mode => SSL_OCSP_NO_STAPLE,
|
|
);
|
|
|
|
# check any certificates which are not yet checked by OCSP stapling or
|
|
# where we have already cached results. For your own resolving combine
|
|
# $ocsp->requests with $ocsp->add_response(uri,response).
|
|
my $ocsp = $client->ocsp_resolver();
|
|
my $errors = $ocsp->resolve_blocking();
|
|
if ($errors) {
|
|
warn "OCSP verification failed: $errors";
|
|
close($client);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>Basic SSL Server</H2>
|
|
|
|
|
|
|
|
A basic <FONT SIZE="-1">SSL</FONT> server looks similar to other IO::Socket servers, only that it
|
|
also contains settings for certificate and key:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
# simple server
|
|
my $server = IO::Socket::SSL->new(
|
|
# where to listen
|
|
LocalAddr => '127.0.0.1',
|
|
LocalPort => 8080,
|
|
Listen => 10,
|
|
|
|
# which certificate to offer
|
|
# with SNI support there can be different certificates per hostname
|
|
SSL_cert_file => 'cert.pem',
|
|
SSL_key_file => 'key.pem',
|
|
) or die "failed to listen: $!";
|
|
|
|
# accept client
|
|
my $client = $server->accept or die
|
|
"failed to accept or ssl handshake: $!,$SSL_ERROR";
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This will automatically use a secure set of ciphers and <FONT SIZE="-1">SSL</FONT> version and also
|
|
supports Forward Secrecy with (Elliptic-Curve) Diffie-Hellmann Key Exchange.
|
|
<P>
|
|
|
|
If you are doing a forking or threading server, we recommend that you do the <FONT SIZE="-1">SSL</FONT>
|
|
handshake inside the new process/thread so that the master is free for new
|
|
connections.
|
|
We recommend this because a client with improper or slow <FONT SIZE="-1">SSL</FONT> handshake could
|
|
make the server block in the handshake which would be bad to do on the
|
|
listening socket:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
# inet server
|
|
my $server = IO::Socket::INET->new(
|
|
# where to listen
|
|
LocalAddr => '127.0.0.1',
|
|
LocalPort => 8080,
|
|
Listen => 10,
|
|
);
|
|
|
|
# accept client
|
|
my $client = $server->accept or die;
|
|
|
|
# SSL upgrade client (in new process/thread)
|
|
IO::Socket::SSL->start_SSL($client,
|
|
SSL_server => 1,
|
|
SSL_cert_file => 'cert.pem',
|
|
SSL_key_file => 'key.pem',
|
|
) or die "failed to ssl handshake: $SSL_ERROR";
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Like with normal sockets, neither forking nor threading servers scale well.
|
|
It is recommended to use non-blocking sockets instead, see
|
|
``Using Non-Blocking Sockets''
|
|
<A NAME="lbAH"> </A>
|
|
<H2>Common Usage Errors</H2>
|
|
|
|
|
|
|
|
This is a list of typical errors seen with the use of IO::Socket::SSL:
|
|
<DL COMPACT>
|
|
<DT id="19">•<DD>
|
|
Disabling verification with <TT>"SSL_verify_mode"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
As described in ``Essential Information About <FONT SIZE="-1">SSL/TLS''</FONT>, a proper
|
|
identification of the peer is essential and failing to verify makes
|
|
Man-In-The-Middle attacks possible.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Nevertheless, lots of scripts and even public modules or applications disable
|
|
verification, because it is probably the easiest way to make the thing work
|
|
and usually nobody notices any security problems anyway.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the verification does not succeed with the default settings, one can do the
|
|
following:
|
|
<DL COMPACT><DT id="20"><DD>
|
|
<DL COMPACT>
|
|
<DT id="21">•<DD>
|
|
Make sure the needed CAs are in the store, maybe use <TT>"SSL_ca_file"</TT> or
|
|
<TT>"SSL_ca_path"</TT> to specify a different <FONT SIZE="-1">CA</FONT> store.
|
|
<DT id="22">•<DD>
|
|
If the validation fails because the certificate is self-signed and that's what
|
|
you expect, you can use the <TT>"SSL_fingerprint"</TT> option to accept specific
|
|
leaf certificates by their certificate or pubkey fingerprint.
|
|
<DT id="23">•<DD>
|
|
If the validation failed because the hostname does not match and you cannot
|
|
access the host with the name given in the certificate, you can use
|
|
<TT>"SSL_verifycn_name"</TT> to specify the hostname you expect in the certificate.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="24"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A common error pattern is also to disable verification if they found no <FONT SIZE="-1">CA</FONT>
|
|
store (different modules look at different ``default'' places).
|
|
Because IO::Socket::SSL is now able to provide a usable <FONT SIZE="-1">CA</FONT> store on most
|
|
platforms (<FONT SIZE="-1">UNIX,</FONT> Mac <FONT SIZE="-1">OSX</FONT> and Windows) it is better to use the defaults provided
|
|
by IO::Socket::SSL.
|
|
If necessary these can be checked with the <TT>"default_ca"</TT> method.
|
|
</DL>
|
|
|
|
<DT id="25">•<DD>
|
|
Polling of <FONT SIZE="-1">SSL</FONT> sockets (e.g. select, poll and other event loops).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you sysread one byte on a normal socket it will result in a syscall to read
|
|
one byte. Thus, if more than one byte is available on the socket it will be kept
|
|
in the network stack of your <FONT SIZE="-1">OS</FONT> and the next select or poll call will return the
|
|
socket as readable.
|
|
But, with <FONT SIZE="-1">SSL</FONT> you don't deliver single bytes. Multiple data bytes are packaged
|
|
and encrypted together in an <FONT SIZE="-1">SSL</FONT> frame. Decryption can only be done on the whole
|
|
frame, so a sysread for one byte actually reads the complete <FONT SIZE="-1">SSL</FONT> frame from the
|
|
socket, decrypts it and returns the first decrypted byte. Further sysreads will
|
|
return more bytes from the same frame until all bytes are returned and the
|
|
next <FONT SIZE="-1">SSL</FONT> frame will be read from the socket.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Thus, in order to decide if you can read more data (e.g. if sysread will block)
|
|
you must check if there are still data in the current <FONT SIZE="-1">SSL</FONT> frame by calling
|
|
<TT>"pending"</TT> and if there are no data pending you might check the underlying
|
|
socket with select or poll.
|
|
Another way might be if you try to sysread at least 16kByte all the time.
|
|
16kByte is the maximum size of an <FONT SIZE="-1">SSL</FONT> frame and because sysread returns data
|
|
from only a single <FONT SIZE="-1">SSL</FONT> frame you can guarantee that there are no pending
|
|
data.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Additionally, contrary to plain sockets the data delivered on the socket are
|
|
not necessarily application payload.
|
|
It might be a <FONT SIZE="-1">TLS</FONT> handshake, it might just be the beginning of a <FONT SIZE="-1">TLS</FONT> record or
|
|
it might be <FONT SIZE="-1">TLS</FONT> session tickets which are send after the <FONT SIZE="-1">TLS</FONT> handshake in <FONT SIZE="-1">TLS
|
|
1.3.</FONT>
|
|
In such situations select will return that data are available for read since it
|
|
only looks at the plain socket.
|
|
A sysread on the IO::Socket::SSL socket will not return any data though since it
|
|
is an abstraction which only returns application data.
|
|
This causes the sysread to hang in case the socket was blocking or to return
|
|
an error with <FONT SIZE="-1">EAGAIN</FONT> on non-blocking sockets.
|
|
Applications using select or similar should therefore set the socket to
|
|
non-blocking and also expect that the sysread might temporarily fail with
|
|
<FONT SIZE="-1">EAGAIN.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See also ``Using Non-Blocking Sockets''.
|
|
<DT id="26">•<DD>
|
|
Expecting exactly the same behavior as plain sockets.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
IO::Socket::SSL tries to emulate the usual socket behavior as good as possible,
|
|
but full emulation can not be done. Specifically a read on the <FONT SIZE="-1">SSL</FONT> socket might
|
|
also result in a write on the <FONT SIZE="-1">TCP</FONT> socket or a write on the <FONT SIZE="-1">SSL</FONT> socket might
|
|
result in a read on the <FONT SIZE="-1">TCP</FONT> socket. Also <TT>"accept"</TT> and <B>close</B> on the <FONT SIZE="-1">SSL</FONT>
|
|
socket will result in writing and reading data to the <FONT SIZE="-1">TCP</FONT> socket too.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Especially the hidden writes might result in a connection reset if the
|
|
underlying <FONT SIZE="-1">TCP</FONT> socket is already closed by the peer. Unless signal <FONT SIZE="-1">PIPE</FONT> is
|
|
explicitly handled by the application this will usually result in the
|
|
application crashing. It is thus recommended to explicitly <FONT SIZE="-1">IGNORE</FONT> signal <FONT SIZE="-1">PIPE</FONT> so
|
|
that the errors get propagated as <FONT SIZE="-1">EPIPE</FONT> instead of causing a crash of the
|
|
application.
|
|
<DT id="27">•<DD>
|
|
Set 'SSL_version' or 'SSL_cipher_list' to a ``better'' value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
IO::Socket::SSL tries to set these values to reasonable, secure values which
|
|
are compatible with the rest of the world.
|
|
But, there are some scripts or modules out there which tried to be smart and
|
|
get more secure or compatible settings.
|
|
Unfortunately, they did this years ago and never updated these values, so they
|
|
are still forced to do only 'TLSv1' (instead of also using TLSv12 or TLSv11).
|
|
Or they set '<FONT SIZE="-1">HIGH</FONT>' as the cipher list and thought they were secure, but did not
|
|
notice that '<FONT SIZE="-1">HIGH</FONT>' includes anonymous ciphers, e.g. without identification of
|
|
the peer.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
So it is recommended to leave the settings at the secure defaults which
|
|
IO::Socket::SSL sets and which get updated from time to time to
|
|
better fit the real world.
|
|
<DT id="28">•<DD>
|
|
Make <FONT SIZE="-1">SSL</FONT> settings inaccessible by the user, together with bad builtin settings.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Some modules use IO::Socket::SSL, but don't make the <FONT SIZE="-1">SSL</FONT> settings available
|
|
to the user. This is often combined with bad builtin settings or defaults (like
|
|
switching verification off).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Thus the user needs to hack around these restrictions by using
|
|
<TT>"set_args_filter_hack"</TT> or similar.
|
|
<DT id="29">•<DD>
|
|
Use of constants as strings.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Constants like <TT>"SSL_VERIFY_PEER"</TT> or <TT>"SSL_WANT_READ"</TT> should be used as
|
|
constants and not be put inside quotes, because they represent numerical values.
|
|
<DT id="30">•<DD>
|
|
Forking and handling the socket in parent and child.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A <B>fork</B> of the process will duplicate the internal user space <FONT SIZE="-1">SSL</FONT> state of the
|
|
socket. If both master and child interact with the socket by using their own <FONT SIZE="-1">SSL</FONT>
|
|
state strange error messages will happen. Such interaction includes explicit or
|
|
implicit <B>close</B> of the <FONT SIZE="-1">SSL</FONT> socket. To avoid this the socket should be explicitly
|
|
closed with <B>SSL_no_shutdown</B>.
|
|
<DT id="31">•<DD>
|
|
Forking and executing a new process.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Since the <FONT SIZE="-1">SSL</FONT> state is stored in user space it will be duplicated by a <B>fork</B> but
|
|
it will be lost when doing <B>exec</B>. This means it is not possible to simply
|
|
redirect stdin and stdout for the new process to the <FONT SIZE="-1">SSL</FONT> socket by duplicating
|
|
the relevant file handles. Instead explicitly exchanging plain data between
|
|
child-process and <FONT SIZE="-1">SSL</FONT> socket are needed.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>Common Problems with SSL</H2>
|
|
|
|
|
|
|
|
<FONT SIZE="-1">SSL</FONT> is a complex protocol with multiple implementations and each of these has
|
|
their own quirks. While most of these implementations work together, it often
|
|
gets problematic with older versions, minimal versions in load balancers, or plain
|
|
wrong setups.
|
|
<P>
|
|
|
|
Unfortunately these problems are hard to debug.
|
|
Helpful for debugging are a knowledge of <FONT SIZE="-1">SSL</FONT> internals, wireshark and the use of
|
|
the debug settings of IO::Socket::SSL and Net::SSLeay, which can both be
|
|
set with <TT>$IO::Socket::SSL::DEBUG</TT>.
|
|
The following debugs levels are defined, but used not in any consistent way:
|
|
<DL COMPACT>
|
|
<DT id="32">•<DD>
|
|
0 - No debugging (default).
|
|
<DT id="33">•<DD>
|
|
1 - Print out errors from IO::Socket::SSL and ciphers from Net::SSLeay.
|
|
<DT id="34">•<DD>
|
|
2 - Print also information about call flow from IO::Socket::SSL and progress
|
|
information from Net::SSLeay.
|
|
<DT id="35">•<DD>
|
|
3 - Print also some data dumps from IO::Socket::SSL and from Net::SSLeay.
|
|
</DL>
|
|
<P>
|
|
|
|
Also, <TT>"analyze-ssl.pl"</TT> from the ssl-tools repository at
|
|
<<A HREF="https://github.com/noxxi/p5-ssl-tools">https://github.com/noxxi/p5-ssl-tools</A>> might be a helpful tool when debugging
|
|
<FONT SIZE="-1">SSL</FONT> problems, as do the <TT>"openssl"</TT> command line tool and a check with a
|
|
different <FONT SIZE="-1">SSL</FONT> implementation (e.g. a web browser).
|
|
<P>
|
|
|
|
The following problems are not uncommon:
|
|
<DL COMPACT>
|
|
<DT id="36">•<DD>
|
|
Bad server setup: missing intermediate certificates.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is a regular problem that administrators fail to include all necessary
|
|
certificates into their server setup, e.g. everything needed to build the trust
|
|
chain from the trusted root.
|
|
If they check the setup with the browser everything looks ok, because browsers
|
|
work around these problems by caching any intermediate certificates and apply
|
|
them to new connections if certificates are missing.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
But, fresh browser profiles which have never seen these intermediates cannot
|
|
fill in the missing certificates and fail to verify; the same is true with
|
|
IO::Socket::SSL.
|
|
<DT id="37">•<DD>
|
|
Old versions of servers or load balancers which do not understand specific <FONT SIZE="-1">TLS</FONT>
|
|
versions or croak on specific data.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
From time to time one encounters an <FONT SIZE="-1">SSL</FONT> peer, which just closes the connection
|
|
inside the <FONT SIZE="-1">SSL</FONT> handshake. This can usually be worked around by downgrading the
|
|
<FONT SIZE="-1">SSL</FONT> version, e.g. by setting <TT>"SSL_version"</TT>. Modern Browsers usually deal with
|
|
such servers by automatically downgrading the <FONT SIZE="-1">SSL</FONT> version and repeat the
|
|
connection attempt until they succeed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Worse servers do not close the underlying <FONT SIZE="-1">TCP</FONT> connection but instead just
|
|
drop the relevant packet. This is harder to detect because it looks like a
|
|
stalled connection. But downgrading the <FONT SIZE="-1">SSL</FONT> version often works here too.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A cause of such problems are often load balancers or security devices, which
|
|
have hardware acceleration and only a minimal (and less robust) <FONT SIZE="-1">SSL</FONT> stack. They
|
|
can often be detected because they support much fewer ciphers than other
|
|
implementations.
|
|
<DT id="38">•<DD>
|
|
Bad or old OpenSSL versions.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
IO::Socket::SSL uses OpenSSL with the help of the Net::SSLeay library. It
|
|
is recommend to have a recent version of this library, because it has more
|
|
features and usually fewer known bugs.
|
|
<DT id="39">•<DD>
|
|
Validation of client certificates fail.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Make sure that the purpose of the certificate allows use as ssl client (check
|
|
with <TT>"openssl x509 -purpose"</TT>, that the necessary root certificate is in the
|
|
path specified by <TT>"SSL_ca*"</TT> (or the default path) and that any intermediate
|
|
certificates needed to build the trust chain are sent by the client.
|
|
<DT id="40">•<DD>
|
|
Validation of self-signed certificate fails even if it is given with
|
|
<TT>"SSL_ca*"</TT> argument.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"SSL_ca*"</TT> arguments do not give a general trust store for arbitrary
|
|
certificates but only specify a store for <FONT SIZE="-1">CA</FONT> certificates which then can be used
|
|
to verify other certificates. This especially means that certificates which are
|
|
not a <FONT SIZE="-1">CA</FONT> get simply ignored, notably self-signed certificates which do not also
|
|
have the CA-flag set.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This behavior of OpenSSL differs from the more general trust-store concept which
|
|
can be found in browsers and where it is possible to simply added arbitrary
|
|
certificates (<FONT SIZE="-1">CA</FONT> or not) as trusted.
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>Using Non-Blocking Sockets</H2>
|
|
|
|
|
|
|
|
If you have a non-blocking socket, the expected behavior on read, write, accept
|
|
or connect is to set <TT>$!</TT> to <FONT SIZE="-1">EWOULDBLOCK</FONT> if the operation cannot be completed
|
|
immediately. Note that <FONT SIZE="-1">EWOULDBLOCK</FONT> is the same as <FONT SIZE="-1">EAGAIN</FONT> on <FONT SIZE="-1">UNIX</FONT> systems, but
|
|
is different on Windows.
|
|
<P>
|
|
|
|
With <FONT SIZE="-1">SSL,</FONT> handshakes might occur at any time, even within an established
|
|
connection. In these cases it is necessary to finish the handshake before
|
|
you can read or write data. This might result in situations where you want to
|
|
read but must first finish the write of a handshake or where you want to write
|
|
but must first finish a read.
|
|
In these cases <TT>$!</TT> is set to <FONT SIZE="-1">EAGAIN</FONT> like expected, and additionally
|
|
<TT>$SSL_ERROR</TT> is set to either <FONT SIZE="-1">SSL_WANT_READ</FONT> or <FONT SIZE="-1">SSL_WANT_WRITE.</FONT>
|
|
Thus if you get <FONT SIZE="-1">EWOULDBLOCK</FONT> on a <FONT SIZE="-1">SSL</FONT> socket you must check <TT>$SSL_ERROR</TT> for
|
|
SSL_WANT_* and adapt your event mask accordingly.
|
|
<P>
|
|
|
|
Using readline on non-blocking sockets does not make much sense and I would
|
|
advise against using it.
|
|
And, while the behavior is not documented for other IO::Socket classes, it
|
|
will try to emulate the behavior seen there, e.g. to return the received data
|
|
instead of blocking, even if the line is not complete. If an unrecoverable error
|
|
occurs it will return nothing, even if it already received some data.
|
|
<P>
|
|
|
|
Also, I would advise against using <TT>"accept"</TT> with a non-blocking <FONT SIZE="-1">SSL</FONT> object
|
|
because it might block and this is not what most would expect. The reason for
|
|
this is that <TT>"accept"</TT> on a non-blocking <FONT SIZE="-1">TCP</FONT> socket (e.g. IO::Socket::IP,
|
|
IO::Socket::INET..) results in a new <FONT SIZE="-1">TCP</FONT> socket which does not inherit the
|
|
non-blocking behavior of the master socket. And thus, the initial <FONT SIZE="-1">SSL</FONT> handshake
|
|
on the new socket inside <TT>"IO::Socket::SSL::accept"</TT> will be done in a blocking
|
|
way. To work around this you are safer by doing a <FONT SIZE="-1">TCP</FONT> accept and later upgrade the
|
|
<FONT SIZE="-1">TCP</FONT> socket in a non-blocking way with <TT>"start_SSL"</TT> and <TT>"accept_SSL"</TT>.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $cl = IO::Socket::SSL->new($dst);
|
|
$cl->blocking(0);
|
|
my $sel = IO::Select->new($cl);
|
|
while (1) {
|
|
# with SSL a call for reading n bytes does not result in reading of n
|
|
# bytes from the socket, but instead it must read at least one full SSL
|
|
# frame. If the socket has no new bytes, but there are unprocessed data
|
|
# from the SSL frame can_read will block!
|
|
|
|
# wait for data on socket
|
|
$sel->can_read();
|
|
|
|
# new data on socket or eof
|
|
READ:
|
|
# this does not read only 1 byte from socket, but reads the complete SSL
|
|
# frame and then just returns one byte. On subsequent calls it than
|
|
# returns more byte of the same SSL frame until it needs to read the
|
|
# next frame.
|
|
my $n = sysread( $cl,my $buf,1);
|
|
if ( ! defined $n ) {
|
|
die $! if not ${EWOULDBLOCK};
|
|
next if $SSL_ERROR == SSL_WANT_READ;
|
|
if ( $SSL_ERROR == SSL_WANT_WRITE ) {
|
|
# need to write data on renegotiation
|
|
$sel->can_write;
|
|
next;
|
|
}
|
|
die "something went wrong: $SSL_ERROR";
|
|
} elsif ( ! $n ) {
|
|
last; # eof
|
|
} else {
|
|
# read next bytes
|
|
# we might have still data within the current SSL frame
|
|
# thus first process these data instead of waiting on the underlying
|
|
# socket object
|
|
goto READ if $cl->pending; # goto sysread
|
|
next; # goto $sel->can_read
|
|
}
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Additionally there are differences to plain sockets when using select, poll,
|
|
kqueue or similar technologies to get notified if data are available.
|
|
Relying only on these calls is not sufficient in all cases since unread data
|
|
might be internally buffered in the <FONT SIZE="-1">SSL</FONT> stack. To detect such buffering
|
|
<B>pending()</B> need to be used. Alternatively the buffering can be avoided by using
|
|
<B>sysread</B> with the maximum size of an <FONT SIZE="-1">SSL</FONT> frame. See ``Common Usage Errors''
|
|
for details.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>Advanced Usage</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3><FONT SIZE="-1">SNI</FONT> Support</H3>
|
|
|
|
|
|
|
|
Newer extensions to <FONT SIZE="-1">SSL</FONT> can distinguish between multiple hostnames on the same
|
|
<FONT SIZE="-1">IP</FONT> address using Server Name Indication (<FONT SIZE="-1">SNI</FONT>).
|
|
<P>
|
|
|
|
Support for <FONT SIZE="-1">SNI</FONT> on the client side was added somewhere in the OpenSSL 0.9.8
|
|
series, but with 1.0 a bug was fixed when the server could not decide about
|
|
its hostname. Therefore client side <FONT SIZE="-1">SNI</FONT> is only supported with OpenSSL 1.0 or
|
|
higher in IO::Socket::SSL.
|
|
With a supported version, <FONT SIZE="-1">SNI</FONT> is used automatically on the client side, if it
|
|
can determine the hostname from <TT>"PeerAddr"</TT> or <TT>"PeerHost"</TT> (which are synonyms
|
|
in the underlying IO::Socket:: classes and thus should never be set both or at
|
|
least not to different values).
|
|
On unsupported OpenSSL versions it will silently not use <FONT SIZE="-1">SNI.</FONT>
|
|
The hostname can also be given explicitly given with <TT>"SSL_hostname"</TT>, but in
|
|
this case it will throw in error, if <FONT SIZE="-1">SNI</FONT> is not supported.
|
|
To check for support you might call <TT>"IO::Socket::SSL->can_client_sni()"</TT>.
|
|
<P>
|
|
|
|
On the server side, earlier versions of OpenSSL are supported, but only together
|
|
with Net::SSLeay version >= 1.50.
|
|
To check for support you might call <TT>"IO::Socket::SSL->can_server_sni()"</TT>.
|
|
If server side <FONT SIZE="-1">SNI</FONT> is supported, you might specify different certificates per
|
|
host with <TT>"SSL_cert*"</TT> and <TT>"SSL_key*"</TT>, and check the requested name using
|
|
<TT>"get_servername"</TT>.
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Talk Plain and <FONT SIZE="-1">SSL</FONT> With The Same Socket</H3>
|
|
|
|
|
|
|
|
It is often required to first exchange some plain data and then upgrade the
|
|
socket to <FONT SIZE="-1">SSL</FONT> after some kind of <FONT SIZE="-1">STARTTLS</FONT> command. Protocols like <FONT SIZE="-1">FTPS</FONT> even
|
|
need a way to downgrade the socket again back to plain.
|
|
<P>
|
|
|
|
The common way to do this would be to create a normal socket and use <TT>"start_SSL"</TT>
|
|
to upgrade and stop_SSL to downgrade:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $sock = IO::Socket::INET->new(...) or die $!;
|
|
... exchange plain data on $sock until starttls command ...
|
|
IO::Socket::SSL->start_SSL($sock,%sslargs) or die $SSL_ERROR;
|
|
... now $sock is an IO::Socket::SSL object ...
|
|
... exchange data with SSL on $sock until stoptls command ...
|
|
$sock->stop_SSL or die $SSL_ERROR;
|
|
... now $sock is again an IO::Socket::INET object ...
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
But, lots of modules just derive directly from IO::Socket::INET.
|
|
While this base class can be replaced with IO::Socket::SSL, these modules cannot
|
|
easily support different base classes for <FONT SIZE="-1">SSL</FONT> and plain data and switch between
|
|
these classes on a starttls command.
|
|
<P>
|
|
|
|
To help in this case, IO::Socket::SSL can be reduced to a plain socket on
|
|
startup, and connect_SSL/accept_SSL/start_SSL can be used to enable <FONT SIZE="-1">SSL</FONT> and
|
|
<TT>"stop_SSL"</TT> to talk plain again:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $sock = IO::Socket::SSL->new(
|
|
PeerAddr => ...
|
|
SSL_startHandshake => 0,
|
|
%sslargs
|
|
) or die $!;
|
|
... exchange plain data on $sock until starttls command ...
|
|
$sock->connect_SSL or die $SSL_ERROR;
|
|
... now $sock is an IO::Socket::SSL object ...
|
|
... exchange data with SSL on $sock until stoptls command ...
|
|
$sock->stop_SSL or die $SSL_ERROR;
|
|
... $sock is still an IO::Socket::SSL object ...
|
|
... but data exchanged again in plain ...
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>Integration Into Own Modules</H2>
|
|
|
|
|
|
|
|
IO::Socket::SSL behaves similarly to other IO::Socket modules and thus could
|
|
be integrated in the same way, but you have to take special care when using
|
|
non-blocking I/O (like for handling timeouts) or using select or poll.
|
|
Please study the documentation on how to deal with these differences.
|
|
<P>
|
|
|
|
Also, it is recommended to not set or touch most of the <TT>"SSL_*"</TT> options, so
|
|
that they keep their secure defaults. It is also recommended to let the user
|
|
override these <FONT SIZE="-1">SSL</FONT> specific settings without the need of global settings or hacks
|
|
like <TT>"set_args_filter_hack"</TT>.
|
|
<P>
|
|
|
|
The notable exception is <TT>"SSL_verifycn_scheme"</TT>.
|
|
This should be set to the hostname verification scheme required by the module or
|
|
protocol.
|
|
<A NAME="lbAO"> </A>
|
|
<H2>Description Of Methods</H2>
|
|
|
|
|
|
|
|
IO::Socket::SSL inherits from another IO::Socket module.
|
|
The choice of the super class depends on the installed modules:
|
|
<DL COMPACT>
|
|
<DT id="41">•<DD>
|
|
If IO::Socket::IP with at least version 0.20 is installed it will use this
|
|
module as super class, transparently providing IPv6 and IPv4 support.
|
|
<DT id="42">•<DD>
|
|
If IO::Socket::INET6 is installed it will use this module as super class,
|
|
transparently providing IPv6 and IPv4 support.
|
|
<DT id="43">•<DD>
|
|
Otherwise it will fall back to IO::Socket::INET, which is a perl core module.
|
|
With IO::Socket::INET you only get IPv4 support.
|
|
</DL>
|
|
<P>
|
|
|
|
Please be aware that with the IPv6 capable super classes, it will look first
|
|
for the IPv6 address of a given hostname. If the resolver provides an IPv6
|
|
address, but the host cannot be reached by IPv6, there will be no automatic
|
|
fallback to IPv4.
|
|
To avoid these problems you can enforce IPv4 for a specific socket by
|
|
using the <TT>"Domain"</TT> or <TT>"Family"</TT> option with the value <FONT SIZE="-1">AF_INET</FONT> as described in
|
|
IO::Socket::IP. Alternatively you can enforce IPv4 globally by loading
|
|
IO::Socket::SSL with the option 'inet4', in which case it will use the IPv4
|
|
only class IO::Socket::INET as the super class.
|
|
<P>
|
|
|
|
IO::Socket::SSL will provide all of the methods of its super class, but
|
|
sometimes it will override them to match the behavior expected from <FONT SIZE="-1">SSL</FONT> or to
|
|
provide additional arguments.
|
|
<P>
|
|
|
|
The new or changed methods are described below, but please also read the
|
|
section about <FONT SIZE="-1">SSL</FONT> specific error handling.
|
|
<DL COMPACT>
|
|
<DT id="44">Error Handling<DD>
|
|
|
|
|
|
If an <FONT SIZE="-1">SSL</FONT> specific error occurs, the global variable <TT>$SSL_ERROR</TT> will be set.
|
|
If the error occurred on an existing <FONT SIZE="-1">SSL</FONT> socket, the method <TT>"errstr"</TT> will
|
|
give access to the latest socket specific error.
|
|
Both <TT>$SSL_ERROR</TT> and the <TT>"errstr"</TT> method give a dualvar similar to <TT>$!</TT>, e.g.
|
|
providing an error number in numeric context or an error description in string
|
|
context.
|
|
<DT id="45"><B>new(...)</B><DD>
|
|
|
|
|
|
Creates a new IO::Socket::SSL object. You may use all the friendly options
|
|
that came bundled with the super class (e.g. IO::Socket::IP,
|
|
IO::Socket::INET, ...) plus (optionally) the ones described below.
|
|
If you don't specify any <FONT SIZE="-1">SSL</FONT> related options it will do its best in using
|
|
secure defaults, e.g. choosing good ciphers, enabling proper verification, etc.
|
|
<DL COMPACT><DT id="46"><DD>
|
|
<DL COMPACT>
|
|
<DT id="47">SSL_server<DD>
|
|
|
|
|
|
Set this option to a true value if the socket should be used as a server.
|
|
If this is not explicitly set it is assumed if the <TT>"Listen"</TT> parameter is given
|
|
when creating the socket.
|
|
<DT id="48">SSL_hostname<DD>
|
|
|
|
|
|
This can be given to specify the hostname used for <FONT SIZE="-1">SNI,</FONT> which is needed if you
|
|
have multiple <FONT SIZE="-1">SSL</FONT> hostnames on the same <FONT SIZE="-1">IP</FONT> address. If not given it will try to
|
|
determine the hostname from <TT>"PeerAddr"</TT>, which will fail if only an <FONT SIZE="-1">IP</FONT> was given or if
|
|
this argument is used within <TT>"start_SSL"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you want to disable <FONT SIZE="-1">SNI,</FONT> set this argument to ''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Currently only supported for the client side and will be ignored for the server
|
|
side.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See section ``<FONT SIZE="-1">SNI</FONT> Support'' for details of <FONT SIZE="-1">SNI</FONT> the support.
|
|
<DT id="49">SSL_startHandshake<DD>
|
|
|
|
|
|
If this option is set to false (defaults to true) it will not start the <FONT SIZE="-1">SSL</FONT>
|
|
handshake yet. This has to be done later with <TT>"accept_SSL"</TT> or <TT>"connect_SSL"</TT>.
|
|
Before the handshake is started read/write/etc. can be used to exchange plain
|
|
data.
|
|
<DT id="50">SSL_keepSocketOnError<DD>
|
|
|
|
|
|
If this option is set to true (defaults to false) it will not close the
|
|
underlying <FONT SIZE="-1">TCP</FONT> socket on errors. In most cases there is no real use for this
|
|
behavior since both sides of the <FONT SIZE="-1">TCP</FONT> connection will probably have a
|
|
different idea of the current state of the connection.
|
|
<DT id="51">SSL_ca | SSL_ca_file | SSL_ca_path<DD>
|
|
|
|
|
|
Usually you want to verify that the peer certificate has been signed by a
|
|
trusted certificate authority. In this case you should use this option to
|
|
specify the file (<TT>"SSL_ca_file"</TT>) or directory (<TT>"SSL_ca_path"</TT>) containing the
|
|
certificate(s) of the trusted certificate authorities.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<TT>"SSL_ca_path"</TT> can also be an array or a string containing multiple path, where
|
|
the path are separated by the platform specific separator. This separator is
|
|
<TT>";"</TT> on <FONT SIZE="-1">DOS,</FONT> Windows, Netware, <TT>","</TT> on <FONT SIZE="-1">VMS</FONT> and <TT>":"</TT> for all the other systems.
|
|
If multiple path are given at least one of these must be accessible.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You can also give a list of X509* certificate handles (like you get from
|
|
Net::SSLeay or IO::Socket::SSL::Utils::PEM_xxx2cert) with <TT>"SSL_ca"</TT>. These
|
|
will be added to the <FONT SIZE="-1">CA</FONT> store before path and file and thus take precedence.
|
|
If neither SSL_ca, nor SSL_ca_file or SSL_ca_path are set it will use
|
|
<TT>"default_ca()"</TT> to determine the user-set or system defaults.
|
|
If you really don't want to set a <FONT SIZE="-1">CA</FONT> set SSL_ca_file or SSL_ca_path to
|
|
<TT>"\undef"</TT> or SSL_ca to an empty list. (unfortunately <TT>''</TT> is used by some
|
|
modules using IO::Socket::SSL when <FONT SIZE="-1">CA</FONT> is not explicitly given).
|
|
<DT id="52">SSL_client_ca | SSL_client_ca_file<DD>
|
|
|
|
|
|
If verify_mode is <FONT SIZE="-1">VERIFY_PEER</FONT> on the server side these options can be used to
|
|
set the list of acceptable CAs for the client. This way the client can select
|
|
they required certificate from a list of certificates.
|
|
The value for these options is similar to <TT>"SSL_ca"</TT> and <TT>"SSL_ca_file"</TT>.
|
|
<DT id="53">SSL_fingerprint<DD>
|
|
|
|
|
|
Sometimes you have a self-signed certificate or a certificate issued by an
|
|
unknown <FONT SIZE="-1">CA</FONT> and you really want to accept it, but don't want to disable
|
|
verification at all. In this case you can specify the fingerprint of the
|
|
certificate as <TT>'algo$hex_fingerprint'</TT>. <TT>"algo"</TT> is a fingerprint algorithm
|
|
supported by OpenSSL, e.g. 'sha1','sha256'... and <TT>"hex_fingerprint"</TT> is the
|
|
hexadecimal representation of the binary fingerprint. Any colons inside the
|
|
hex string will be ignored.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you want to use the fingerprint of the pubkey inside the certificate instead
|
|
of the certificate use the syntax <TT>'algo$pub$hex_fingerprint'</TT> instead.
|
|
To get the fingerprint of an established connection you can use
|
|
<TT>"get_fingerprint"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It is also possible to skip <TT>"algo$"</TT>, i.e. only specify the fingerprint. In
|
|
this case the likely algorithms will be automatically detected based on the
|
|
length of the digest string.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You can specify a list of fingerprints in case you have several acceptable
|
|
certificates.
|
|
If a fingerprint matches the topmost (i.e. leaf) certificate no additional
|
|
validations can make the verification fail.
|
|
<DT id="54">SSL_cert_file | SSL_cert | SSL_key_file | SSL_key<DD>
|
|
|
|
|
|
If you create a server you usually need to specify a server certificate which
|
|
should be verified by the client. Same is true for client certificates, which
|
|
should be verified by the server.
|
|
The certificate can be given as a file with SSL_cert_file or as an internal
|
|
representation of an X509* object (like you get from Net::SSLeay or
|
|
IO::Socket::SSL::Utils::PEM_xxx2cert) with SSL_cert.
|
|
If given as a file it will automatically detect the format.
|
|
Supported file formats are <FONT SIZE="-1">PEM, DER</FONT> and PKCS#12, where <FONT SIZE="-1">PEM</FONT> and PKCS#12 can
|
|
contain the certificate and the chain to use, while <FONT SIZE="-1">DER</FONT> can only contain a single
|
|
certificate.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If given as a list of X509* please note, that the all the chain certificates
|
|
(e.g. all except the first) will be ``consumed'' by openssl and will be freed
|
|
if the <FONT SIZE="-1">SSL</FONT> context gets destroyed - so you should never free them yourself. But
|
|
the servers certificate (e.g. the first) will not be consumed by openssl and
|
|
thus must be freed by the application.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For each certificate a key is need, which can either be given as a file with
|
|
SSL_key_file or as an internal representation of an EVP_PKEY* object with
|
|
SSL_key (like you get from Net::SSLeay or
|
|
IO::Socket::SSL::Utils::PEM_xxx2key).
|
|
If a key was already given within the PKCS#12 file specified by SSL_cert_file
|
|
it will ignore any SSL_key or SSL_key_file.
|
|
If no SSL_key or SSL_key_file was given it will try to use the <FONT SIZE="-1">PEM</FONT> file given
|
|
with SSL_cert_file again, maybe it contains the key too.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If your <FONT SIZE="-1">SSL</FONT> server should be able to use different certificates on the same <FONT SIZE="-1">IP</FONT>
|
|
address, depending on the name given by <FONT SIZE="-1">SNI,</FONT> you can use a hash reference
|
|
instead of a file with <TT>"<hostname ="</TT> cert_file>>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If your <FONT SIZE="-1">SSL</FONT> server should be able to use both <FONT SIZE="-1">RSA</FONT> and <FONT SIZE="-1">ECDSA</FONT> certificates for the
|
|
same domain/IP a similar hash reference like with <FONT SIZE="-1">SNI</FONT> is given. The
|
|
domain names used to specify the additional certificates should be
|
|
<TT>"hostname%whatever"</TT>, i.e. <TT>"hostname%ecc"</TT> or similar. This needs at least
|
|
OpenSSL 1.0.2. To let the server pick the certificate based on the clients
|
|
cipher preference <TT>"SSL_honor_cipher_order"</TT> should be set to false.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In case certs and keys are needed but not given it might fall back to builtin
|
|
defaults, see ``Defaults for Cert, Key and <FONT SIZE="-1">CA''.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
SSL_cert_file => 'mycert.pem',
|
|
SSL_key_file => 'mykey.pem',
|
|
|
|
SSL_cert_file => {
|
|
"foo.example.org" => 'foo-cert.pem',
|
|
"foo.example.org%ecc" => 'foo-ecc-cert.pem',
|
|
"bar.example.org" => 'bar-cert.pem',
|
|
# used when nothing matches or client does not support SNI
|
|
'' => 'default-cert.pem',
|
|
'%ecc' => 'default-ecc-cert.pem',
|
|
},
|
|
SSL_key_file => {
|
|
"foo.example.org" => 'foo-key.pem',
|
|
"foo.example.org%ecc" => 'foo-ecc-key.pem',
|
|
"bar.example.org" => 'bar-key.pem',
|
|
# used when nothing matches or client does not support SNI
|
|
'' => 'default-key.pem',
|
|
'%ecc' => 'default-ecc-key.pem',
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="55">SSL_passwd_cb<DD>
|
|
|
|
|
|
If your private key is encrypted, you might not want the default password prompt
|
|
from Net::SSLeay. This option takes a reference to a subroutine that should
|
|
return the password required to decrypt your private key.
|
|
<DT id="56">SSL_use_cert<DD>
|
|
|
|
|
|
If this is true, it forces IO::Socket::SSL to use a certificate and key, even if
|
|
you are setting up an <FONT SIZE="-1">SSL</FONT> client. If this is set to 0 (the default), then you
|
|
will only need a certificate and key if you are setting up a server.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
SSL_use_cert will implicitly be set if SSL_server is set.
|
|
For convenience it is also set if it was not given but a cert was given for use
|
|
(SSL_cert_file or similar).
|
|
<DT id="57">SSL_version<DD>
|
|
|
|
|
|
Sets the version of the <FONT SIZE="-1">SSL</FONT> protocol used to transmit data.
|
|
'SSLv23' uses a handshake compatible with <FONT SIZE="-1">SSL2.0, SSL3.0</FONT> and <FONT SIZE="-1">TLS1</FONT>.x, while
|
|
'SSLv2', 'SSLv3', 'TLSv1', 'TLSv1_1', 'TLSv1_2', or 'TLSv1_3' restrict
|
|
handshake and protocol to the specified version.
|
|
All values are case-insensitive. Instead of 'TLSv1_1', 'TLSv1_2', and
|
|
'TLSv1_3' one can also use 'TLSv11', 'TLSv12', and 'TLSv13'. Support for
|
|
'TLSv1_1', 'TLSv1_2', and 'TLSv1_3' requires recent versions of Net::SSLeay
|
|
and openssl.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Independent from the handshake format you can limit to set of accepted <FONT SIZE="-1">SSL</FONT>
|
|
versions by adding !version separated by ':'.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default SSL_version is 'SSLv23:!SSLv3:!SSLv2' which means, that the
|
|
handshake format is compatible to <FONT SIZE="-1">SSL2.0</FONT> and higher, but that the successful
|
|
handshake is limited to <FONT SIZE="-1">TLS1.0</FONT> and higher, that is no <FONT SIZE="-1">SSL2.0</FONT> or <FONT SIZE="-1">SSL3.0</FONT> because
|
|
both of these versions have serious security issues and should not be used
|
|
anymore.
|
|
You can also use !TLSv1_1 and !TLSv1_2 to disable <FONT SIZE="-1">TLS</FONT> versions 1.1 and 1.2 while
|
|
still allowing <FONT SIZE="-1">TLS</FONT> version 1.0.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Setting the version instead to 'TLSv1' might break interaction with older
|
|
clients, which need and <FONT SIZE="-1">SSL2.0</FONT> compatible handshake. On the other
|
|
side some clients just close the connection when they receive a <FONT SIZE="-1">TLS</FONT> version 1.1
|
|
request. In this case setting the version to
|
|
'SSLv23:!SSLv2:!SSLv3:!TLSv1_1:!TLSv1_2' might help.
|
|
<DT id="58">SSL_cipher_list<DD>
|
|
|
|
|
|
If this option is set the cipher list for the connection will be set to the
|
|
given value, e.g. something like '<FONT SIZE="-1">ALL:</FONT>!LOW:!EXP:!aNULL'. Look into the OpenSSL
|
|
documentation (<<A HREF="https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-STRINGS">https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-STRINGS</A>>)
|
|
for more details.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Unless you fail to contact your peer because of no shared ciphers it is
|
|
recommended to leave this option at the default setting. The default setting
|
|
prefers ciphers with forward secrecy, disables anonymous authentication and
|
|
disables known insecure ciphers like <FONT SIZE="-1">MD5, DES</FONT> etc. This gives a grade A result
|
|
at the tests of <FONT SIZE="-1">SSL</FONT> Labs.
|
|
To use the less secure OpenSSL builtin default (whatever this is) set
|
|
SSL_cipher_list to ''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In case different cipher lists are needed for different <FONT SIZE="-1">SNI</FONT> hosts a hash can be
|
|
given with the host as key and the cipher suite as value, similar to
|
|
<B>SSL_cert*</B>.
|
|
<DT id="59">SSL_honor_cipher_order<DD>
|
|
|
|
|
|
If this option is true the cipher order the server specified is used instead
|
|
of the order proposed by the client. This option defaults to true to make use of
|
|
our secure cipher list setting.
|
|
<DT id="60">SSL_dh_file<DD>
|
|
|
|
|
|
To create a server which provides forward secrecy you need to either give the <FONT SIZE="-1">DH</FONT>
|
|
parameters or (better, because faster) the <FONT SIZE="-1">ECDH</FONT> curve. This setting cares
|
|
about <FONT SIZE="-1">DH</FONT> parameters.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To support non-elliptic Diffie-Hellman key exchange a suitable file needs to
|
|
be given here or the SSL_dh should be used with an appropriate value.
|
|
See dhparam command in openssl for more information.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If neither <TT>"SSL_dh_file"</TT> nor <TT>"SSL_dh"</TT> are set a builtin <FONT SIZE="-1">DH</FONT> parameter with a
|
|
length of 2048 bit is used to offer <FONT SIZE="-1">DH</FONT> key exchange by default. If you don't
|
|
want this (e.g. disable <FONT SIZE="-1">DH</FONT> key exchange) explicitly set this or the <TT>"SSL_dh"</TT>
|
|
parameter to undef.
|
|
<DT id="61">SSL_dh<DD>
|
|
|
|
|
|
Like SSL_dh_file, but instead of giving a file you use a preloaded or generated
|
|
DH*.
|
|
<DT id="62">SSL_ecdh_curve<DD>
|
|
|
|
|
|
To create a server which provides forward secrecy you need to either give the <FONT SIZE="-1">DH</FONT>
|
|
parameters or (better, because faster) the <FONT SIZE="-1">ECDH</FONT> curve. This setting cares
|
|
about the <FONT SIZE="-1">ECDH</FONT> curve(s).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To support Elliptic Curve Diffie-Hellmann key exchange the <FONT SIZE="-1">OID</FONT> or <FONT SIZE="-1">NID</FONT> of at
|
|
least one suitable curve needs to be provided here.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
With OpenSSL 1.1.0+ this parameter defaults to <TT>"auto"</TT>, which means that it
|
|
lets OpenSSL pick the best settings. If support for CTX_set_ecdh_auto is
|
|
implemented in Net::SSLeay (needs at least version 1.86) it will use this to
|
|
implement the same default. Otherwise it will default to <TT>"prime256v1"</TT>
|
|
(builtin of OpenSSL) in order to offer <FONT SIZE="-1">ECDH</FONT> key exchange by default.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If setting groups or curves is supported by Net::SSLeay (needs at least
|
|
version 1.86) then multiple curves can be given here in the order of the
|
|
preference, i.e. <TT>"P-521:P-384:P-256"</TT>. When used at the client side this
|
|
will include the supported curves as extension in the <FONT SIZE="-1">TLS</FONT> handshake.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you don't want to have <FONT SIZE="-1">ECDH</FONT> key exchange this could be set to undef or
|
|
set <TT>"SSL_ciphers"</TT> to exclude all of these ciphers.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You can check if <FONT SIZE="-1">ECDH</FONT> support is available by calling
|
|
<TT>"IO::Socket::SSL->can_ecdh"</TT>.
|
|
<DT id="63">SSL_verify_mode<DD>
|
|
|
|
|
|
This option sets the verification mode for the peer certificate.
|
|
You may combine <FONT SIZE="-1">SSL_VERIFY_PEER</FONT> (verify_peer), <FONT SIZE="-1">SSL_VERIFY_FAIL_IF_NO_PEER_CERT</FONT>
|
|
(fail verification if no peer certificate exists; ignored for clients),
|
|
<FONT SIZE="-1">SSL_VERIFY_CLIENT_ONCE</FONT> (verify client once; ignored for clients).
|
|
See OpenSSL man page for SSL_CTX_set_verify for more information.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default is <FONT SIZE="-1">SSL_VERIFY_NONE</FONT> for server (e.g. no check for client
|
|
certificate) and <FONT SIZE="-1">SSL_VERIFY_PEER</FONT> for client (check server certificate).
|
|
<DT id="64">SSL_verify_callback<DD>
|
|
|
|
|
|
If you want to verify certificates yourself, you can pass a sub reference along
|
|
with this parameter to do so. When the callback is called, it will be passed:
|
|
<DL COMPACT><DT id="65"><DD>
|
|
<DL COMPACT>
|
|
<DT id="66">1. a true/false value that indicates what OpenSSL thinks of the certificate,<DD>
|
|
|
|
|
|
|
|
<DT id="67">2. a C-style memory address of the certificate store,<DD>
|
|
|
|
|
|
<DT id="68">3. a string containing the certificate's issuer attributes and owner attributes, and<DD>
|
|
|
|
|
|
<DT id="69">4. a string containing any errors encountered (0 if no errors).<DD>
|
|
|
|
|
|
<DT id="70">5. a C-style memory address of the peer's own certificate (convertible to <FONT SIZE="-1">PEM</FONT> form with <B>Net::SSLeay::PEM_get_string_X509()</B>).<DD>
|
|
|
|
|
|
<DT id="71">6. The depth of the certificate in the chain. Depth 0 is the leaf certificate.<DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="72"><DD>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The function should return 1 or 0, depending on whether it thinks the
|
|
certificate is valid or invalid. The default is to let OpenSSL do all of the
|
|
busy work.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The callback will be called for each element in the certificate chain.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See the OpenSSL documentation for SSL_CTX_set_verify for more information.
|
|
</DL>
|
|
|
|
<DT id="73">SSL_verifycn_scheme<DD>
|
|
|
|
|
|
The scheme is used to correctly verify the identity inside the certificate
|
|
by using the hostname of the peer.
|
|
See the information about the verification schemes in <B>verify_hostname</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you don't specify a scheme it will use 'default', but only complain loudly if
|
|
the name verification fails instead of letting the whole certificate
|
|
verification fail. <FONT SIZE="-1">THIS WILL CHANGE,</FONT> e.g. it will let the certificate
|
|
verification fail in the future if the hostname does not match the certificate
|
|
!!!! To override the name used in verification use <B>SSL_verifycn_name</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The scheme 'default' is a superset of the usual schemes, which will accept the
|
|
hostname in common name and subjectAltName and allow wildcards everywhere.
|
|
While using this scheme is way more secure than no name verification at all you
|
|
better should use the scheme specific to your application protocol, e.g. 'http',
|
|
'ftp'...
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you are really sure, that you don't want to verify the identity using the
|
|
hostname you can use 'none' as a scheme. In this case you'd better have
|
|
alternative forms of verification, like a certificate fingerprint or do a manual
|
|
verification later by calling <B>verify_hostname</B> yourself.
|
|
<DT id="74">SSL_verifycn_publicsuffix<DD>
|
|
|
|
|
|
This option is used to specify the behavior when checking wildcards certificates
|
|
for public suffixes, e.g. no wildcard certificates for *.com or *.co.uk should
|
|
be accepted, while *.example.com or *.example.co.uk is ok.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If not specified it will simply use the builtin default of
|
|
IO::Socket::SSL::PublicSuffix, you can create another object with
|
|
from_string or from_file of this module.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To disable verification of public suffix set this option to <TT>''</TT>.
|
|
<DT id="75">SSL_verifycn_name<DD>
|
|
|
|
|
|
Set the name which is used in verification of hostname. If SSL_verifycn_scheme
|
|
is set and no SSL_verifycn_name is given it will try to use SSL_hostname or
|
|
PeerHost and PeerAddr settings and fail if no name can be determined.
|
|
If SSL_verifycn_scheme is not set it will use a default scheme and warn if it
|
|
cannot determine a hostname, but it will not fail.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Using PeerHost or PeerAddr works only if you create the connection directly
|
|
with <TT>"IO::Socket::SSL->new"</TT>, if an IO::Socket::INET object is upgraded
|
|
with <B>start_SSL</B> the name has to be given in <B>SSL_verifycn_name</B> or
|
|
<B>SSL_hostname</B>.
|
|
<DT id="76">SSL_check_crl<DD>
|
|
|
|
|
|
If you want to verify that the peer certificate has not been revoked
|
|
by the signing authority, set this value to true. OpenSSL will search
|
|
for the <FONT SIZE="-1">CRL</FONT> in your SSL_ca_path, or use the file specified by
|
|
SSL_crl_file. See the Net::SSLeay documentation for more details.
|
|
Note that this functionality appears to be broken with OpenSSL <
|
|
v0.9.7b, so its use with lower versions will result in an error.
|
|
<DT id="77">SSL_crl_file<DD>
|
|
|
|
|
|
If you want to specify the <FONT SIZE="-1">CRL</FONT> file to be used, set this value to the
|
|
pathname to be used. This must be used in addition to setting
|
|
SSL_check_crl.
|
|
<DT id="78">SSL_ocsp_mode<DD>
|
|
|
|
|
|
Defines how certificate revocation is done using <FONT SIZE="-1">OCSP</FONT> (Online Status Revocation
|
|
Protocol). The default is to send a request for <FONT SIZE="-1">OCSP</FONT> stapling to the server and
|
|
if the server sends an <FONT SIZE="-1">OCSP</FONT> response back the result will be used.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Any other <FONT SIZE="-1">OCSP</FONT> checking needs to be done manually with <TT>"ocsp_resolver"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The following flags can be combined with <TT>"|"</TT>:
|
|
<DL COMPACT><DT id="79"><DD>
|
|
<DL COMPACT>
|
|
<DT id="80"><FONT SIZE="-1">SSL_OCSP_NO_STAPLE</FONT><DD>
|
|
|
|
|
|
Don't ask for <FONT SIZE="-1">OCSP</FONT> stapling.
|
|
This is the default if SSL_verify_mode is <FONT SIZE="-1">VERIFY_NONE.</FONT>
|
|
<DT id="81"><FONT SIZE="-1">SSL_OCSP_TRY_STAPLE</FONT><DD>
|
|
|
|
|
|
Try <FONT SIZE="-1">OCSP</FONT> stapling, but don't complain if it gets no stapled response back.
|
|
This is the default if SSL_verify_mode is <FONT SIZE="-1">VERIFY_PEER</FONT> (the default).
|
|
<DT id="82"><FONT SIZE="-1">SSL_OCSP_MUST_STAPLE</FONT><DD>
|
|
|
|
|
|
Consider it a hard error, if the server does not send a stapled <FONT SIZE="-1">OCSP</FONT> response
|
|
back. Most servers currently send no stapled <FONT SIZE="-1">OCSP</FONT> response back.
|
|
<DT id="83"><FONT SIZE="-1">SSL_OCSP_FAIL_HARD</FONT><DD>
|
|
|
|
|
|
Fail hard on response errors, default is to fail soft like the browsers do.
|
|
Soft errors mean, that the <FONT SIZE="-1">OCSP</FONT> response is not usable, e.g. no response,
|
|
error response, no valid signature etc.
|
|
Certificate revocations inside a verified response are considered hard errors
|
|
in any case.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Soft errors inside a stapled response are never considered hard, e.g. it is
|
|
expected that in this case an <FONT SIZE="-1">OCSP</FONT> request will be send to the responsible
|
|
<FONT SIZE="-1">OCSP</FONT> responder.
|
|
<DT id="84"><FONT SIZE="-1">SSL_OCSP_FULL_CHAIN</FONT><DD>
|
|
|
|
|
|
This will set up the <TT>"ocsp_resolver"</TT> so that all certificates from the peer
|
|
chain will be checked, otherwise only the leaf certificate will be checked
|
|
against revocation.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="85"><DD>
|
|
</DL>
|
|
|
|
<DT id="86">SSL_ocsp_staple_callback<DD>
|
|
|
|
|
|
If this callback is defined, it will be called with the <FONT SIZE="-1">SSL</FONT> object and the <FONT SIZE="-1">OCSP</FONT>
|
|
response handle obtained from the peer, e.g. <TT>"<$cb-"</TT>($ssl,$resp)>>.
|
|
If the peer did not provide a stapled <FONT SIZE="-1">OCSP</FONT> response the function will be called
|
|
with <TT>"$resp=undef"</TT>.
|
|
Because the <FONT SIZE="-1">OCSP</FONT> response handle is no longer valid after leaving this function
|
|
it should not by copied or freed. If access to the response is necessary after
|
|
leaving this function it can be serialized with
|
|
<TT>"Net::SSLeay::i2d_OCSP_RESPONSE"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If no such callback is provided, it will use the default one, which verifies the
|
|
response and uses it to check if the certificate(s) of the connection got
|
|
revoked.
|
|
<DT id="87">SSL_ocsp_cache<DD>
|
|
|
|
|
|
With this option a cache can be given for caching <FONT SIZE="-1">OCSP</FONT> responses, which could
|
|
be shared between different <FONT SIZE="-1">SSL</FONT> contexts. If not given a cache specific to the
|
|
<FONT SIZE="-1">SSL</FONT> context only will be used.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You can either create a new cache with
|
|
<TT>"IO::Socket::SSL::OCSP_Cache->new([size])"</TT> or implement your own cache,
|
|
which needs to have methods <TT>"put($key,\%entry)"</TT> and <TT>"get($key)"</TT> (returning
|
|
<TT>"\%entry"</TT>) where entry is the hash representation of the <FONT SIZE="-1">OCSP</FONT> response with
|
|
fields like <TT>"nextUpdate"</TT>. The default implementation of the cache will consider
|
|
responses valid as long as <TT>"nextUpdate"</TT> is less then the current time.
|
|
<DT id="88">SSL_reuse_ctx<DD>
|
|
|
|
|
|
If you have already set the above options for a previous instance of
|
|
IO::Socket::SSL, then you can reuse the <FONT SIZE="-1">SSL</FONT> context of that instance by passing
|
|
it as the value for the SSL_reuse_ctx parameter. You may also create a
|
|
new instance of the IO::Socket::SSL::SSL_Context class, using any context
|
|
options that you desire without specifying connection options, and pass that
|
|
here instead.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you use this option, all other context-related options that you pass
|
|
in the same call to <B>new()</B> will be ignored unless the context supplied was
|
|
invalid. Note that, contrary to versions of IO::Socket::SSL below v0.90, a
|
|
global <FONT SIZE="-1">SSL</FONT> context will not be implicitly used unless you use the
|
|
<B>set_default_context()</B> function.
|
|
<DT id="89">SSL_create_ctx_callback<DD>
|
|
|
|
|
|
With this callback you can make individual settings to the context after it
|
|
got created and the default setup was done.
|
|
The callback will be called with the <FONT SIZE="-1">CTX</FONT> object from Net::SSLeay as the single
|
|
argument.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example for limiting the server session cache size:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
SSL_create_ctx_callback => sub {
|
|
my $ctx = shift;
|
|
Net::SSLeay::CTX_sess_set_cache_size($ctx,128);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="90">SSL_session_cache_size<DD>
|
|
|
|
|
|
If you make repeated connections to the same host/port and the <FONT SIZE="-1">SSL</FONT> renegotiation
|
|
time is an issue, you can turn on client-side session caching with this option
|
|
by specifying a positive cache size. For successive connections, pass the
|
|
SSL_reuse_ctx option to the <B>new()</B> calls (or use <B>set_default_context()</B>) to make
|
|
use of the cached sessions. The session cache size refers to the number of
|
|
unique host/port pairs that can be stored at one time; the oldest sessions in
|
|
the cache will be removed if new ones are added.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option does not effect the session cache a server has for it's clients,
|
|
e.g. it does not affect <FONT SIZE="-1">SSL</FONT> objects with SSL_server set.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that session caching with <FONT SIZE="-1">TLS 1.3</FONT> needs at least Net::SSLeay 1.86.
|
|
<DT id="91">SSL_session_cache<DD>
|
|
|
|
|
|
Specifies session cache object which should be used instead of creating a new.
|
|
Overrules SSL_session_cache_size.
|
|
This option is useful if you want to reuse the cache, but not the rest of
|
|
the context.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A session cache object can be created using
|
|
<TT>"IO::Socket::SSL::Session_Cache->new( cachesize )"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Use <B>set_default_session_cache()</B> to set a global cache object.
|
|
<DT id="92">SSL_session_key<DD>
|
|
|
|
|
|
Specifies a key to use for lookups and inserts into client-side session cache.
|
|
Per default ip:port of destination will be used, but sometimes you want to
|
|
share the same session over multiple ports on the same server (like with <FONT SIZE="-1">FTPS</FONT>).
|
|
<DT id="93">SSL_session_id_context<DD>
|
|
|
|
|
|
This gives an id for the servers session cache. It's necessary if you want
|
|
clients to connect with a client certificate. If not given but SSL_verify_mode
|
|
specifies the need for client certificate a context unique id will be picked.
|
|
<DT id="94">SSL_error_trap<DD>
|
|
|
|
|
|
When using the <B>accept()</B> or <B>connect()</B> methods, it may be the case that the
|
|
actual socket connection works but the <FONT SIZE="-1">SSL</FONT> negotiation fails, as in the case of
|
|
an <FONT SIZE="-1">HTTP</FONT> client connecting to an <FONT SIZE="-1">HTTPS</FONT> server. Passing a subroutine ref attached
|
|
to this parameter allows you to gain control of the orphaned socket instead of
|
|
having it be closed forcibly.
|
|
The subroutine, if called, will be passed two parameters:
|
|
a reference to the socket on which the <FONT SIZE="-1">SSL</FONT> negotiation failed and the full
|
|
text of the error message.
|
|
<DT id="95">SSL_npn_protocols<DD>
|
|
|
|
|
|
If used on the server side it specifies list of protocols advertised by <FONT SIZE="-1">SSL</FONT>
|
|
server as an array ref, e.g. ['spdy/2','http1.1'].
|
|
On the client side it specifies the protocols offered by the client for <FONT SIZE="-1">NPN</FONT>
|
|
as an array ref.
|
|
See also method <TT>"next_proto_negotiated"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Next Protocol Negotiation (<FONT SIZE="-1">NPN</FONT>) is available with Net::SSLeay 1.46+ and
|
|
openssl-1.0.1+. <FONT SIZE="-1">NPN</FONT> is unavailable in TLSv1.3 protocol.
|
|
To check support you might call <TT>"IO::Socket::SSL->can_npn()"</TT>.
|
|
If you use this option with an unsupported Net::SSLeay/OpenSSL it will
|
|
throw an error.
|
|
<DT id="96">SSL_alpn_protocols<DD>
|
|
|
|
|
|
If used on the server side it specifies list of protocols supported by the <FONT SIZE="-1">SSL</FONT>
|
|
server as an array ref, e.g. ['http/2.0', 'spdy/3.1','http/1.1'].
|
|
On the client side it specifies the protocols advertised by the client for <FONT SIZE="-1">ALPN</FONT>
|
|
as an array ref.
|
|
See also method <TT>"alpn_selected"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Application-Layer Protocol Negotiation (<FONT SIZE="-1">ALPN</FONT>) is available with Net::SSLeay
|
|
1.56+ and openssl-1.0.2+. More details about the extension are in <FONT SIZE="-1">RFC7301.</FONT> To
|
|
check support you might call <TT>"IO::Socket::SSL->can_alpn()"</TT>. If you use
|
|
this option with an unsupported Net::SSLeay/OpenSSL it will throw an error.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that some client implementations may encounter problems if both <FONT SIZE="-1">NPN</FONT> and
|
|
<FONT SIZE="-1">ALPN</FONT> are specified. Since <FONT SIZE="-1">ALPN</FONT> is intended as a replacement for <FONT SIZE="-1">NPN,</FONT> try
|
|
providing <FONT SIZE="-1">ALPN</FONT> protocols then fall back to <FONT SIZE="-1">NPN</FONT> if that fails.
|
|
<DT id="97">SSL_ticket_keycb => [$sub,$data] | $sub<DD>
|
|
|
|
|
|
|
|
|
|
This is a callback used for stateless session reuse (Session Tickets, <FONT SIZE="-1">RFC 5077</FONT>).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This callback will be called as <TT>"$sub->($data,[$key_name])"</TT> where <TT>$data</TT>
|
|
is the argument given to SSL_ticket_keycb (or undef) and <TT>$key_name</TT> depends
|
|
on the mode:
|
|
<DL COMPACT><DT id="98"><DD>
|
|
<DL COMPACT>
|
|
<DT id="99">encrypt ticket<DD>
|
|
|
|
|
|
If a ticket needs to be encrypted the callback will be called without
|
|
<TT>$key_name</TT>. In this case it should return <TT>"($current_key,$current_key_name"</TT>)
|
|
where <TT>$current_key</TT> is the current key (32 byte random data) and
|
|
<TT>$current_key_name</TT> the name associated with this key (exactly 16 byte). This
|
|
<TT>$current_key_name</TT> will be incorporated into the ticket.
|
|
<DT id="100">decrypt ticket<DD>
|
|
|
|
|
|
If a ticket needs to be decrypted the callback will be called with <TT>$key_name</TT>
|
|
as found in the ticket. It should return <TT>"($key,$current_key_name"</TT>) where
|
|
<TT>$key</TT> is the key associated with the given <TT>$key_name</TT> and
|
|
<TT>$current_key_name</TT> the name associated with the currently active key.
|
|
If <TT>$current_key_name</TT> is different from the given <TT>$key_name</TT> the callback
|
|
will be called again to re-encrypt the ticket with the currently active key.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If no key can be found which matches the given <TT>$key_name</TT> then this function
|
|
should return nothing (empty list).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This mechanism should be used to limit the life time for each key encrypting the
|
|
ticket. Compromise of a ticket encryption key might lead to decryption of <FONT SIZE="-1">SSL</FONT>
|
|
sessions which used session tickets protected by this key.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="101"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Net::SSLeay::RAND_bytes(my $oldkey,32);
|
|
Net::SSLeay::RAND_bytes(my $newkey,32);
|
|
my $oldkey_name = pack("a16",'oldsecret');
|
|
my $newkey_name = pack("a16",'newsecret');
|
|
|
|
my @keys = (
|
|
[ $newkey_name, $newkey ], # current active key
|
|
[ $oldkey_name, $oldkey ], # already expired
|
|
);
|
|
|
|
my $keycb = [ sub {
|
|
my ($mykeys,$name) = @_;
|
|
|
|
# return (current_key, current_key_name) if no name given
|
|
return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
|
|
|
|
# return (matching_key, current_key_name) if we find a key matching
|
|
# the given name
|
|
for(my $i = 0; $i<@$mykeys; $i++) {
|
|
next if $name ne $mykeys->[$i][0];
|
|
return ($mykeys->[$i][1],$mykeys->[0][0]);
|
|
}
|
|
|
|
# no matching key found
|
|
return;
|
|
},\@keys ];
|
|
|
|
my $srv = IO::Socket::SSL->new(..., SSL_ticket_keycb => $keycb);
|
|
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
|
|
<DT id="102">SSL_mode_release_buffers 1|0<DD>
|
|
|
|
|
|
This enables or disables the <FONT SIZE="-1">SSL_MODE_RELEASE_BUFFERS</FONT> option on the <FONT SIZE="-1">SSL</FONT> object.
|
|
With this option the read buffer will be released after each SSL_read but will
|
|
need to be reallocated for each new SSL_read. If memory usage is a concern this
|
|
might save lots of memory in the mean time though, about 34k per idle <FONT SIZE="-1">SSL</FONT>
|
|
connection according to the documentation in <B>SSL_CTX_set_mode</B>(3ssl).
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="103"><DD>
|
|
</DL>
|
|
|
|
<DT id="104"><B>accept</B><DD>
|
|
|
|
|
|
This behaves similar to the accept function of the underlying socket class, but
|
|
additionally does the initial <FONT SIZE="-1">SSL</FONT> handshake. But because the underlying socket
|
|
class does return a blocking file handle even when accept is called on a
|
|
non-blocking socket, the <FONT SIZE="-1">SSL</FONT> handshake on the new file object will be done in a
|
|
blocking way. Please see the section about non-blocking I/O for details.
|
|
If you don't like this behavior you should do accept on the <FONT SIZE="-1">TCP</FONT> socket and then
|
|
upgrade it with <TT>"start_SSL"</TT> later.
|
|
<DT id="105"><B>connect(...)</B><DD>
|
|
|
|
|
|
This behaves similar to the connect function but also does an <FONT SIZE="-1">SSL</FONT> handshake.
|
|
Because you cannot give <FONT SIZE="-1">SSL</FONT> specific arguments to this function, you should
|
|
better either use <TT>"new"</TT> to create a connect <FONT SIZE="-1">SSL</FONT> socket or <TT>"start_SSL"</TT> to
|
|
upgrade an established <FONT SIZE="-1">TCP</FONT> socket to <FONT SIZE="-1">SSL.</FONT>
|
|
<DT id="106"><B>close(...)</B><DD>
|
|
|
|
|
|
Contrary to a close for a simple <FONT SIZE="-1">INET</FONT> socket a close in <FONT SIZE="-1">SSL</FONT> also mandates a
|
|
proper shutdown of the <FONT SIZE="-1">SSL</FONT> part. This is done by sending a close notify message
|
|
by both peers.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A naive implementation would thus wait until it receives the
|
|
close notify message from the peer - which conflicts with the commonly expected
|
|
semantic that a close will not block. The default behavior is thus to only send
|
|
a close notify but not wait for the close notify of the peer. If this is
|
|
required <TT>"SSL_fast_shutdown"</TT> need to be explicitly set to false.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
There are also cases where a <FONT SIZE="-1">SSL</FONT> shutdown should not be done at all. This is
|
|
true for example when forking to let a child deal with the socket and closing
|
|
the socket in the parent process. A naive explicit <TT>"close"</TT> or an implicit close
|
|
when destroying the socket in the parent would send a close notify to the peer
|
|
which would make the <FONT SIZE="-1">SSL</FONT> socket in the client process unusable. In this case an
|
|
explicit <TT>"close"</TT> with <TT>"SSL_no_shutdown"</TT> set to true should be done in the
|
|
parent process.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For more details and other arguments see <TT>"stop_SSL"</TT> which gets called from
|
|
<TT>"close"</TT> to shutdown the <FONT SIZE="-1">SSL</FONT> state of the socket.
|
|
<DT id="107"><B>sysread( </B><FONT SIZE="-1"><B>BUF, LEN,</B></FONT><B> [ </B><FONT SIZE="-1"><B>OFFSET</B></FONT><B> ] )</B><DD>
|
|
|
|
|
|
This function behaves from the outside the same as <B>sysread</B> in other
|
|
IO::Socket objects, e.g. it returns at most <FONT SIZE="-1">LEN</FONT> bytes of data.
|
|
But in reality it reads not only <FONT SIZE="-1">LEN</FONT> bytes from the underlying socket, but at
|
|
a single <FONT SIZE="-1">SSL</FONT> frame. It then returns up to <FONT SIZE="-1">LEN</FONT> bytes it decrypted from this <FONT SIZE="-1">SSL</FONT>
|
|
frame. If the frame contained more data than requested it will return only <FONT SIZE="-1">LEN</FONT>
|
|
data, buffer the rest and return it on further read calls.
|
|
This means, that it might be possible to read data, even if the underlying
|
|
socket is not readable, so using poll or select might not be sufficient.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
sysread will only return data from a single <FONT SIZE="-1">SSL</FONT> frame, e.g. either the pending
|
|
data from the already buffered frame or it will read a frame from the underlying
|
|
socket and return the decrypted data. It will not return data spanning several
|
|
<FONT SIZE="-1">SSL</FONT> frames in a single call.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Also, calls to sysread might fail, because it must first finish an <FONT SIZE="-1">SSL</FONT>
|
|
handshake.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To understand these behaviors is essential, if you write applications which use
|
|
event loops and/or non-blocking sockets. Please read the specific sections in
|
|
this documentation.
|
|
<DT id="108"><B>syswrite( </B><FONT SIZE="-1"><B>BUF,</B></FONT><B> [ </B><FONT SIZE="-1"><B>LEN,</B></FONT><B> [ </B><FONT SIZE="-1"><B>OFFSET</B></FONT><B> ]] )</B><DD>
|
|
|
|
|
|
This functions behaves from the outside the same as <B>syswrite</B> in other
|
|
IO::Socket objects, e.g. it will write at most <FONT SIZE="-1">LEN</FONT> bytes to the socket, but
|
|
there is no guarantee, that all <FONT SIZE="-1">LEN</FONT> bytes are written. It will return the number
|
|
of bytes written.
|
|
Because it basically just calls SSL_write from OpenSSL syswrite will write at
|
|
most a single <FONT SIZE="-1">SSL</FONT> frame. This means, that no more than 16.384 bytes, which is
|
|
the maximum size of an <FONT SIZE="-1">SSL</FONT> frame, will be written at once.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For non-blocking sockets <FONT SIZE="-1">SSL</FONT> specific behavior applies.
|
|
Pease read the specific section in this documentation.
|
|
<DT id="109"><B>peek( </B><FONT SIZE="-1"><B>BUF, LEN,</B></FONT><B> [ </B><FONT SIZE="-1"><B>OFFSET</B></FONT><B> ])</B><DD>
|
|
|
|
|
|
This function has exactly the same syntax as <B>sysread</B>, and performs nearly the
|
|
same task but will not advance the read position so that successive calls to
|
|
<B>peek()</B> with the same arguments will return the same results. This function
|
|
requires OpenSSL 0.9.6a or later to work.
|
|
<DT id="110"><B>pending()</B><DD>
|
|
|
|
|
|
This function gives you the number of bytes available without reading from the
|
|
underlying socket object. This function is essential if you work with event
|
|
loops, please see the section about polling <FONT SIZE="-1">SSL</FONT> sockets.
|
|
<DT id="111"><B>get_fingerprint([algo,certificate,pubkey])</B><DD>
|
|
|
|
|
|
This methods returns the fingerprint of the given certificate in the form
|
|
<TT>"algo$digest_hex"</TT>, where <TT>"algo"</TT> is the used algorithm, default 'sha256'.
|
|
If no certificate is given the peer certificate of the connection is used.
|
|
If <TT>"pubkey"</TT> is true it will not return the fingerprint of the certificate but
|
|
instead the fingerprint of the pubkey inside the certificate as
|
|
<TT>"algo$pub$digest_hex"</TT>.
|
|
<DT id="112"><B>get_fingerprint_bin([algo,certificate,pubkey])</B><DD>
|
|
|
|
|
|
This methods returns the binary fingerprint of the given certificate by using
|
|
the algorithm <TT>"algo"</TT>, default 'sha256'.
|
|
If no certificate is given the peer certificate of the connection is used.
|
|
If <TT>"pubkey"</TT> is true it will not return the fingerprint of the certificate but
|
|
instead the fingerprint of the pubkey inside the certificate.
|
|
<DT id="113"><B>get_cipher()</B><DD>
|
|
|
|
|
|
Returns the string form of the cipher that the IO::Socket::SSL object is using.
|
|
<DT id="114"><B>get_sslversion()</B><DD>
|
|
|
|
|
|
Returns the string representation of the <FONT SIZE="-1">SSL</FONT> version of an established
|
|
connection.
|
|
<DT id="115"><B>get_sslversion_int()</B><DD>
|
|
|
|
|
|
Returns the integer representation of the <FONT SIZE="-1">SSL</FONT> version of an established
|
|
connection.
|
|
<DT id="116"><B>get_session_reused()</B><DD>
|
|
|
|
|
|
This returns true if the session got reused and false otherwise. Note that with
|
|
a reused session no certificates are send within the handshake and no ciphers
|
|
are offered and thus functions which rely on this might not work.
|
|
<DT id="117"><B>dump_peer_certificate()</B><DD>
|
|
|
|
|
|
Returns a parsable string with select fields from the peer <FONT SIZE="-1">SSL</FONT> certificate.
|
|
This method directly returns the result of the <B>dump_peer_certificate()</B> method of
|
|
Net::SSLeay.
|
|
<DT id="118"><B>peer_certificate($field;[$refresh])</B><DD>
|
|
|
|
|
|
If a peer certificate exists, this function can retrieve values from it.
|
|
If no field is given the internal representation of certificate from Net::SSLeay
|
|
is returned.
|
|
If refresh is true it will not used a cached version, but check again in case
|
|
the certificate of the connection has changed due to renegotiation.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The following fields can be queried:
|
|
<DL COMPACT><DT id="119"><DD>
|
|
<DL COMPACT>
|
|
<DT id="120">authority (alias issuer)<DD>
|
|
|
|
|
|
The certificate authority which signed the certificate.
|
|
<DT id="121">owner (alias subject)<DD>
|
|
|
|
|
|
The owner of the certificate.
|
|
<DT id="122">commonName (alias cn) - only for Net::SSLeay version >=1.30<DD>
|
|
|
|
|
|
The common name, usually the server name for <FONT SIZE="-1">SSL</FONT> certificates.
|
|
<DT id="123">subjectAltNames - only for Net::SSLeay version >=1.33<DD>
|
|
|
|
|
|
Alternative names for the subject, usually different names for the same
|
|
server, like example.org, example.com, *.example.com.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It returns a list of (typ,value) with typ <FONT SIZE="-1">GEN_DNS, GEN_IPADD</FONT> etc (these
|
|
constants are exported from IO::Socket::SSL).
|
|
See Net::SSLeay::X509_get_subjectAltNames.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="124"><DD>
|
|
</DL>
|
|
|
|
<DT id="125"><B>sock_certificate($field)</B><DD>
|
|
|
|
|
|
This is similar to <TT>"peer_certificate"</TT> but will return the sites own
|
|
certificate. The same arguments for <B></B>$field<B></B> can be used.
|
|
If no <B></B>$field<B></B> is given the certificate handle from the underlying OpenSSL will
|
|
be returned. This handle will only be valid as long as the <FONT SIZE="-1">SSL</FONT> connection exists
|
|
and if used afterwards it might result in strange crashes of the application.
|
|
<DT id="126"><B>peer_certificates</B><DD>
|
|
|
|
|
|
This returns all the certificates send by the peer, e.g. first the peers own
|
|
certificate and then the rest of the chain. You might use <B>CERT_asHash</B> from
|
|
IO::Socket::SSL::Utils to inspect each of the certificates.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This function depends on a version of Net::SSLeay >= 1.58 .
|
|
<DT id="127"><B>get_servername</B><DD>
|
|
|
|
|
|
This gives the name requested by the client if Server Name Indication
|
|
(<FONT SIZE="-1">SNI</FONT>) was used.
|
|
<DT id="128"><B>verify_hostname($hostname,$scheme,$publicsuffix)</B><DD>
|
|
|
|
|
|
This verifies the given hostname against the peer certificate using the
|
|
given scheme. Hostname is usually what you specify within the PeerAddr.
|
|
See the <TT>"SSL_verifycn_publicsuffix"</TT> parameter for an explanation of suffix
|
|
checking and for the possible values.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Verification of hostname against a certificate is different between various
|
|
applications and RFCs. Some scheme allow wildcards for hostnames, some only
|
|
in subjectAltNames, and even their different wildcard schemes are possible.
|
|
<FONT SIZE="-1">RFC 6125</FONT> provides a good overview.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To ease the verification the following schemes are predefined (both protocol
|
|
name and rfcXXXX name can be used):
|
|
<DL COMPACT><DT id="129"><DD>
|
|
<DL COMPACT>
|
|
<DT id="130">rfc2818, xmpp (rfc3920), ftp (rfc4217)<DD>
|
|
|
|
|
|
Extended wildcards in subjectAltNames and common name are possible, e.g.
|
|
*.example.org or even www*.example.org. The common
|
|
name will be only checked if no <FONT SIZE="-1">DNS</FONT> names are given in subjectAltNames.
|
|
<DT id="131">http (alias www)<DD>
|
|
|
|
|
|
While name checking is defined in rfc2818 the current browsers usually accept
|
|
also an <FONT SIZE="-1">IP</FONT> address (w/o wildcards) within the common name as long as no
|
|
subjectAltNames are defined. Thus this is rfc2818 extended with this feature.
|
|
<DT id="132">smtp (rfc2595), imap, pop3, acap (rfc4642), netconf (rfc5538), syslog (rfc5425), snmp (rfc5953)<DD>
|
|
|
|
|
|
Simple wildcards in subjectAltNames are possible, e.g. *.example.org matches
|
|
<A HREF="http://www.example.org">www.example.org</A> but not lala.<A HREF="http://www.example.org">www.example.org</A>. If nothing from subjectAltNames
|
|
match it checks against the common name, where wildcards are also allowed to
|
|
match the full leftmost label.
|
|
<DT id="133">ldap (rfc4513)<DD>
|
|
|
|
|
|
Simple wildcards are allowed in subjectAltNames, but not in common name.
|
|
Common name will be checked even if subjectAltNames exist.
|
|
<DT id="134">sip (rfc5922)<DD>
|
|
|
|
|
|
No wildcards are allowed and common name is checked even if subjectAltNames
|
|
exist.
|
|
<DT id="135">gist (rfc5971)<DD>
|
|
|
|
|
|
Simple wildcards are allowed in subjectAltNames and common name, but common name
|
|
will only be checked if their are no <FONT SIZE="-1">DNS</FONT> names in subjectAltNames.
|
|
<DT id="136">default<DD>
|
|
|
|
|
|
This is a superset of all the rules and is automatically used if no scheme is
|
|
given but a hostname (instead of <FONT SIZE="-1">IP</FONT>) is known.
|
|
Extended wildcards are allowed in subjectAltNames and common name and common
|
|
name is checked always.
|
|
<DT id="137">none<DD>
|
|
|
|
|
|
No verification will be done.
|
|
Actually is does not make any sense to call verify_hostname in this case.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="138"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The scheme can be given either by specifying the name for one of the above
|
|
predefined schemes, or by using a hash which can have the following keys and
|
|
values:
|
|
<DL COMPACT>
|
|
<DT id="139">check_cn: 0|'always'|'when_only'<DD>
|
|
|
|
|
|
Determines if the common name gets checked. If 'always' it will always be
|
|
checked (like in ldap), if 'when_only' it will only be checked if no names are
|
|
given in subjectAltNames (like in http), for any other values the common name
|
|
will not be checked.
|
|
<DT id="140">wildcards_in_alt: 0|'full_label'|'anywhere'<DD>
|
|
|
|
|
|
Determines if and where wildcards in subjectAltNames are possible. If
|
|
'full_label' only cases like *.example.org will be possible (like in ldap), for
|
|
'anywhere' www*.example.org is possible too (like http), dangerous things like
|
|
but www.*.org or even '*' will not be allowed.
|
|
For compatibility with older versions 'leftmost' can be given instead of
|
|
'full_label'.
|
|
<DT id="141">wildcards_in_cn: 0|'full_label'|'anywhere'<DD>
|
|
|
|
|
|
Similar to wildcards_in_alt, but checks the common name. There is no predefined
|
|
scheme which allows wildcards in common names.
|
|
<DT id="142">ip_in_cn: 0|1|4|6<DD>
|
|
|
|
|
|
Determines if an <FONT SIZE="-1">IP</FONT> address is allowed in the common name (no wildcards are
|
|
allowed). If set to 4 or 6 it only allows IPv4 or IPv6 addresses, any other
|
|
true value allows both.
|
|
<DT id="143">callback: \&coderef<DD>
|
|
|
|
|
|
If you give a subroutine for verification it will be called with the arguments
|
|
($hostname,$commonName,@subjectAltNames), where hostname is the name given for
|
|
verification, commonName is the result from peer_certificate('cn') and
|
|
subjectAltNames is the result from peer_certificate('subjectAltNames').
|
|
|
|
|
|
<P>
|
|
|
|
|
|
All other arguments for the verification scheme will be ignored in this case.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="144"><DD>
|
|
</DL>
|
|
|
|
<DT id="145"><B>next_proto_negotiated()</B><DD>
|
|
|
|
|
|
This method returns the name of negotiated protocol - e.g. 'http/1.1'. It works
|
|
for both client and server side of <FONT SIZE="-1">SSL</FONT> connection.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<FONT SIZE="-1">NPN</FONT> support is available with Net::SSLeay 1.46+ and openssl-1.0.1+.
|
|
To check support you might call <TT>"IO::Socket::SSL->can_npn()"</TT>.
|
|
<DT id="146"><B>alpn_selected()</B><DD>
|
|
|
|
|
|
Returns the protocol negotiated via <FONT SIZE="-1">ALPN</FONT> as a string, e.g. 'http/1.1',
|
|
'http/2.0' or 'spdy/3.1'.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<FONT SIZE="-1">ALPN</FONT> support is available with Net::SSLeay 1.56+ and openssl-1.0.2+.
|
|
To check support, use <TT>"IO::Socket::SSL->can_alpn()"</TT>.
|
|
<DT id="147"><B>errstr()</B><DD>
|
|
|
|
|
|
Returns the last error (in string form) that occurred.<TT> </TT>If you do not have a<BR>
|
|
real object to perform this method on, call <B>IO::Socket::SSL::errstr()</B> instead.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For read and write errors on non-blocking sockets, this method may include the
|
|
string <TT>"SSL wants a read first!"</TT> or <TT>"SSL wants a write first!"</TT> meaning that
|
|
the other side is expecting to read from or write to the socket and wants to be
|
|
satisfied before you get to do anything. But with version 0.98 you are better
|
|
comparing the global exported variable <TT>$SSL_ERROR</TT> against the exported symbols
|
|
<FONT SIZE="-1">SSL_WANT_READ</FONT> and <FONT SIZE="-1">SSL_WANT_WRITE.</FONT>
|
|
<DT id="148"><B>opened()</B><DD>
|
|
|
|
|
|
This returns false if the socket could not be opened, 1 if the socket could be
|
|
opened and the <FONT SIZE="-1">SSL</FONT> handshake was successful done and -1 if the underlying
|
|
IO::Handle is open, but the <FONT SIZE="-1">SSL</FONT> handshake failed.
|
|
<DT id="149"><B>IO::Socket::SSL->start_SSL($socket, ... )</B><DD>
|
|
|
|
|
|
This will convert a glob reference or a socket that you provide to an
|
|
IO::Socket::SSL object.<TT> </TT> You may also pass parameters to specify context or<BR>
|
|
connection options as with a call to <B>new()</B>. If you are using this function on
|
|
an <B>accept()</B>ed socket, you must set the parameter ``SSL_server'' to 1, i.e.
|
|
IO::Socket::SSL->start_SSL($socket, SSL_server => 1). If you have a class that
|
|
inherits from IO::Socket::SSL and you want the <TT>$socket</TT> to be blessed into your
|
|
own class instead, use MyClass->start_SSL($socket) to achieve the desired
|
|
effect.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that if <B>start_SSL()</B> fails in <FONT SIZE="-1">SSL</FONT> negotiation, <TT>$socket</TT> will remain blessed
|
|
in its original class.<TT> </TT> For non-blocking sockets you better just upgrade the<BR>
|
|
socket to IO::Socket::SSL and call accept_SSL or connect_SSL and the upgraded
|
|
object. To just upgrade the socket set <B>SSL_startHandshake</B> explicitly to 0. If
|
|
you call start_SSL w/o this parameter it will revert to blocking behavior for
|
|
accept_SSL and connect_SSL.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If given the parameter ``Timeout'' it will stop if after the timeout no <FONT SIZE="-1">SSL</FONT>
|
|
connection was established. This parameter is only used for blocking sockets, if
|
|
it is not given the default Timeout from the underlying IO::Socket will be
|
|
used.
|
|
<DT id="150"><B>stop_SSL(...)</B><DD>
|
|
|
|
|
|
This is the opposite of <B>start_SSL()</B>, <B>connect_SSL()</B> and <B>accept_SSL()</B>, e.g. it
|
|
will shutdown the <FONT SIZE="-1">SSL</FONT> connection and return to the class before <B>start_SSL()</B>. It
|
|
gets the same arguments as <B>close()</B>, in fact <B>close()</B> calls <B>stop_SSL()</B> (but
|
|
without downgrading the class).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Will return true if it succeeded and undef if failed. This might be the case for
|
|
non-blocking sockets. In this case $! is set to <FONT SIZE="-1">EWOULDBLOCK</FONT> and the ssl error to
|
|
<FONT SIZE="-1">SSL_WANT_READ</FONT> or <FONT SIZE="-1">SSL_WANT_WRITE.</FONT> In this case the call should be retried again
|
|
with the same arguments once the socket is ready.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For calling from <TT>"stop_SSL"</TT> <TT>"SSL_fast_shutdown"</TT> default to false, e.g. it
|
|
waits for the close_notify of the peer. This is necessary in case you want to
|
|
downgrade the socket and continue to use it as a plain socket.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After stop_SSL the socket can again be used to exchange plain data.
|
|
<DT id="151"><B>connect_SSL</B>, <B>accept_SSL</B><DD>
|
|
|
|
|
|
These functions should be used to do the relevant handshake, if the socket got
|
|
created with <TT>"new"</TT> or upgraded with <TT>"start_SSL"</TT> and <TT>"SSL_startHandshake"</TT> was
|
|
set to false.
|
|
They will return undef until the handshake succeeded or an error got thrown.
|
|
As long as the function returns undef and $! is set to <FONT SIZE="-1">EWOULDBLOCK</FONT> one could
|
|
retry the call after the socket got readable (<FONT SIZE="-1">SSL_WANT_READ</FONT>) or writeable
|
|
(<FONT SIZE="-1">SSL_WANT_WRITE</FONT>).
|
|
<DT id="152"><B>ocsp_resolver</B><DD>
|
|
|
|
|
|
This will create an <FONT SIZE="-1">OCSP</FONT> resolver object, which can be used to create <FONT SIZE="-1">OCSP</FONT>
|
|
requests for the certificates of the <FONT SIZE="-1">SSL</FONT> connection. Which certificates are
|
|
verified depends on the setting of <TT>"SSL_ocsp_mode"</TT>: by default only the leaf
|
|
certificate will be checked, but with <FONT SIZE="-1">SSL_OCSP_FULL_CHAIN</FONT> all chain
|
|
certificates will be checked.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Because to create an <FONT SIZE="-1">OCSP</FONT> request the certificate and its issuer certificate
|
|
need to be known it is not possible to check certificates when the trust chain
|
|
is incomplete or if the certificate is self-signed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <FONT SIZE="-1">OCSP</FONT> resolver gets created by calling <TT>"$ssl->ocsp_resolver"</TT> and
|
|
provides the following methods:
|
|
<DL COMPACT><DT id="153"><DD>
|
|
<DL COMPACT>
|
|
<DT id="154">hard_error<DD>
|
|
|
|
|
|
This returns the hard error when checking the <FONT SIZE="-1">OCSP</FONT> response.
|
|
Hard errors are certificate revocations. With the <TT>"SSL_ocsp_mode"</TT> of
|
|
<FONT SIZE="-1">SSL_OCSP_FAIL_HARD</FONT> any soft error (e.g. failures to get signed information
|
|
about the certificates) will be considered a hard error too.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <FONT SIZE="-1">OCSP</FONT> resolving will stop on the first hard error.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The method will return undef as long as no hard errors occurred and still
|
|
requests to be resolved. If all requests got resolved and no hard errors
|
|
occurred the method will return <TT>''</TT>.
|
|
<DT id="155">soft_error<DD>
|
|
|
|
|
|
This returns the soft error(s) which occurred when asking the <FONT SIZE="-1">OCSP</FONT> responders.
|
|
<DT id="156">requests<DD>
|
|
|
|
|
|
This will return a hash consisting of <TT>"(url,request)"</TT>-tuples, e.g. which
|
|
contain the <FONT SIZE="-1">OCSP</FONT> request string and the <FONT SIZE="-1">URL</FONT> where it should be sent too. The
|
|
usual way to send such a request is as <FONT SIZE="-1">HTTP POST</FONT> request with a content-type
|
|
of <TT>"application/ocsp-request"</TT> or as a <FONT SIZE="-1">GET</FONT> request with the base64 and
|
|
url-encoded request is added to the path of the <FONT SIZE="-1">URL.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After you've handled all these requests and added the response with
|
|
<TT>"add_response"</TT> you should better call this method again to make sure, that no
|
|
more requests are outstanding. IO::Socket::SSL will combine multiple <FONT SIZE="-1">OCSP</FONT>
|
|
requests for the same server inside a single request, but some server don't
|
|
give a response to all these requests, so that one has to ask again with the
|
|
remaining requests.
|
|
<DT id="157">add_response($uri,$response)<DD>
|
|
|
|
|
|
This method takes the <FONT SIZE="-1">HTTP</FONT> body of the response which got received when sending
|
|
the <FONT SIZE="-1">OCSP</FONT> request to <TT>$uri</TT>. If no response was received or an error occurred
|
|
one should either retry or consider <TT>$response</TT> as empty which will trigger a
|
|
soft error.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The method returns the current value of <TT>"hard_error"</TT>, e.g. a defined value
|
|
when no more requests need to be done.
|
|
<DT id="158">resolve_blocking(%args)<DD>
|
|
|
|
|
|
This combines <TT>"requests"</TT> and <TT>"add_response"</TT> which HTTP::Tiny to do all
|
|
necessary requests in a blocking way. <TT>%args</TT> will be given to HTTP::Tiny
|
|
so that you can put proxy settings etc here. HTTP::Tiny will be called with
|
|
<TT>"verify_SSL"</TT> of false, because the <FONT SIZE="-1">OCSP</FONT> responses have their own signatures so
|
|
no extra <FONT SIZE="-1">SSL</FONT> verification is needed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you don't want to use blocking requests you need to roll your own user agent
|
|
with <TT>"requests"</TT> and <TT>"add_response"</TT>.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="159"><DD>
|
|
</DL>
|
|
|
|
<DT id="160"><B>IO::Socket::SSL->new_from_fd($fd, [mode], </B>%sslargs<B>)</B><DD>
|
|
|
|
|
|
This will convert a socket identified via a file descriptor into an <FONT SIZE="-1">SSL</FONT> socket.
|
|
Note that the argument list does not include a ``<FONT SIZE="-1">MODE''</FONT> argument; if you supply
|
|
one, it will be thoughtfully ignored (for compatibility with IO::Socket::INET).
|
|
Instead, a mode of '+<' is assumed, and the file descriptor passed must be able
|
|
to handle such I/O because the initial <FONT SIZE="-1">SSL</FONT> handshake requires bidirectional
|
|
communication.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Internally the given <TT>$fd</TT> will be upgraded to a socket object using the
|
|
<TT>"new_from_fd"</TT> method of the super class (IO::Socket::INET or similar) and
|
|
then <TT>"start_SSL"</TT> will be called using the given <TT>%sslargs</TT>.
|
|
If <TT>$fd</TT> is already an IO::Socket object you should better call <TT>"start_SSL"</TT>
|
|
directly.
|
|
<DT id="161"><B>IO::Socket::SSL::default_ca([ path|dir| SSL_ca_file =</B> ..., SSL_ca_path => ... ])><DD>
|
|
|
|
|
|
Determines or sets the default <FONT SIZE="-1">CA</FONT> path.
|
|
If existing path or dir or a hash is given it will set the default <FONT SIZE="-1">CA</FONT> path to
|
|
this value and never try to detect it automatically.
|
|
If <TT>"undef"</TT> is given it will forget any stored defaults and continue with
|
|
detection of system defaults.
|
|
If no arguments are given it will start detection of system defaults, unless it
|
|
has already stored user-set or previously detected values.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The detection of system defaults works similar to OpenSSL, e.g. it will check
|
|
the directory specified in environment variable <FONT SIZE="-1">SSL_CERT_DIR</FONT> or the path
|
|
OPENSSLDIR/certs (<FONT SIZE="-1">SSLCERTS:</FONT> on <FONT SIZE="-1">VMS</FONT>) and the file specified in environment
|
|
variable <FONT SIZE="-1">SSL_CERT_FILE</FONT> or the path OPENSSLDIR/cert.pem (SSLCERTS:cert.pem on
|
|
<FONT SIZE="-1">VMS</FONT>). Contrary to OpenSSL it will check if the SSL_ca_path contains <FONT SIZE="-1">PEM</FONT> files
|
|
with the hash as file name and if the SSL_ca_file looks like <FONT SIZE="-1">PEM.</FONT>
|
|
If no usable system default can be found it will try to load and use
|
|
Mozilla::CA and if not available give up detection.
|
|
The result of the detection will be saved to speed up future calls.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The function returns the saved default <FONT SIZE="-1">CA</FONT> as hash with SSL_ca_file and
|
|
SSL_ca_path.
|
|
<DT id="162"><B>IO::Socket::SSL::set_default_context(...)</B><DD>
|
|
|
|
|
|
You may use this to make IO::Socket::SSL automatically re-use a given context
|
|
(unless specifically overridden in a call to <B>new()</B>).
|
|
It accepts one argument, which should be either an IO::Socket::SSL object or an
|
|
IO::Socket::SSL::SSL_Context object.
|
|
See the SSL_reuse_ctx option of <B>new()</B> for more details.
|
|
Note that this sets the default context globally, so use with caution (esp. in
|
|
mod_perl scripts).
|
|
<DT id="163"><B>IO::Socket::SSL::set_default_session_cache(...)</B><DD>
|
|
|
|
|
|
You may use this to make IO::Socket::SSL automatically re-use a given session
|
|
cache (unless specifically overridden in a call to <B>new()</B>).
|
|
It accepts one argument, which should be an IO::Socket::SSL::Session_Cache
|
|
object or similar (e.g. something which implements get_session, add_session and
|
|
del_session like IO::Socket::SSL::Session_Cache does).
|
|
See the SSL_session_cache option of <B>new()</B> for more details.
|
|
Note that this sets the default cache globally, so use with caution.
|
|
<DT id="164"><B>IO::Socket::SSL::set_defaults(%args)</B><DD>
|
|
|
|
|
|
With this function one can set defaults for all SSL_* parameter used for
|
|
creation of the context, like the SSL_verify* parameter. Any SSL_* parameter can
|
|
be given or the following short versions:
|
|
<DL COMPACT><DT id="165"><DD>
|
|
<DL COMPACT>
|
|
<DT id="166">mode - SSL_verify_mode<DD>
|
|
|
|
|
|
|
|
<DT id="167">callback - SSL_verify_callback<DD>
|
|
|
|
|
|
<DT id="168">scheme - SSL_verifycn_scheme<DD>
|
|
|
|
|
|
<DT id="169">name - SSL_verifycn_name<DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="170"><DD>
|
|
</DL>
|
|
|
|
<DT id="171"><B>IO::Socket::SSL::set_client_defaults(%args)</B><DD>
|
|
|
|
|
|
|
|
Similar to <TT>"set_defaults"</TT>, but only sets the defaults for client mode.
|
|
<DT id="172"><B>IO::Socket::SSL::set_server_defaults(%args)</B><DD>
|
|
|
|
|
|
Similar to <TT>"set_defaults"</TT>, but only sets the defaults for server mode.
|
|
<DT id="173"><B>IO::Socket::SSL::set_args_filter_hack(\&code|'use_defaults')</B><DD>
|
|
|
|
|
|
Sometimes one has to use code which uses unwanted or invalid arguments for <FONT SIZE="-1">SSL,</FONT>
|
|
typically disabling <FONT SIZE="-1">SSL</FONT> verification or setting wrong ciphers or <FONT SIZE="-1">SSL</FONT> versions.
|
|
With this hack it is possible to override these settings and restore sanity.
|
|
Example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
IO::Socket::SSL::set_args_filter_hack( sub {
|
|
my ($is_server,$args) = @_;
|
|
if ( ! $is_server ) {
|
|
# client settings - enable verification with default CA
|
|
# and fallback hostname verification etc
|
|
delete @{$args}{qw(
|
|
SSL_verify_mode
|
|
SSL_ca_file
|
|
SSL_ca_path
|
|
SSL_verifycn_scheme
|
|
SSL_version
|
|
)};
|
|
# and add some fingerprints for known certs which are signed by
|
|
# unknown CAs or are self-signed
|
|
$args->{SSL_fingerprint} = ...
|
|
}
|
|
});
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
With the short setting <TT>"set_args_filter_hack('use_defaults')"</TT> it will prefer
|
|
the default settings in all cases. These default settings can be modified with
|
|
<TT>"set_defaults"</TT>, <TT>"set_client_defaults"</TT> and <TT>"set_server_defaults"</TT>.
|
|
</DL>
|
|
<P>
|
|
|
|
The following methods are unsupported (not to mention futile!) and
|
|
IO::Socket::SSL will emit a large <FONT SIZE="-1"><B>CROAK</B></FONT><B>()</B> if you are silly enough to use them:
|
|
<DL COMPACT>
|
|
<DT id="174">truncate<DD>
|
|
|
|
|
|
|
|
<DT id="175">stat<DD>
|
|
|
|
|
|
<DT id="176">ungetc<DD>
|
|
|
|
|
|
<DT id="177">setbuf<DD>
|
|
|
|
|
|
<DT id="178">setvbuf<DD>
|
|
|
|
|
|
<DT id="179">fdopen<DD>
|
|
|
|
|
|
<DT id="180">send/recv<DD>
|
|
|
|
|
|
|
|
Note that <B>send()</B> and <B>recv()</B> cannot be reliably trapped by a tied filehandle
|
|
(such as that used by IO::Socket::SSL) and so may send unencrypted data over the
|
|
socket.<TT> </TT> Object-oriented calls to these functions will fail, telling you to use<BR>
|
|
the print/printf/syswrite and read/sysread families instead.
|
|
</DL>
|
|
<A NAME="lbAP"> </A>
|
|
<H2>DEPRECATIONS</H2>
|
|
|
|
|
|
|
|
The following functions are deprecated and are only retained for compatibility:
|
|
<DL COMPACT>
|
|
<DT id="181"><B>context_init()</B><DD>
|
|
|
|
|
|
use the SSL_reuse_ctx option if you want to re-use a context
|
|
<DT id="182"><B>socketToSSL()</B> and <B>socket_to_SSL()</B><DD>
|
|
|
|
|
|
use IO::Socket::SSL-><B>start_SSL()</B> instead
|
|
<DT id="183"><B>kill_socket()</B><DD>
|
|
|
|
|
|
use <B>close()</B> instead
|
|
<DT id="184"><B>get_peer_certificate()</B><DD>
|
|
|
|
|
|
use the <B>peer_certificate()</B> function instead.
|
|
Used to return X509_Certificate with methods subject_name and issuer_name.
|
|
Now simply returns <TT>$self</TT> which has these methods (although deprecated).
|
|
<DT id="185"><B>issuer_name()</B><DD>
|
|
|
|
|
|
use peer_certificate( 'issuer' ) instead
|
|
<DT id="186"><B>subject_name()</B><DD>
|
|
|
|
|
|
use peer_certificate( 'subject' ) instead
|
|
</DL>
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
|
|
|
|
See the 'example' directory, the tests in 't' and also the tools in 'util'.
|
|
<A NAME="lbAR"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
If you use IO::Socket::SSL together with threads you should load it (e.g. use or
|
|
require) inside the main thread before creating any other threads which use it.
|
|
This way it is much faster because it will be initialized only once. Also there
|
|
are reports that it might crash the other way.
|
|
<P>
|
|
|
|
Creating an IO::Socket::SSL object in one thread and closing it in another
|
|
thread will not work.
|
|
<P>
|
|
|
|
IO::Socket::SSL does not work together with Storable::fd_retrieve/fd_store.
|
|
See <FONT SIZE="-1">BUGS</FONT> file for more information and how to work around the problem.
|
|
<P>
|
|
|
|
Non-blocking and timeouts (which are based on non-blocking) are not
|
|
supported on Win32, because the underlying IO::Socket::INET does not support
|
|
non-blocking on this platform.
|
|
<P>
|
|
|
|
If you have a server and it looks like you have a memory leak you might
|
|
check the size of your session cache. Default for Net::SSLeay seems to be
|
|
20480, see the example for SSL_create_ctx_callback for how to limit it.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">TLS 1.3</FONT> support regarding session reuse is incomplete.
|
|
<A NAME="lbAS"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
IO::Socket::INET, IO::Socket::INET6, IO::Socket::IP, Net::SSLeay.
|
|
<A NAME="lbAT"> </A>
|
|
<H2>THANKS</H2>
|
|
|
|
|
|
|
|
Many thanks to all who added patches or reported bugs or helped IO::Socket::SSL
|
|
another way. Please keep reporting bugs and help with patches, even if they just
|
|
fix the documentation.
|
|
<P>
|
|
|
|
Special thanks to the team of Net::SSLeay for the good cooperation.
|
|
<A NAME="lbAU"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
|
|
|
|
Steffen Ullrich, <sullr at cpan.org> is the current maintainer.
|
|
<P>
|
|
|
|
Peter Behroozi, <behrooz at fas.harvard.edu> (Note the lack of an ``i'' at the end of ``behrooz'')
|
|
<P>
|
|
|
|
Marko Asplund, <marko.asplund at kronodoc.fi>, was the original author of IO::Socket::SSL.
|
|
<P>
|
|
|
|
Patches incorporated from various people, see file Changes.
|
|
<A NAME="lbAV"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
The original versions of this module are Copyright (C) 1999-2002 Marko Asplund.
|
|
<P>
|
|
|
|
The rewrite of this module is Copyright (C) 2002-2005 Peter Behroozi.
|
|
<P>
|
|
|
|
Versions 0.98 and newer are Copyright (C) 2006-2014 Steffen Ullrich.
|
|
<P>
|
|
|
|
This module is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="187"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="188"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="189"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="190"><A HREF="#lbAE">Essential Information About SSL/TLS</A><DD>
|
|
<DT id="191"><A HREF="#lbAF">Basic SSL Client</A><DD>
|
|
<DT id="192"><A HREF="#lbAG">Basic SSL Server</A><DD>
|
|
<DT id="193"><A HREF="#lbAH">Common Usage Errors</A><DD>
|
|
<DT id="194"><A HREF="#lbAI">Common Problems with SSL</A><DD>
|
|
<DT id="195"><A HREF="#lbAJ">Using Non-Blocking Sockets</A><DD>
|
|
<DT id="196"><A HREF="#lbAK">Advanced Usage</A><DD>
|
|
<DL>
|
|
<DT id="197"><A HREF="#lbAL"><FONT SIZE="-1">SNI</FONT> Support</A><DD>
|
|
<DT id="198"><A HREF="#lbAM">Talk Plain and <FONT SIZE="-1">SSL</FONT> With The Same Socket</A><DD>
|
|
</DL>
|
|
<DT id="199"><A HREF="#lbAN">Integration Into Own Modules</A><DD>
|
|
<DT id="200"><A HREF="#lbAO">Description Of Methods</A><DD>
|
|
<DT id="201"><A HREF="#lbAP">DEPRECATIONS</A><DD>
|
|
<DT id="202"><A HREF="#lbAQ">EXAMPLES</A><DD>
|
|
<DT id="203"><A HREF="#lbAR">BUGS</A><DD>
|
|
<DT id="204"><A HREF="#lbAS">SEE ALSO</A><DD>
|
|
<DT id="205"><A HREF="#lbAT">THANKS</A><DD>
|
|
<DT id="206"><A HREF="#lbAU">AUTHORS</A><DD>
|
|
<DT id="207"><A HREF="#lbAV">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|