CURLOPT_SSL_VERIFYHOST.md: refresh

Move mentions of old behavior to the HISTORY section to make it easier
to read about modern behavior.

Added a MATCHING section.

Closes #14241

diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md
index 9c7715bf5a6952de7cabd4b93b3e763a7f857030..30b1525fe430c930efb4f5fb5b0027f75cfb8197 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md
+++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md
@@ -29,40 +29,27 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify);
 
 # DESCRIPTION
 
-Pass a long as parameter specifying what to *verify*.
+Pass a long set to 2L to make libcurl verify the host in the server's TLS
+certificate.
 
-This option determines whether libcurl verifies that the server cert is for
-the server it is known as.
+When negotiating a TLS connection, the server sends a certificate indicating
+its identity.
 
-When negotiating TLS and SSL connections, the server sends a certificate
-indicating its identity.
+When CURLOPT_SSL_VERIFYHOST(3) is set to 1 or 2, the server certificate must
+indicate that it was made for the hostname or address curl connects to, or the
+connection fails. Simply put, it means it has to have the same name in the
+certificate as is used in the URL you operate against.
 
-When CURLOPT_SSL_VERIFYHOST(3) is 2, that certificate must indicate that
-the server is the server to which you meant to connect, or the connection
-fails. Simply put, it means it has to have the same name in the certificate as
-is in the URL you operate against.
-
-Curl considers the server the intended one when the Common Name field or a
+curl considers the server the intended one when the Common Name field or a
 Subject Alternate Name field in the certificate matches the hostname in the
-URL to which you told Curl to connect.
-
-If *verify* value is set to 1:
-
-In 7.28.0 and earlier: treated as a debug option of some sorts, not supported
-anymore due to frequently leading to programmer mistakes.
+URL to which you told curl to connect.
 
-From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt(3) return
-an error and leaving the flag untouched.
+When the *verify* value is 0, the connection succeeds regardless of the names
+in the certificate. Use that ability with caution,
 
-From 7.66.0: treats 1 and 2 the same.
-
-When the *verify* value is 0, the connection succeeds regardless of the
-names in the certificate. Use that ability with caution!
-
-The default value for this option is 2.
-
-This option controls checking the server's certificate's claimed identity.
-The server could be lying. To control lying, see CURLOPT_SSL_VERIFYPEER(3).
+This option controls checking the server's certificate's claimed identity. The
+separate CURLOPT_SSL_VERIFYPEER(3) options enables/disables verification that
+the certificate is signed by a trusted Certificate Authority.
 
 WARNING: disabling verification of the certificate allows bad guys to
 man-in-the-middle the communication without you knowing it. Disabling
@@ -75,13 +62,24 @@ HSTS and Alt-Svc information to be stored and used subsequently. Disabling
 certificate verification can make libcurl trust and use such information from
 malicious servers.
 
+# MATCHING
+
+A certificate can have the name as a wildcard. The only asterisk (`*`) must
+then be the left-most character and it must be followed by a period. The
+wildcard must further contain more than one period as it cannot be set for a
+top-level domain.
+
+A certificate can be set for a numerical IP address (IPv4 or IPv6), but then
+it should be a Subject Alternate Name kind and its type should correctly
+identify the field as an IP address.
+
 # LIMITATIONS
 
-Secure Transport: If *verify* value is 0, then SNI is also disabled. SNI is
-a TLS extension that sends the hostname to the server. The server may use that
+Secure Transport: If *verify* value is 0, then SNI is also disabled. SNI is a
+TLS extension that sends the hostname to the server. The server may use that
 information to do such things as sending back a specific certificate for the
-hostname, or forwarding the request to a specific origin server. Some hostnames
-may be inaccessible if SNI is not sent.
+hostname, or forwarding the request to a specific origin server. Some
+hostnames may be inaccessible if SNI is not sent.
 
 # DEFAULT
 
@@ -108,8 +106,16 @@ int main(void)
 
 # %AVAILABILITY%
 
+# HISTORY
+
+In 7.28.0 and earlier: the value 1 was treated as a debug option of some
+sorts, not supported anymore due to frequently leading to programmer mistakes.
+
+From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt(3) return
+an error and leaving the flag untouched.
+
+From 7.66.0: libcurl treats 1 and 2 to this option the same.
+
 # RETURN VALUE
 
 Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not.
-
-If 1 is set as argument, *CURLE_BAD_FUNCTION_ARGUMENT* is returned.