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