update docs

[amesgen]

The previous documentation is misleading, as OpenSSL 1.1.0 did not change the fact that contextSetVerificationMode is necessary for OpenSSL to check anything about the certificate. Also, I added a link to the (new) function enabling the OpenSSL built-in hostname validation instead of referring to a PDF.

[redneb]

Hi @amesgen, thanks for the PR.

You absolutely right, contextSetVerificationMode has to be called even with OpenSSL >= 1.1.0. When I changed that part of the documentation a few weeks ago I wasn't careful enough.

My only concern with the new phrasing that you propose is that I think it would be better to keep the note about old (<1.1.0) versions of OpenSSL not verifying automatically the peer's hostname, even with contextSetVerificationMode. How about if we added the following at the end of your version:

In addition to that, if you are using a version of OpenSSL older than 1.1.0, you also need to verify that the peer's hostname matches with one specified in the certificate. You can find information on how to do that here. Newer versions of OpenSSL (>=1.1.0) perform that check automatically.

or something like that.

[amesgen]

Hmm, I am no expert in OpenSSL, but I think that, even in OpenSSL >= 1.1.0, setting contextSetVerificationMode to VerifyPeer only checks that there is a valid certificate chain (how should OpenSSL know about the correct hostname? It is not passed as an argument to contextSetVerificationMode.). Hostname validation has to be enabled in addition to this, either manually or with the "new" functions added in OpenSSL 1.1.0 and 1.0.2, which I recently added to HsOpenSSL: enableHostnameValidation and vshabanov/HsOpenSSL#52, see https://wiki.openssl.org/index.php/Hostname_validation.