From bb639db6fbcc1bc6519b13998561ff361b98aa7e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 20 Jul 2024 01:11:13 +0200 Subject: [PATCH] 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 --- docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md | 74 +++++++++++---------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md index 9c7715bf5a..30b1525fe4 100644 --- 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. +URL to which you told curl to connect. -If *verify* value is set to 1: +When the *verify* value is 0, the connection succeeds regardless of the names +in the certificate. Use that ability with caution, -In 7.28.0 and earlier: 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: 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.