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