123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153 |
- SSL Certificate Verification
- ============================
- SSL is TLS
- ----------
- SSL is the old name. It is called TLS these days.
- Native SSL
- ----------
- If libcurl was built with Schannel or Secure Transport support (the native SSL
- libraries included in Windows and Mac OS X), then this does not apply to
- you. Scroll down for details on how the OS-native engines handle SSL
- certificates. If you're not sure, then run "curl -V" and read the results. If
- the version string says "WinSSL" in it, then it was built with Schannel
- support.
- It is about trust
- -----------------
- This system is about trust. In your local CA cert bundle you have certs from
- *trusted* Certificate Authorities that you then can use to verify that the
- server certificates you see are valid. They're signed by one of the CAs you
- trust.
- Which CAs do you trust? You can decide to trust the same set of companies your
- operating system trusts, or the set one of the known browsers trust. That's
- basically trust via someone else you trust. You should just be aware that
- modern operating systems and browsers are setup to trust *hundreds* of
- companies and recent years several such CAs have been found untrustworthy.
- Certificate Verification
- ------------------------
- libcurl performs peer SSL certificate verification by default. This is done
- by using CA cert bundle that the SSL library can use to make sure the peer's
- server certificate is valid.
- If you communicate with HTTPS, FTPS or other TLS-using servers using
- certificates that are signed by CAs present in the bundle, you can be sure
- that the remote server really is the one it claims to be.
- If the remote server uses a self-signed certificate, if you don't install a CA
- cert bundle, if the server uses a certificate signed by a CA that isn't
- included in the bundle you use or if the remote host is an impostor
- impersonating your favorite site, and you want to transfer files from this
- server, do one of the following:
- 1. Tell libcurl to *not* verify the peer. With libcurl you disable this with
- `curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`
- With the curl command line tool, you disable this with -k/--insecure.
- 2. Get a CA certificate that can verify the remote server and use the proper
- option to point out this CA cert for verification when connecting. For
- libcurl hackers: `curl_easy_setopt(curl, CURLOPT_CAPATH, capath);`
- With the curl command line tool: --cacert [file]
- 3. Add the CA cert for your server to the existing default CA cert bundle.
- The default path of the CA bundle used can be changed by running configure
- with the --with-ca-bundle option pointing out the path of your choice.
- To do this, you need to get the CA cert for your server in PEM format and
- then append that to your CA cert bundle.
- If you use Internet Explorer, this is one way to get extract the CA cert
- for a particular server:
- - View the certificate by double-clicking the padlock
- - Find out where the CA certificate is kept (Certificate>
- Authority Information Access>URL)
- - Get a copy of the crt file using curl
- - Convert it from crt to PEM using the openssl tool:
- openssl x509 -inform DES -in yourdownloaded.crt \
- -out outcert.pem -text
- - Append the 'outcert.pem' to the CA cert bundle or use it stand-alone
- as described below.
- If you use the 'openssl' tool, this is one way to get extract the CA cert
- for a particular server:
- - `openssl s_client -connect xxxxx.com:443 |tee logfile`
- - type "QUIT", followed by the "ENTER" key
- - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"
- markers.
- - If you want to see the data in the certificate, you can do: "openssl
- x509 -inform PEM -in certfile -text -out certdata" where certfile is
- the cert you extracted from logfile. Look in certdata.
- - If you want to trust the certificate, you can append it to your
- cert bundle or use it stand-alone as described. Just remember that the
- security is no better than the way you obtained the certificate.
- 4. If you're using the curl command line tool, you can specify your own CA
- cert path by setting the environment variable `CURL_CA_BUNDLE` to the path
- of your choice.
- If you're using the curl command line tool on Windows, curl will search
- for a CA cert file named "curl-ca-bundle.crt" in these directories and in
- this order:
- 1. application's directory
- 2. current working directory
- 3. Windows System directory (e.g. C:\windows\system32)
- 4. Windows Directory (e.g. C:\windows)
- 5. all directories along %PATH%
- 5. Get a better/different/newer CA cert bundle! One option is to extract the
- one a recent Firefox browser uses by running 'make ca-bundle' in the curl
- build tree root, or possibly download a version that was generated this
- way for you: [CA Extract](http://curl.haxx.se/docs/caextract.html)
- Neglecting to use one of the above methods when dealing with a server using a
- certificate that isn't signed by one of the certificates in the installed CA
- cert bundle, will cause SSL to report an error ("certificate verify failed")
- during the handshake and SSL will then refuse further communication with that
- server.
- Certificate Verification with NSS
- ---------------------------------
- If libcurl was built with NSS support, then depending on the OS distribution,
- it is probably required to take some additional steps to use the system-wide
- CA cert db. RedHat ships with an additional module, libnsspem.so, which
- enables NSS to read the OpenSSL PEM CA bundle. This library is missing in
- OpenSuSE, and without it, NSS can only work with its own internal formats. NSS
- also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB).
- Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to
- the certdb directory (either the hardcoded default /etc/pki/nssdb or the
- directory configured with SSL_DIR environment variable). To check which certdb
- format your distribution provides, examine the default certdb location:
- /etc/pki/nssdb; the new certdb format can be identified by the filenames
- cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db,
- key3.db, secmod.db.
- Certificate Verification with Schannel and Secure Transport
- -----------------------------------------------------------
- If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure
- Transport (Apple's native TLS engine) support, then libcurl will still perform
- peer certificate verification, but instead of using a CA cert bundle, it will
- use the certificates that are built into the OS. These are the same
- certificates that appear in the Internet Options control panel (under Windows)
- or Keychain Access application (under OS X). Any custom security rules for
- certificates will be honored.
- Schannel will run CRL checks on certificates unless peer verification is
- disabled. Secure Transport on iOS will run OCSP checks on certificates unless
- peer verification is disabled. Secure Transport on OS X will run either OCSP
- or CRL checks on certificates if those features are enabled, and this behavior
- can be adjusted in the preferences of Keychain Access.
|