SSL is the old name. It is called TLS these days.
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.
This system is about trust. In your local CA certificate store 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.
libcurl performs peer SSL certificate verification by default. This is done by using a CA certificate store 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 store, 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 store, if the server uses a certificate signed by a CA that isn’t included in the store 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:
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.
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]
Add the CA cert for your server to the existing default CA certificate store. The default CA certificate store can changed at compile time with the following configure options:
--with-ca-bundle=FILE: use the specified file as CA certificate store. CA certificates need to be concatenated in PEM format into this file.
--with-ca-path=PATH: use the specified path as CA certificate store. CA certificates need to be stored as individual PEM files in this directory. You may need to run c_rehash after adding files there.
If neither of the two options is specified, configure will try to auto-detect a setting. It's also possible to explicitly not hardcode any default store but rely on the built in default the crypto library may provide instead. You can achieve that by passing both --without-ca-bundle and --without-ca-path to the configure script.
If you use Internet Explorer, this is one way to get extract the CA cert for a particular server:
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 logfileIf 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:
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
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 certificate store, will cause SSL to report an error (“certificate verify failed”) during the handshake and SSL will then refuse further communication with that server.
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. On openSUSE you can install p11-kit-nss-trust which makes NSS use the system wide CA certificate store. NSS also has a new database format.
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.
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.