Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/SSLCERTS.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
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_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 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 path 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.