curl/docs/SSLCERTS.md

<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.

SPDX-License-Identifier: curl
-->

SSL Certificate Verification
============================

SSL is TLS
----------

SSL is the old name. It is called TLS these days.

Native SSL
----------

If libcurl was built with Schannel or Secure Transport support (the native SSL
libraries included in Windows and Mac OS X), 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.

It is about trust
-----------------

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.

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.

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:

 1. Tell libcurl to *not* verify the peer. With libcurl you disable this with
    `curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`

    With the curl command line tool, you disable this with `-k`/`--insecure`.

 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);`

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

 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:

    `--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.

    `--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.

    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 Internet Explorer, this is one way to get extract the CA cert
    for a particular server:

     - 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.

    If you use the `openssl` tool, this is one way to get extract the CA cert
    for a particular server:

     - `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.

 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.

    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%

 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)

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.

Certificate Verification with Schannel and Secure Transport
-----------------------------------------------------------

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 OS X). 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
verification is disabled. Secure Transport on OS X 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
-----------

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
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.