Artifactspublic-v0

curl

master
ply4 git calls250 ms289 KiB2 cachedprotocol v2
120 lines3.4 KiBRaw

NAME

CURLOPT_SSL_VERIFYHOST - verify the certificate's name against host

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify);

DESCRIPTION

Pass a long set to 2L to make libcurl verify the host in the server's TLS certificate.

When negotiating a TLS connection, 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. The certificate has to have the same name as is used in the URL you operate against.

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.

When the verify value is 0, the connection succeeds regardless of the names in the certificate. Use that ability with caution.

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 verification makes the communication insecure. Having encryption on a transfer is not enough as you cannot be sure that you are communicating with the correct end-point.

When libcurl uses secure protocols it trusts responses and allows for example 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.

DEFAULT

2

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* Set the default value: strict name check please */
    curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);

    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

%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

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

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)
11 - CURLOPT_PROXY_SSL_VERIFYHOST (3)
12 - CURLOPT_DOH_SSL_VERIFYHOST (3)
13Protocol:
14 - TLS
15TLS-backend:
16 - All
17Added-in: 7.8.1
18---
20# NAME
22CURLOPT_SSL_VERIFYHOST - verify the certificate's name against host
24# SYNOPSIS
26~~~c
27#include <curl/curl.h>
29CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify);
30~~~
32# DESCRIPTION
34Pass a long set to 2L to make libcurl verify the host in the server's TLS
35certificate.
37When negotiating a TLS connection, the server sends a certificate indicating
38its identity.
40When CURLOPT_SSL_VERIFYHOST(3) is set to 1 or 2, the server certificate must
41indicate that it was made for the hostname or address curl connects to, or the
42connection fails. The certificate has to have the same name as is used in the
43URL you operate against.
45curl considers the server the intended one when the Common Name field or a
46Subject Alternate Name field in the certificate matches the hostname in the
47URL to which you told curl to connect.
49When the *verify* value is 0, the connection succeeds regardless of the names
50in the certificate. Use that ability with caution.
52This option controls checking the server's certificate's claimed identity. The
53separate CURLOPT_SSL_VERIFYPEER(3) options enables/disables verification that
54the certificate is signed by a trusted Certificate Authority.
56**WARNING:** disabling verification of the certificate allows bad guys to
57man-in-the-middle the communication without you knowing it. Disabling
58verification makes the communication insecure. Having encryption on a transfer
59is not enough as you cannot be sure that you are communicating with the
60correct end-point.
62When libcurl uses secure protocols it trusts responses and allows for example
63HSTS and Alt-Svc information to be stored and used subsequently. Disabling
64certificate verification can make libcurl trust and use such information from
65malicious servers.
67# MATCHING
69A certificate can have the name as a wildcard. The only asterisk (`*`) must
70then be the left-most character and it must be followed by a period. The
71wildcard must further contain more than one period as it cannot be set for a
72top-level domain.
74A certificate can be set for a numerical IP address (IPv4 or IPv6), but then
75it should be a Subject Alternate Name kind and its type should correctly
76identify the field as an IP address.
78# DEFAULT
82# %PROTOCOLS%
84# EXAMPLE
86~~~c
87int main(void)
89 CURL *curl = curl_easy_init();
90 if(curl) {
91 CURLcode result;
92 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
94 /* Set the default value: strict name check please */
95 curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);
97 result = curl_easy_perform(curl);
98 curl_easy_cleanup(curl);
99 }
101~~~
103# %AVAILABILITY%
105# HISTORY
107In 7.28.0 and earlier: the value 1 was treated as a debug option of some
108sorts, not supported anymore due to frequently leading to programmer mistakes.
110From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt(3) return
111an error and leaving the flag untouched.
113From 7.66.0: libcurl treats 1 and 2 to this option the same.
115# RETURN VALUE
117curl_easy_setopt(3) returns a CURLcode indicating success or error.
119CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
120libcurl-errors(3).
Diagnostics4 git calls · 250 ms
CallStatusSizeTime0250 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=244
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.7 KiB244 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1734
git.response.cache=MISS
git.response.duration_ms=244
git.fetch.wants=d4c0ae9acf949c034ca0aeb47ab19190df5ae7be
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1734
git.pkt.payload.max=1713
git.sideband.band1.bytes=1712
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e35caafc3f5cd4
Request
1a4ed5b8…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format