openssl_*: deprecate PyOpenSSL backends (#59907)

* Deprecate PyOpenSSL backends.

* Add changelog.

* Add porting guide entry.

* Improve tests to ignore deprecations when comparing results.

* Deprecating pyopenssl backend for get_certificate and openssl_publickey.

* Fix typo.

changelogs/fragments/59907-openssl-deprecate-pyopenssl.yml

@@ -0,0 +1,9 @@
+minor_changes:
+ - "get_certificate - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_certificate - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_certificate_info - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_csr - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_csr_info - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_privatekey - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_privatekey_info - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."
+ - "openssl_publickey - the ``pyopenssl`` backend has been deprecated, it will be removed in Ansible 2.13."

docs/docsite/rst/porting_guides/porting_guide_2.9.rst

@@ -161,6 +161,18 @@ The following functionality will be removed in Ansible 2.13. Please update updat
   :ref:`openssl_csr_info <openssl_csr_info_module>`, :ref:`openssl_privatekey_info <openssl_privatekey_info_module>`
   and :ref:`assert <assert_module>` modules.
 
+For the following modules, the PyOpenSSL-based backend ``pyopenssl`` has been deprecated and will be
+removed in Ansible 2.13:
+
+* :ref:`get_certificate <get_certificate_module>`
+* :ref:`openssl_certificate <openssl_certificate_module>`
+* :ref:`openssl_certificate_info <openssl_certificate_info_module>`
+* :ref:`openssl_csr <openssl_csr_module>`
+* :ref:`openssl_csr_info <openssl_csr_info_module>`
+* :ref:`openssl_privatekey <openssl_privatekey_module>`
+* :ref:`openssl_privatekey_info <openssl_privatekey_info_module>`
+* :ref:`openssl_publickey <openssl_publickey_module>`
+
 
 Renamed modules
 ^^^^^^^^^^^^^^^

lib/ansible/modules/crypto/get_certificate.py

@@ -20,7 +20,8 @@ description:
     - Makes a secure connection and returns information about the presented certificate
     - The module can use the cryptography Python library, or the pyOpenSSL Python
       library. By default, it tries to detect which one is available. This can be
-      overridden with the I(select_crypto_backend) option."
+      overridden with the I(select_crypto_backend) option. Please note that the PyOpenSSL
+      backend was deprecated in Ansible 2.9 and will be removed in Ansible 2.13."
 options:
     host:
       description:
@@ -233,6 +234,7 @@ def main():
         if not PYOPENSSL_FOUND:
             module.fail_json(msg=missing_required_lib('pyOpenSSL >= {0}'.format(MINIMAL_PYOPENSSL_VERSION)),
                              exception=PYOPENSSL_IMP_ERR)
+        module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
     elif backend == 'cryptography':
         if not CRYPTOGRAPHY_FOUND:
             module.fail_json(msg=missing_required_lib('cryptography >= {0}'.format(MINIMAL_CRYPTOGRAPHY_VERSION)),

lib/ansible/modules/crypto/openssl_certificate.py

@@ -37,7 +37,8 @@ description:
       your existing certificate, consider using the I(backup) option."
     - It uses the pyOpenSSL or cryptography python library to interact with OpenSSL.
     - If both the cryptography and PyOpenSSL libraries are available (and meet the minimum version requirements)
-      cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with C(select_crypto_backend))
+      cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with C(select_crypto_backend)).
+      Please note that the PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in Ansible 2.13.
 requirements:
     - PyOpenSSL >= 0.15 or cryptography >= 1.6 (if using C(selfsigned) or C(assertonly) provider)
     - acme-tiny (if using the C(acme) provider)
@@ -445,6 +446,8 @@ options:
             - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
             - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
             - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+            - Please note that the C(pyopenssl) backend has been deprecated in Ansible 2.9, and will be removed in Ansible 2.13.
+              From that point on, only the C(cryptography) backend will be available.
         type: str
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
@@ -2520,6 +2523,7 @@ def main():
                     except AttributeError:
                         module.fail_json(msg='You need to have PyOpenSSL>=0.15')
 
+                module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
                 if provider == 'selfsigned':
                     certificate = SelfSignedCertificate(module)
                 elif provider == 'acme':

lib/ansible/modules/crypto/openssl_certificate_info.py

@@ -22,7 +22,8 @@ description:
     - It uses the pyOpenSSL or cryptography python library to interact with OpenSSL. If both the
       cryptography and PyOpenSSL libraries are available (and meet the minimum version requirements)
       cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with
