2002-11-12 01:41:45 +03:00
|
|
|
Peer SSL Certificate Verification
|
|
|
|
=================================
|
2003-06-27 01:30:48 +04:00
|
|
|
|
2013-02-19 03:27:30 +04:00
|
|
|
(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.)
|
|
|
|
|
2008-02-18 14:35:12 +03:00
|
|
|
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.
|
2002-11-12 01:37:59 +03:00
|
|
|
|
2004-08-09 11:02:51 +04:00
|
|
|
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.
|
2002-11-12 01:37:59 +03:00
|
|
|
|
2008-02-18 14:35:12 +03:00
|
|
|
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
|
|
|
|
included in the bundle you use or if the remote host is an impostor
|
2004-06-29 17:16:30 +04:00
|
|
|
impersonating your favorite site, and you want to transfer files from this
|
2004-03-16 10:25:52 +03:00
|
|
|
server, do one of the following:
|
2002-11-12 01:37:59 +03:00
|
|
|
|
2008-02-09 00:04:24 +03:00
|
|
|
1. Tell libcurl to *not* verify the peer. With libcurl you disable this with
|
2002-11-12 01:37:59 +03:00
|
|
|
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);
|
|
|
|
|
2004-06-29 11:58:52 +04:00
|
|
|
With the curl command line tool, you disable this with -k/--insecure.
|
2002-11-12 01:37:59 +03:00
|
|
|
|
|
|
|
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);
|
|
|
|
|
2004-06-29 11:58:52 +04:00
|
|
|
With the curl command line tool: --cacert [file]
|
2002-11-12 01:37:59 +03:00
|
|
|
|
2004-03-30 10:46:36 +04:00
|
|
|
3. Add the CA cert for your server to the existing default CA cert bundle.
|
2008-02-18 14:35:12 +03:00
|
|
|
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.
|
2004-03-30 10:46:36 +04:00
|
|
|
|
2004-08-25 12:09:48 +04:00
|
|
|
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:
|
|
|
|
|
|
|
|
o View the certificate by double-clicking the padlock
|
|
|
|
o Find out where the CA certificate is kept (Certificate>
|
|
|
|
Authority Information Access>URL)
|
|
|
|
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
|
|
|
|
o Append the 'outcert.pem' to the CA cert bundle or use it stand-alone
|
|
|
|
as described below.
|
|
|
|
|
2004-09-12 22:27:12 +04:00
|
|
|
If you use the 'openssl' tool, this is one way to get extract the CA cert
|
|
|
|
for a particular server:
|
|
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
2004-08-25 12:09:48 +04:00
|
|
|
4. If you're using the curl command line tool, you can specify your own CA
|
2004-06-29 11:58:52 +04:00
|
|
|
cert path by setting the environment variable CURL_CA_BUNDLE to the path
|
|
|
|
of your choice.
|
|
|
|
|
2004-06-29 17:16:30 +04:00
|
|
|
If you're using the curl command line tool on Windows, curl will search
|
2004-06-29 11:58:52 +04:00
|
|
|
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%
|
|
|
|
|
2004-08-25 12:09:48 +04:00
|
|
|
5. Get a better/different/newer CA cert bundle! One option is to extract the
|
2009-08-18 23:51:18 +04:00
|
|
|
one a recent Firefox browser uses by running 'make ca-bundle' in the curl
|
2008-02-08 14:18:23 +03:00
|
|
|
build tree root, or possibly download a version that was generated this
|
|
|
|
way for you:
|
2004-08-09 11:02:51 +04:00
|
|
|
|
|
|
|
http://curl.haxx.se/docs/caextract.html
|
|
|
|
|
2004-06-29 17:16:30 +04:00
|
|
|
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
|
2003-01-23 09:15:26 +03:00
|
|
|
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.
|
2009-09-22 03:00:12 +04:00
|
|
|
|
|
|
|
Peer SSL Certificate Verification with NSS
|
|
|
|
==========================================
|
|
|
|
|
2013-02-19 03:27:30 +04:00
|
|
|
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 will check for the NSS version it runs,
|
|
|
|
and automatically add the 'sql:' prefix to the certdb directory (either the
|
2009-09-22 03:00:12 +04:00
|
|
|
hardcoded default /etc/pki/nssdb or the directory configured with SSL_DIR
|
2013-02-19 03:27:30 +04:00
|
|
|
environment variable) if version 3.12.0 or later is detected. To check which
|
|
|
|
ertdb format your distribution provides, examine the default
|
|
|
|
certdb location: /etc/pki/nssdb; the new certdb format can be identified by
|
2009-09-22 03:00:12 +04:00
|
|
|
the filenames cert9.db, key4.db, pkcs11.txt; filenames of older versions are
|
|
|
|
cert8.db, key3.db, modsec.db.
|
|
|
|
|
2013-02-19 03:27:30 +04:00
|
|
|
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
|
2009-09-22 03:00:12 +04:00
|
|
|
|
2013-02-19 03:27:30 +04:00
|
|
|
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)
|
|
|
|
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.
|