NAME¶

AnyEvent::TLS - SSLv2/SSLv3/TLSv1 contexts for use in AnyEvent::Handle

SYNOPSIS¶

   # via AnyEvent::Handle
   use AnyEvent;
   use AnyEvent::Handle;
   use AnyEvent::Socket;
   # simple https-client
   my $handle = new AnyEvent::Handle
      connect  => [$host, $port],
      tls      => "connect",
      tls_ctx  => { verify => 1, verify_peername => "https" },
      ...
   # simple ssl-server
   tcp_server undef, $port, sub {
      my ($fh) = @_;
      my $handle = new AnyEvent::Handle
         fh       => $fh,
         tls      => "accept",
         tls_ctx  => { cert_file => "my-server-keycert.pem" },
         ...
   # directly
   my $tls = new AnyEvent::TLS
      verify => 1,
      verify_peername => "ldaps",
      ca_file => "/etc/cacertificates.pem";

DESCRIPTION¶

This module is a helper module that implements TLS/SSL (Transport Layer Security/Secure Sockets Layer) contexts. A TLS context is a common set of configuration values for use in establishing TLS connections.

For some quick facts about SSL/TLS, see the section of the same name near the end of the document.

A single TLS context can be used for any number of TLS connections that wish to use the same certificates, policies etc.

Note that this module is inherently tied to Net::SSLeay, as this library is used to implement it. Since that perl module is rather ugly, and OpenSSL has a rather ugly license, AnyEvent might switch TLS providers at some future point, at which this API will change dramatically, at least in the Net::SSLeay-specific parts (most constructor arguments should still work, though).

Although this module does not require a specific version of Net::SSLeay, many features will gradually stop working, or bugs will be introduced with old versions (verification might succeed when it shouldn't - this is a real security issue). Version 1.35 is recommended, 1.33 should work, 1.32 might, and older versions are yours to keep.

USAGE EXAMPLES¶

See the AnyEvent::Handle manpage, NONFREQUENTLY ASKED QUESTIONS, for some actual usage examples.

PUBLIC METHODS AND FUNCTIONS¶

$tls = new AnyEvent::TLS key => value...

The constructor supports these arguments (all as key => value pairs).

$tls = new_from_ssleay AnyEvent::TLS $ctx

This constructor takes an existing Net::SSLeay SSL_CTX object (which is just an integer) and converts it into an "AnyEvent::TLS" object. This only works because AnyEvent::TLS is currently implemented using Net::SSLeay. As this is such a horrible perl module and OpenSSL has such an annoying license, this might change in the future, in which case this method might vanish.

$ctx = $tls->ctx

Returns the actual Net::SSLeay::CTX object (just an integer).

AnyEvent::TLS::init

AnyEvent::TLS does on-demand initialisation, and normally there is no need to call an initialise function.

As initialisation might take some time (to read e.g. "/dev/urandom"), this could be annoying in some highly interactive programs. In that case, you can call "AnyEvent::TLS::init" to make sure there will be no costly initialisation later. It is harmless to call "AnyEvent::TLS::init" multiple times.

$certname = AnyEvent::TLS::certname $x509

Utility function that returns a user-readable string identifying the X509 certificate object.

SSL/TLS QUICK FACTS¶

Here are some quick facts about TLS/SSL that might help you:

• A certificate is the public key part, a key is the private key part.

  While not strictly true, certificates are the things you can hand around publicly as a kind of identity, while keys should really be kept private, as proving that you have the private key is usually interpreted as being the entity behind the certificate.

• A certificate is signed by a CA (Certificate Authority).

  By signing, the CA basically claims that the certificate it signs really belongs to the identity named in it, verified according to the CA policies. For e.g. HTTPS, the CA usually makes some checks that the hostname mentioned in the certificate really belongs to the company/person that requested the signing and owns the domain.

• CAs can be certified by other CAs.

  Or by themselves - a certificate that is signed by a CA that is itself is called a self-signed certificate, a trust chain of length zero. When you find a certificate signed by another CA, which is in turn signed by another CA you trust, you have a trust chain of depth two.

• "Trusting" a CA means trusting all certificates it has signed.

  If you "trust" a CA certificate, then all certificates signed by it are automatically considered trusted as well.

• A successfully verified certificate means that you can be reasonably sure that whoever you are talking with really is who he claims he is.

  By verifying certificates against a number of CAs that you trust (meaning it is signed directly or indirectly by such a CA), you can find out that the other side really is whoever he claims, according to the CA policies, and your belief in the integrity of the CA.

• Verifying the certificate signature is not everything.

  Even when the certificate is correct, it might belong to somebody else: if www.attacker.com can make your computer believe that it is really called www.mybank.com (by making your DNS server believe this for example), then it could send you the certificate for www.attacker.com that your software trusts because it is signed by a CA you trust, and intercept all your traffic that you think goes to www.mybank.com. This works because your software sees that the certificate is correctly signed (for www.attacker.com) and you think you are talking to your bank.

  To thwart this attack vector, peername verification should be used, which basically checks that the certificate (for www.attacker.com) really belongs to the host you are trying to talk to (www.mybank.com), which in this example is not the case, as www.attacker.com (from the certificate) doesn't match www.mybank.com (the hostname used to create the connection).

  So peername verification is almost as important as checking the CA signing. Unfortunately, every protocol implements this differently, if at all...

• Switching off verification is sometimes reasonable.

  You can switch off verification. You still get an encrypted connection that is protected against eavesdropping and injection - you just lose protection against man in the middle attacks, i.e. somebody else with enough abilities to intercept all traffic can masquerade herself as the other side.

  For many applications, switching off verification is entirely reasonable. Downloading random stuff from websites using HTTPS for no reason is such an application. Talking to your bank and entering TANs is not such an application.

• A SSL/TLS server always needs a certificate/key pair to operate, for clients this is optional.

  Apart from (usually disabled) anonymous cipher suites, a server always needs a certificate/key pair to operate.

  Clients almost never use certificates, but if they do, they can be used to authenticate the client, just as server certificates can be used to authenticate the server.

• SSL version 2 is very insecure.

  SSL version 2 is old and not only has it some security issues, SSLv2-only implementations are usually buggy, too, due to their age.

• Sometimes, even losing your "private" key might not expose all your data.

  With Diffie-Hellman ephemeral key exchange, you can lose the DH parameters (the "keys"), but all your connections are still protected. Diffie-Hellman needs special set-up (done by default by AnyEvent::TLS).

SECURITY CONSIDERATIONS¶

When you use any of the options that pass in keys or certificates as strings (e.g. "ca_cert"), then, due to serious shortcomings in Net::SSLeay, this module creates a temporary file to store the string - see File::Temp and possibly its "safe_level" setting for more details on what to watch out for.

BUGS¶

Due to the abysmal code quality of Net::SSLeay, this module will leak small amounts of memory per TLS connection (currently at least one perl scalar).

AUTHORS¶

Marc Lehmann <schmorp@schmorp.de>.

Some of the API, documentation and implementation (verify_hostname), and a lot of ideas/workarounds/knowledge have been taken from the IO::Socket::SSL module. Care has been taken to keep the API similar to that and other modules, to the extent possible while providing a sensible API for AnyEvent.