docs/SSLCERTS - platform/external/curl - Git at Google


            
            SSL Certificate Verification

            
            ============================


            SSL is TLS

            
            ----------


            SSL is the old name. It is called TLS these days.


            Native SSL

            
            ----------


            If libcurl was built with Schannel or Secure Transport support (the native SSL

            
            libraries included in Windows and Mac OS X), then this does not apply to

            
            you. Scroll down for details on how the OS-native engines handle SSL

            
            certificates. If you're not sure, then run "curl -V" and read the results. If

            
            the version string says "WinSSL" in it, then it was built with Schannel

            
            support.


            It is about trust

            
            -----------------


            This system is about trust. In your local CA cert bundle you have certs from

            
            *trusted* Certificate Authorities that you then can use to verify that the

            
            server certificates you see are valid. They're signed by one of the CAs you

            
            trust.


            Which CAs do you trust? You can decide to trust the same set of companies your

            
            operating system trusts, or the set one of the known browsers trust. That's

            
            basically trust via someone else you trust. You should just be aware that

            
            modern operating systems and browsers are setup to trust *hundreds* of

            
            companies and recent years several such CAs have been found untrustworthy.


            Certificate Verification

            
            ------------------------


            libcurl performs peer SSL certificate verification by default.  This is done

            
            by using CA cert bundle that the SSL library can use to make sure the peer's

            
            server certificate is valid.


            If you communicate with HTTPS, FTPS or other TLS-using servers using

            
            certificates that are signed by CAs present in the bundle, 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 a CA

            
            cert bundle, if the server uses a certificate signed by a CA that isn't

            
            included in the bundle you use or if the remote host is an impostor

            
            impersonating your favorite 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 this with

            
                `curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`


                With the curl command line 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 line 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 used can be changed by running configure

            
                with the --with-ca-bundle option pointing out the path of your choice.


                To do this, you need to get the CA cert for your server in PEM format and

            
                then append that to your CA cert bundle.


                If you use Internet Explorer, this is one way to get extract the CA cert

            
                for a particular server:


                 - View the certificate by double-clicking the padlock

            
                 - Find out where the CA certificate is kept (Certificate>

            
                   Authority Information Access>URL)

            
                 - Get a copy of the crt file using curl

            
                 - Convert it from crt to PEM using the openssl tool:

            
                   openssl x509 -inform DES -in yourdownloaded.crt \

            
                   -out outcert.pem -text

            
                 - Append the 'outcert.pem' to the CA cert bundle or use it stand-alone

            
                   as described below.


                If you use the 'openssl' tool, this is one way to get extract the CA cert

            
                for a particular server:


                 - `openssl s_client -connect xxxxx.com:443 |tee logfile`

            
                 - type "QUIT", followed by the "ENTER" key

            
                 - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"

            
                   markers.

            
                 - If you want to see the data in the certificate, you can do: "openssl

            
                   x509 -inform PEM -in certfile -text -out certdata" where certfile is

            
                   the cert you extracted from logfile. Look in certdata.

            
                 - If you want to trust the certificate, you can append it to your

            
                   cert bundle or use it stand-alone as described. Just remember that the

            
                   security is no better than the way you obtained the certificate.


             4. If you're using the curl command line tool, you can specify your own CA

            
                cert path by setting the environment variable `CURL_CA_BUNDLE` to the path

            
                of your choice.


                If you're using the curl command line tool on Windows, curl will search

            
                for a CA cert file named "curl-ca-bundle.crt" in these directories and in

            
                this order:

            
                  1. application's directory

            
                  2. current working directory

            
                  3. Windows System directory (e.g. C:\windows\system32)

            
                  4. Windows Directory (e.g. C:\windows)

            
                  5. all directories along %PATH%


             5. Get a better/different/newer CA cert bundle! One option is to extract the

            
                one a recent Firefox browser uses by running 'make ca-bundle' in the curl

            
                build tree root, or possibly download a version that was generated this

            
                way for you: [CA Extract](http://curl.haxx.se/docs/caextract.html)


            Neglecting to use one of the above methods when dealing with a server using a

            
            certificate that isn't signed by one of the certificates 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.


            Certificate Verification with NSS

            
            ---------------------------------


            If libcurl was built with NSS support, then depending on the OS distribution,

            
            it is probably required to take some additional steps to use the system-wide

            
            CA cert db. RedHat ships with an additional module, libnsspem.so, which

            
            enables NSS to read the OpenSSL PEM CA bundle. This library is missing in

            
            OpenSuSE, and without it, NSS can only work with its own internal formats. NSS

            
            also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB).


            Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to

            
            the certdb directory (either the hardcoded default /etc/pki/nssdb or the

            
            directory configured with SSL_DIR environment variable). To check which certdb

            
            format your distribution provides, examine the default certdb location:

            
            /etc/pki/nssdb; the new certdb format can be identified by the filenames

            
            cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db,

            
            key3.db, secmod.db.


            Certificate Verification with Schannel and Secure Transport

            
            -----------------------------------------------------------


            If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure

            
            Transport (Apple's native TLS engine) support, then libcurl will still perform

            
            peer certificate verification, but instead of using a CA cert bundle, it will

            
            use the certificates that are built into the OS. These are the same

            
            certificates that appear in the Internet Options control panel (under Windows)

            
            or Keychain Access application (under OS X). Any custom security rules for

            
            certificates will be honored.


            Schannel will run CRL checks on certificates unless peer verification is

            
            disabled. Secure Transport on iOS will run OCSP checks on certificates unless

            
            peer verification is disabled. Secure Transport on OS X will run either OCSP

            
            or CRL checks on certificates if those features are enabled, and this behavior

            
            can be adjusted in the preferences of Keychain Access.
	SSL Certificate Verification
	============================

	SSL is TLS
	----------

	SSL is the old name. It is called TLS these days.


	Native SSL
	----------

	If libcurl was built with Schannel or Secure Transport support (the native SSL
	libraries included in Windows and Mac OS X), then this does not apply to
	you. Scroll down for details on how the OS-native engines handle SSL
	certificates. If you're not sure, then run "curl -V" and read the results. If
	the version string says "WinSSL" in it, then it was built with Schannel
	support.

	It is about trust
	-----------------

	This system is about trust. In your local CA cert bundle you have certs from
	trusted Certificate Authorities that you then can use to verify that the
	server certificates you see are valid. They're signed by one of the CAs you
	trust.

	Which CAs do you trust? You can decide to trust the same set of companies your
	operating system trusts, or the set one of the known browsers trust. That's
	basically trust via someone else you trust. You should just be aware that
	modern operating systems and browsers are setup to trust hundreds of
	companies and recent years several such CAs have been found untrustworthy.

	Certificate Verification
	------------------------

	libcurl performs peer SSL certificate verification by default. This is done
	by using CA cert bundle that the SSL library can use to make sure the peer's
	server certificate is valid.

	If you communicate with HTTPS, FTPS or other TLS-using servers using
	certificates that are signed by CAs present in the bundle, 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 a CA
	cert bundle, if the server uses a certificate signed by a CA that isn't
	included in the bundle you use or if the remote host is an impostor
	impersonating your favorite 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 this with
	`curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);`

	With the curl command line 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 line 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 used can be changed by running configure
	with the --with-ca-bundle option pointing out the path of your choice.

	To do this, you need to get the CA cert for your server in PEM format and
	then append that to your CA cert bundle.

	If you use Internet Explorer, this is one way to get extract the CA cert
	for a particular server:

	- View the certificate by double-clicking the padlock
	- Find out where the CA certificate is kept (Certificate>
	Authority Information Access>URL)
	- Get a copy of the crt file using curl
	- Convert it from crt to PEM using the openssl tool:
	openssl x509 -inform DES -in yourdownloaded.crt \
	-out outcert.pem -text
	- Append the 'outcert.pem' to the CA cert bundle or use it stand-alone
	as described below.

	If you use the 'openssl' tool, this is one way to get extract the CA cert
	for a particular server:

	- `openssl s_client -connect xxxxx.com:443 \|tee logfile`
	- type "QUIT", followed by the "ENTER" key
	- The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE"
	markers.
	- If you want to see the data in the certificate, you can do: "openssl
	x509 -inform PEM -in certfile -text -out certdata" where certfile is
	the cert you extracted from logfile. Look in certdata.
	- If you want to trust the certificate, you can append it to your
	cert bundle or use it stand-alone as described. Just remember that the
	security is no better than the way you obtained the certificate.

	4. If you're using the curl command line tool, you can specify your own CA
	cert path by setting the environment variable `CURL_CA_BUNDLE` to the path
	of your choice.

	If you're using the curl command line tool on Windows, curl will search
	for a CA cert file named "curl-ca-bundle.crt" in these directories and in
	this order:
	1. application's directory
	2. current working directory
	3. Windows System directory (e.g. C:\windows\system32)
	4. Windows Directory (e.g. C:\windows)
	5. all directories along %PATH%

	5. Get a better/different/newer CA cert bundle! One option is to extract the
	one a recent Firefox browser uses by running 'make ca-bundle' in the curl
	build tree root, or possibly download a version that was generated this
	way for you: [CA Extract](http://curl.haxx.se/docs/caextract.html)

	Neglecting to use one of the above methods when dealing with a server using a
	certificate that isn't signed by one of the certificates 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.

	Certificate Verification with NSS
	---------------------------------

	If libcurl was built with NSS support, then depending on the OS distribution,
	it is probably required to take some additional steps to use the system-wide
	CA cert db. RedHat ships with an additional module, libnsspem.so, which
	enables NSS to read the OpenSSL PEM CA bundle. This library is missing in
	OpenSuSE, and without it, NSS can only work with its own internal formats. NSS
	also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB).

	Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to
	the certdb directory (either the hardcoded default /etc/pki/nssdb or the
	directory configured with SSL_DIR environment variable). To check which certdb
	format your distribution provides, examine the default certdb location:
	/etc/pki/nssdb; the new certdb format can be identified by the filenames
	cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db,
	key3.db, secmod.db.

	Certificate Verification with Schannel and Secure Transport
	-----------------------------------------------------------

	If libcurl was built with Schannel (Microsoft's native TLS engine) or Secure
	Transport (Apple's native TLS engine) support, then libcurl will still perform
	peer certificate verification, but instead of using a CA cert bundle, it will
	use the certificates that are built into the OS. These are the same
	certificates that appear in the Internet Options control panel (under Windows)
	or Keychain Access application (under OS X). Any custom security rules for
	certificates will be honored.

	Schannel will run CRL checks on certificates unless peer verification is
	disabled. Secure Transport on iOS will run OCSP checks on certificates unless
	peer verification is disabled. Secure Transport on OS X will run either OCSP
	or CRL checks on certificates if those features are enabled, and this behavior
	can be adjusted in the preferences of Keychain Access.