CURLOPT_SSL_VERIFYHOST.md (3407B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: CURLOPT_SSL_VERIFYHOST 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_CAINFO (3) 9 - CURLOPT_PINNEDPUBLICKEY (3) 10 - CURLOPT_SSL_VERIFYPEER (3) 11 Protocol: 12 - TLS 13 TLS-backend: 14 - All 15 Added-in: 7.8.1 16 --- 17 18 # NAME 19 20 CURLOPT_SSL_VERIFYHOST - verify the certificate's name against host 21 22 # SYNOPSIS 23 24 ~~~c 25 #include <curl/curl.h> 26 27 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify); 28 ~~~ 29 30 # DESCRIPTION 31 32 Pass a long set to 2L to make libcurl verify the host in the server's TLS 33 certificate. 34 35 When negotiating a TLS connection, the server sends a certificate indicating 36 its identity. 37 38 When CURLOPT_SSL_VERIFYHOST(3) is set to 1 or 2, the server certificate must 39 indicate that it was made for the hostname or address curl connects to, or the 40 connection fails. Simply put, it means it has to have the same name in the 41 certificate as is used in the URL you operate against. 42 43 curl considers the server the intended one when the Common Name field or a 44 Subject Alternate Name field in the certificate matches the hostname in the 45 URL to which you told curl to connect. 46 47 When the *verify* value is 0, the connection succeeds regardless of the names 48 in the certificate. Use that ability with caution, 49 50 This option controls checking the server's certificate's claimed identity. The 51 separate CURLOPT_SSL_VERIFYPEER(3) options enables/disables verification that 52 the certificate is signed by a trusted Certificate Authority. 53 54 WARNING: disabling verification of the certificate allows bad guys to 55 man-in-the-middle the communication without you knowing it. Disabling 56 verification makes the communication insecure. Just having encryption on a 57 transfer is not enough as you cannot be sure that you are communicating with 58 the correct end-point. 59 60 When libcurl uses secure protocols it trusts responses and allows for example 61 HSTS and Alt-Svc information to be stored and used subsequently. Disabling 62 certificate verification can make libcurl trust and use such information from 63 malicious servers. 64 65 # MATCHING 66 67 A certificate can have the name as a wildcard. The only asterisk (`*`) must 68 then be the left-most character and it must be followed by a period. The 69 wildcard must further contain more than one period as it cannot be set for a 70 top-level domain. 71 72 A certificate can be set for a numerical IP address (IPv4 or IPv6), but then 73 it should be a Subject Alternate Name kind and its type should correctly 74 identify the field as an IP address. 75 76 # DEFAULT 77 78 2 79 80 # %PROTOCOLS% 81 82 # EXAMPLE 83 84 ~~~c 85 int main(void) 86 { 87 CURL *curl = curl_easy_init(); 88 if(curl) { 89 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 90 91 /* Set the default value: strict name check please */ 92 curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L); 93 94 curl_easy_perform(curl); 95 } 96 } 97 ~~~ 98 99 # %AVAILABILITY% 100 101 # HISTORY 102 103 In 7.28.0 and earlier: the value 1 was treated as a debug option of some 104 sorts, not supported anymore due to frequently leading to programmer mistakes. 105 106 From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt(3) return 107 an error and leaving the flag untouched. 108 109 From 7.66.0: libcurl treats 1 and 2 to this option the same. 110 111 # RETURN VALUE 112 113 curl_easy_setopt(3) returns a CURLcode indicating success or error. 114 115 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 116 libcurl-errors(3).