[2/8] git commit: docs: Update "SSL Certificate Validation" section.

[to...@apache.org]

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 <to...@apache.org>
Authored: Sun Dec 8 20:04:30 2013 +0100
Committer: Tomaz Muraus <to...@apache.org>
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...