mirror of
https://github.com/curl/curl.git
synced 2026-04-17 23:01:45 +03:00
08a3e8e19a
These libraries do not support TLS 1.3 and have been marked for removal for over a year. We want to help users select a TLS dependency that is future-proof and reliable, and not supporting TLS 1.3 in 2025 does not infer confidence. Users who build libcurl are likely to be served better and get something more future-proof with a TLS library that supports 1.3. Closes #16677
120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
<!--
|
|
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
|
|
SPDX-License-Identifier: curl
|
|
-->
|
|
|
|
# TLS Certificate Verification
|
|
|
|
## Native vs file based
|
|
|
|
If curl was built with Schannel support, then curl uses the system native CA
|
|
store for verification. 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.
|
|
|
|
### Use the native store
|
|
|
|
In several environments, in particular on Windows, you can ask curl to use the
|
|
system's native CA store when verifying the certificate.
|
|
|
|
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](https://curl.se/docs/caextract.html) page. It always features the
|
|
latest Firefox bundle.
|
|
|
|
## Native CA store
|
|
|
|
If curl was built with Schannel or was instructed to use the native CA Store,
|
|
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)
|
|
or Keychain Access application (under macOS). Any custom security rules for
|
|
certificates are honored.
|
|
|
|
Schannel runs CRL checks on certificates unless peer verification is disabled.
|
|
|
|
## 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.
|