docs/SSLCERTS

   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 cert bundle you have certs from
  24 *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 CA cert bundle that the SSL library can use to make sure the peer's
  39 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 bundle, 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 bundle, if the server uses a certificate signed by a CA that isn't
  47 included in the bundle 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_CAPATH, capath);`
  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 cert bundle.
  63     The default path of the CA bundle used can be changed by running configure
  64     with the --with-ca-bundle option pointing out the path of your choice.
  65
  66     To do this, you need to get the CA cert for your server in PEM format and
  67     then append that to your CA cert bundle.
  68
  69     If you use Internet Explorer, this is one way to get extract the CA cert
  70     for a particular server:
  71
  72      - View the certificate by double-clicking the padlock
  73      - Find out where the CA certificate is kept (Certificate>
  74        Authority Information Access>URL)
  75      - Get a copy of the crt file using curl
  76      - Convert it from crt to PEM using the openssl tool:
  77        openssl x509 -inform DES -in yourdownloaded.crt \
  78        -out outcert.pem -text
  79      - Append the 'outcert.pem' to the CA cert bundle or use it stand-alone
  80        as described below.
  81
  82     If you use the 'openssl' tool, this is one way to get extract the CA cert
  83     for a particular server:
  84
  85      - `openssl s_client -connect xxxxx.com:443 |tee logfile`
  86      - type "QUIT", followed by the "ENTER" key
  87      - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"
  88        markers.
  89      - If you want to see the data in the certificate, you can do: "openssl
  90        x509 -inform PEM -in certfile -text -out certdata" where certfile is
  91        the cert you extracted from logfile. Look in certdata.
  92      - If you want to trust the certificate, you can append it to your
  93        cert bundle or use it stand-alone as described. Just remember that the
  94        security is no better than the way you obtained the certificate.
  95
  96  4. If you're using the curl command line tool, you can specify your own CA
  97     cert path by setting the environment variable `CURL_CA_BUNDLE` to the path
  98     of your choice.
  99
 100     If you're using the curl command line tool on Windows, curl will search
 101     for a CA cert file named "curl-ca-bundle.crt" in these directories and in
 102     this order:
 103       1. application's directory
 104       2. current working directory
 105       3. Windows System directory (e.g. C:\windows\system32)
 106       4. Windows Directory (e.g. C:\windows)
 107       5. all directories along %PATH%
 108
 109  5. Get a better/different/newer CA cert bundle! One option is to extract the
 110     one a recent Firefox browser uses by running 'make ca-bundle' in the curl
 111     build tree root, or possibly download a version that was generated this
 112     way for you: [CA Extract](http://curl.haxx.se/docs/caextract.html)
 113
 114 Neglecting to use one of the above methods when dealing with a server using a
 115 certificate that isn't signed by one of the certificates in the installed CA
 116 cert bundle, will cause SSL to report an error ("certificate verify failed")
 117 during the handshake and SSL will then refuse further communication with that
 118 server.
 119
 120 Certificate Verification with NSS
 121 ---------------------------------
 122
 123 If libcurl was built with NSS support, then depending on the OS distribution,
 124 it is probably required to take some additional steps to use the system-wide
 125 CA cert db. RedHat ships with an additional module, libnsspem.so, which
 126 enables NSS to read the OpenSSL PEM CA bundle. This library is missing in
 127 OpenSuSE, and without it, NSS can only work with its own internal formats. NSS
 128 also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB).
 129
 130 Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to
 131 the certdb directory (either the hardcoded default /etc/pki/nssdb or the
 132 directory configured with SSL_DIR environment variable). To check which certdb
 133 format your distribution provides, examine the default certdb location:
 134 /etc/pki/nssdb; the new certdb format can be identified by the filenames
 135 cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db,
 136 key3.db, secmod.db.
 137
 138 Certificate Verification with Schannel and Secure Transport
 139 -----------------------------------------------------------
 140
 141 If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure
 142 Transport (Apple's native TLS engine) support, then libcurl will still perform
 143 peer certificate verification, but instead of using a CA cert bundle, it will
 144 use the certificates that are built into the OS. These are the same
 145 certificates that appear in the Internet Options control panel (under Windows)
 146 or Keychain Access application (under OS X). Any custom security rules for
 147 certificates will be honored.
 148
 149 Schannel will run CRL checks on certificates unless peer verification is
 150 disabled. Secure Transport on iOS will run OCSP checks on certificates unless
 151 peer verification is disabled. Secure Transport on OS X will run either OCSP
 152 or CRL checks on certificates if those features are enabled, and this behavior
 153 can be adjusted in the preferences of Keychain Access.