view release on metacpan or  search on metacpan

lib/IO/Socket/SSL.pod  view on Meta::CPAN

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 C<prime256v1>
(builtin of OpenSSL) in order to offer ECDH key exchange by default.

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.  C<P-521:P-384:P-256>. When used at the client side this
will include the supported curves as extension in the TLS handshake.

If you don't want to have ECDH key exchange this could be set to undef or
set C<SSL_ciphers> to exclude all of these ciphers.

You can check if ECDH support is available by calling
C<< IO::Socket::SSL->can_ecdh >>.

=item SSL_verify_mode

This option sets the verification mode for the peer certificate.
You may combine SSL_VERIFY_PEER (verify_peer), SSL_VERIFY_FAIL_IF_NO_PEER_CERT
(fail verification if no peer certificate exists; ignored for clients),
SSL_VERIFY_CLIENT_ONCE (verify client once; ignored for clients).
Note that SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE must be
used together with SSL_VERIFY_PEER.
See OpenSSL man page for SSL_CTX_set_verify for more information.

The default is SSL_VERIFY_NONE for server  (e.g. no check for client
certificate) and SSL_VERIFY_PEER for client (check server certificate).

=item SSL_verify_callback

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:

=over 4

=item 1.
a true/false value that indicates what OpenSSL thinks of the certificate,

=item 2.
a C-style memory address of the certificate store,

=item 3.
a string containing the certificate's issuer attributes and owner attributes,
and

=item 4.
a string containing any errors encountered (0 if no errors).

=item 5.
a C-style memory address of the peer's own certificate (convertible to
PEM form with Net::SSLeay::PEM_get_string_X509()).

=item 6.
The depth of the certificate in the chain. Depth 0 is the leaf certificate.

=back

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.

The callback will be called for each element in the certificate chain.

See the OpenSSL documentation for SSL_CTX_set_verify for more information.

=item SSL_verifycn_scheme

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

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. THIS WILL CHANGE, 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>.

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'...

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> yourself.

=item SSL_verifycn_publicsuffix

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.

If not specified it will simply use the builtin default of
L<IO::Socket::SSL::PublicSuffix>, you can create another object with
from_string or from_file of this module.

To disable verification of public suffix set this option to C<''>.

=item SSL_verifycn_name

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.

Using PeerHost or PeerAddr works only if you create the connection directly
with C<< IO::Socket::SSL->new >>, if an IO::Socket::INET object is upgraded
with B<start_SSL> the name has to be given in B<SSL_verifycn_name> or
B<SSL_hostname>.

=item SSL_check_crl

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 CRL in your SSL_ca_path, or use the file specified by
SSL_crl_file.  See the Net::SSLeay documentation for more details.