-      C(select_crypto_backend))
+      C(select_crypto_backend)). Please note that the PyOpenSSL backend was deprecated in Ansible 2.9
+      and will be removed in Ansible 2.13.
 requirements:
     - PyOpenSSL >= 0.15 or cryptography >= 1.6
 author:
@@ -52,6 +53,8 @@ options:
             - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
             - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
             - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+            - Please note that the C(pyopenssl) backend has been deprecated in Ansible 2.9, and will be removed in Ansible 2.13.
+              From that point on, only the C(cryptography) backend will be available.
         type: str
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
@@ -844,6 +847,7 @@ def main():
             except AttributeError:
                 module.fail_json(msg='You need to have PyOpenSSL>=0.15')
 
+            module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
             certificate = CertificateInfoPyOpenSSL(module)
         elif backend == 'cryptography':
             if not CRYPTOGRAPHY_FOUND:

lib/ansible/modules/crypto/openssl_csr.py

@@ -24,6 +24,10 @@ description:
     - "Please note that the module regenerates existing CSR if it doesn't match the module's
       options, or if it seems to be corrupt. If you are concerned that this could overwrite
       your existing CSR, consider using the I(backup) option."
+    - The module can use the cryptography Python library, or the pyOpenSSL Python
+      library. By default, it tries to detect which one is available. This can be
+      overridden with the I(select_crypto_backend) option. Please note that the
+      PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in Ansible 2.13."
 requirements:
     - Either cryptography >= 1.3
     - Or pyOpenSSL >= 0.15
@@ -189,6 +193,8 @@ options:
             - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
             - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
             - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+            - Please note that the C(pyopenssl) backend has been deprecated in Ansible 2.9, and will be removed in Ansible 2.13.
+              From that point on, only the C(cryptography) backend will be available.
         type: str
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
@@ -1042,6 +1048,8 @@ def main():
                 getattr(crypto.X509Req, 'get_extensions')
             except AttributeError:
                 module.fail_json(msg='You need to have PyOpenSSL>=0.15 to generate CSRs')
+
+            module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
             csr = CertificateSigningRequestPyOpenSSL(module)
         elif backend == 'cryptography':
             if not CRYPTOGRAPHY_FOUND:

lib/ansible/modules/crypto/openssl_csr_info.py

@@ -24,7 +24,8 @@ description:
     - It uses the pyOpenSSL or cryptography python library to interact with OpenSSL. If both the
       cryptography and PyOpenSSL libraries are available (and meet the minimum version requirements)
       cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with
-      C(select_crypto_backend))
+      C(select_crypto_backend)). Please note that the PyOpenSSL backend was deprecated in Ansible 2.9
+      and will be removed in Ansible 2.13.
 requirements:
     - PyOpenSSL >= 0.15 or cryptography >= 1.3
 author:
@@ -43,6 +44,8 @@ options:
             - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
             - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
             - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+            - Please note that the C(pyopenssl) backend has been deprecated in Ansible 2.9, and will be removed in Ansible 2.13.
+              From that point on, only the C(cryptography) backend will be available.
         type: str
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
@@ -625,6 +628,7 @@ def main():
             except AttributeError:
                 module.fail_json(msg='You need to have PyOpenSSL>=0.15')
 
+            module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
             certificate = CertificateSigningRequestInfoPyOpenSSL(module)
         elif backend == 'cryptography':
             if not CRYPTOGRAPHY_FOUND:

lib/ansible/modules/crypto/openssl_privatekey.py

@@ -30,7 +30,8 @@ description:
       consider using the I(backup) option."
     - The module can use the cryptography Python library, or the pyOpenSSL Python
       library. By default, it tries to detect which one is available. This can be
-      overridden with the I(select_crypto_backend) option."
+      overridden with the I(select_crypto_backend) option. Please note that the
+      PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in Ansible 2.13."
 requirements:
     - Either cryptography >= 1.2.3 (older versions might work as well)
     - Or pyOpenSSL
@@ -116,6 +117,8 @@ options:
             - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
             - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
             - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+            - Please note that the C(pyopenssl) backend has been deprecated in Ansible 2.9, and will be removed in Ansible 2.13.
+              From that point on, only the C(cryptography) backend will be available.
         type: str
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
@@ -674,6 +677,7 @@ def main():
             if not PYOPENSSL_FOUND:
                 module.fail_json(msg=missing_required_lib('pyOpenSSL >= {0}'.format(MINIMAL_PYOPENSSL_VERSION)),
                                  exception=PYOPENSSL_IMP_ERR)
