SSLCERTS.md (4484B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 # TLS Certificate Verification 8 9 ## Native vs file based 10 11 If curl was built with Schannel support, then curl uses the system native CA 12 store for verification. All other TLS libraries use a file based CA store by 13 default. 14 15 ## Verification 16 17 Every trusted server certificate is digitally signed by a Certificate 18 Authority, a CA. 19 20 In your local CA store you have a collection of certificates from *trusted* 21 certificate authorities that TLS clients like curl use to verify servers. 22 23 curl does certificate verification by default. This is done by verifying the 24 signature and making sure the certificate was crafted for the server name 25 provided in the URL. 26 27 If you communicate with HTTPS, FTPS or other TLS-using servers using 28 certificates signed by a CA whose certificate is present in the store, you can 29 be sure that the remote server really is the one it claims to be. 30 31 If the remote server uses a self-signed certificate, if you do not install a 32 CA cert store, if the server uses a certificate signed by a CA that is not 33 included in the store you use or if the remote host is an impostor 34 impersonating your favorite site, the certificate check fails and reports an 35 error. 36 37 If you think it wrongly failed the verification, consider one of the following 38 sections. 39 40 ### Skip verification 41 42 Tell curl to *not* verify the peer with `-k`/`--insecure`. 43 44 We **strongly** recommend this is avoided and that even if you end up doing 45 this for experimentation or development, **never** skip verification in 46 production. 47 48 ### Use a custom CA store 49 50 Get a CA certificate that can verify the remote server and use the proper 51 option to point out this CA cert for verification when connecting - for this 52 specific transfer only. 53 54 With the curl command line tool: `--cacert [file]` 55 56 If you use the curl command line tool without a native CA store, then you can 57 specify your own CA cert file by setting the environment variable 58 `CURL_CA_BUNDLE` to the path of your choice. `SSL_CERT_FILE` and `SSL_CERT_DIR` 59 are also supported. 60 61 If you are using the curl command line tool on Windows, curl searches for a CA 62 cert file named `curl-ca-bundle.crt` in these directories and in this order: 63 1. application's directory 64 2. current working directory 65 3. Windows System directory (e.g. C:\Windows\System32) 66 4. Windows Directory (e.g. C:\Windows) 67 5. all directories along %PATH% 68 69 curl 8.11.0 added a build-time option to disable this search behavior, and 70 another option to restrict search to the application's directory. 71 72 ### Use the native store 73 74 In several environments, in particular on Windows, you can ask curl to use the 75 system's native CA store when verifying the certificate. 76 77 With the curl command line tool: `--ca-native`. 78 79 ### Modify the CA store 80 81 Add the CA cert for your server to the existing default CA certificate store. 82 83 Usually you can figure out the path to the local CA store by looking at the 84 verbose output that `curl -v` shows when you connect to an HTTPS site. 85 86 ### Change curl's default CA store 87 88 The default CA certificate store curl uses is set at build time. When you 89 build curl you can point out your preferred path. 90 91 ### Extract CA cert from a server 92 93 curl -w %{certs} https://example.com > cacert.pem 94 95 The certificate has `BEGIN CERTIFICATE` and `END CERTIFICATE` markers. 96 97 ### Get the Mozilla CA store 98 99 Download a version of the Firefox CA store converted to PEM format on the [CA 100 Extract](https://curl.se/docs/caextract.html) page. It always features the 101 latest Firefox bundle. 102 103 ## Native CA store 104 105 If curl was built with Schannel or was instructed to use the native CA Store, 106 then curl uses the certificates that are built into the OS. These are the same 107 certificates that appear in the Internet Options control panel (under Windows) 108 or Keychain Access application (under macOS). Any custom security rules for 109 certificates are honored. 110 111 Schannel runs CRL checks on certificates unless peer verification is disabled. 112 113 ## HTTPS proxy 114 115 curl can do HTTPS to the proxy separately from the connection to the server. 116 This TLS connection is handled and verified separately from the server 117 connection so instead of `--insecure` and `--cacert` to control the 118 certificate verification, you use `--proxy-insecure` and `--proxy-cacert`. 119 With these options, you make sure that the TLS connection and the trust of the 120 proxy can be kept totally separate from the TLS connection to the server.