Annotation of embedaddon/curl/docs/SSLCERTS.md, revision 1.1.1.1
1.1 misho 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_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 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 file 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to SSLCERTS.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs