view release on metacpan or  search on metacpan

lib/Net/SSLeay.pod  view on Meta::CPAN

    $Net::SSLeay::ssl_version = 13; # Insist on TLSv1.3

Although the autonegotiation is nice to have, the SSL standards
do not formally specify any such mechanism. Most of the world has
accepted the SSLeay/OpenSSL way of doing it as the de facto standard. But
for the few that think differently, you have to explicitly speak
the correct version. This is not really a bug, but rather a deficiency
in the standards. If a site refuses to respond or sends back some
nonsensical error codes (at the SSL handshake level), try this option
before mailing me.

On some systems, OpenSSL may be compiled without support for SSLv2.
If this is the case, Net::SSLeay will warn if ssl_version has been set
to 2.

The high level API returns the certificate of the peer, thus allowing
one to check what certificate was supplied. However, you will only be
able to check the certificate after the fact, i.e. you already sent
your form data by the time you find out that you did not trust them,
oops.

So, while being able to know the certificate after the fact is surely
useful, the security minded would still choose to do the connection
and certificate verification first and only then exchange data
with the site. Currently none of the high level API functions do
this, thus you would have to program it using the low level API. A
good place to start is to see how the C<Net::SSLeay::http_cat()> function
is implemented.

The high level API functions use a global file handle C<SSLCAT_S>
internally. This really should not be a problem because there is no
way to interleave the high level API functions, unless you use threads
(but threads are not very well supported in perl anyway). However, you
may run into problems if you call undocumented internal functions in an
interleaved fashion. The best solution is to "require Net::SSLeay" in
one thread after all the threads have been created.

=head1 DIAGNOSTICS

=over

=item Random number generator not seeded!!!

B<(W)> This warning indicates that C<randomize()> was not able to read
C</dev/random> or C</dev/urandom>, possibly because your system does not
have them or they are differently named. You can still use SSL, but
the encryption will not be as strong.

=item open_tcp_connection: destination host not found:`server' (port 123) ($!)

Name lookup for host named C<server> failed.

=item open_tcp_connection: failed `server', 123 ($!)

The name was resolved, but establishing the TCP connection failed.

=item msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown proto

SSLeay error string. The first number (123) is the PID, the second number
(1) indicates the position of the error message in SSLeay error stack.
You often see a pile of these messages as errors cascade.

=item msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)

The same as above, but you didn't call load_error_strings() so SSLeay
couldn't verbosely explain the error. You can still find out what it
means with this command:

    /usr/local/ssl/bin/ssleay errstr 02001002

=item Password is being asked for private key

This is normal behaviour if your private key is encrypted. Either
you have to supply the password or you have to use an unencrypted
private key. Scan OpenSSL.org for the FAQ that explains how to
do this (or just study examples/makecert.pl which is used
during C<make test> to do just that).

=back

=head1 SECURITY

You can mitigate some of the security vulnerabilities that might be present in your SSL/TLS application:

=head2 BEAST Attack

=over

=item * L<https://web.archive.org/web/20140424022931/https://blogs.cisco.com/security/beat-the-beast-with-tls>

=item * L<https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls>

=item * L<https://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html>

=back

The BEAST attack relies on a weakness in the way CBC mode is used in SSL/TLS.
In OpenSSL versions 0.9.6d and later, the protocol-level mitigation is enabled by default,
thus making it not vulnerable to the BEAST attack.

Solutions:

=over

=item * Compile with OpenSSL versions 0.9.6d or later, which enables SSL_OP_ALL by default

=item * Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not enabled by default)

=item * Don't support SSLv2, SSLv3

=item * Actively control the ciphers your server supports with set_cipher_list:

=back

    Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');

=head2 Session Resumption

=over

=item * L<https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html>