1SSL Certificate Verification 2============================ 3 4SSL is TLS 5---------- 6 7SSL is the old name. It is called TLS these days. 8 9Native SSL 10---------- 11 12If libcurl was built with Schannel or Secure Transport support (the native SSL 13libraries included in Windows and Mac OS X), then this does not apply to 14you. Scroll down for details on how the OS-native engines handle SSL 15certificates. If you are not sure, then run "curl -V" and read the results. If 16the version string says `Schannel` in it, then it was built with Schannel 17support. 18 19It is about trust 20----------------- 21 22This system is about trust. In your local CA certificate store you have certs 23from *trusted* Certificate Authorities that you then can use to verify that 24the server certificates you see are valid. They are signed by one of the 25certificate authorities you trust. 26 27Which certificate authorities do you trust? You can decide to trust the same 28set of companies your operating system trusts, or the set one of the known 29browsers trust. That is basically trust via someone else you trust. You should 30just be aware that modern operating systems and browsers are setup to trust 31*hundreds* of companies and in recent years several certificate authorities 32have been found untrustworthy. 33 34Certificate Verification 35------------------------ 36 37libcurl performs peer SSL certificate verification by default. This is done 38by using a CA certificate store that the SSL library can use to make sure the 39peer's server certificate is valid. 40 41If you communicate with HTTPS, FTPS or other TLS-using servers using 42certificates in the CA store, you can be sure that the remote server really is 43the one it claims to be. 44 45If the remote server uses a self-signed certificate, if you do not install a CA 46cert store, if the server uses a certificate signed by a CA that is not 47included in the store 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_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 be changed at compile time with 64 the following configure options: 65 66 `--with-ca-bundle=FILE`: use the specified file as the CA certificate 67 store. CA certificates need to be concatenated in PEM format into this 68 file. 69 70 `--with-ca-path=PATH`: use the specified path as CA certificate store. CA 71 certificates need to be stored as individual PEM files in this directory. 72 You may need to run c_rehash after adding files there. 73 74 If neither of the two options is specified, configure will try to 75 auto-detect a setting. It's also possible to explicitly not set any 76 default store but rely on the built in default the crypto library may 77 provide instead. You can achieve that by passing both 78 `--without-ca-bundle` and `--without-ca-path` to the configure script. 79 80 If you use Internet Explorer, this is one way to get extract the CA cert 81 for a particular server: 82 83 - View the certificate by double-clicking the padlock 84 - Find out where the CA certificate is kept (Certificate> 85 Authority Information Access>URL) 86 - Get a copy of the crt file using curl 87 - Convert it from crt to PEM using the OpenSSL tool: 88 `openssl x509 -inform DES -in yourdownloaded.crt -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 are using the curl command line tool and the TLS backend is not 107 Schannel then you can specify your own CA cert file by setting the 108 environment variable `CURL_CA_BUNDLE` to the path of your choice. 109 110 If you are 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 another CA cert bundle. One option is to extract the one a recent 120 Firefox browser uses by running 'make ca-bundle' in the curl build tree 121 root, or possibly download a version that was generated this way for you: 122 [CA Extract](https://curl.se/docs/caextract.html) 123 124Neglecting to use one of the above methods when dealing with a server using a 125certificate that is not signed by one of the certificates in the installed CA 126certificate store, will cause SSL to report an error ("certificate verify 127failed") during the handshake and SSL will then refuse further communication 128with that server. 129 130Certificate Verification with Schannel and Secure Transport 131----------------------------------------------------------- 132 133If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure 134Transport (Apple's native TLS engine) support, then libcurl will still perform 135peer certificate verification, but instead of using a CA cert bundle, it will 136use the certificates that are built into the OS. These are the same 137certificates that appear in the Internet Options control panel (under Windows) 138or Keychain Access application (under OS X). Any custom security rules for 139certificates will be honored. 140 141Schannel will run CRL checks on certificates unless peer verification is 142disabled. Secure Transport on iOS will run OCSP checks on certificates unless 143peer verification is disabled. Secure Transport on OS X will run either OCSP 144or CRL checks on certificates if those features are enabled, and this behavior 145can be adjusted in the preferences of Keychain Access. 146 147HTTPS proxy 148----------- 149 150Since version 7.52.0, curl can do HTTPS to the proxy separately from the 151connection to the server. This TLS connection is handled separately from the 152server connection so instead of `--insecure` and `--cacert` to control the 153certificate verification, you use `--proxy-insecure` and `--proxy-cacert`. 154With these options, you make sure that the TLS connection and the trust of the 155proxy can be kept totally separate from the TLS connection to the server. 156