1 Peer SSL Certificate Verification 2 ================================= 3 4(NOTE: If libcurl was built with Schannel or Secure Transport support, then 5this does not apply to you. Scroll down for details on how the OS-native 6engines handle SSL certificates. If you're not sure, then run "curl -V" and 7read the results. If the version string says "WinSSL" in it, then it was built 8with Schannel support.) 9 10libcurl performs peer SSL certificate verification by default. This is done 11by using CA cert bundle that the SSL library can use to make sure the peer's 12server certificate is valid. 13 14If you communicate with HTTPS or FTPS servers using certificates that are 15signed by CAs present in the bundle, you can be sure that the remote server 16really is the one it claims to be. 17 18Until 7.18.0, curl bundled a severely outdated ca bundle file that was 19installed by default. These days, the curl archives include no ca certs at 20all. You need to get them elsewhere. See below for example. 21 22If the remote server uses a self-signed certificate, if you don't install a CA 23cert bundle, if the server uses a certificate signed by a CA that isn't 24included in the bundle you use or if the remote host is an impostor 25impersonating your favorite site, and you want to transfer files from this 26server, do one of the following: 27 28 1. Tell libcurl to *not* verify the peer. With libcurl you disable this with 29 curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE); 30 31 With the curl command line tool, you disable this with -k/--insecure. 32 33 2. Get a CA certificate that can verify the remote server and use the proper 34 option to point out this CA cert for verification when connecting. For 35 libcurl hackers: curl_easy_setopt(curl, CURLOPT_CAPATH, capath); 36 37 With the curl command line tool: --cacert [file] 38 39 3. Add the CA cert for your server to the existing default CA cert bundle. 40 The default path of the CA bundle used can be changed by running configure 41 with the --with-ca-bundle option pointing out the path of your choice. 42 43 To do this, you need to get the CA cert for your server in PEM format and 44 then append that to your CA cert bundle. 45 46 If you use Internet Explorer, this is one way to get extract the CA cert 47 for a particular server: 48 49 o View the certificate by double-clicking the padlock 50 o Find out where the CA certificate is kept (Certificate> 51 Authority Information Access>URL) 52 o Get a copy of the crt file using curl 53 o Convert it from crt to PEM using the openssl tool: 54 openssl x509 -inform DES -in yourdownloaded.crt \ 55 -out outcert.pem -text 56 o Append the 'outcert.pem' to the CA cert bundle or use it stand-alone 57 as described below. 58 59 If you use the 'openssl' tool, this is one way to get extract the CA cert 60 for a particular server: 61 62 o openssl s_client -connect xxxxx.com:443 |tee logfile 63 o type "QUIT", followed by the "ENTER" key 64 o The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE" 65 markers. 66 o If you want to see the data in the certificate, you can do: "openssl 67 x509 -inform PEM -in certfile -text -out certdata" where certfile is 68 the cert you extracted from logfile. Look in certdata. 69 o If you want to trust the certificate, you can append it to your 70 cert_bundle or use it stand-alone as described. Just remember that the 71 security is no better than the way you obtained the certificate. 72 73 4. If you're using the curl command line tool, you can specify your own CA 74 cert path by setting the environment variable CURL_CA_BUNDLE to the path 75 of your choice. 76 77 If you're using the curl command line tool on Windows, curl will search 78 for a CA cert file named "curl-ca-bundle.crt" in these directories and in 79 this order: 80 1. application's directory 81 2. current working directory 82 3. Windows System directory (e.g. C:\windows\system32) 83 4. Windows Directory (e.g. C:\windows) 84 5. all directories along %PATH% 85 86 5. Get a better/different/newer CA cert bundle! One option is to extract the 87 one a recent Firefox browser uses by running 'make ca-bundle' in the curl 88 build tree root, or possibly download a version that was generated this 89 way for you: 90 91 http://curl.haxx.se/docs/caextract.html 92 93Neglecting to use one of the above methods when dealing with a server using a 94certificate that isn't signed by one of the certificates in the installed CA 95cert bundle, will cause SSL to report an error ("certificate verify failed") 96during the handshake and SSL will then refuse further communication with that 97server. 98 99 Peer SSL Certificate Verification with NSS 100 ========================================== 101 102If libcurl was built with NSS support, then depending on the OS distribution, 103it is probably required to take some additional steps to use the system-wide CA 104cert db. RedHat ships with an additional module, libnsspem.so, which enables 105NSS to read the OpenSSL PEM CA bundle. This library is missing in OpenSuSE, and 106without it, NSS can only work with its own internal formats. NSS also has a new 107database format: https://wiki.mozilla.org/NSS_Shared_DB 108 109Starting with version 7.19.7, libcurl will check for the NSS version it runs, 110and automatically add the 'sql:' prefix to the certdb directory (either the 111hardcoded default /etc/pki/nssdb or the directory configured with SSL_DIR 112environment variable) if version 3.12.0 or later is detected. To check which 113certdb format your distribution provides, examine the default 114certdb location: /etc/pki/nssdb; the new certdb format can be identified by 115the filenames cert9.db, key4.db, pkcs11.txt; filenames of older versions are 116cert8.db, key3.db, modsec.db. 117 118Usually these cert databases are empty, but NSS also has built-in CAs which are 119provided through a shared library, libnssckbi.so; if you want to use these 120built-in CAs, then create a symlink to libnssckbi.so in /etc/pki/nssdb: 121ln -s /usr/lib[64]/libnssckbi.so /etc/pki/nssdb/libnssckbi.so 122 123 Peer SSL Certificate Verification with Schannel and Secure Transport 124 ==================================================================== 125 126If libcurl was built with Schannel (Microsoft's TLS/SSL engine) or Secure 127Transport (Apple's TLS/SSL engine) support, then libcurl will still perform 128peer certificate verification, but instead of using a CA cert bundle, it will 129use the certificates that are built into the OS. These are the same 130certificates that appear in the Internet Options control panel (under Windows) 131or Keychain Access application (under OS X). Any custom security rules for 132certificates will be honored. 133 134Schannel will run CRL checks on certificates unless peer verification is 135disabled. Secure Transport on iOS will run OCSP checks on certificates unless 136peer verification is disabled. Secure Transport on OS X will run either OCSP 137or CRL checks on certificates if those features are enabled, and this behavior 138can be adjusted in the preferences of Keychain Access. 139