1SSL Certificate Verification 2============================ 3 4SSL is TLS 5---------- 6 7SSL is the old name. It is called TLS these days. 8 9 10Native SSL 11---------- 12 13If libcurl was built with Schannel or Secure Transport support (the native SSL 14libraries included in Windows and Mac OS X), then this does not apply to 15you. Scroll down for details on how the OS-native engines handle SSL 16certificates. If you're not sure, then run "curl -V" and read the results. If 17the version string says "WinSSL" in it, then it was built with Schannel 18support. 19 20It is about trust 21----------------- 22 23This 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 25server certificates you see are valid. They're signed by one of the CAs you 26trust. 27 28Which CAs do you trust? You can decide to trust the same set of companies your 29operating system trusts, or the set one of the known browsers trust. That's 30basically trust via someone else you trust. You should just be aware that 31modern operating systems and browsers are setup to trust *hundreds* of 32companies and recent years several such CAs have been found untrustworthy. 33 34Certificate Verification 35------------------------ 36 37libcurl performs peer SSL certificate verification by default. This is done 38by using CA cert bundle that the SSL library can use to make sure the peer's 39server certificate is valid. 40 41If you communicate with HTTPS, FTPS or other TLS-using servers using 42certificates that are signed by CAs present in the bundle, you can be sure 43that the remote server really is the one it claims to be. 44 45If the remote server uses a self-signed certificate, if you don't install a CA 46cert bundle, if the server uses a certificate signed by a CA that isn't 47included in the bundle you use or if the remote host is an impostor 48impersonating your favorite site, and you want to transfer files from this 49server, 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 114Neglecting to use one of the above methods when dealing with a server using a 115certificate that isn't signed by one of the certificates in the installed CA 116cert bundle, will cause SSL to report an error ("certificate verify failed") 117during the handshake and SSL will then refuse further communication with that 118server. 119 120Certificate Verification with NSS 121--------------------------------- 122 123If libcurl was built with NSS support, then depending on the OS distribution, 124it is probably required to take some additional steps to use the system-wide 125CA cert db. RedHat ships with an additional module, libnsspem.so, which 126enables NSS to read the OpenSSL PEM CA bundle. This library is missing in 127OpenSuSE, and without it, NSS can only work with its own internal formats. NSS 128also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB). 129 130Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to 131the certdb directory (either the hardcoded default /etc/pki/nssdb or the 132directory configured with SSL_DIR environment variable). To check which certdb 133format your distribution provides, examine the default certdb location: 134/etc/pki/nssdb; the new certdb format can be identified by the filenames 135cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db, 136key3.db, secmod.db. 137 138Certificate Verification with Schannel and Secure Transport 139----------------------------------------------------------- 140 141If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure 142Transport (Apple's native TLS engine) support, then libcurl will still perform 143peer certificate verification, but instead of using a CA cert bundle, it will 144use the certificates that are built into the OS. These are the same 145certificates that appear in the Internet Options control panel (under Windows) 146or Keychain Access application (under OS X). Any custom security rules for 147certificates will be honored. 148 149Schannel will run CRL checks on certificates unless peer verification is 150disabled. Secure Transport on iOS will run OCSP checks on certificates unless 151peer verification is disabled. Secure Transport on OS X will run either OCSP 152or CRL checks on certificates if those features are enabled, and this behavior 153can be adjusted in the preferences of Keychain Access. 154