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