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