QRScanner/mobile/jni/thirdparty/curl/docs/SSLCERTS

   1                       Peer SSL Certificate Verification
   2                       =================================
   3
   4 (NOTE: If libcurl was built with Schannel or Secure Transport support, then
   5 this does not apply to you. Scroll down for details on how the OS-native
   6 engines handle SSL certificates. If you're not sure, then run "curl -V" and
   7 read the results. If the version string says "WinSSL" in it, then it was built
   8 with Schannel support.)
   9
  10 libcurl performs peer SSL certificate verification by default.  This is done
  11 by using CA cert bundle that the SSL library can use to make sure the peer's
  12 server certificate is valid.
  13
  14 If you communicate with HTTPS or FTPS servers using certificates that are
  15 signed by CAs present in the bundle, you can be sure that the remote server
  16 really is the one it claims to be.
  17
  18 Until 7.18.0, curl bundled a severely outdated ca bundle file that was
  19 installed by default. These days, the curl archives include no ca certs at
  20 all. You need to get them elsewhere. See below for example.
  21
  22 If the remote server uses a self-signed certificate, if you don't install a CA
  23 cert bundle, if the server uses a certificate signed by a CA that isn't
  24 included in the bundle you use or if the remote host is an impostor
  25 impersonating your favorite site, and you want to transfer files from this
  26 server, 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
  93 Neglecting to use one of the above methods when dealing with a server using a
  94 certificate that isn't signed by one of the certificates in the installed CA
  95 cert bundle, will cause SSL to report an error ("certificate verify failed")
  96 during the handshake and SSL will then refuse further communication with that
  97 server.
  98
  99                       Peer SSL Certificate Verification with NSS
 100                       ==========================================
 101
 102 If libcurl was built with NSS support, then depending on the OS distribution,
 103 it is probably required to take some additional steps to use the system-wide CA
 104 cert db. RedHat ships with an additional module, libnsspem.so, which enables
 105 NSS to read the OpenSSL PEM CA bundle. This library is missing in OpenSuSE, and
 106 without it, NSS can only work with its own internal formats. NSS also has a new
 107 database format: https://wiki.mozilla.org/NSS_Shared_DB
 108
 109 Starting with version 7.19.7, libcurl will check for the NSS version it runs,
 110 and automatically add the 'sql:' prefix to the certdb directory (either the
 111 hardcoded default /etc/pki/nssdb or the directory configured with SSL_DIR
 112 environment variable) if version 3.12.0 or later is detected. To check which
 113 ertdb format your distribution provides, examine the default
 114 certdb location: /etc/pki/nssdb; the new certdb format can be identified by
 115 the filenames cert9.db, key4.db, pkcs11.txt; filenames of older versions are
 116 cert8.db, key3.db, modsec.db.
 117
 118 Usually these cert databases are empty, but NSS also has built-in CAs which are
 119 provided through a shared library, libnssckbi.so; if you want to use these
 120 built-in CAs, then create a symlink to libnssckbi.so in /etc/pki/nssdb:
 121 ln -s /usr/lib[64]/libnssckbi.so /etc/pki/nssdb/libnssckbi.so
 122
 123      Peer SSL Certificate Verification with Schannel and Secure Transport
 124      ====================================================================
 125
 126 If libcurl was built with Schannel (Microsoft's TLS/SSL engine) or Secure
 127 Transport (Apple's TLS/SSL engine) support, then libcurl will still perform
 128 peer certificate verification, but instead of using a CA cert bundle, it will
 129 use the certificates that are built into the OS. These are the same
 130 certificates that appear in the Internet Options control panel (under Windows)
 131 or Keychain Access application (under OS X). Any custom security rules for
 132 certificates will be honored.
 133
 134 Schannel will run CRL checks on certificates unless peer verification is
 135 disabled. Secure Transport on iOS will run OCSP checks on certificates unless
 136 peer verification is disabled. Secure Transport on OS X will run either OCSP
 137 or CRL checks on certificates if those features are enabled, and this behavior
 138 can be adjusted in the preferences of Keychain Access.