Artifactspublic-v0

curl

master
ply4 git calls33 ms289 KiB3 cachedprotocol v2
159 lines5.9 KiBRaw

TLS Certificate Verification

Native vs file based

If curl was built with Schannel support, then curl uses the Windows native CA store for verification. On Apple operating systems, it is possible to use Apple's "SecTrust" services for certain TLS backends, details below. All other TLS libraries use a file based CA store by default.

Verification

Every trusted server certificate is digitally signed by a Certificate Authority, a CA.

In your local CA store you have a collection of certificates from trusted certificate authorities that TLS clients like curl use to verify servers.

curl does certificate verification by default. This is done by verifying the signature and making sure the certificate was crafted for the server name provided in the URL.

If you communicate with HTTPS, FTPS or other TLS-using servers using certificates signed by a CA whose certificate is present in the store, you can be sure that the remote server really is the one it claims to be.

If the remote server uses a self-signed certificate, if you do not install a CA cert store, if the server uses a certificate signed by a CA that is not included in the store you use or if the remote host is an impostor impersonating your favorite site, the certificate check fails and reports an error.

If you think it wrongly failed the verification, consider one of the following sections.

Skip verification

Tell curl to not verify the peer with -k/--insecure.

We strongly recommend this is avoided and that even if you end up doing this for experimentation or development, never skip verification in production.

Use a custom CA store

Get a CA certificate that can verify the remote server and use the proper option to point out this CA cert for verification when connecting - for this specific transfer only.

With the curl command line tool: --cacert [file]

If you use the curl command line tool without a native CA store, then you can specify your own CA cert file by setting the environment variable CURL_CA_BUNDLE to the path of your choice. SSL_CERT_FILE and SSL_CERT_DIR are also supported.

If you are using the curl command line tool on Windows, curl searches for a CA cert file named curl-ca-bundle.crt in these directories and in this order:

  1. application's directory
  2. current working directory
  3. Windows System directory (e.g. C:\Windows\System32)
  4. Windows Directory (e.g. C:\Windows)
  5. all directories along %PATH%

curl 8.11.0 added a build-time option to disable this search behavior, and another option to restrict search to the application's directory.

curl 8.19.0 added a build-time option to enable Native CA by default on Windows. This build-time option by default also disables searching for a curl-ca-bundle.crt on disk.

Use the native store

In several environments, in particular on Microsoft and Apple operating systems, you can ask curl to use the system's native CA store when verifying the certificate. Depending on how curl was built, this may already be the default.

With the curl command line tool: --ca-native.

Modify the CA store

Add the CA cert for your server to the existing default CA certificate store.

Usually you can figure out the path to the local CA store by looking at the verbose output that curl -v shows when you connect to an HTTPS site.

Change curl's default CA store

The default CA certificate store curl uses is set at build time. When you build curl you can point out your preferred path.

Extract CA cert from a server

curl -w %{certs} https://example.com > cacert.pem

The certificate has BEGIN CERTIFICATE and END CERTIFICATE markers.

Get the Mozilla CA store

Download a version of the Firefox CA store converted to PEM format on the CA Extract page. It always features the latest Firefox bundle.

Native CA store

Windows + Schannel

If curl was built with Schannel, then curl uses the certificates that are built into the OS. These are the same certificates that appear in the Internet Options control panel (under Windows). Any custom security rules for certificates are honored.

Schannel runs CRL checks on certificates unless peer verification is disabled.

Apple + OpenSSL/GnuTLS

When curl is built with Apple SecTrust enabled and uses an OpenSSL compatible TLS backend or GnuTLS, the default verification is handled by that Apple service. As in:

curl https://example.com

You may still provide your own certificates on the command line, such as:

curl --cacert mycerts.pem https://example.com

In this situation, Apple SecTrust is not used and verification is done only with the trust anchors found in mycerts.pem. If you want both Apple SecTrust and your own file to be considered, use:

curl --ca-native --cacert mycerts.pem https://example.com
Other Combinations

How well the use of native CA stores work in all other combinations depends on the TLS backend and the OS. Many TLS backends offer functionality to access the native CA on a range of operating systems. Some provide this only on specific configurations.

Specific support in curl exists for Windows and OpenSSL compatible TLS backends. It tries to load the certificates from the Windows "CA" and "ROOT" stores for transfers requesting the native CA. Due to Window's delayed population of those stores, this might not always find all certificates.

HTTPS proxy

