Expand documentation for "?ca=/..." option

[TobyGoodwin]

Describing issue #840 in more detail, as requested.

Problem: construct a listen URL for https with a 3-certificate chain (own cert, intermediate, and trust anchor).

My initial attempt, having read the Mojo::Server::Daemon documentation:

https://10.1.2.3:443?cert=/path/to/my.crt&key=/path/to/my.key&ca=/path/to/intermed.crt

Frustratingly, this nearly works. In fact, openssl s_client gives no errors, and it's only if you notice that you don't actually end up talking to the server that you realise something has gone wrong. Similarly, an online SSL tester reports that it is fine. But gnutls-cli, and anything that actually tries to communicate with the server, report errors like this one:

OpenSSL: error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure

A URL that actually works for my configuration is as follows:

https://10.1.2.3:443?cert=/path/to/chain.crt&key=/path/to/my.key

where chain.crt contains both my certificate and the intermediate.

As you point out in #840, I don't know what ca= does. If I did, I would amend the documentation myself to describe it, and send you a PR. My best guess as to what it does is that it enables client authentication. This makes sense of a lot of things: it explains the handshake failure. It makes sense of "Path to TLS certificate authority file", the 6 words which are supposed to explain the option: if the server is verifying certificates too, we need to tell it what trust anchors to use. And it makes sense of the comment in the examples: Or even a custom certificate authority, since client authentication is unusual (to say the least).

Suggested fix: somebody who definitely knows what ca= means should expand the documentation to describe it in more detail. If my guess is correct, then something like this would do:

ca
    ca=/etc/tls/ca.crt

Enables client authentication and specifies the path to a file containing trusted CA certificates for the server to use when verifying client certificates.

[kraih]

Thanks, mentioned in the docs now.