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