curl can do HTTPS to the proxy separately from the connection to the server. This TLS connection is handled and verified separately from the server connection so instead of --insecure and --cacert to control the certificate verification, you use --proxy-insecure and --proxy-cacert. With these options, you make sure that the TLS connection and the trust of the proxy can be kept totally separate from the TLS connection to the server.

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# TLS Certificate Verification
9## Native vs file based
11If curl was built with Schannel support, then curl uses the Windows native CA
12store for verification. On Apple operating systems, it is possible to use Apple's
13"SecTrust" services for certain TLS backends, details below.
14All other TLS libraries use a file based CA store by
15default.
17## Verification
19Every trusted server certificate is digitally signed by a Certificate
20Authority, a CA.
22In your local CA store you have a collection of certificates from *trusted*
23certificate authorities that TLS clients like curl use to verify servers.
25curl does certificate verification by default. This is done by verifying the
26signature and making sure the certificate was crafted for the server name
27provided in the URL.
29If you communicate with HTTPS, FTPS or other TLS-using servers using
30certificates signed by a CA whose certificate is present in the store, you can
31be sure that the remote server really is the one it claims to be.
33If the remote server uses a self-signed certificate, if you do not install a
34CA cert store, if the server uses a certificate signed by a CA that is not
35included in the store you use or if the remote host is an impostor
36impersonating your favorite site, the certificate check fails and reports an
37error.
39If you think it wrongly failed the verification, consider one of the following
40sections.
42### Skip verification
44Tell curl to *not* verify the peer with `-k`/`--insecure`.
46We **strongly** recommend this is avoided and that even if you end up doing
47this for experimentation or development, **never** skip verification in
48production.
50### Use a custom CA store
52Get a CA certificate that can verify the remote server and use the proper
53option to point out this CA cert for verification when connecting - for this
54specific transfer only.
56With the curl command line tool: `--cacert [file]`
58If you use the curl command line tool without a native CA store, then you can
59specify your own CA cert file by setting the environment variable
60`CURL_CA_BUNDLE` to the path of your choice. `SSL_CERT_FILE` and `SSL_CERT_DIR`
61are also supported.
63If you are using the curl command line tool on Windows, curl searches for a CA
64cert file named `curl-ca-bundle.crt` in these directories and in this order:
65 1. application's directory
66 2. current working directory
67 3. Windows System directory (e.g. C:\Windows\System32)
68 4. Windows Directory (e.g. C:\Windows)
69 5. all directories along %PATH%
71curl 8.11.0 added a build-time option to disable this search behavior, and
72another option to restrict search to the application's directory.
74curl 8.19.0 added a build-time option to enable Native CA by default on
75Windows. This build-time option by default also disables searching for
76a `curl-ca-bundle.crt` on disk.
78### Use the native store
80In several environments, in particular on Microsoft and Apple operating
81systems, you can ask curl to use the system's native CA store when verifying
82the certificate. Depending on how curl was built, this may already be the
83default.
85With the curl command line tool: `--ca-native`.
87### Modify the CA store
89Add the CA cert for your server to the existing default CA certificate store.
91Usually you can figure out the path to the local CA store by looking at the
92verbose output that `curl -v` shows when you connect to an HTTPS site.
94### Change curl's default CA store
96The default CA certificate store curl uses is set at build time. When you
97build curl you can point out your preferred path.
99### Extract CA cert from a server
101 curl -w %{certs} https://example.com > cacert.pem
103The certificate has `BEGIN CERTIFICATE` and `END CERTIFICATE` markers.
105### Get the Mozilla CA store
107Download a version of the Firefox CA store converted to PEM format on the [CA
108Extract](https://curl.se/docs/caextract.html) page. It always features the
109latest Firefox bundle.
111## Native CA store
113### Windows + Schannel
115If curl was built with Schannel, then curl uses the certificates that are
116built into the OS. These are the same certificates that appear in the
117Internet Options control panel (under Windows).
118Any custom security rules for certificates are honored.
120Schannel runs CRL checks on certificates unless peer verification is disabled.
122### Apple + OpenSSL/GnuTLS
124When curl is built with Apple SecTrust enabled and uses an OpenSSL compatible
125TLS backend or GnuTLS, the default verification is handled by that Apple
126service. As in:
128 curl https://example.com
130You may still provide your own certificates on the command line, such as:
132 curl --cacert mycerts.pem https://example.com
134In this situation, Apple SecTrust is **not** used and verification is done
135**only** with the trust anchors found in `mycerts.pem`. If you want **both**
136Apple SecTrust and your own file to be considered, use:
138 curl --ca-native --cacert mycerts.pem https://example.com
140#### Other Combinations
142How well the use of native CA stores work in all other combinations depends
143on the TLS backend and the OS. Many TLS backends offer functionality to access
144the native CA on a range of operating systems. Some provide this only on specific
145configurations.
147Specific support in curl exists for Windows and OpenSSL compatible TLS backends.
148It tries to load the certificates from the Windows "CA" and "ROOT" stores for
149transfers requesting the native CA. Due to Window's delayed population of those
150stores, this might not always find all certificates.
152## HTTPS proxy
154curl can do HTTPS to the proxy separately from the connection to the server.
155This TLS connection is handled and verified separately from the server
156connection so instead of `--insecure` and `--cacert` to control the
157certificate verification, you use `--proxy-insecure` and `--proxy-cacert`.
158With these options, you make sure that the TLS connection and the trust of the
159proxy can be kept totally separate from the TLS connection to the server.
Diagnostics4 git calls · 33 ms
CallStatusSizeTime033 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=3
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=27
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
fetch2002.6 KiB · hit27 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2644
git.response.cache=HIT
git.response.duration_ms=27
git.fetch.wants=d5110e18f0f4f1efcb6798983c4c8484e7344b3d
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=2644
git.pkt.payload.max=2623
git.sideband.band1.bytes=2622
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
a5e154bfef1c90ce
Request
20e3aea3…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format