+            module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
             private_key = PrivateKeyPyOpenSSL(module)
         elif backend == 'cryptography':
             if not CRYPTOGRAPHY_FOUND:

lib/ansible/modules/crypto/openssl_privatekey_info.py

@@ -26,7 +26,8 @@ description:
     - It uses the pyOpenSSL or cryptography python library to interact with OpenSSL. If both the
       cryptography and PyOpenSSL libraries are available (and meet the minimum version requirements)
       cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with
-      C(select_crypto_backend))
+      C(select_crypto_backend)). Please note that the PyOpenSSL backend was deprecated in Ansible 2.9
+      and will be removed in Ansible 2.13.
 requirements:
     - PyOpenSSL >= 0.15 or cryptography >= 1.2.3
 author:
@@ -57,6 +58,8 @@ options:
             - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
             - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
             - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+            - Please note that the C(pyopenssl) backend has been deprecated in Ansible 2.9, and will be removed in Ansible 2.13.
+              From that point on, only the C(cryptography) backend will be available.
         type: str
         default: auto
         choices: [ auto, cryptography, pyopenssl ]
@@ -612,6 +615,7 @@ def main():
             if not PYOPENSSL_FOUND:
                 module.fail_json(msg=missing_required_lib('pyOpenSSL >= {0}'.format(MINIMAL_PYOPENSSL_VERSION)),
                                  exception=PYOPENSSL_IMP_ERR)
+            module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
             privatekey = PrivateKeyInfoPyOpenSSL(module)
         elif backend == 'cryptography':
             if not CRYPTOGRAPHY_FOUND:

lib/ansible/modules/crypto/openssl_publickey.py

@@ -22,7 +22,8 @@ description:
     - The module can use the cryptography Python library, or the pyOpenSSL Python
       library. By default, it tries to detect which one is available. This can be
       overridden with the I(select_crypto_backend) option. When I(format) is C(OpenSSH),
-      the C(cryptography) backend has to be used."
+      the C(cryptography) backend has to be used. Please note that the PyOpenSSL backend
+      was deprecated in Ansible 2.9 and will be removed in Ansible 2.13."
 requirements:
     - Either cryptography >= 1.2.3 (older versions might work as well)
     - Or pyOpenSSL >= 16.0.0
@@ -390,6 +391,7 @@ def main():
         if not PYOPENSSL_FOUND:
             module.fail_json(msg=missing_required_lib('pyOpenSSL >= {0}'.format(MINIMAL_PYOPENSSL_VERSION)),
                              exception=PYOPENSSL_IMP_ERR)
+        module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated', version='2.13')
     elif backend == 'cryptography':
         if not CRYPTOGRAPHY_FOUND:
             module.fail_json(msg=missing_required_lib('cryptography >= {0}'.format(minimal_cryptography_version)),

test/integration/targets/openssl_certificate_info/tasks/main.yml

@@ -169,6 +169,7 @@
   when: pyopenssl_version.stdout is version('0.15', '>=') and cryptography_version.stdout is version('1.6', '>=')
   vars:
     keys_to_ignore:
+      - deprecations
       - subject_key_identifier
       - authority_key_identifier
       - authority_cert_issuer

test/integration/targets/openssl_csr_info/tasks/main.yml

@@ -154,6 +154,7 @@
   when: pyopenssl_version.stdout is version('0.15', '>=') and cryptography_version.stdout is version('1.3', '>=')
   vars:
     keys_to_ignore:
+      - deprecations
       - subject_key_identifier
       - authority_key_identifier
       - authority_cert_issuer

test/integration/targets/openssl_privatekey_info/tasks/main.yml

@@ -65,6 +65,7 @@
   - name: Compare results
     assert:
       that:
-      - pyopenssl_info_results[item] == cryptography_info_results[item]
+      - '  (pyopenssl_info_results[item] | dict2items | rejectattr("key", "equalto", "deprecations") | list | items2dict)
+        == (cryptography_info_results[item] | dict2items | rejectattr("key", "equalto", "deprecations") | list | items2dict)'
     loop: "{{ pyopenssl_info_results.keys() | intersect(cryptography_info_results.keys()) | list }}"
   when: pyopenssl_version.stdout is version('0.15', '>=') and cryptography_version.stdout is version('1.2.3', '>=')