view release on metacpan or  search on metacpan

lib/AnyEvent/TLS.pm  view on Meta::CPAN

issued by the CA. The revocation lists will be expected in the C<ca_path>
directory.

certificate verification will fail if this is enabled but no revocation
list was found.

This requires OpenSSL >= 0.9.7b. Check the OpenSSL documentation for more
details.

=item key_file => $path

Path to the local private key file in PEM format (might be a combined
certificate/private key file).

The local certificate is used to authenticate against the peer - servers
mandatorily need a certificate and key, clients can use a certificate and
key optionally to authenticate, e.g. for log-in purposes.

The key in the file should look similar this:

   -----BEGIN RSA PRIVATE KEY-----
   ...header data
   ... (key data in base64 encoding) ...
   -----END RSA PRIVATE KEY-----

=item key => $string

The private key string in PEM format (see C<key_file>, only one of
C<key_file> or C<key> can be specified).

The idea behind being able to specify a string is to avoid blocking in
I/O. Unfortunately, Net::SSLeay fails to implement any interface to the
needed OpenSSL functionality, this is currently implemented by writing to
a temporary file.

=item cert_file => $path

The path to the local certificate file in PEM format (might be a combined
certificate/private key file, including chained certificates).

The local certificate (and key) are used to authenticate against the
peer - servers mandatorily need a certificate and key, clients can use
certificate and key optionally to authenticate, e.g. for log-in purposes.

The certificate in the file should look like this:

   -----BEGIN CERTIFICATE-----
   ... (certificate in base64 encoding) ...
   -----END CERTIFICATE-----

If the certificate file or string contain both the certificate and
private key, then there is no need to specify a separate C<key_file> or
C<key>.

Additional signing certifiates to send to the peer (in SSLv3 and newer)
can be specified by appending them to the certificate proper: the order
must be from issuer certificate over any intermediate CA certificates to
the root CA.

So the recommended ordering for a combined key/cert/chain file, specified
via C<cert_file> or C<cert> looks like this:

  certificate private key
  client/server certificate
  ca 1, signing client/server certficate
  ca 2, signing ca 1
  ...

=item cert => $string

The local certificate in PEM format (might be a combined
certificate/private key file). See C<cert_file>.

The idea behind being able to specify a string is to avoid blocking in
I/O. Unfortunately, Net::SSLeay fails to implement any interface to the
needed OpenSSL functionality, this is currently implemented by writing to
a temporary file.

=item cert_password => $string | $callback->($tls)

The certificate password - if the certificate is password-protected, then
you can specify its password here.

Instead of providing a password directly (which is not so recommended),
you can also provide a password-query callback. The callback will be
called whenever a password is required to decode a local certificate, and
is supposed to return the password.

=item dh_file => $path

Path to a file containing Diffie-Hellman parameters in PEM format, for
use in servers. See also C<dh> on how to specify them directly, or use a
pre-generated set.

Diffie-Hellman key exchange generates temporary encryption keys that
are not transferred over the connection, which means that even if the
certificate key(s) are made public at a later time and a full dump of the
connection exists, the key still cannot be deduced.

These ciphers are only available with SSLv3 and later (which is the
default with AnyEvent::TLS), and are only used in server/accept
mode. Anonymous DH protocols are usually disabled by default, and usually
not even compiled into the underlying library, as they provide no direct
protection against man-in-the-middle attacks. The same is true for the
common practise of self-signed certificates that you have to accept first,
of course.

=item dh => $string

Specify the Diffie-Hellman parameters in PEM format directly as a string
(see C<dh_file>), the default is C<ffdhe3072> unless C<dh_file> was
specified.

AnyEvent::TLS supports supports a number of precomputed DH parameters,
since computing them is expensive. They are:

   # from RFC 7919 - recommended
   ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144, ffdhe8192

   # from "Assigned Number for SKIP Protocols"
   skip512, skip1024, skip2048, skip4096