Verifying server certificates

Having a secure connection to a server is not worth a lot if you cannot alsobe certain that you are communicating with thecorrect host. If we do notknow that, we could just as well be talking with an impostor that justappears to be who we think it is.

To check that it communicates with the right TLS server, curl uses a CAstore - a set of certificates to verify the signature of the server'scertificate. All servers provide a certificate to the client as part of theTLS handshake and all public TLS-using servers have acquired that certificatefrom an established Certificate Authority.

After some applied crypto magic, curl knows that the server is in fact thecorrect one that acquired that certificate for the hostname that curl used toconnect to it. Failing to verify the server's certificate is a TLS handshakefailure and curl exits with an error.

In rare circumstances, you may decide that you still want to communicate witha TLS server even if the certificate verification fails. You then accept thefact that your communication may be subject to Man-In-The-Middle attacks. Youlower your guards with the-k or--insecure option.

Native CA stores

Operating systems like Windows and macOS tend to have their own CA stores.

If you run curl with Schannel on Windows, curl uses Windows' own CA store bydefault.

If you run curl with Secure Transport on macOS, curl uses macOS' own CA storeby default.

If you use curl with any other TLS backend than Schannel or Secure Transport,it uses a CA store provided in a separate file or directory, independently ofthe native CA store. However, for some of them you can still ask curl toinstead prefer the native CA store using the--ca-native command lineoption. This option is supported with OpenSSL (and forks), wolfSSL and GnuTLS.

For HTTPS proxies, the corresponding option is called--proxy-ca-native.

CA store in file(s)

If curl is not built to use a TLS library that is native to your platform(like Schannel or Secure Transport), it has to either have been built to knowwhere the local CA store is, or users need to provide a path to the CA storewhen curl is invoked.

You can point out a specific CA bundle to use in the TLS handshake with the--cacert command line option. That bundle needs to be in PEM format. You canalso set the environment variableCURL_CA_BUNDLE to the full path.

CA store on windows

curl built on windows that is not using the native TLS library (Schannel),have an extra sequence for how the CA store can be found and used.

curl searches for a CA cert file namedcurl-ca-bundle.crt in thesedirectories 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%