-SSL Certificate Verification
-============================
+ Peer 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
-------------------------
+(NOTE: If libcurl was built with Schannel or Secure Transport support, 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.)
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 you communicate with HTTPS or FTPS 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.
+
+Until 7.18.0, curl bundled a severely outdated ca bundle file that was
+installed by default. These days, the curl archives include no ca certs at
+all. You need to get them elsewhere. See below for example.
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
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);`
+ 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);`
+ libcurl hackers: curl_easy_setopt(curl, CURLOPT_CAPATH, capath);
With the curl command line tool: --cacert [file]
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>
+ o View the certificate by double-clicking the padlock
+ o 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:
+ o Get a copy of the crt file using curl
+ o 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
+ o 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"
+ o openssl s_client -connect xxxxx.com:443 |tee logfile
+ o type "QUIT", followed by the "ENTER" key
+ o The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"
markers.
- - If you want to see the data in the certificate, you can do: "openssl
+ o 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
+ o 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
+ 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
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)
+ way for you:
+
+ 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
during the handshake and SSL will then refuse further communication with that
server.
-Certificate Verification with NSS
----------------------------------
+ Peer SSL 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
+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 will check for the NSS version it runs,
+and automatically add the 'sql:' prefix to the certdb directory (either the
+hardcoded default /etc/pki/nssdb or the directory configured with SSL_DIR
+environment variable) if version 3.12.0 or later is detected. 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, modsec.db.
+
+Usually these cert databases are empty, but NSS also has built-in CAs which are
+provided through a shared library, libnssckbi.so; if you want to use these
+built-in CAs, then create a symlink to libnssckbi.so in /etc/pki/nssdb:
+ln -s /usr/lib[64]/libnssckbi.so /etc/pki/nssdb/libnssckbi.so
+
+ Peer SSL Certificate Verification with Schannel and Secure Transport
+ ====================================================================
+
+If libcurl was built with Schannel (Microsoft's TLS/SSL engine) or Secure
+Transport (Apple's TLS/SSL 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)
projects / platform / upstream / curl.git / blobdiff