| Peer SSL Certificate Verification |
| ================================= |
| |
| Since version 7.10, libcurl performs peer SSL certificate verification by |
| default. This is done by installing a default CA cert bundle on 'make install' |
| (or similar), that CA bundle package is used by default on operations against |
| SSL servers. |
| |
| Alas, if you communicate with HTTPS servers using certificates that are signed |
| by CAs present in the bundle, you will not notice any changed behavior and you |
| will seamlessly get a higher security level on your SSL connections since 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 |
| curl's CA cert bundle, if the server uses a certificate signed by a CA that |
| isn't included in the bundle or if the remoste host is an imposter |
| impersonating your favourite 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 with with |
| curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE); |
| |
| With the curl command 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 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 installed with the curl package is: |
| /usr/local/share/curl/curl-ca-bundle.crt, which can be changed by running |
| configure with the --with-ca-bundle option pointing out the path of your |
| choice. |
| |
| Neglecting to use one of the above menthods when dealing with a server using a |
| certficate that isn't signed by one of the certficates 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. |
| |
| This procedure has been deemed The Right Thing even though it adds this extra |
| trouble for some users, since it adds security to a majority of the SSL |
| connections that previously weren't really secure. It turned out many people |
| were using previous versions of curl/libcurl without realizing the need for |
| the CA cert options to get truly secure SSL connections. |
| |