docs: Update "SSL Certificate Validation" section.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/7307ac93 Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/7307ac93 Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/7307ac93 Branch: refs/heads/trunk Commit: 7307ac9333d136faf7513b88c0b9c3afd58484ce Parents: fe72fc1 Author: Tomaz Muraus <[email protected]> Authored: Sun Dec 8 20:04:30 2013 +0100 Committer: Tomaz Muraus <[email protected]> Committed: Sun Dec 8 20:04:30 2013 +0100 ---------------------------------------------------------------------- docs/other/ssl-certificate-validation.rst | 65 ++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/7307ac93/docs/other/ssl-certificate-validation.rst ---------------------------------------------------------------------- diff --git a/docs/other/ssl-certificate-validation.rst b/docs/other/ssl-certificate-validation.rst index ec02782..9df5765 100644 --- a/docs/other/ssl-certificate-validation.rst +++ b/docs/other/ssl-certificate-validation.rst @@ -3,15 +3,16 @@ SSL Certificate Validation When establishing a secure connection to a cloud provider endpoint, Libcloud verifies server SSL certificate. By default, Libcloud searches -paths listed in ``libcloud.security.CA_CERTS_PATH`` for CA certificate files. +paths listed in ``libcloud.security.CA_CERTS_PATH`` variable for the CA +certificate files. ``CA_CERTS_PATH`` contains common paths to CA bundle installations on the following platforms: -* openssl on CentOS / Fedora -* ca-certificates on Debian / Ubuntu / Arch / Gentoo -* ca_root_nss on FreeBSD -* curl-ca-bundle on Mac OS X +* ``openssl`` package on CentOS / Fedora +* ``ca-certificates`` package on Debian / Ubuntu / Arch / Gentoo +* ``ca_root_nss`` port on FreeBSD +* ``curl-ca-bundle`` port on Mac OS X If no valid CA certificate files are found, you will see an error message similar to the one bellow: @@ -24,3 +25,57 @@ Acquiring CA Certificates If the above packages are unavailable to you, and you don't wish to roll your own, the makers of cURL provides an excellent resource, generated from Mozilla: http://curl.haxx.se/docs/caextract.html. + +Adding additional CA certificate to the path +-------------------------------------------- + +If you want to add an additional CA certificate to the ``CA_CERTS_PATH``, you +can do this by appending a path to your CA file to the +``libcloud.security.CA_CERTS_PATH`` list. + +For example: + +.. sourcecode:: python + + import libcloud.security + libcloud.security.CA_CERTS_PATH.append('/home/user/path-to-your-ca-file.crt') + + # Instantiate and work with the driver here... + +Using a custom CA certificate +----------------------------- + +If you want to use a custom CA certificate file for validating the server +certificate, you can do that by setting ``libcloud.security.CA_CERTS_PATH`` +variable (``list``) to point to your CA file. + +For example: + +.. sourcecode:: python + + import libcloud.security + libcloud.security.CA_CERTS_PATH = ['/home/user/path-to-your-ca-file.crt'] + + # Instantiate and work with the driver here... + +Disabling SSL certificate validation +------------------------------------ + +.. note:: + + Disabling SSL certificate validations makes you vulnerable to MITM attacks + so you are strongly discouraged from doing that. You should only disable it + if you are aware of the consequences and you know what you are doing. + +To disable SSL certificate validation, set +``libcloud.security.VERIFY_SSL_CERT`` variable to ``False`` at the top of your +script, before instantiating a driver and interacting with other Libcloud code. + +For example: + +.. sourcecode:: python + + import libcloud.security + libcloud.security.VERIFY_SSL_CERT = True + + # Instantiate and work with the driver here...
