mirror of
https://github.com/curl/curl.git
synced 2026-05-14 21:36:23 +03:00
docs/SSLCERTS: rewrite
cleanup, modernize, refresh Remove libcurl solutions, only do curl command lines. Closes #14616
This commit is contained in:
Daniel Stenberg
parent
8e9056f8b1
commit
69b50017a4
1 changed files with 75 additions and 115 deletions
190
docs/SSLCERTS.md
190
docs/SSLCERTS.md
|
|
@ -4,144 +4,105 @@ Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|||
SPDX-License-Identifier: curl
|
||||
-->
|
||||
|
||||
SSL Certificate Verification
|
||||
============================
|
||||
# TLS Certificate Verification
|
||||
|
||||
SSL is TLS
|
||||
----------
|
||||
## Native vs file based
|
||||
|
||||
SSL is the old name. It is called TLS these days.
|
||||
If curl was built with Schannel or Secure Transport support, then curl uses
|
||||
the system native CA store for verification. All other TLS libraries use a
|
||||
file based CA store by default.
|
||||
|
||||
Native SSL
|
||||
----------
|
||||
## Verification
|
||||
|
||||
If libcurl was built with Schannel or Secure Transport support (the native SSL
|
||||
libraries included in Windows and macOS), then this does not apply to
|
||||
you. Scroll down for details on how the OS-native engines handle SSL
|
||||
certificates. If you are not sure, then run "curl -V" and read the results. If
|
||||
the version string says `Schannel` in it, then it was built with Schannel
|
||||
support.
|
||||
Every trusted server certificate is digitally signed by a Certificate
|
||||
Authority, a CA.
|
||||
|
||||
It is about trust
|
||||
-----------------
|
||||
In your local CA store you have a collection of certificates from *trusted*
|
||||
certificate authorities that TLS clients like curl use to verify servers.
|
||||
|
||||
This system is about trust. In your local CA certificate store you have certs
|
||||
from *trusted* Certificate Authorities that you then can use to verify that
|
||||
the server certificates you see are valid. They are signed by one of the
|
||||
certificate authorities you trust.
|
||||
|
||||
Which certificate authorities do you trust? You can decide to trust the same
|
||||
set of companies your operating system trusts, or the set one of the known
|
||||
browsers trust. That is basically trust via someone else you trust. You should
|
||||
just be aware that modern operating systems and browsers are setup to trust
|
||||
*hundreds* of companies and in recent years several certificate authorities
|
||||
have been found untrustworthy.
|
||||
|
||||
Certificate Verification
|
||||
------------------------
|
||||
|
||||
libcurl performs peer SSL certificate verification by default. This is done
|
||||
by using a CA certificate store that the SSL library can use to make sure the
|
||||
peer's server certificate is valid.
|
||||
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 in the CA store, you can be sure that the remote server really is
|
||||
the one it claims to be.
|
||||
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
|
||||
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, and you want to transfer files from this
|
||||
server, do one of the following:
|
||||
impersonating your favorite site, the certificate check fails and reports an
|
||||
error.
|
||||
|
||||
1. Tell libcurl to *not* verify the peer. With libcurl you disable this with
|
||||
`curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`
|
||||
If you think it wrongly failed the verification, consider one of the following
|
||||
sections.
|
||||
|
||||
With the curl command line tool, you disable this with `-k`/`--insecure`.
|
||||
### Skip verification
|
||||
|
||||
2. 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
|
||||
libcurl hackers: `curl_easy_setopt(curl, CURLOPT_CAINFO, cacert);`
|
||||
Tell curl to *not* verify the peer with `-k`/`--insecure`.
|
||||
|
||||
With the curl command line tool: `--cacert [file]`
|
||||
We **strongly** recommend this is avoided and that even if you end up doing
|
||||
this for experimentation or development, **never** skip verification in
|
||||
production.
|
||||
|
||||
3. Add the CA cert for your server to the existing default CA certificate
|
||||
store. The default CA certificate store can be changed at compile time with
|
||||
the following configure options:
|
||||
### Use a custom CA store
|
||||
|
||||
`--with-ca-bundle=FILE`: use the specified file as the CA certificate
|
||||
store. CA certificates need to be concatenated in PEM format into this
|
||||
file.
|
||||
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-ca-path=PATH`: use the specified path as CA certificate store. CA
|
||||
certificates need to be stored as individual PEM files in this directory.
|
||||
You may need to run c_rehash after adding files there.
|
||||
With the curl command line tool: `--cacert [file]`
|
||||
|
||||
If neither of the two options is specified, configure tries to auto-detect
|
||||
a setting. It's also possible to explicitly not set any default store but
|
||||
rely on the built in default the crypto library may provide instead. You
|
||||
can achieve that by passing both `--without-ca-bundle` and
|
||||
`--without-ca-path` to the configure script.
|
||||
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.
|
||||
|
||||
If you use Internet Explorer, this is one way to get extract the CA cert
|
||||
for a particular server:
|
||||
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%
|
||||
|
||||
- View the certificate by double-clicking the padlock
|
||||
- Find out where the CA certificate is kept (Certificate>
|
||||
Authority Information Access>URL)
|
||||
- Get a copy of the crt file using curl
|
||||
- Convert it from crt to PEM using the OpenSSL tool:
|
||||
`openssl x509 -inform DES -in yourdownloaded.crt -out outcert.pem -text`
|
||||
- Add the `outcert.pem` to the CA certificate store or use it stand-alone
|
||||
as described below.
|
||||
### Use the native store
|
||||
|
||||
If you use the `openssl` tool, this is one way to get extract the CA cert
|
||||
for a particular server:
|
||||
In several environments, in particular on Windows, you can ask curl to use the
|
||||
system's native CA store when verifying the certificate.
|
||||
|
||||
- `openssl s_client -showcerts -servername server -connect server:443 > cacert.pem`
|
||||
- type "quit", followed by the "ENTER" key
|
||||
- The certificate has `BEGIN CERTIFICATE` and `END CERTIFICATE` markers.
|
||||
- If you want to see the data in the certificate, you can do: `openssl
|
||||
x509 -inform PEM -in certfile -text -out certdata` where `certfile` is
|
||||
the cert you extracted from logfile. Look in `certdata`.
|
||||
- If you want to trust the certificate, you can add it to your CA
|
||||
certificate store or use it stand-alone as described. Just remember that
|
||||
the security is no better than the way you obtained the certificate.
|
||||
With the curl command line tool: `--ca-native`.
|
||||
|
||||
4. If you are using the curl command line tool and the TLS backend is not
|
||||
Schannel then you can specify your own CA cert file by setting the
|
||||
environment variable `CURL_CA_BUNDLE` to the path of your choice.
|
||||
### Modify the CA store
|
||||
|
||||
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%
|
||||
Add the CA cert for your server to the existing default CA certificate store.
|
||||
|
||||
5. Get another CA cert bundle. One option is to extract the one a recent
|
||||
Firefox browser uses by running 'make ca-bundle' in the curl build tree
|
||||
root, or possibly download a version that was generated this way for you:
|
||||
[CA Extract](https://curl.se/docs/caextract.html)
|
||||
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.
|
||||
|
||||
Neglecting to use one of the above methods when dealing with a server using a
|
||||
certificate that is not signed by one of the certificates in the installed CA
|
||||
certificate store, causes SSL to report an error (`certificate verify failed`)
|
||||
during the handshake and SSL then refuses further communication with that
|
||||
server.
|
||||
### Change curl's default CA store
|
||||
|
||||
Certificate Verification with Schannel and Secure Transport
|
||||
-----------------------------------------------------------
|
||||
The default CA certificate store curl uses is set at build time. When you
|
||||
build curl you can point out your preferred path.
|
||||
|
||||
If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure
|
||||
Transport (Apple's native TLS engine) support, then libcurl still performs
|
||||
peer certificate verification, but instead of using a CA cert bundle, it 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.
|
||||
### 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, Secure Transport or were 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.
|
||||
Secure Transport on iOS runs OCSP checks on certificates unless peer
|
||||
|
|
@ -149,12 +110,11 @@ verification is disabled. Secure Transport on macOS runs either OCSP or CRL
|
|||
checks on certificates if those features are enabled, and this behavior can be
|
||||
adjusted in the preferences of Keychain Access.
|
||||
|
||||
HTTPS proxy
|
||||
-----------
|
||||
## HTTPS proxy
|
||||
|
||||
Since version 7.52.0, curl can do HTTPS to the proxy separately from the
|
||||
connection to the server. This TLS connection is handled separately from the
|
||||
server connection so instead of `--insecure` and `--cacert` to control the
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue