Annotation of embedaddon/curl/docs/SSLCERTS.md, revision 1.1
1.1 ! misho 1: SSL Certificate Verification
! 2: ============================
! 3:
! 4: SSL is TLS
! 5: ----------
! 6:
! 7: SSL is the old name. It is called TLS these days.
! 8:
! 9:
! 10: Native SSL
! 11: ----------
! 12:
! 13: If libcurl was built with Schannel or Secure Transport support (the native SSL
! 14: libraries included in Windows and Mac OS X), then this does not apply to
! 15: you. Scroll down for details on how the OS-native engines handle SSL
! 16: certificates. If you're not sure, then run "curl -V" and read the results. If
! 17: the version string says "WinSSL" in it, then it was built with Schannel
! 18: support.
! 19:
! 20: It is about trust
! 21: -----------------
! 22:
! 23: This system is about trust. In your local CA certificate store you have certs
! 24: from *trusted* Certificate Authorities that you then can use to verify that the
! 25: server certificates you see are valid. They're signed by one of the CAs you
! 26: trust.
! 27:
! 28: Which CAs do you trust? You can decide to trust the same set of companies your
! 29: operating system trusts, or the set one of the known browsers trust. That's
! 30: basically trust via someone else you trust. You should just be aware that
! 31: modern operating systems and browsers are setup to trust *hundreds* of
! 32: companies and recent years several such CAs have been found untrustworthy.
! 33:
! 34: Certificate Verification
! 35: ------------------------
! 36:
! 37: libcurl performs peer SSL certificate verification by default. This is done
! 38: by using a CA certificate store that the SSL library can use to make sure the
! 39: peer's server certificate is valid.
! 40:
! 41: If you communicate with HTTPS, FTPS or other TLS-using servers using
! 42: certificates that are signed by CAs present in the store, you can be sure
! 43: that the remote server really is the one it claims to be.
! 44:
! 45: If the remote server uses a self-signed certificate, if you don't install a CA
! 46: cert store, if the server uses a certificate signed by a CA that isn't
! 47: included in the store you use or if the remote host is an impostor
! 48: impersonating your favorite site, and you want to transfer files from this
! 49: server, do one of the following:
! 50:
! 51: 1. Tell libcurl to *not* verify the peer. With libcurl you disable this with
! 52: `curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`
! 53:
! 54: With the curl command line tool, you disable this with -k/--insecure.
! 55:
! 56: 2. Get a CA certificate that can verify the remote server and use the proper
! 57: option to point out this CA cert for verification when connecting. For
! 58: libcurl hackers: `curl_easy_setopt(curl, CURLOPT_CAINFO, cacert);`
! 59:
! 60: With the curl command line tool: --cacert [file]
! 61:
! 62: 3. Add the CA cert for your server to the existing default CA certificate
! 63: store. The default CA certificate store can changed at compile time with the
! 64: following configure options:
! 65:
! 66: --with-ca-bundle=FILE: use the specified file as CA certificate store. CA
! 67: certificates need to be concatenated in PEM format into this file.
! 68:
! 69: --with-ca-path=PATH: use the specified path as CA certificate store. CA
! 70: certificates need to be stored as individual PEM files in this directory.
! 71: You may need to run c_rehash after adding files there.
! 72:
! 73: If neither of the two options is specified, configure will try to auto-detect
! 74: a setting. It's also possible to explicitly not hardcode any default store
! 75: but rely on the built in default the crypto library may provide instead.
! 76: You can achieve that by passing both --without-ca-bundle and
! 77: --without-ca-path to the configure script.
! 78:
! 79: If you use Internet Explorer, this is one way to get extract the CA cert
! 80: for a particular server:
! 81:
! 82: - View the certificate by double-clicking the padlock
! 83: - Find out where the CA certificate is kept (Certificate>
! 84: Authority Information Access>URL)
! 85: - Get a copy of the crt file using curl
! 86: - Convert it from crt to PEM using the openssl tool:
! 87: openssl x509 -inform DES -in yourdownloaded.crt \
! 88: -out outcert.pem -text
! 89: - Add the 'outcert.pem' to the CA certificate store or use it stand-alone
! 90: as described below.
! 91:
! 92: If you use the 'openssl' tool, this is one way to get extract the CA cert
! 93: for a particular server:
! 94:
! 95: - `openssl s_client -showcerts -servername server -connect server:443 > cacert.pem`
! 96: - type "quit", followed by the "ENTER" key
! 97: - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"
! 98: markers.
! 99: - If you want to see the data in the certificate, you can do: "openssl
! 100: x509 -inform PEM -in certfile -text -out certdata" where certfile is
! 101: the cert you extracted from logfile. Look in certdata.
! 102: - If you want to trust the certificate, you can add it to your CA
! 103: certificate store or use it stand-alone as described. Just remember that
! 104: the security is no better than the way you obtained the certificate.
! 105:
! 106: 4. If you're using the curl command line tool, you can specify your own CA
! 107: cert file by setting the environment variable `CURL_CA_BUNDLE` to the path
! 108: of your choice.
! 109:
! 110: If you're using the curl command line tool on Windows, curl will search
! 111: for a CA cert file named "curl-ca-bundle.crt" in these directories and in
! 112: this order:
! 113: 1. application's directory
! 114: 2. current working directory
! 115: 3. Windows System directory (e.g. C:\windows\system32)
! 116: 4. Windows Directory (e.g. C:\windows)
! 117: 5. all directories along %PATH%
! 118:
! 119: 5. Get a better/different/newer CA cert bundle! One option is to extract the
! 120: one a recent Firefox browser uses by running 'make ca-bundle' in the curl
! 121: build tree root, or possibly download a version that was generated this
! 122: way for you: [CA Extract](https://curl.haxx.se/docs/caextract.html)
! 123:
! 124: Neglecting to use one of the above methods when dealing with a server using a
! 125: certificate that isn't signed by one of the certificates in the installed CA
! 126: certificate store, will cause SSL to report an error ("certificate verify
! 127: failed") during the handshake and SSL will then refuse further communication
! 128: with that server.
! 129:
! 130: Certificate Verification with NSS
! 131: ---------------------------------
! 132:
! 133: If libcurl was built with NSS support, then depending on the OS distribution,
! 134: it is probably required to take some additional steps to use the system-wide
! 135: CA cert db. RedHat ships with an additional module, libnsspem.so, which
! 136: enables NSS to read the OpenSSL PEM CA bundle. On openSUSE you can install
! 137: p11-kit-nss-trust which makes NSS use the system wide CA certificate store. NSS
! 138: also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB).
! 139:
! 140: Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to
! 141: the certdb directory (either the hardcoded default /etc/pki/nssdb or the
! 142: directory configured with SSL_DIR environment variable). To check which certdb
! 143: format your distribution provides, examine the default certdb location:
! 144: /etc/pki/nssdb; the new certdb format can be identified by the filenames
! 145: cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db,
! 146: key3.db, secmod.db.
! 147:
! 148: Certificate Verification with Schannel and Secure Transport
! 149: -----------------------------------------------------------
! 150:
! 151: If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure
! 152: Transport (Apple's native TLS engine) support, then libcurl will still perform
! 153: peer certificate verification, but instead of using a CA cert bundle, it will
! 154: use the certificates that are built into the OS. These are the same
! 155: certificates that appear in the Internet Options control panel (under Windows)
! 156: or Keychain Access application (under OS X). Any custom security rules for
! 157: certificates will be honored.
! 158:
! 159: Schannel will run CRL checks on certificates unless peer verification is
! 160: disabled. Secure Transport on iOS will run OCSP checks on certificates unless
! 161: peer verification is disabled. Secure Transport on OS X will run either OCSP
! 162: or CRL checks on certificates if those features are enabled, and this behavior
! 163: can be adjusted in the preferences of Keychain Access.
! 164:
! 165: HTTPS proxy
! 166: -----------
! 167:
! 168: Since version 7.52.0, curl can do HTTPS to the proxy separately from the
! 169: connection to the server. This TLS connection is handled separately from the
! 170: server connection so instead of `--insecure` and `--cacert` to control the
! 171: certificate verification, you use `--proxy-insecure` and `--proxy-cacert`.
! 172: With these options, you make sure that the TLS connection and the trust of the
! 173: proxy can be kept totally separate from the TLS connection to the server.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to SSLCERTS.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs