Return to SSLCERTS.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs

curl

    1: SSL Certificate Verification
    2: ============================
    3: 
    4: SSL is TLS
    5: ----------
    6: 
    7: SSL is the old name. It is called TLS these days.
    8: 
    9: 
   10: Native SSL
   11: ----------
   12: 
   13: If libcurl was built with Schannel or Secure Transport support (the native SSL
   14: libraries included in Windows and Mac OS X), then this does not apply to
   15: you. Scroll down for details on how the OS-native engines handle SSL
   16: certificates. If you're not sure, then run "curl -V" and read the results. If
   17: the version string says "WinSSL" in it, then it was built with Schannel
   18: support.
   19: 
   20: It is about trust
   21: -----------------
   22: 
   23: This system is about trust. In your local CA certificate store you have certs
   24: from *trusted* Certificate Authorities that you then can use to verify that the
   25: server certificates you see are valid. They're signed by one of the CAs you
   26: trust.
   27: 
   28: Which CAs do you trust? You can decide to trust the same set of companies your
   29: operating system trusts, or the set one of the known browsers trust. That's
   30: basically trust via someone else you trust. You should just be aware that
   31: modern operating systems and browsers are setup to trust *hundreds* of
   32: companies and recent years several such CAs have been found untrustworthy.
   33: 
   34: Certificate Verification
   35: ------------------------
   36: 
   37: libcurl performs peer SSL certificate verification by default.  This is done
   38: by using a CA certificate store that the SSL library can use to make sure the
   39: peer's server certificate is valid.
   40: 
   41: If you communicate with HTTPS, FTPS or other TLS-using servers using
   42: certificates that are signed by CAs present in the store, you can be sure
   43: that the remote server really is the one it claims to be.
   44: 
   45: If the remote server uses a self-signed certificate, if you don't install a CA
   46: cert store, if the server uses a certificate signed by a CA that isn't
   47: included in the store you use or if the remote host is an impostor
   48: impersonating your favorite site, and you want to transfer files from this
   49: server, do one of the following:
   50: 
   51:  1. Tell libcurl to *not* verify the peer. With libcurl you disable this with
   52:     `curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`
   53: 
   54:     With the curl command line tool, you disable this with -k/--insecure.
   55: 
   56:  2. Get a CA certificate that can verify the remote server and use the proper
   57:     option to point out this CA cert for verification when connecting. For
   58:     libcurl hackers: `curl_easy_setopt(curl, CURLOPT_CAINFO, cacert);`
   59: 
   60:     With the curl command line tool: --cacert [file]
   61: 
   62:  3. Add the CA cert for your server to the existing default CA certificate
   63:     store. The default CA certificate store can changed at compile time with the
   64:     following configure options:
   65: 
   66:     --with-ca-bundle=FILE: use the specified file as CA certificate store. CA
   67:     certificates need to be concatenated in PEM format into this file.
   68: 
   69:     --with-ca-path=PATH: use the specified path as CA certificate store. CA
   70:     certificates need to be stored as individual PEM files in this directory.
   71:     You may need to run c_rehash after adding files there.
   72: 
   73:     If neither of the two options is specified, configure will try to auto-detect
   74:     a setting. It's also possible to explicitly not hardcode any default store
   75:     but rely on the built in default the crypto library may provide instead.
   76:     You can achieve that by passing both --without-ca-bundle and
   77:     --without-ca-path to the configure script.
   78: 
   79:     If you use Internet Explorer, this is one way to get extract the CA cert
   80:     for a particular server:
   81: 
   82:      - View the certificate by double-clicking the padlock
   83:      - Find out where the CA certificate is kept (Certificate>
   84:        Authority Information Access>URL)
   85:      - Get a copy of the crt file using curl
   86:      - Convert it from crt to PEM using the openssl tool:
   87:        openssl x509 -inform DES -in yourdownloaded.crt \
   88:        -out outcert.pem -text
   89:      - Add the 'outcert.pem' to the CA certificate store or use it stand-alone
   90:        as described below.
   91: 
   92:     If you use the 'openssl' tool, this is one way to get extract the CA cert
   93:     for a particular server:
   94: 
   95:      - `openssl s_client -showcerts -servername server -connect server:443 > cacert.pem`
   96:      - type "quit", followed by the "ENTER" key
   97:      - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"
   98:        markers.
   99:      - If you want to see the data in the certificate, you can do: "openssl
  100:        x509 -inform PEM -in certfile -text -out certdata" where certfile is
  101:        the cert you extracted from logfile. Look in certdata.
  102:      - If you want to trust the certificate, you can add it to your CA
  103:        certificate store or use it stand-alone as described. Just remember that
  104:        the security is no better than the way you obtained the certificate.
  105: 
  106:  4. If you're using the curl command line tool, you can specify your own CA
  107:     cert file by setting the environment variable `CURL_CA_BUNDLE` to the path
  108:     of your choice.
  109: 
  110:     If you're using the curl command line tool on Windows, curl will search
  111:     for a CA cert file named "curl-ca-bundle.crt" in these directories and in
  112:     this order:
  113:       1. application's directory
  114:       2. current working directory
  115:       3. Windows System directory (e.g. C:\windows\system32)
  116:       4. Windows Directory (e.g. C:\windows)
  117:       5. all directories along %PATH%
  118: 
  119:  5. Get a better/different/newer CA cert bundle! One option is to extract the
  120:     one a recent Firefox browser uses by running 'make ca-bundle' in the curl
  121:     build tree root, or possibly download a version that was generated this
  122:     way for you: [CA Extract](https://curl.haxx.se/docs/caextract.html)
  123: 
  124: Neglecting to use one of the above methods when dealing with a server using a
  125: certificate that isn't signed by one of the certificates in the installed CA
  126: certificate store, will cause SSL to report an error ("certificate verify
  127: failed") during the handshake and SSL will then refuse further communication
  128: with that server.
  129: 
  130: Certificate Verification with NSS
  131: ---------------------------------
  132: 
  133: If libcurl was built with NSS support, then depending on the OS distribution,
  134: it is probably required to take some additional steps to use the system-wide
  135: CA cert db. RedHat ships with an additional module, libnsspem.so, which
  136: enables NSS to read the OpenSSL PEM CA bundle. On openSUSE you can install
  137: p11-kit-nss-trust which makes NSS use the system wide CA certificate store. NSS
  138: also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB).
  139: 
  140: Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to
  141: the certdb directory (either the hardcoded default /etc/pki/nssdb or the
  142: directory configured with SSL_DIR environment variable). To check which certdb
  143: format your distribution provides, examine the default certdb location:
  144: /etc/pki/nssdb; the new certdb format can be identified by the filenames
  145: cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db,
  146: key3.db, secmod.db.
  147: 
  148: Certificate Verification with Schannel and Secure Transport
  149: -----------------------------------------------------------
  150: 
  151: If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure
  152: Transport (Apple's native TLS engine) support, then libcurl will still perform
  153: peer certificate verification, but instead of using a CA cert bundle, it will
  154: use the certificates that are built into the OS. These are the same
  155: certificates that appear in the Internet Options control panel (under Windows)
  156: or Keychain Access application (under OS X). Any custom security rules for
  157: certificates will be honored.
  158: 
  159: Schannel will run CRL checks on certificates unless peer verification is
  160: disabled. Secure Transport on iOS will run OCSP checks on certificates unless
  161: peer verification is disabled. Secure Transport on OS X will run either OCSP
  162: or CRL checks on certificates if those features are enabled, and this behavior
  163: can be adjusted in the preferences of Keychain Access.
  164: 
  165: HTTPS proxy
  166: -----------
  167: 
  168: Since version 7.52.0, curl can do HTTPS to the proxy separately from the
  169: connection to the server. This TLS connection is handled separately from the
  170: server connection so instead of `--insecure` and `--cacert` to control the
  171: certificate verification, you use `--proxy-insecure` and `--proxy-cacert`.
  172: With these options, you make sure that the TLS connection and the trust of the
  173: proxy can be kept totally separate from the TLS connection to the server.