diff options
Diffstat (limited to 'libs/libcurl/docs/SSLCERTS')
| -rw-r--r-- | libs/libcurl/docs/SSLCERTS | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/libs/libcurl/docs/SSLCERTS b/libs/libcurl/docs/SSLCERTS new file mode 100644 index 0000000000..e6b05c3e3f --- /dev/null +++ b/libs/libcurl/docs/SSLCERTS @@ -0,0 +1,138 @@ + Peer SSL 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 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 +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: + + 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. + + 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. + + 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: + + 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. + + 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 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 +ertdb 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) +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. |