1<!-- 2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4SPDX-License-Identifier: curl 5--> 6 7# TLS Certificate Verification 8 9## Native vs file based 10 11If curl was built with Schannel or Secure Transport support, then curl uses 12the system native CA store for verification. All other TLS libraries use a 13file based CA store by default. 14 15## Verification 16 17Every trusted server certificate is digitally signed by a Certificate 18Authority, a CA. 19 20In your local CA store you have a collection of certificates from *trusted* 21certificate authorities that TLS clients like curl use to verify servers. 22 23curl does certificate verification by default. This is done by verifying the 24signature and making sure the certificate was crafted for the server name 25provided in the URL. 26 27If you communicate with HTTPS, FTPS or other TLS-using servers using 28certificates signed by a CA whose certificate is present in the store, you can 29be sure that the remote server really is the one it claims to be. 30 31If the remote server uses a self-signed certificate, if you do not install a 32CA cert store, if the server uses a certificate signed by a CA that is not 33included in the store you use or if the remote host is an impostor 34impersonating your favorite site, the certificate check fails and reports an 35error. 36 37If you think it wrongly failed the verification, consider one of the following 38sections. 39 40### Skip verification 41 42Tell curl to *not* verify the peer with `-k`/`--insecure`. 43 44We **strongly** recommend this is avoided and that even if you end up doing 45this for experimentation or development, **never** skip verification in 46production. 47 48### Use a custom CA store 49 50Get a CA certificate that can verify the remote server and use the proper 51option to point out this CA cert for verification when connecting - for this 52specific transfer only. 53 54With the curl command line tool: `--cacert [file]` 55 56If you use the curl command line tool without a native CA store, then you can 57specify your own CA cert file by setting the environment variable 58`CURL_CA_BUNDLE` to the path of your choice. 59 60If you are using the curl command line tool on Windows, curl searches for a CA 61cert file named `curl-ca-bundle.crt` in these directories and in this order: 62 1. application's directory 63 2. current working directory 64 3. Windows System directory (e.g. C:\Windows\System32) 65 4. Windows Directory (e.g. C:\Windows) 66 5. all directories along %PATH% 67 68curl 8.11.0 added a build-time option to disable this search behavior, and 69another option to restrict search to the application's directory. 70 71### Use the native store 72 73In several environments, in particular on Windows, you can ask curl to use the 74system's native CA store when verifying the certificate. 75 76With the curl command line tool: `--ca-native`. 77 78### Modify the CA store 79 80Add the CA cert for your server to the existing default CA certificate store. 81 82Usually you can figure out the path to the local CA store by looking at the 83verbose output that `curl -v` shows when you connect to an HTTPS site. 84 85### Change curl's default CA store 86 87The default CA certificate store curl uses is set at build time. When you 88build curl you can point out your preferred path. 89 90### Extract CA cert from a server 91 92 curl -w %{certs} https://example.com > cacert.pem 93 94The certificate has `BEGIN CERTIFICATE` and `END CERTIFICATE` markers. 95 96### Get the Mozilla CA store 97 98Download a version of the Firefox CA store converted to PEM format on the [CA 99Extract](https://curl.se/docs/caextract.html) page. It always features the 100latest Firefox bundle. 101 102## Native CA store 103 104If curl was built with Schannel, Secure Transport or were instructed to use 105the native CA Store, then curl uses the certificates that are built into the 106OS. These are the same certificates that appear in the Internet Options 107control panel (under Windows) or Keychain Access application (under macOS). 108Any custom security rules for certificates are honored. 109 110Schannel runs CRL checks on certificates unless peer verification is disabled. 111Secure Transport on iOS runs OCSP checks on certificates unless peer 112verification is disabled. Secure Transport on macOS runs either OCSP or CRL 113checks on certificates if those features are enabled, and this behavior can be 114adjusted in the preferences of Keychain Access. 115 116## HTTPS proxy 117 118curl can do HTTPS to the proxy separately from the connection to the server. 119This TLS connection is handled and verified separately from the server 120connection so instead of `--insecure` and `--cacert` to control the 121certificate verification, you use `--proxy-insecure` and `--proxy-cacert`. 122With these options, you make sure that the TLS connection and the trust of the 123proxy can be kept totally separate from the TLS connection to the server. 124
