Docs: Clarified use of ca_certs parameter and its defaults.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>
pywbem · Dec 21, 2017 · 4533812 · 4533812
1 parent 9b558bb
commit 4533812
Show file tree

Hide file tree

Showing 3 changed files with 25 additions and 8 deletions.
diff --git a/docs/changes.rst b/docs/changes.rst
@@ -169,6 +169,9 @@ Enhancements
 * Docs: Added "New in pywbem M.N ..." text to descriptions of anything that was
   introduced in version 0.8 or later.
 
+* Docs: Clarified use of `ca_certs` parameter of `WBEMConnection` and its
+  defaults in `DEFAULT_CA_CERT_PATHS`.
+
 Bug fixes
 ^^^^^^^^^
 

diff --git a/pywbem/cim_http.py b/pywbem/cim_http.py
@@ -123,9 +123,12 @@ def create_pywbem_ssl_context():
 DEFAULT_PORT_HTTP = 5988        # default port for http
 DEFAULT_PORT_HTTPS = 5989       # default port for https
 
-# TODO 5/16 ks This is a linux based set of defaults:
 
-#: Default directory paths for looking up CA certificates for linux.
+#: Default directory paths to be used when the ``ca_certs`` parameter of
+#: :class:`~pywbem.WBEMConnection` is `None`. The first existing directory is
+#: used as a default for that parameter.
+#: Note that these default directory paths only work on some Linux
+#: distributions.
 DEFAULT_CA_CERT_PATHS = \
     ['/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt',
      '/etc/ssl/certs', '/etc/ssl/certificates']

diff --git a/pywbem/cim_operations.py b/pywbem/cim_operations.py
@@ -622,6 +622,7 @@ def __init__(self, url, creds=None, default_namespace=DEFAULT_NAMESPACE,
                  x509=None, verify_callback=None, ca_certs=None,
                  no_verification=False, timeout=None, use_pull_operations=False,
                  enable_stats=False):
+        # pylint: disable=line-too-long
         """
         Parameters:
 
@@ -772,12 +773,21 @@ def __init__(self, url, creds=None, default_namespace=DEFAULT_NAMESPACE,
 
             This parameter is ignored when HTTP is used.
 
-            The parameter value is either the directory path of a directory
-            prepared using the ``c_rehash`` tool included with OpenSSL, or the
-            file path of a file in PEM format.
+            The parameter value must be one of:
+
+            * a path to a file containing one or more CA certificates in
+              PEM format. See the description of `CAfile` in the OpenSSL
+              `SSL_CTX_load_verify_locations`_ function for details.
+
+            * a path to a directory with files each of which contains one CA
+              certificate in PEM format. See the description of `CApath` in the
+              OpenSSL `SSL_CTX_load_verify_locations`_ function for details.
+
+            If `None`, the directory path of the first existing directory from
+            the list in :data:`~pywbem.cim_http.DEFAULT_CA_CERT_PATHS` will be
+            used as a default.
 
-            If `None`, default directory paths will be used to look up CA
-            certificates (see :data:`~pywbem.cim_http.DEFAULT_CA_CERT_PATHS`).
+            .. _`SSL_CTX_load_verify_locations`: https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html
 
           no_verification (:class:`py:bool`):
             Disables verification of the X.509 server certificate returned by
@@ -843,7 +853,8 @@ def __init__(self, url, creds=None, default_namespace=DEFAULT_NAMESPACE,
             Statistics may also be enabled or disabled with the WBEMConnection
             property `stats_enabled`. This may be used to view the current
             status or change the status (ex. `conn.stats_enabled(False)`)
-        """
+        """  # noqa: E501
+        # pylint: enable=line-too-long
 
         # Connection attributes
         self.url = url