Added support for verifying HMC certificates

Details: * Added module parameters 'ca_certs' and 'verify' to all modules (issue #401) * Increased minimum version of zhmcclient to 0.31.0 in order to have the support for certificate verification. Signed-off-by: Andreas Maier <[email protected]>
zhmcclient · Jun 8, 2021 · f4ef475 · f4ef475
1 parent 917dfb6
commit f4ef475
Show file tree

Hide file tree

Showing 26 changed files with 507 additions and 74 deletions.
diff --git a/docs/source/modules/zhmc_adapter.rst b/docs/source/modules/zhmc_adapter.rst
@@ -56,6 +56,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 name
   The name of the target adapter. In case of renaming an adapter, this is the new name of the adapter.

diff --git a/docs/source/modules/zhmc_cpc.rst b/docs/source/modules/zhmc_cpc.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 name
   The name of the target CPC.

diff --git a/docs/source/modules/zhmc_crypto_attachment.rst b/docs/source/modules/zhmc_crypto_attachment.rst
@@ -56,6 +56,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC that has the partition and the crypto adapters.

diff --git a/docs/source/modules/zhmc_hba.rst b/docs/source/modules/zhmc_hba.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC with the partition containing the HBA.

diff --git a/docs/source/modules/zhmc_nic.rst b/docs/source/modules/zhmc_nic.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC with the partition containing the NIC.

diff --git a/docs/source/modules/zhmc_partition.rst b/docs/source/modules/zhmc_partition.rst
@@ -56,6 +56,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC with the target partition.

diff --git a/docs/source/modules/zhmc_storage_group.rst b/docs/source/modules/zhmc_storage_group.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC associated with the target storage group.

diff --git a/docs/source/modules/zhmc_storage_group_attachment.rst b/docs/source/modules/zhmc_storage_group_attachment.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC that has the partition and is associated with the storage group.

diff --git a/docs/source/modules/zhmc_storage_volume.rst b/docs/source/modules/zhmc_storage_volume.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC associated with the storage group containing the target storage volume.

diff --git a/docs/source/modules/zhmc_user.rst b/docs/source/modules/zhmc_user.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 name
   The userid of the target user (i.e. the 'name' property of the User object).

diff --git a/docs/source/modules/zhmc_virtual_function.rst b/docs/source/modules/zhmc_virtual_function.rst
@@ -55,6 +55,21 @@ hmc_auth
     | **type**: str
 
 
+  ca_certs
+    Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the 'REQUESTS_CA_BUNDLE' environment variable or the path name in the 'CURL_CA_BUNDLE' environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the 'certifi' Python package are used for verifying the HMC certificate.
+
+    | **required**: False
+    | **type**: str
+
+
+  verify
+    If True (default), verify the HMC certificate as specified in the ``ca_certs`` parameter. If False, ignore what is specified in the ``ca_certs`` parameter and do not verify the HMC certificate.
+
+    | **required**: False
+    | **type**: bool
+    | **default**: True
+
+
 
 cpc_name
   The name of the CPC with the partition containing the virtual function.

diff --git a/docs/source/release_notes.rst b/docs/source/release_notes.rst
@@ -29,6 +29,13 @@ Released: not yet
 
 **Incompatible changes:**
 
+* The new support for verifying HMC certificates will by default verify the
+  HMC certificate using the "Mozilla CA Certificate List" provided by the
+  'certifi' Python package, causing self-signed HMC certificates to be
+  rejected. The verification behavior can be controlled with the new
+  'ca_certs' and 'verify' sub-parameters of the 'hmc_auth' module parameter
+  of each module.
+
 **Deprecations:**
 
 **Bug fixes:**
@@ -67,6 +74,10 @@ Released: not yet
 
 * Increased minimum version of zhmcclient to 0.29.0 to pick up fixes.
 
+* Added support for verifying HMC certificates by adding module sub-parameters
+  'ca_certs' and 'verify' to the 'hmc_auth' module parameter of all modules.
+  (issue #401)
+
 **Cleanup:**
 
 * Renamed "Bibliography" page to "Resources" and removed common Ansible links

diff --git a/minimum-constraints.txt b/minimum-constraints.txt
@@ -87,8 +87,8 @@ wheel==0.33.5; python_version >= '3.8'
 
 ansible==2.9.0.0
 requests==2.20.1
-# git+https://github.com/zhmcclient/python-zhmcclient@master#egg=zhmcclient
-zhmcclient==0.29.0
+# TODO: Enable zhmcclient 0.31.0 once released on Pypi
+# zhmcclient==0.31.0
 
 # Indirect dependencies for installation (must be consistent with requirements.txt)
 

diff --git a/plugins/module_utils/common.py b/plugins/module_utils/common.py
@@ -153,11 +153,14 @@ def get_hmc_auth(hmc_auth):
 
     Parameters:
       hmc_auth (dict): value of the 'hmc_auth' module input parameter,
-        which is a dictionary with items 'userid' and 'password'.
+        which is a dictionary with required items 'userid' and 'password'
+        and optional items 'ca_certs' and 'verify'.
 
     Returns:
-      tuple(userid, password): A tuple with the respective items
-        of the input dictionary.
+      tuple(userid, password, ca_certs, verify): A tuple with the respective
+        items of the input dictionary. Optional items are defaulted:
+        - ca_certs: Defaults to None.
+        - verify: Defaults to True.
 
     Raises:
       ParameterError: An item in the input dictionary was missing.
@@ -172,7 +175,9 @@ def get_hmc_auth(hmc_auth):
     except KeyError:
         raise ParameterError("Required item 'password' is missing in "
                              "dictionary module parameter 'hmc_auth'.")
-    return userid, password
+    ca_certs = hmc_auth.get('ca_certs', None)
+    verify = hmc_auth.get('verify', True)
+    return userid, password, ca_certs, verify
 
 
 def pull_partition_status(partition):
@@ -364,21 +369,21 @@ def wait_for_transition_completion(partition):
             raise AssertionError()
 
 
-def get_session(faked_session, host, userid, password):
+def get_session(faked_session, host, userid, password, ca_certs, verify):
     """
     Return a session object for the HMC.
 
     Parameters:
       faked_session (zhmcclient_mock.FakedSession or None):
         If this object is a `zhmcclient_mock.FakedSession` object, return that
         object.
-        Else, return a new `zhmcclient.Session` object from the `host`,
-        `userid`, and `password` arguments.
+        Else, return a new `zhmcclient.Session` object from the other arguments.
     """
     if isinstance(faked_session, FakedSession):
         return faked_session
     else:
-        return Session(host, userid, password)
+        verify_cert = ca_certs if verify else False
+        return Session(host, userid, password, verify_cert=verify_cert)
 
 
 def to_unicode(value):