Release 2.26.3.

* Check for 'externalAccountRequired' error.

* Add changelog fragment.

(cherry picked from commit 056ae1cf69)

.azure-pipelines/README.md

@@ -1,3 +1,9 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
 ## Azure Pipelines Configuration
 
 Please see the [Documentation](https://github.com/ansible/community/wiki/Testing:-Azure-Pipelines) for more information.

.azure-pipelines/azure-pipelines.yml

@@ -1,3 +1,8 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 trigger:
   batch: true
   branches:
@@ -19,6 +24,11 @@ schedules:
     branches:
       include:
         - main
+  - cron: 0 12 * * 0
+    displayName: Weekly (old stable branches)
+    always: true
+    branches:
+      include:
         - stable-*
 
 variables:
@@ -26,8 +36,6 @@ variables:
     value: ansible_collections/community/crypto
   - name: coverageBranches
     value: main
-  - name: pipelinesCoverage
-    value: coverage
   - name: entryPoint
     value: tests/utils/shippable/shippable.sh
   - name: fetchDepth
@@ -36,7 +44,7 @@ variables:
 resources:
   containers:
     - container: default
-      image: quay.io/ansible/azure-pipelines-test-container:1.9.0
+      image: quay.io/ansible/azure-pipelines-test-container:6.0.0
 
 pool: Standard
 
@@ -51,54 +59,41 @@ stages:
           targets:
             - name: Sanity
               test: 'devel/sanity/1'
-            - name: Sanity Extra # Only on devel
-              test: 'devel/sanity/extra'
             - name: Units
               test: 'devel/units/1'
-  - stage: Ansible_2_12
-    displayName: Sanity & Units 2.12
+  - stage: Ansible_2_18
+    displayName: Sanity & Units 2.18
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           targets:
             - name: Sanity
-              test: '2.12/sanity/1'
+              test: '2.18/sanity/1'
             - name: Units
-              test: '2.12/units/1'
-  - stage: Ansible_2_11
-    displayName: Sanity & Units 2.11
+              test: '2.18/units/1'
+  - stage: Ansible_2_17
+    displayName: Sanity & Units 2.17
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           targets:
             - name: Sanity
-              test: '2.11/sanity/1'
+              test: '2.17/sanity/1'
             - name: Units
-              test: '2.11/units/1'
-  - stage: Ansible_2_10
-    displayName: Sanity & Units 2.10
+              test: '2.17/units/1'
+  - stage: Ansible_2_16
+    displayName: Sanity & Units 2.16
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           targets:
             - name: Sanity
-              test: '2.10/sanity/1'
+              test: '2.16/sanity/1'
             - name: Units
-              test: '2.10/units/1'
-  - stage: Ansible_2_9
-    displayName: Sanity & Units 2.9
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          targets:
-            - name: Sanity
-              test: '2.9/sanity/1'
-            - name: Units
-              test: '2.9/units/1'
+              test: '2.16/units/1'
 ### Docker
   - stage: Docker_devel
     displayName: Docker devel
@@ -106,222 +101,242 @@ stages:
     jobs:
       - template: templates/matrix.yml
         parameters:
-          testFormat: devel/linux/{0}/1
+          testFormat: devel/linux/{0}
           targets:
-            - name: CentOS 6
-              test: centos6
-            - name: CentOS 7
-              test: centos7
-            - name: CentOS 8
-              test: centos8
-            - name: Fedora 33
-              test: fedora33
-            - name: Fedora 34
-              test: fedora34
-            - name: openSUSE 15 py2
-              test: opensuse15py2
-            - name: openSUSE 15 py3
+            - name: Fedora 41
+              test: fedora41
+            - name: Ubuntu 24.04
+              test: ubuntu2404
+            - name: Alpine 3.21
+              test: alpine321
+          groups:
+            - 1
+            - 2
+  - stage: Docker_2_18
+    displayName: Docker 2.18
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: 2.18/linux/{0}
+          targets:
+            - name: Fedora 40
+              test: fedora40
+            - name: Ubuntu 24.04
+              test: ubuntu2404
+            - name: Alpine 3.20
+              test: alpine320
+          groups:
+            - 1
+            - 2
+  - stage: Docker_2_17
+    displayName: Docker 2.17
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: 2.17/linux/{0}
+          targets:
+            - name: Fedora 39
+              test: fedora39
+            - name: Ubuntu 22.04
+              test: ubuntu2204
+            - name: Alpine 3.19
+              test: alpine319
+          groups:
+            - 1
+            - 2
+  - stage: Docker_2_16
+    displayName: Docker 2.16
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: 2.16/linux/{0}
+          targets:
+            - name: Fedora 38
+              test: fedora38
+            - name: openSUSE 15
               test: opensuse15
-            - name: Ubuntu 18.04
-              test: ubuntu1804
-            - name: Ubuntu 20.04
-              test: ubuntu2004
-  - stage: Docker_2_12
-    displayName: Docker 2.12
+            - name: Alpine 3
+              test: alpine3
+          groups:
+            - 1
+            - 2
+
+### Community Docker
+  - stage: Docker_community_devel
+    displayName: Docker (community images) devel
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
-          testFormat: 2.12/linux/{0}/1
+          testFormat: devel/linux-community/{0}
           targets:
-            - name: CentOS 8
-              test: centos8
-            - name: Fedora 33
-              test: fedora33
-            - name: openSUSE 15 py3
-              test: opensuse15
-            - name: Ubuntu 20.04
-              test: ubuntu2004
-  - stage: Docker_2_11
-    displayName: Docker 2.11
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.11/linux/{0}/1
-          targets:
-            - name: CentOS 7
-              test: centos7
-            - name: CentOS 8
-              test: centos8
-            - name: Fedora 32
-              test: fedora32
-            - name: openSUSE 15 py2
-              test: opensuse15py2
-            - name: Ubuntu 18.04
-              test: ubuntu1804
-  - stage: Docker_2_10
-    displayName: Docker 2.10
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.10/linux/{0}/1
-          targets:
-            - name: CentOS 6
-              test: centos6
-            - name: Fedora 31
-              test: fedora31
-            - name: Ubuntu 16.04
-              test: ubuntu1604
-  - stage: Docker_2_9
-    displayName: Docker 2.9
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.9/linux/{0}/1
-          targets:
-            - name: CentOS 6
-              test: centos6
-            - name: CentOS 7
-              test: centos7
-            - name: Fedora 31
-              test: fedora31
-            - name: Ubuntu 16.04
-              test: ubuntu1604
-            - name: Ubuntu 18.04
-              test: ubuntu1804
+            - name: Debian Bullseye
+              test: debian-bullseye/3.9
+            - name: Debian Bookworm
+              test: debian-bookworm/3.11
+            - name: ArchLinux
+              test: archlinux/3.13
+          groups:
+            - 1
+            - 2
 
 ### Remote
+  - stage: Remote_devel_extra_vms
+    displayName: Remote devel extra VMs
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: devel/{0}
+          targets:
+            - name: Alpine 3.21
+              test: alpine/3.21
+            - name: Fedora 41
+              test: fedora/41
+            - name: Ubuntu 22.04
+              test: ubuntu/22.04
+            - name: Ubuntu 24.04
+              test: ubuntu/24.04
+          groups:
+            - vm
   - stage: Remote_devel
     displayName: Remote devel
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
-          testFormat: devel/{0}/1
+          testFormat: devel/{0}
           targets:
-            - name: macOS 11.1
-              test: macos/11.1
+            - name: macOS 15.3
+              test: macos/15.3
+            - name: RHEL 10.0
+              test: rhel/10.0
+            - name: RHEL 9.5
+              test: rhel/9.5
+            - name: FreeBSD 14.2
+              test: freebsd/14.2
+            - name: FreeBSD 13.5
+              test: freebsd/13.5
+          groups:
+            - 1
+            - 2
+  - stage: Remote_2_18
+    displayName: Remote 2.18
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: 2.18/{0}
+          targets:
+            - name: macOS 14.3
+              test: macos/14.3
+            - name: RHEL 9.4
+              test: rhel/9.4
+            - name: FreeBSD 14.1
+              test: freebsd/14.1
+          groups:
+            - 1
+            - 2
+  - stage: Remote_2_17
+    displayName: Remote 2.17
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: 2.17/{0}
+          targets:
+            - name: RHEL 9.3
+              test: rhel/9.3
+            - name: FreeBSD 13.3
+              test: freebsd/13.3
+          groups:
+            - 1
+            - 2
+  - stage: Remote_2_16
+    displayName: Remote 2.16
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: 2.16/{0}
+          targets:
+            - name: macOS 13.2
+              test: macos/13.2
+            - name: RHEL 9.2
+              test: rhel/9.2
+            - name: RHEL 8.8
+              test: rhel/8.8
             - name: RHEL 7.9
               test: rhel/7.9
-            - name: RHEL 8.4
-              test: rhel/8.4
-            - name: FreeBSD 12.2
-              test: freebsd/12.2
-            - name: FreeBSD 13.0
-              test: freebsd/13.0
-  - stage: Remote_2_12
-    displayName: Remote 2.12
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.12/{0}/1
-          targets:
-            - name: macOS 11.1
-              test: macos/11.1
-            - name: RHEL 8.4
-              test: rhel/8.4
-            - name: FreeBSD 13.0
-              test: freebsd/13.0
-  - stage: Remote_2_11
-    displayName: Remote 2.11
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.11/{0}/1
-          targets:
-            - name: RHEL 7.9
-              test: rhel/7.9
-            - name: RHEL 8.3
-              test: rhel/8.3
-            - name: FreeBSD 12.2
-              test: freebsd/12.2
-  - stage: Remote_2_10
-    displayName: Remote 2.10
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.10/{0}/1
-          targets:
-            - name: OS X 10.11
-              test: osx/10.11
-            - name: macOS 10.15
-              test: macos/10.15
-            - name: FreeBSD 12.1
-              test: freebsd/12.1
-  - stage: Remote_2_9
-    displayName: Remote 2.9
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.9/{0}/1
-          targets:
-            - name: 'RHEL 7.8'
-              test: 'rhel/7.8'
-### cloud
-  - stage: Cloud_devel
-    displayName: Cloud devel
+            # - name: FreeBSD 13.2
+            #   test: freebsd/13.2
+          groups:
+            - 1
+            - 2
+### Generic
+  - stage: Generic_devel
+    displayName: Generic devel
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           nameFormat: Python {0}
-          testFormat: devel/cloud/{0}/1
+          testFormat: devel/generic/{0}
           targets:
-            - test: 2.6
-            - test: 2.7
-            - test: 3.5
-            - test: 3.6
-            - test: 3.7
-            - test: 3.8
-            - test: 3.9
-            - test: "3.10"
-  - stage: Cloud_2_12
-    displayName: Cloud 2.12
+            - test: "3.8"
+            # - test: "3.9"
+            # - test: "3.10"
+            - test: "3.11"
+            - test: "3.13"
+          groups:
+            - 1
+            - 2
+  - stage: Generic_2_18
+    displayName: Generic 2.18
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           nameFormat: Python {0}
-          testFormat: 2.12/cloud/{0}/1
+          testFormat: 2.18/generic/{0}
           targets:
-            - test: 3.9
-  - stage: Cloud_2_11
-    displayName: Cloud 2.11
+            - test: "3.8"
+            - test: "3.13"
+          groups:
+            - 1
+            - 2
+  - stage: Generic_2_17
+    displayName: Generic 2.17
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           nameFormat: Python {0}
-          testFormat: 2.11/cloud/{0}/1
+          testFormat: 2.17/generic/{0}
           targets:
-            - test: 3.8
-  - stage: Cloud_2_10
-    displayName: Cloud 2.10
+            - test: "3.7"
+            - test: "3.12"
+          groups:
+            - 1
+            - 2
+  - stage: Generic_2_16
+    displayName: Generic 2.16
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           nameFormat: Python {0}
-          testFormat: 2.10/cloud/{0}/1
+          testFormat: 2.16/generic/{0}
           targets:
-            - test: 3.6
-  - stage: Cloud_2_9
-    displayName: Cloud 2.9
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          nameFormat: Python {0}
-          testFormat: 2.9/cloud/{0}/1
-          targets:
-            - test: 3.5
+            - test: "2.7"
+            - test: "3.6"
+            - test: "3.11"
+          groups:
+            - 1
+            - 2
 
   ## Finally
 
@@ -329,24 +344,22 @@ stages:
     condition: succeededOrFailed()
     dependsOn:
       - Ansible_devel
-      - Ansible_2_12
-      - Ansible_2_11
-      - Ansible_2_10
-      - Ansible_2_9
+      - Ansible_2_18
+      - Ansible_2_17
+      - Ansible_2_16
+      - Remote_devel_extra_vms
       - Remote_devel
-      - Remote_2_12
-      - Remote_2_11
-      - Remote_2_10
-      - Remote_2_9
+      - Remote_2_18
+      - Remote_2_17
+      - Remote_2_16
       - Docker_devel
-      - Docker_2_12
-      - Docker_2_11
-      - Docker_2_10
-      - Docker_2_9
-      - Cloud_devel
-      - Cloud_2_12
-      - Cloud_2_11
-      - Cloud_2_10
-      - Cloud_2_9
+      - Docker_2_18
+      - Docker_2_17
+      - Docker_2_16
+      - Docker_community_devel
+      - Generic_devel
+      - Generic_2_18
+      - Generic_2_17
+      - Generic_2_16
     jobs:
       - template: templates/coverage.yml

.azure-pipelines/scripts/aggregate-coverage.sh

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # Aggregate code coverage results for later processing.
 
 set -o pipefail -eu
@@ -9,9 +13,13 @@ PATH="${PWD}/bin:${PATH}"
 
 mkdir "${agent_temp_directory}/coverage/"
 
+if [[ "$(ansible --version)" =~ \ 2\.9\. ]]; then
+    exit
+fi
+
 options=(--venv --venv-system-site-packages --color -v)
 
-ansible-test coverage combine --export "${agent_temp_directory}/coverage/" "${options[@]}"
+ansible-test coverage combine --group-by command --export "${agent_temp_directory}/coverage/" "${options[@]}"
 
 if ansible-test coverage analyze targets generate --help >/dev/null 2>&1; then
     # Only analyze coverage if the installed version of ansible-test supports it.

.azure-pipelines/scripts/combine-coverage.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 """
 Combine coverage data from multiple jobs, keeping the data only from the most recent attempt from each job.
 Coverage artifacts must be named using the format: "Coverage $(System.JobAttempt) {StableUniqueNameForEachJob}"

.azure-pipelines/scripts/process-results.sh

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # Check the test results and set variables for use in later steps.
 
 set -o pipefail -eu

.azure-pipelines/scripts/publish-codecov.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Upload code coverage reports to codecov.io.
+Multiple coverage files from multiple languages are accepted and aggregated after upload.
+Python coverage, as well as PowerShell and Python stubs can all be uploaded.
+"""
+
+import argparse
+import dataclasses
+import pathlib
+import shutil
+import subprocess
+import tempfile
+import typing as t
+import urllib.request
+
+
+@dataclasses.dataclass(frozen=True)
+class CoverageFile:
+    name: str
+    path: pathlib.Path
+    flags: t.List[str]
+
+
+@dataclasses.dataclass(frozen=True)
+class Args:
+    dry_run: bool
+    path: pathlib.Path
+
+
+def parse_args() -> Args:
+    parser = argparse.ArgumentParser()
+    parser.add_argument('-n', '--dry-run', action='store_true')
+    parser.add_argument('path', type=pathlib.Path)
+
+    args = parser.parse_args()
+
+    # Store arguments in a typed dataclass
+    fields = dataclasses.fields(Args)
+    kwargs = {field.name: getattr(args, field.name) for field in fields}
+
+    return Args(**kwargs)
+
+
+def process_files(directory: pathlib.Path) -> t.Tuple[CoverageFile, ...]:
+    processed = []
+    for file in directory.joinpath('reports').glob('coverage*.xml'):
+        name = file.stem.replace('coverage=', '')
+
+        # Get flags from name
+        flags = name.replace('-powershell', '').split('=')  # Drop '-powershell' suffix
+        flags = [flag if not flag.startswith('stub') else flag.split('-')[0] for flag in flags]  # Remove "-01" from stub files
+
+        processed.append(CoverageFile(name, file, flags))
+
+    return tuple(processed)
+
+
+def upload_files(codecov_bin: pathlib.Path, files: t.Tuple[CoverageFile, ...], dry_run: bool = False) -> None:
+    for file in files:
+        cmd = [
+            str(codecov_bin),
+            '--name', file.name,
+            '--file', str(file.path),
+        ]
+        for flag in file.flags:
+            cmd.extend(['--flags', flag])
+
+        if dry_run:
+            print(f'DRY-RUN: Would run command: {cmd}')
+            continue
+
+        subprocess.run(cmd, check=True)
+
+
+def download_file(url: str, dest: pathlib.Path, flags: int, dry_run: bool = False) -> None:
+    if dry_run:
+        print(f'DRY-RUN: Would download {url} to {dest} and set mode to {flags:o}')
+        return
+
+    with urllib.request.urlopen(url) as resp:
+        with dest.open('w+b') as f:
+            # Read data in chunks rather than all at once
+            shutil.copyfileobj(resp, f, 64 * 1024)
+
+    dest.chmod(flags)
+
+
+def main():
+    args = parse_args()
+    url = 'https://ansible-ci-files.s3.amazonaws.com/codecov/linux/codecov'
+    with tempfile.TemporaryDirectory(prefix='codecov-') as tmpdir:
+        codecov_bin = pathlib.Path(tmpdir) / 'codecov'
+        download_file(url, codecov_bin, 0o755, args.dry_run)
+
+        files = process_files(args.path)
+        upload_files(codecov_bin, files, args.dry_run)
+
+
+if __name__ == '__main__':
+    main()

.azure-pipelines/scripts/publish-codecov.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-# Upload code coverage reports to codecov.io.
-# Multiple coverage files from multiple languages are accepted and aggregated after upload.
-# Python coverage, as well as PowerShell and Python stubs can all be uploaded.
-
-set -o pipefail -eu
-
-output_path="$1"
-
-curl --silent --show-error https://ansible-ci-files.s3.us-east-1.amazonaws.com/codecov/codecov.sh > codecov.sh
-
-for file in "${output_path}"/reports/coverage*.xml; do
-    name="${file}"
-    name="${name##*/}"  # remove path
-    name="${name##coverage=}"  # remove 'coverage=' prefix if present
-    name="${name%.xml}"  # remove '.xml' suffix
-
-    bash codecov.sh \
-        -f "${file}" \
-        -n "${name}" \
-        -X coveragepy \
-        -X gcov \
-        -X fix \
-        -X search \
-        -X xcode \
-        || echo "Failed to upload code coverage report to codecov.io: ${file}"
-done

.azure-pipelines/scripts/report-coverage.sh

@@ -1,10 +1,18 @@
 #!/usr/bin/env bash
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # Generate code coverage reports for uploading to Azure Pipelines and codecov.io.
 
 set -o pipefail -eu
 
 PATH="${PWD}/bin:${PATH}"
 
+if [[ "$(ansible --version)" =~ \ 2\.9\. ]]; then
+    exit
+fi
+
 if ! ansible-test --help >/dev/null 2>&1; then
     # Install the devel version of ansible-test for generating code coverage reports.
     # This is only used by Ansible Collections, which are typically tested against multiple Ansible versions (in separate jobs).
@@ -12,4 +20,4 @@ if ! ansible-test --help >/dev/null 2>&1; then
     pip install https://github.com/ansible/ansible/archive/devel.tar.gz --disable-pip-version-check
 fi
 
-ansible-test coverage xml --stub --venv --venv-system-site-packages --color -v
+ansible-test coverage xml --group-by command --stub --venv --venv-system-site-packages --color -v

.azure-pipelines/scripts/run-tests.sh

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # Configure the test environment and run the tests.
 
 set -o pipefail -eu

.azure-pipelines/scripts/time-command.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 """Prepends a relative timestamp to each input line from stdin and writes it to stdout."""
 
 from __future__ import (absolute_import, division, print_function)

.azure-pipelines/templates/coverage.yml

@@ -1,3 +1,8 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # This template adds a job for processing code coverage data.
 # It will upload results to Azure Pipelines and codecov.io.
 # Use it from a job stage that completes after all other jobs have completed.
@@ -23,17 +28,7 @@ jobs:
       - bash: .azure-pipelines/scripts/report-coverage.sh
         displayName: Generate Coverage Report
         condition: gt(variables.coverageFileCount, 0)
-      - task: PublishCodeCoverageResults@1
-        inputs:
-          codeCoverageTool: Cobertura
-          # Azure Pipelines only accepts a single coverage data file.
-          # That means only Python or PowerShell coverage can be uploaded, but not both.
-          # Set the "pipelinesCoverage" variable to determine which type is uploaded.
-          # Use "coverage" for Python and "coverage-powershell" for PowerShell.
-          summaryFileLocation: "$(outputPath)/reports/$(pipelinesCoverage).xml"
-        displayName: Publish to Azure Pipelines
-        condition: gt(variables.coverageFileCount, 0)
-      - bash: .azure-pipelines/scripts/publish-codecov.sh "$(outputPath)"
+      - bash: .azure-pipelines/scripts/publish-codecov.py "$(outputPath)"
         displayName: Publish to codecov.io
         condition: gt(variables.coverageFileCount, 0)
         continueOnError: true

.azure-pipelines/templates/matrix.yml

@@ -1,3 +1,8 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # This template uses the provided targets and optional groups to generate a matrix which is then passed to the test template.
 # If this matrix template does not provide the required functionality, consider using the test template directly instead.
 
@@ -45,11 +50,11 @@ jobs:
     parameters:
       jobs:
         - ${{ if eq(length(parameters.groups), 0) }}:
-          - ${{ each target in parameters.targets }}:
-            - name: ${{ format(parameters.nameFormat, coalesce(target.name, target.test)) }}
-              test: ${{ format(parameters.testFormat, coalesce(target.test, target.name)) }}
-        - ${{ if not(eq(length(parameters.groups), 0)) }}:
-          - ${{ each group in parameters.groups }}:
             - ${{ each target in parameters.targets }}:
-              - name: ${{ format(format(parameters.nameGroupFormat, parameters.nameFormat), coalesce(target.name, target.test), group) }}
-                test: ${{ format(format(parameters.testGroupFormat, parameters.testFormat), coalesce(target.test, target.name), group) }}
+                - name: ${{ format(parameters.nameFormat, coalesce(target.name, target.test)) }}
+                  test: ${{ format(parameters.testFormat, coalesce(target.test, target.name)) }}
+        - ${{ if not(eq(length(parameters.groups), 0)) }}:
+            - ${{ each group in parameters.groups }}:
+                - ${{ each target in parameters.targets }}:
+                    - name: ${{ format(format(parameters.nameGroupFormat, parameters.nameFormat), coalesce(target.name, target.test), group) }}
+                      test: ${{ format(format(parameters.testGroupFormat, parameters.testFormat), coalesce(target.test, target.name), group) }}

.azure-pipelines/templates/test.yml

@@ -1,3 +1,8 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # This template uses the provided list of jobs to create test one or more test jobs.
 # It can be used directly if needed, or through the matrix template.
 
@@ -9,37 +14,37 @@ parameters:
 
 jobs:
   - ${{ each job in parameters.jobs }}:
-    - job: test_${{ replace(replace(replace(job.test, '/', '_'), '.', '_'), '-', '_') }}
-      displayName: ${{ job.name }}
-      container: default
-      workspace:
-        clean: all
-      steps:
-        - checkout: self
-          fetchDepth: $(fetchDepth)
-          path: $(checkoutPath)
-        - bash: .azure-pipelines/scripts/run-tests.sh "$(entryPoint)" "${{ job.test }}" "$(coverageBranches)"
-          displayName: Run Tests
-        - bash: .azure-pipelines/scripts/process-results.sh
-          condition: succeededOrFailed()
-          displayName: Process Results
-        - bash: .azure-pipelines/scripts/aggregate-coverage.sh "$(Agent.TempDirectory)"
-          condition: eq(variables.haveCoverageData, 'true')
-          displayName: Aggregate Coverage Data
-        - task: PublishTestResults@2
-          condition: eq(variables.haveTestResults, 'true')
-          inputs:
-            testResultsFiles: "$(outputPath)/junit/*.xml"
-          displayName: Publish Test Results
-        - task: PublishPipelineArtifact@1
-          condition: eq(variables.haveBotResults, 'true')
-          displayName: Publish Bot Results
-          inputs:
-            targetPath: "$(outputPath)/bot/"
-            artifactName: "Bot $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)"
-        - task: PublishPipelineArtifact@1
-          condition: eq(variables.haveCoverageData, 'true')
-          displayName: Publish Coverage Data
-          inputs:
-            targetPath: "$(Agent.TempDirectory)/coverage/"
-            artifactName: "Coverage $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)"
+      - job: test_${{ replace(replace(replace(job.test, '/', '_'), '.', '_'), '-', '_') }}
+        displayName: ${{ job.name }}
+        container: default
+        workspace:
+          clean: all
+        steps:
+          - checkout: self
+            fetchDepth: $(fetchDepth)
+            path: $(checkoutPath)
+          - bash: .azure-pipelines/scripts/run-tests.sh "$(entryPoint)" "${{ job.test }}" "$(coverageBranches)"
+            displayName: Run Tests
+          - bash: .azure-pipelines/scripts/process-results.sh
+            condition: succeededOrFailed()
+            displayName: Process Results
+          - bash: .azure-pipelines/scripts/aggregate-coverage.sh "$(Agent.TempDirectory)"
+            condition: eq(variables.haveCoverageData, 'true')
+            displayName: Aggregate Coverage Data
+          - task: PublishTestResults@2
+            condition: eq(variables.haveTestResults, 'true')
+            inputs:
+              testResultsFiles: "$(outputPath)/junit/*.xml"
+            displayName: Publish Test Results
+          - task: PublishPipelineArtifact@1
+            condition: eq(variables.haveBotResults, 'true')
+            displayName: Publish Bot Results
+            inputs:
+              targetPath: "$(outputPath)/bot/"
+              artifactName: "Bot $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)"
+          - task: PublishPipelineArtifact@1
+            condition: eq(variables.haveCoverageData, 'true')
+            displayName: Publish Coverage Data
+            inputs:
+              targetPath: "$(Agent.TempDirectory)/coverage/"
+              artifactName: "Coverage $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)"

.git-blame-ignore-revs

@@ -0,0 +1,8 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Reformat YAML: https://github.com/ansible-collections/community.crypto/pull/866
+33ef158b094f16d5e04ea9db3ed8bad010744d02
+# Reformat with black, keeping Python 2 compatibility: https://github.com/ansible-collections/community.crypto/pull/871
+aec1826c34051b9e7f8af7950489915b661e320b

.github/dependabot.yml

@@ -0,0 +1,15 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      ci:
+        patterns:
+          - "*"

.github/patchback.yml

@@ -0,0 +1,9 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+backport_branch_prefix: patchback/backports/
+backport_label_prefix: backport-
+target_branch_prefix: stable-
+...

.github/workflows/ansible-test.yml

@@ -0,0 +1,291 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# For the comprehensive list of the inputs supported by the ansible-community/ansible-test-gh-action GitHub Action, see
+# https://github.com/marketplace/actions/ansible-test
+
+name: EOL CI
+'on':
+  # Run EOL CI against all pushes (direct commits, also merged PRs), Pull Requests
+  push:
+    branches:
+      - main
+      - stable-*
+  pull_request:
+  # Run EOL CI once per day (at 09:00 UTC)
+  schedule:
+    - cron: '0 9 * * *'
+
+concurrency:
+  # Make sure there is at most one active run per PR, but do not cancel any non-PR runs
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.event.number) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  sanity:
+    name: EOL Sanity (Ⓐ${{ matrix.ansible }})
+    strategy:
+      matrix:
+        ansible:
+          - '2.9'
+          - '2.10'
+          - '2.11'
+          - '2.12'
+          - '2.13'
+          - '2.14'
+          - '2.15'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Perform sanity testing
+        uses: felixfontein/ansible-test-gh-action@main
+        with:
+          ansible-core-github-repository-slug: ${{ contains(fromJson('["2.9", "2.10", "2.11"]'), matrix.ansible) && 'ansible-community/eol-ansible' || 'ansible/ansible' }}
+          ansible-core-version: stable-${{ matrix.ansible }}
+          codecov-token: ${{ secrets.CODECOV_TOKEN }}
+          coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }}
+          pre-test-cmd: >-
+            git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ../../community/internal_test_tools
+          pull-request-change-detection: 'true'
+          testing-type: sanity
+
+  units:
+    runs-on: ubuntu-latest
+    name: EOL Units (Ⓐ${{ matrix.ansible }})
+    strategy:
+      # As soon as the first unit test fails, cancel the others to free up the CI queue
+      fail-fast: true
+      matrix:
+        ansible:
+          - '2.9'
+          - '2.10'
+          - '2.11'
+          - '2.12'
+          - '2.13'
+          - '2.14'
+          - '2.15'
+
+    steps:
+      - name: >-
+          Perform unit testing against
+          Ansible version ${{ matrix.ansible }}
+        uses: felixfontein/ansible-test-gh-action@main
+        with:
+          ansible-core-github-repository-slug: ${{ contains(fromJson('["2.9", "2.10", "2.11"]'), matrix.ansible) && 'ansible-community/eol-ansible' || 'ansible/ansible' }}
+          ansible-core-version: stable-${{ matrix.ansible }}
+          codecov-token: ${{ secrets.CODECOV_TOKEN }}
+          coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }}
+          pre-test-cmd: >-
+            git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ../../community/internal_test_tools
+          pull-request-change-detection: 'true'
+          testing-type: units
+
+  integration:
+    runs-on: ubuntu-latest
+    name: EOL I (Ⓐ${{ matrix.ansible }}+${{ matrix.docker }}+py${{ matrix.python }}:${{ matrix.target }})
+    strategy:
+      fail-fast: false
+      matrix:
+        ansible:
+          - ''
+        docker:
+          - ''
+        python:
+          - ''
+        target:
+          - ''
+        exclude:
+          - ansible: ''
+        include:
+          # 2.9
+          - ansible: '2.9'
+            docker: ubuntu1804
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.9'
+            docker: ubuntu1804
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.9'
+            docker: default
+            python: '2.7'
+            target: azp/generic/1/
+          - ansible: '2.9'
+            docker: default
+            python: '2.7'
+            target: azp/generic/2/
+          # 2.10
+          - ansible: '2.10'
+            docker: centos6
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.10'
+            docker: centos6
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.10'
+            docker: default
+            python: '3.6'
+            target: azp/generic/1/
+          - ansible: '2.10'
+            docker: default
+            python: '3.6'
+            target: azp/generic/2/
+          # 2.11
+          - ansible: '2.11'
+            docker: alpine3
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.11'
+            docker: alpine3
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.11'
+            docker: default
+            python: '3.8'
+            target: azp/generic/1/
+          - ansible: '2.11'
+            docker: default
+            python: '3.8'
+            target: azp/generic/2/
+          # 2.12
+          - ansible: '2.12'
+            docker: centos6
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.12'
+            docker: centos6
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.12'
+            docker: fedora33
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.12'
+            docker: fedora33
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.12'
+            docker: default
+            python: '2.6'
+            target: azp/generic/1/
+          - ansible: '2.12'
+            docker: default
+            python: '3.9'
+            target: azp/generic/2/
+          # 2.13
+          - ansible: '2.13'
+            docker: opensuse15py2
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.13'
+            docker: opensuse15py2
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.13'
+            docker: fedora35
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.13'
+            docker: fedora35
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.13'
+            docker: fedora34
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.13'
+            docker: fedora34
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.13'
+            docker: ubuntu1804
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.13'
+            docker: ubuntu1804
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.13'
+            docker: alpine3
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.13'
+            docker: alpine3
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.13'
+            docker: default
+            python: '3.8'
+            target: azp/generic/1/
+          - ansible: '2.13'
+            docker: default
+            python: '3.8'
+            target: azp/generic/2/
+          # 2.14
+          - ansible: '2.14'
+            docker: ubuntu2004
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.14'
+            docker: ubuntu2004
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.14'
+            docker: default
+            python: '3.9'
+            target: azp/generic/1/
+          - ansible: '2.14'
+            docker: default
+            python: '3.9'
+            target: azp/generic/2/
+          # 2.15
+          - ansible: '2.15'
+            docker: fedora37
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.15'
+            docker: fedora37
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.15'
+            docker: default
+            python: '3.5'
+            target: azp/generic/1/
+          - ansible: '2.15'
+            docker: default
+            python: '3.5'
+            target: azp/generic/2/
+          - ansible: '2.15'
+            docker: default
+            python: '3.10'
+            target: azp/generic/1/
+          - ansible: '2.15'
+            docker: default
+            python: '3.10'
+            target: azp/generic/2/
+
+    steps:
+      - name: >-
+          Perform integration testing against
+          Ansible version ${{ matrix.ansible }}
+          under Python ${{ matrix.python }}
+        uses: felixfontein/ansible-test-gh-action@main
+        with:
+          ansible-core-github-repository-slug: ${{ contains(fromJson('["2.9", "2.10", "2.11"]'), matrix.ansible) && 'ansible-community/eol-ansible' || 'ansible/ansible' }}
+          ansible-core-version: stable-${{ matrix.ansible }}
+          codecov-token: ${{ secrets.CODECOV_TOKEN }}
+          coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }}
+          docker-image: ${{ matrix.docker }}
+          integration-continue-on-error: 'false'
+          integration-diff: 'false'
+          integration-retry-on-error: 'true'
+          pre-test-cmd: >-
+            git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ../../community/internal_test_tools
+            ;
+            git clone --depth=1 --single-branch --branch stable-10 https://github.com/ansible-collections/community.general.git ../../community/general
+          pull-request-change-detection: 'true'
+          target: ${{ matrix.target }}
+          target-python-version: ${{ matrix.python }}
+          testing-type: integration

.github/workflows/docs-pr.yml

@@ -0,0 +1,95 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+name: Collection Docs
+concurrency:
+  group: docs-pr-${{ github.head_ref }}
+  cancel-in-progress: true
+'on':
+  pull_request_target:
+    types: [opened, synchronize, reopened, closed]
+
+env:
+  GHP_BASE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
+
+jobs:
+  build-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-pr.yml@main
+    with:
+      collection-name: community.crypto
+      init-lenient: false
+      init-fail-on-error: true
+      squash-hierarchy: true
+      init-project: Community.Crypto Collection
+      init-copyright: Community.Crypto Contributors
+      init-title: Community.Crypto Collection Documentation
+      init-html-short-title: Community.Crypto Collection Docs
+      init-extra-html-theme-options: |
+        documentation_home_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/branch/main/
+      render-file-line: '> * `$<status>` [$<path_tail>](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}/$<path_tail>)'
+
+  publish-docs-gh-pages:
+    # for now we won't run this on forks
+    if: github.repository == 'ansible-collections/community.crypto'
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    needs: [build-docs]
+    name: Publish Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
+    with:
+      artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+      action: ${{ (github.event.action == 'closed' || needs.build-docs.outputs.changed != 'true') && 'teardown' || 'publish' }}
+      publish-gh-pages-branch: true
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  comment:
+    permissions:
+      pull-requests: write
+    runs-on: ubuntu-latest
+    needs: [build-docs, publish-docs-gh-pages]
+    name: PR comments
+    steps:
+      - name: PR comment
+        uses: ansible-community/github-docs-build/actions/ansible-docs-build-comment@main
+        with:
+          body-includes: '## Docs Build'
+          reactions: heart
+          action: ${{ needs.build-docs.outputs.changed != 'true' && 'remove' || '' }}
+          on-closed-body: |
+            ## Docs Build 📝
+
+            This PR is closed and any previously published docsite has been unpublished.
+          on-merged-body: |
+            ## Docs Build 📝
+
+            Thank you for contribution!✨
+
+            This PR has been merged and the docs are now incorporated into `main`:
+            ${{ env.GHP_BASE_URL }}/branch/main
+          body: |
+            ## Docs Build 📝
+
+            Thank you for contribution!✨
+
+            The docs for **this PR** have been published here:
+            ${{ env.GHP_BASE_URL }}/pr/${{ github.event.number }}
+
+            You can compare to the docs for the `main` branch here:
+            ${{ env.GHP_BASE_URL }}/branch/main
+
+            The docsite for **this PR** is also available for download as an artifact from this run:
+            ${{ needs.build-docs.outputs.artifact-url }}
+
+            File changes:
+
+            ${{ needs.build-docs.outputs.diff-files-rendered }}
+
+            ${{ needs.build-docs.outputs.diff-rendered }}

.github/workflows/docs-push.yml

@@ -0,0 +1,55 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+name: Collection Docs
+concurrency:
+  group: docs-push-${{ github.sha }}
+  cancel-in-progress: true
+'on':
+  push:
+    branches:
+      - main
+      - stable-*
+    tags:
+      - '*'
+  # Run CI once per day (at 09:00 UTC)
+  schedule:
+    - cron: '0 9 * * *'
+  # Allow manual trigger (for newer antsibull-docs, sphinx-ansible-theme, ... versions)
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
+    with:
+      collection-name: community.crypto
+      init-lenient: false
+      init-fail-on-error: true
+      squash-hierarchy: true
+      init-project: Community.Crypto Collection
+      init-copyright: Community.Crypto Contributors
+      init-title: Community.Crypto Collection Documentation
+      init-html-short-title: Community.Crypto Collection Docs
+      init-extra-html-theme-options: |
+        documentation_home_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/branch/main/
+
+  publish-docs-gh-pages:
+    # for now we won't run this on forks
+    if: github.repository == 'ansible-collections/community.crypto'
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    needs: [build-docs]
+    name: Publish Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
+    with:
+      artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+      publish-gh-pages-branch: true
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ee.yml

@@ -0,0 +1,180 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+name: execution environment
+'on':
+  # Run CI against all pushes (direct commits, also merged PRs), Pull Requests
+  push:
+    branches:
+      - main
+      - stable-*
+  pull_request:
+  # Run CI once per day (at 09:00 UTC)
+  # This ensures that even if there haven't been commits that we are still testing against latest version of ansible-builder
+  schedule:
+    - cron: '0 9 * * *'
+
+env:
+  NAMESPACE: community
+  COLLECTION_NAME: crypto
+
+jobs:
+  build:
+    name: Build and test EE (${{ matrix.name }})
+    strategy:
+      fail-fast: false
+      matrix:
+        name:
+          - ''
+        ansible_core:
+          - ''
+        ansible_runner:
+          - ''
+        base_image:
+          - ''
+        pre_base:
+          - ''
+        extra_vars:
+          - ''
+        other_deps:
+          - ''
+        exclude:
+          - ansible_core: ''
+        include:
+          - name: ansible-core devel @ RHEL UBI 9
+            ansible_core: https://github.com/ansible/ansible/archive/devel.tar.gz
+            ansible_runner: ansible-runner
+            other_deps: |2
+                python_interpreter:
+                  package_system: python3.11 python3.11-pip python3.11-wheel python3.11-cryptography
+                  python_path: "/usr/bin/python3.11"
+            base_image: docker.io/redhat/ubi9:latest
+            pre_base: '"#"'
+            # For some reason ansible-builder will not install EPEL dependencies on RHEL
+            extra_vars: -e has_no_pyopenssl=true
+          - name: ansible-core 2.15 @ Rocky Linux 9
+            ansible_core: https://github.com/ansible/ansible/archive/stable-2.15.tar.gz
+            ansible_runner: ansible-runner
+            base_image: quay.io/rockylinux/rockylinux:9
+            pre_base: RUN dnf install -y epel-release
+            # For some reason ansible-builder will not install EPEL dependencies on Rocky Linux
+            extra_vars: -e has_no_pyopenssl=true
+          - name: ansible-core 2.14 @ CentOS Stream 9
+            ansible_core: https://github.com/ansible/ansible/archive/stable-2.14.tar.gz
+            ansible_runner: ansible-runner
+            base_image: quay.io/centos/centos:stream9
+            pre_base: RUN dnf install -y epel-release epel-next-release
+            # For some reason, PyOpenSSL is **broken** on CentOS Stream 9 / EPEL
+            extra_vars: -e has_no_pyopenssl=true
+          - name: ansible-core 2.13 @ RHEL UBI 8
+            ansible_core: https://github.com/ansible/ansible/archive/stable-2.13.tar.gz
+            ansible_runner: ansible-runner
+            other_deps: |2
+                python_interpreter:
+                  package_system: python39 python39-pip python39-wheel python39-cryptography
+            base_image: docker.io/redhat/ubi8:latest
+            pre_base: '"#"'
+            # We don't have PyOpenSSL for Python 3.9
+            extra_vars: -e has_no_pyopenssl=true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          path: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install ansible-builder and ansible-navigator
+        run: pip install ansible-builder ansible-navigator
+
+      - name: Verify requirements
+        run: ansible-builder introspect --sanitize .
+
+      - name: Make sure galaxy.yml has version entry
+        run: >-
+          python -c
+          'import yaml ;
+          f = open("galaxy.yml", "rb") ;
+          data = yaml.safe_load(f) ;
+          f.close() ;
+          data["version"] = data.get("version") or "0.0.1" ;
+          f = open("galaxy.yml", "wb") ;
+          f.write(yaml.dump(data).encode("utf-8")) ;
+          f.close() ;
+          '
+        working-directory: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
+
+      - name: Build collection
+        run: |
+          ansible-galaxy collection build --output-path ../../../
+        working-directory: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}
+
+      - name: Create files for building execution environment
+        run: |
+          COLLECTION_FILENAME="$(ls "${NAMESPACE}-${COLLECTION_NAME}"-*.tar.gz)"
+
+          # EE config
+          cat > execution-environment.yml <<EOF
+          ---
+          version: 3
+          dependencies:
+            ansible_core:
+              package_pip: ${{ matrix.ansible_core }}
+            ansible_runner:
+              package_pip: ${{ matrix.ansible_runner }}
+            galaxy: requirements.yml
+          ${{ matrix.other_deps }}
+
+          images:
+            base_image:
+              name: ${{ matrix.base_image }}
+
+          additional_build_files:
+            - src: ${COLLECTION_FILENAME}
+              dest: src
+
+          additional_build_steps:
+            prepend_base:
+              - ${{ matrix.pre_base }}
+          EOF
+          echo "::group::execution-environment.yml"
+          cat execution-environment.yml
+          echo "::endgroup::"
+
+          # Requirements
+          cat > requirements.yml <<EOF
+          ---
+          collections:
+            - name: src/${COLLECTION_FILENAME}
+              type: file
+          EOF
+          echo "::group::requirements.yml"
+          cat requirements.yml
+          echo "::endgroup::"
+
+      - name: Build image based on ${{ matrix.base_image }}
+        run: |
+          ansible-builder build --verbosity 3 --tag test-ee:latest --container-runtime podman
+
+      - name: Show images
+        run: podman image ls
+
+      - name: Run basic tests
+        run: >
+          ansible-navigator run
+          --mode stdout
+          --container-engine podman
+          --pull-policy never
+          --set-environment-variable ANSIBLE_PRIVATE_ROLE_VARS=true
+          --execution-environment-image test-ee:latest
+          -v
+          all.yml
+          ${{ matrix.extra_vars }}
+        working-directory: ansible_collections/${{ env.NAMESPACE }}/${{ env.COLLECTION_NAME }}/tests/ee

.github/workflows/nox.yml

@@ -0,0 +1,28 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+name: nox
+'on':
+  push:
+    branches:
+      - main
+      - stable-*
+  pull_request:
+  # Run CI once per day (at 09:00 UTC)
+  schedule:
+    - cron: '0 9 * * *'
+  workflow_dispatch:
+
+jobs:
+  nox:
+    runs-on: ubuntu-latest
+    name: "Run extra sanity tests"
+    steps:
+      - name: Check out collection
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Run nox
+        uses: ansible-community/antsibull-nox@main

.gitignore

@@ -1,5 +1,10 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 # Community.crypt specific things
 /changelogs/.plugin-cache.yaml
+/tests/integration/inventory
 
 
 # Created by https://www.gitignore.io/api/git,linux,pydev,python,windows,pycharm+all,jupyternotebook,vim,webstorm,emacs,dotenv

.yamllint

@@ -0,0 +1,53 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 300
+    level: error
+  document-start:
+    present: true
+  document-end: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

.yamllint-docs

@@ -0,0 +1,54 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 160
+    level: error
+  document-start:
+    present: false
+  document-end:
+    present: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

.yamllint-examples

@@ -0,0 +1,54 @@
+---
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 160
+    level: error
+  document-start:
+    present: true
+  document-end:
+    present: false
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

CHANGELOG.md.license

@@ -0,0 +1,3 @@
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: Ansible Project

CHANGELOG.rst.license

@@ -0,0 +1,3 @@
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: Ansible Project

LICENSES/Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

LICENSES/BSD-2-Clause.txt

@@ -0,0 +1,8 @@
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

LICENSES/BSD-3-Clause.txt

@@ -0,0 +1,27 @@
+Copyright (c) Individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of PyCA Cryptography nor the names of its contributors
+       may be used to endorse or promote products derived from this software
+       without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSES/GPL-3.0-or-later.txt

@@ -0,0 +1 @@
+../COPYING

LICENSES/PSF-2.0.txt

@@ -0,0 +1,48 @@
+PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+--------------------------------------------
+
+1. This LICENSE AGREEMENT is between the Python Software Foundation
+("PSF"), and the Individual or Organization ("Licensee") accessing and
+otherwise using this software ("Python") in source or binary form and
+its associated documentation.
+
+2. Subject to the terms and conditions of this License Agreement, PSF hereby
+grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
+analyze, test, perform and/or display publicly, prepare derivative works,
+distribute, and otherwise use Python alone or in any derivative version,
+provided, however, that PSF's License Agreement and PSF's notice of copyright,
+i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Python Software Foundation;
+All Rights Reserved" are retained in Python alone or in any derivative version
+prepared by Licensee.
+
+3. In the event Licensee prepares a derivative work that is based on
+or incorporates Python or any part thereof, and wants to make
+the derivative work available to others as provided herein, then
+Licensee hereby agrees to include in any such work a brief summary of
+the changes made to Python.
+
+4. PSF is making Python available to Licensee on an "AS IS"
+basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
+DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
+INFRINGE ANY THIRD PARTY RIGHTS.
+
+5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
+FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
+A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
+OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+
+6. This License Agreement will automatically terminate upon a material
+breach of its terms and conditions.
+
+7. Nothing in this License Agreement shall be deemed to create any
+relationship of agency, partnership, or joint venture between PSF and
+Licensee.  This License Agreement does not grant permission to use PSF
+trademarks or trade name in a trademark sense to endorse or promote
+products or services of Licensee, or any third party.
+
+8. By copying, installing or otherwise using Python, Licensee
+agrees to be bound by the terms and conditions of this License
+Agreement.

README.md

@@ -1,7 +1,17 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
 # Ansible Community Crypto Collection
 
-[![Build Status](https://dev.azure.com/ansible/community.crypto/_apis/build/status/CI?branchName=main)](https://dev.azure.com/ansible/community.crypto/_build?definitionId=21)
+[![Documentation](https://img.shields.io/badge/docs-brightgreen.svg)](https://docs.ansible.com/ansible/devel/collections/community/crypto/)
+[![Build Status](https://dev.azure.com/ansible/community.crypto/_apis/build/status/CI?branchName=stable-2)](https://dev.azure.com/ansible/community.crypto/_build?definitionId=21)
+[![EOL CI](https://github.com/ansible-collections/community.crypto/actions/workflows/ansible-test.yml/badge.svg?branch=stable-2)](https://github.com/ansible-collections/community.crypto/actions)
+[![Nox CI](https://github.com/ansible-collections/community.crypto/actions/workflows/nox.yml/badge.svg?branch=stable-2)](https://github.com/ansible-collections/community.crypto/actions)
 [![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.crypto)](https://codecov.io/gh/ansible-collections/community.crypto)
+[![REUSE status](https://api.reuse.software/badge/github.com/ansible-collections/community.crypto)](https://api.reuse.software/info/github.com/ansible-collections/community.crypto)
 
 Provides modules for [Ansible](https://www.ansible.com/community) for various cryptographic operations.
 
@@ -9,9 +19,28 @@ You can find [documentation for this collection on the Ansible docs site](https:
 
 Please note that this collection does **not** support Windows targets.
 
+## Code of Conduct
+
+We follow [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html) in all our interactions within this project.
+
+If you encounter abusive behavior violating the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html), please refer to the [policy violations](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html#policy-violations) section of the Code of Conduct for information on how to raise a complaint.
+
+## Communication
+
+* Join the Ansible forum:
+  * [Get Help](https://forum.ansible.com/c/help/6): get help or help others. Please add appropriate tags if you start new discussions, for example the `crypto` or `acme` tags.
+  * [Posts tagged with 'crypto'](https://forum.ansible.com/tag/crypto): subscribe to participate in cryptography related conversations.
+  * [Posts tagged with 'acme'](https://forum.ansible.com/tag/acme): subscribe to participate in ACME (RFC 8555) related conversations.
+  * [Social Spaces](https://forum.ansible.com/c/chat/4): gather and interact with fellow enthusiasts.
+  * [News & Announcements](https://forum.ansible.com/c/news/5): track project-wide announcements including social events.
+
+* The Ansible [Bullhorn newsletter](https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn): used to announce releases and important changes.
+
+For more information about communication, see the [Ansible communication guide](https://docs.ansible.com/ansible/devel/community/communication.html).
+
 ## Tested with Ansible
 
-Tested with the current Ansible 2.9, ansible-base 2.10, ansible-core 2.11 and ansible-core 2.12 releases and the current development version of ansible-core. Ansible versions before 2.9.10 are not supported.
+Tested with the current Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, ansible-core 2.14, ansible-core 2.15, ansible-core 2.16, ansible-core-2.17, and ansible-core 2.18 releases and the current development version of ansible-core. Ansible versions before 2.9.10 are not supported.
 
 ## External requirements
 
@@ -19,41 +48,68 @@ The exact requirements for every module are listed in the module documentation.
 
 Most modules require a recent enough version of [the Python cryptography library](https://pypi.org/project/cryptography/). See the module documentations for the minimal version supported for each module.
 
+## Collection Documentation
+
+Browsing the [**latest** collection documentation](https://docs.ansible.com/ansible/latest/collections/community/crypto) will show docs for the _latest version released in the Ansible package_, not the latest version of the collection released on Galaxy.
+
+Browsing the [**devel** collection documentation](https://docs.ansible.com/ansible/devel/collections/community/crypto) shows docs for the _latest version released on Galaxy_.
+
+We also separately publish [**latest commit** collection documentation](https://ansible-collections.github.io/community.crypto/branch/stable-2/) which shows docs for the _latest commit in the `stable-2` branch_.
+
+If you use the Ansible package and do not update collections independently, use **latest**. If you install or update this collection directly from Galaxy, use **devel**. If you are looking to contribute, use **latest commit**.
+
 ## Included content
 
-- OpenSSL / PKI modules:
-  - openssl_csr_info
-  - openssl_csr
-  - openssl_dhparam
-  - openssl_pkcs12
-  - openssl_privatekey_info
-  - openssl_privatekey
-  - openssl_publickey
-  - openssl_signature_info
-  - openssl_signature
-  - x509_certificate_info
-  - x509_certificate
-  - x509_crl_info
-  - x509_crl
-  - certificate_complete_chain
-- OpenSSH modules:
-  - openssh_cert
-  - openssh_keypair
-- ACME modules:
-  - acme_account_info
-  - acme_account
-  - acme_certificate
-  - acme_certificate_revoke
-  - acme_challenge_cert_helper
-  - acme_inspect
-- ECS modules:
-  - ecs_certificate
-  - ecs_domain
-- Miscellaneous modules:
-  - get_certificate
-  - luks_device
+- OpenSSL / PKI modules and plugins:
+  - certificate_complete_chain module
+  - openssl_csr_info module and filter
+  - openssl_csr_pipe module
+  - openssl_csr module
+  - openssl_dhparam module
+  - openssl_pkcs12 module
+  - openssl_privatekey_convert module
+  - openssl_privatekey_info module and filter
+  - openssl_privatekey_pipe module
+  - openssl_privatekey module
+  - openssl_publickey_info module and filter
+  - openssl_publickey module
+  - openssl_signature_info module
+  - openssl_signature module
+  - split_pem filter
+  - x509_certificate_convert module
+  - x509_certificate_info module and filter
+  - x509_certificate_pipe module
+  - x509_certificate module
+  - x509_crl_info module and filter
+  - x509_crl module
+- OpenSSH modules and plugins:
+  - openssh_cert module
+  - openssh_keypair module
+- ACME modules and plugins:
+  - acme_account_info module
+  - acme_account module
+  - acme_ari_info module
+  - acme_certificate module
+  - acme_certificate_deactivate_authz module
+  - acme_certificate_order_create module
+  - acme_certificate_order_finalize module
+  - acme_certificate_order_info module
+  - acme_certificate_order_validate module
+  - acme_certificate_revoke module
+  - acme_challenge_cert_helper module
+  - acme_inspect module
+- ECS modules and plugins:
+  - ecs_certificate module
+  - ecs_domain module
+- GnuPG modules and plugins:
+  - gpg_fingerprint lookup and filter
+- Miscellaneous modules and plugins:
+  - crypto_info module
+  - get_certificate module
+  - luks_device module
+  - parse_serial and to_serial filters
 
-You can also find a list of all modules with documentation on the [Ansible docs site](https://docs.ansible.com/ansible/latest/collections/community/crypto/).
+You can also find a list of all modules and plugins with documentation on the [Ansible docs site](https://docs.ansible.com/ansible/latest/collections/community/crypto/), or the [latest commit collection documentation](https://ansible-collections.github.io/community.crypto/branch/stable-2/).
 
 ## Using this collection
 
@@ -85,19 +141,15 @@ See [Ansible's dev guide](https://docs.ansible.com/ansible/devel/dev_guide/devel
 
 ## Release notes
 
-See the [changelog](https://github.com/ansible-collections/community.crypto/blob/main/CHANGELOG.rst).
+See the [changelog](https://github.com/ansible-collections/community.crypto/blob/stable-2/CHANGELOG.md).
 
 ## Roadmap
 
 We plan to regularly release minor and patch versions, whenever new features are added or bugs fixed. Our collection follows [semantic versioning](https://semver.org/), so breaking changes will only happen in major releases.
 
-Most modules will drop PyOpenSSL support in version 2.0.0 of the collection, i.e. in the next major version. We currently plan to release 2.0.0 somewhen during 2021. Around then, the supported versions of the most common distributions will contain a new enough version of ``cryptography``.
-
-Once 2.0.0 has been released, bugfixes will still be backported to 1.0.0 for some time, and some features might also be backported. If we do not want to backport something ourselves because we think it is not worth the effort, backport PRs by non-maintainers are usually accepted.
-
-In 2.0.0, the following notable features will be removed:
-* PyOpenSSL backends of all modules, except ``openssl_pkcs12`` which does not have a ``cryptography`` backend due to lack of support of PKCS#12 functionality in ``cryptography``.
-* The ``assertonly`` provider of ``x509_certificate`` will be removed.
+In 2.0.0, the following notable features have been removed:
+* PyOpenSSL backends of all modules, except ``openssl_pkcs12`` which did now have a ``cryptography`` backend for a long time due to lack of support of PKCS#12 functionality in ``cryptography``. (This changed.)
+* The ``assertonly`` provider of ``x509_certificate`` has been removed.
 
 ## More information
 
@@ -108,6 +160,10 @@ In 2.0.0, the following notable features will be removed:
 
 ## Licensing
 
-GNU General Public License v3.0 or later.
+This collection is primarily licensed and distributed as a whole under the GNU General Public License v3.0 or later.
 
-See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text.
+See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/community.crypto/blob/stable-2/COPYING) for the full text.
+
+Parts of the collection are licensed under the [Apache 2.0 license](https://github.com/ansible-collections/community.crypto/blob/stable-2/LICENSES/Apache-2.0.txt) (`plugins/module_utils/crypto/_obj2txt.py` and `plugins/module_utils/crypto/_objects_data.py`), the [BSD 2-Clause license](https://github.com/ansible-collections/community.crypto/blob/stable-2/LICENSES/BSD-2-Clause.txt) (`plugins/module_utils/ecs/api.py`), the [BSD 3-Clause license](https://github.com/ansible-collections/community.crypto/blob/stable-2/LICENSES/BSD-3-Clause.txt) (`plugins/module_utils/crypto/_obj2txt.py`, `tests/integration/targets/prepare_jinja2_compat/filter_plugins/jinja_compatibility.py`), and the [PSF 2.0 license](https://github.com/ansible-collections/community.crypto/blob/stable-2/LICENSES/PSF-2.0.txt) (`plugins/module_utils/_version.py`). This only applies to vendored files in ``plugins/module_utils/`` and to the ECS module utils.
+
+All files have a machine readable `SDPX-License-Identifier:` comment denoting its respective license(s) or an equivalent entry in an accompanying `.license` file. Only changelog fragments (which will not be part of a release) are covered by a blanket statement in `REUSE.toml`. This conforms to the [REUSE specification](https://reuse.software/spec/).

REUSE.toml

@@ -0,0 +1,11 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+version = 1
+
+[[annotations]]
+path = "changelogs/fragments/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = "Ansible Project"
+SPDX-License-Identifier = "GPL-3.0-or-later"

antsibull-nox.toml

@@ -0,0 +1,48 @@
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+[collection_sources]
+"community.internal_test_tools" = "git+https://github.com/ansible-collections/community.internal_test_tools.git,main"
+
+[sessions]
+
+[sessions.lint]
+run_isort = true
+isort_config = "tests/nox-config-isort.cfg"
+run_black = false
+run_flake8 = true
+flake8_config = "tests/nox-config-flake8.ini"
+run_pylint = false
+run_yamllint = true
+yamllint_config = ".yamllint"
+yamllint_config_plugins = ".yamllint-docs"
+yamllint_config_plugins_examples = ".yamllint-examples"
+run_mypy = false
+
+[sessions.docs_check]
+validate_collection_refs="all"
+
+[sessions.license_check]
+run_reuse = true
+
+[sessions.extra_checks]
+run_no_unwanted_files = true
+no_unwanted_files_module_extensions = [".py"]
+no_unwanted_files_yaml_extensions = [".yml"]
+run_action_groups = true
+
+[[sessions.extra_checks.action_groups_config]]
+name = "acme"
+pattern = "^acme_.*$"
+exclusions = [
+    "acme_ari_info",  # does not support ACME account
+    "acme_certificate_renewal_info",  # does not support ACME account
+    "acme_challenge_cert_helper",  # does not support (and need) any common parameters
+]
+doc_fragment = "community.crypto.attributes.actiongroup_acme"
+
+[sessions.build_import_check]
+run_galaxy_importer = true
+
+# [sessions.ansible_lint]

changelogs/changelog.yaml.license

@@ -0,0 +1,3 @@
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: Ansible Project

changelogs/config.yaml

@@ -1,3 +1,8 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 changelog_filename_template: ../CHANGELOG.rst
 changelog_filename_version_depth: 0
 changes_file: changelog.yaml
@@ -6,23 +11,31 @@ keep_fragments: false
 mention_ancestor: true
 new_plugins_after_name: removed_features
 notesdir: fragments
+output_formats:
+  - md
+  - rst
 prelude_section_name: release_summary
 prelude_section_title: Release Summary
 sections:
-- - major_changes
-  - Major Changes
-- - minor_changes
-  - Minor Changes
-- - breaking_changes
-  - Breaking Changes / Porting Guide
-- - deprecated_features
-  - Deprecated Features
-- - removed_features
-  - Removed Features (previously deprecated)
-- - security_fixes
-  - Security Fixes
-- - bugfixes
-  - Bugfixes
-- - known_issues
-  - Known Issues
+  - - major_changes
+    - Major Changes
+  - - minor_changes
+    - Minor Changes
+  - - breaking_changes
+    - Breaking Changes / Porting Guide
+  - - deprecated_features
+    - Deprecated Features
+  - - removed_features
+    - Removed Features (previously deprecated)
+  - - security_fixes
+    - Security Fixes
+  - - bugfixes
+    - Bugfixes
+  - - known_issues
+    - Known Issues
 title: Community Crypto
+trivial_section_name: trivial
+use_fqcn: true
+add_plugin_period: true
+changelog_nice_yaml: true
+changelog_sort: version

docs/docsite/config.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+changelog:
+  write_changelog: true

docs/docsite/extra-docs.yml

@@ -1,4 +1,8 @@
 ---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 sections:
   - title: Scenario Guides
     toctree:

docs/docsite/links.yml

@@ -0,0 +1,38 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+edit_on_github:
+  repository: ansible-collections/community.crypto
+  branch: main
+  path_prefix: ''
+
+extra_links:
+  - description: Ask for help (crypto)
+    url: https://forum.ansible.com/tags/c/help/6/none/crypto
+  - description: Ask for help (ACME)
+    url: https://forum.ansible.com/tags/c/help/6/none/acme
+  - description: Submit a bug report
+    url: https://github.com/ansible-collections/community.crypto/issues/new?assignees=&labels=&template=bug_report.md
+  - description: Request a feature
+    url: https://github.com/ansible-collections/community.crypto/issues/new?assignees=&labels=&template=feature_request.md
+
+communication:
+  matrix_rooms:
+    - topic: General usage and support questions
+      room: '#users:ansible.im'
+  irc_channels:
+    - topic: General usage and support questions
+      network: Libera
+      channel: '#ansible'
+  forums:
+    - topic: "Ansible Forum: General usage and support questions"
+      # The following URL directly points to the "Get Help" section
+      url: https://forum.ansible.com/c/help/6/none
+    - topic: "Ansible Forum: Discussions about cryptography"
+      # The following URL directly points to the "crpyto" tag
+      url: https://forum.ansible.com/tag/crpyto
+    - topic: "Ansible Forum: Discussions about ACME (RFC 8555)"
+      # The following URL directly points to the "acme" tag
+      url: https://forum.ansible.com/tag/acme

docs/docsite/rst/guide_ownca.rst

@@ -1,9 +1,14 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
 .. _ansible_collections.community.crypto.docsite.guide_ownca:
 
 How to create a small CA
 ========================
 
-The `community.crypto collection <https://galaxy.ansible.com/community/crypto>`_ offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create your own small CA and how to use it to sign certificates.
+The `community.crypto collection <https://galaxy.ansible.com/ui/repo/published/community/crypto/>`_ offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create your own small CA and how to use it to sign certificates.
 
 In all examples, we assume that the CA's private key is password protected, where the password is provided in the ``secret_ca_passphrase`` variable.
 
@@ -29,7 +34,7 @@ The following instructions show how to set up a simple self-signed CA certificat
         use_common_name_for_san: false  # since we do not specify SANs, don't use CN as a SAN
         basic_constraints:
           - 'CA:TRUE'
-        basic_constraints_critical: yes
+        basic_constraints_critical: true
         key_usage:
           - keyCertSign
         key_usage_critical: true
@@ -71,7 +76,7 @@ In the following example, we assume that the certificate to sign (including its
 
     - name: Sign certificate with our CA
       community.crypto.x509_certificate_pipe:
-        csr_content: "{{ ca_csr.csr }}"
+        csr_content: "{{ csr.csr }}"
         provider: ownca
         ownca_path: /path/to/ca-certificate.pem
         ownca_privatekey_path: /path/to/ca-certificate.key
@@ -128,7 +133,7 @@ Please note that the above procedure is **not idempotent**. The following extend
     - name: Sign certificate with our CA
       community.crypto.x509_certificate_pipe:
         content: "{{ (certificate.content | b64decode) if certificate_exists.stat.exists else omit }}"
-        csr_content: "{{ ca_csr.csr }}"
+        csr_content: "{{ csr.csr }}"
         provider: ownca
         ownca_path: /path/to/ca-certificate.pem
         ownca_privatekey_path: /path/to/ca-certificate.key

docs/docsite/rst/guide_selfsigned.rst

@@ -1,11 +1,16 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
 .. _ansible_collections.community.crypto.docsite.guide_selfsigned:
 
 How to create self-signed certificates
 ======================================
 
-The `community.crypto collection <https://galaxy.ansible.com/community/crypto>`_ offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create self-signed certificates.
+The `community.crypto collection <https://galaxy.ansible.com/ui/repo/published/community/crypto/>`_ offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create self-signed certificates.
 
-For creating any kind of certificate, you always have to start with a private key. You can use the :ref:`community.crypto.openssl_privatekey module <ansible_collections.community.crypto.openssl_privatekey_module>` to create a private key. If you only specify ``path``, the default parameters will be used. This will result in a 4096 bit RSA private key:
+For creating any kind of certificate, you always have to start with a private key. You can use the :ref:`community.crypto.openssl_privatekey module <ansible_collections.community.crypto.openssl_privatekey_module>` to create a private key. If you only specify :ansopt:`community.crypto.openssl_privatekey#module:path`, the default parameters will be used. This will result in a 4096 bit RSA private key:
 
 .. code-block:: yaml+jinja
 
@@ -13,7 +18,7 @@ For creating any kind of certificate, you always have to start with a private ke
       community.crypto.openssl_privatekey:
         path: /path/to/certificate.key
 
-You can specify ``type`` to select another key type, ``size`` to select a different key size (only available for RSA and DSA keys), or ``passphrase`` if you want to store the key password-protected:
+You can specify :ansopt:`community.crypto.openssl_privatekey#module:type` to select another key type, :ansopt:`community.crypto.openssl_privatekey#module:size` to select a different key size (only available for RSA and DSA keys), or :ansopt:`community.crypto.openssl_privatekey#module:passphrase` if you want to store the key password-protected:
 
 .. code-block:: yaml+jinja
 
@@ -33,9 +38,9 @@ To create a very simple self-signed certificate with no specific information, yo
         privatekey_path: /path/to/certificate.key
         provider: selfsigned
 
-(If you used ``passphrase`` for the private key, you have to provide ``privatekey_passphrase``.)
+(If you used :ansopt:`community.crypto.openssl_privatekey#module:passphrase` for the private key, you have to provide :ansopt:`community.crypto.x509_certificate#module:privatekey_passphrase`.)
 
-You can use ``selfsigned_not_after`` to define when the certificate expires (default: in roughly 10 years), and ``selfsigned_not_before`` to define from when the certificate is valid (default: now).
+You can use :ansopt:`community.crypto.x509_certificate#module:selfsigned_not_after` to define when the certificate expires (default: in roughly 10 years), and :ansopt:`community.crypto.x509_certificate#module:selfsigned_not_before` to define from when the certificate is valid (default: now).
 
 To define further properties of the certificate, like the subject, Subject Alternative Names (SANs), key usages, name constraints, etc., you need to first create a Certificate Signing Request (CSR) and provide it to the :ref:`community.crypto.x509_certificate module <ansible_collections.community.crypto.x509_certificate_module>`. If you do not need the CSR file, you can use the :ref:`community.crypto.openssl_csr_pipe module <ansible_collections.community.crypto.openssl_csr_pipe_module>` as in the example below. (To store it to disk, use the :ref:`community.crypto.openssl_csr module <ansible_collections.community.crypto.openssl_csr_module>` instead.)
 

galaxy.yml

@@ -1,11 +1,22 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 namespace: community
 name: crypto
-version: 1.9.4
+version: 2.26.3
 readme: README.md
 authors:
   - Ansible (github.com/ansible)
-description: null
-license_file: COPYING
+description: Provides modules and plugins for many cryptographic operations.
+license:
+  - GPL-3.0-or-later
+  - Apache-2.0
+  - BSD-2-Clause
+  - BSD-3-Clause
+  - PSF-2.0
+# license_file: COPYING
 tags:
   - acme
   - certificate

meta/ee-bindep.txt

@@ -0,0 +1,21 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+cryptsetup [platform:dpkg]
+cryptsetup [platform:rpm]
+openssh-client [platform:dpkg]
+openssh-clients [platform:rpm]
+openssl [platform:dpkg]
+openssl [platform:rpm]
+python3-cryptography [platform:dpkg]
+python3-cryptography [platform:rpm]
+python3-openssl [platform:dpkg]
+# On RHEL 9+, CentOS Stream 9+, and Rocky Linux 9+, python3-pyOpenSSL is part of EPEL
+python3-pyOpenSSL [platform:rpm !platform:rhel !platform:centos !platform:rocky]
+python3-pyOpenSSL [platform:rhel-8]
+python3-pyOpenSSL [platform:rhel !platform:rhel-6 !platform:rhel-7 !platform:rhel-8 epel]
+python3-pyOpenSSL [platform:centos-8]
+python3-pyOpenSSL [platform:centos !platform:centos-6 !platform:centos-7 !platform:centos-8 epel]
+python3-pyOpenSSL [platform:rocky-8]
+python3-pyOpenSSL [platform:rocky !platform:rocky-8 epel]

meta/ee-requirements.txt

@@ -0,0 +1,5 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+PyYAML

meta/execution-environment.yml

@@ -0,0 +1,9 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+version: 1
+dependencies:
+  python: meta/ee-requirements.txt
+  system: meta/ee-bindep.txt

meta/runtime.yml

@@ -1,31 +1,39 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 requires_ansible: '>=2.9.10'
 
 action_groups:
   acme:
-  - acme_inspect
-  - acme_certificate_revoke
-  - acme_certificate
-  - acme_account
-  - acme_account_facts
-  - acme_account_info
+    - acme_inspect
+    - acme_certificate
+    - acme_certificate_deactivate_authz
+    - acme_certificate_order_create
+    - acme_certificate_order_finalize
+    - acme_certificate_order_info
+    - acme_certificate_order_validate
+    - acme_certificate_revoke
+    - acme_account
+    - acme_account_info
 
 plugin_routing:
   modules:
     acme_account_facts:
-      deprecation:
+      tombstone:
         removal_version: 2.0.0
         warning_text: The 'community.crypto.acme_account_facts' module has been renamed to 'community.crypto.acme_account_info'.
     openssl_certificate:
-      deprecation:
+      tombstone:
         removal_version: 2.0.0
         warning_text: The 'community.crypto.openssl_certificate' module has been renamed to 'community.crypto.x509_certificate'
     openssl_certificate_info:
-      deprecation:
+      tombstone:
         removal_version: 2.0.0
         warning_text: The 'community.crypto.openssl_certificate_info' module has been renamed to 'community.crypto.x509_certificate_info'
   module_utils:
     crypto.identify:
-      redirect: community.crypto.crypto.pem
-      deprecation:
+      tombstone:
         removal_version: 2.0.0
         warning_text: The 'crypto/identify.py' module_utils has been renamed 'crypto/pem.py'. Please update your imports

noxfile.py

@@ -0,0 +1,40 @@
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025 Felix Fontein <felix@fontein.de>
+
+# /// script
+# dependencies = ["nox>=2025.02.09", "antsibull-nox"]
+# ///
+
+import sys
+
+import nox
+
+
+try:
+    import antsibull_nox
+except ImportError:
+    print("You need to install antsibull-nox in the same Python environment as nox.")
+    sys.exit(1)
+
+
+antsibull_nox.load_antsibull_nox_toml()
+
+
+@nox.session(name="create-certificates", default=False)
+def create_certificates(session: nox.Session) -> None:
+    """
+    Regenerate some vendored certificates.
+    """
+    session.install("cryptography<39.0.0")  # we want support for SHA1 signatures
+    session.run("python", "tests/create-certificates.py")
+    session.warn(
+        "Note that you need to modify some values in tests/integration/targets/x509_certificate_info/tasks/impl.yml"
+        " and tests/integration/targets/filter_x509_certificate_info/tasks/impl.yml!"
+    )
+
+
+# Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar.
+# Requires nox >= 2025.02.09
+if __name__ == "__main__":
+    nox.main()

plugins/action/openssl_privatekey_pipe.py

@@ -1,25 +1,27 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2020, Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import base64
 
-from ansible.module_utils.common.text.converters import to_native, to_bytes
-
-from ansible_collections.community.crypto.plugins.plugin_utils.action_module import ActionModuleBase
-
+from ansible.module_utils.common.text.converters import to_bytes, to_native
 from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
     OpenSSLObjectError,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.privatekey import (
-    select_backend,
     get_privatekey_argument_spec,
+    select_backend,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.action_module import (
+    ActionModuleBase,
 )
 
 
@@ -29,16 +31,18 @@ class PrivateKeyModule(object):
         self.module_backend = module_backend
         self.check_mode = module.check_mode
         self.changed = False
-        self.return_current_key = module.params['return_current_key']
+        self.return_current_key = module.params["return_current_key"]
 
-        if module.params['content'] is not None:
-            if module.params['content_base64']:
+        if module.params["content"] is not None:
+            if module.params["content_base64"]:
                 try:
-                    data = base64.b64decode(module.params['content'])
+                    data = base64.b64decode(module.params["content"])
                 except Exception as e:
-                    module.fail_json(msg='Cannot decode Base64 encoded data: {0}'.format(e))
+                    module.fail_json(
+                        msg="Cannot decode Base64 encoded data: {0}".format(e)
+                    )
             else:
-                data = to_bytes(module.params['content'])
+                data = to_bytes(module.params["content"])
             module_backend.set_existing(data)
 
     def generate(self, module):
@@ -50,6 +54,16 @@ class PrivateKeyModule(object):
                 self.module_backend.generate_private_key()
                 privatekey_data = self.module_backend.get_private_key_data()
                 self.privatekey_bytes = privatekey_data
+            else:
+                self.module.deprecate(
+                    "Check mode support for openssl_privatekey_pipe will change in community.crypto 3.0.0"
+                    " to behave the same as without check mode. You can get that behavior right now"
+                    " by adding `check_mode: false` to the openssl_privatekey_pipe task. If you think this"
+                    " breaks your use-case of this module, please create an issue in the"
+                    " community.crypto repository",
+                    version="3.0.0",
+                    collection_name="community.crypto",
+                )
             self.changed = True
         elif self.module_backend.needs_conversion():
             # Convert
@@ -57,12 +71,24 @@ class PrivateKeyModule(object):
                 self.module_backend.convert_private_key()
                 privatekey_data = self.module_backend.get_private_key_data()
                 self.privatekey_bytes = privatekey_data
+            else:
+                self.module.deprecate(
+                    "Check mode support for openssl_privatekey_pipe will change in community.crypto 3.0.0"
+                    " to behave the same as without check mode. You can get that behavior right now"
+                    " by adding `check_mode: false` to the openssl_privatekey_pipe task. If you think this"
+                    " breaks your use-case of this module, please create an issue in the"
+                    " community.crypto repository",
+                    version="3.0.0",
+                    collection_name="community.crypto",
+                )
             self.changed = True
 
     def dump(self):
         """Serialize the object into a dictionary."""
-        result = self.module_backend.dump(include_key=self.changed or self.return_current_key)
-        result['changed'] = self.changed
+        result = self.module_backend.dump(
+            include_key=self.changed or self.return_current_key
+        )
+        result["changed"] = self.changed
         return result
 
 
@@ -70,11 +96,13 @@ class ActionModule(ActionModuleBase):
     @staticmethod
     def setup_module():
         argument_spec = get_privatekey_argument_spec()
-        argument_spec.argument_spec.update(dict(
-            content=dict(type='str', no_log=True),
-            content_base64=dict(type='bool', default=False),
-            return_current_key=dict(type='bool', default=False),
-        ))
+        argument_spec.argument_spec.update(
+            dict(
+                content=dict(type="str", no_log=True),
+                content_base64=dict(type="bool", default=False),
+                return_current_key=dict(type="bool", default=False),
+            )
+        )
         return argument_spec, dict(
             supports_check_mode=True,
         )
@@ -83,7 +111,7 @@ class ActionModule(ActionModuleBase):
     def run_module(module):
         backend, module_backend = select_backend(
             module=module,
-            backend=module.params['select_crypto_backend'],
+            backend=module.params["select_crypto_backend"],
         )
 
         try:
@@ -98,10 +126,10 @@ class ActionModule(ActionModuleBase):
                 # `module.no_log = True`, this should be safe.
                 module.no_log = True
                 try:
-                    module.no_log_values.remove(module.params['content'])
+                    module.no_log_values.remove(module.params["content"])
                 except KeyError:
                     pass
-                module.params['content'] = 'ANSIBLE_NO_LOG_VALUE'
+                module.params["content"] = "ANSIBLE_NO_LOG_VALUE"
             module.exit_json(**result)
         except OpenSSLObjectError as exc:
             module.fail_json(msg=to_native(exc))

plugins/doc_fragments/acme.py

@@ -1,135 +1,257 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = r'''
+    #
+    # NOTE: This document fragment is DEPRECATED and will be removed from community.crypto 3.0.0.
+    #       Use both the BASIC and ACCOUNT fragments as a replacement.
+    DOCUMENTATION = r"""
 notes:
-  - "If a new enough version of the C(cryptography) library
-     is available (see Requirements for details), it will be used
-     instead of the C(openssl) binary. This can be explicitly disabled
-     or enabled with the C(select_crypto_backend) option. Note that using
-     the C(openssl) binary will be slower and less secure, as private key
-     contents always have to be stored on disk (see
-     C(account_key_content))."
-  - "Although the defaults are chosen so that the module can be used with
-     the L(Let's Encrypt,https://letsencrypt.org/) CA, the module can in
-     principle be used with any CA providing an ACME endpoint, such as
-     L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme)."
+  - If a new enough version of the C(cryptography) library is available (see Requirements for details), it will be used instead
+    of the C(openssl) binary. This can be explicitly disabled or enabled with the O(select_crypto_backend) option. Note that
+    using the C(openssl) binary will be slower and less secure, as private key contents always have to be stored on disk (see
+    O(account_key_content)).
+  - Although the defaults are chosen so that the module can be used with the L(Let's Encrypt,https://letsencrypt.org/) CA,
+    the module can in principle be used with any CA providing an ACME endpoint, such as L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme).
+  - So far, the ACME modules have only been tested by the developers against Let's Encrypt (staging and production), Buypass
+    (staging and production), ZeroSSL (production), and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We
+    have got community feedback that they also work with Sectigo ACME Service for InCommon. If you experience problems with
+    another ACME server, please L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
+    to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
 requirements:
-  - python >= 2.6
   - either openssl or L(cryptography,https://cryptography.io/) >= 1.5
+  - ipaddress
 options:
   account_key_src:
     description:
-      - "Path to a file containing the ACME account RSA or Elliptic Curve
-         key."
-      - "Private keys can be created with the
-         M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
-         modules. If the requisites (pyOpenSSL or cryptography) are not available,
-         keys can also be created directly with the C(openssl) command line tool:
-         RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys
-         can be created with C(openssl ecparam -genkey ...). Any other tool creating
-         private keys in PEM format can be used as well."
-      - "Mutually exclusive with C(account_key_content)."
-      - "Required if C(account_key_content) is not used."
+      - Path to a file containing the ACME account RSA or Elliptic Curve key.
+      - 'Private keys can be created with the M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
+        modules. If the requisite (cryptography) is not available, keys can also be created directly with the C(openssl) command
+        line tool: RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys can be created with C(openssl ecparam
+        -genkey ...). Any other tool creating private keys in PEM format can be used as well.'
+      - Mutually exclusive with O(account_key_content).
+      - Required if O(account_key_content) is not used.
     type: path
-    aliases: [ account_key ]
+    aliases: [account_key]
   account_key_content:
     description:
-      - "Content of the ACME account RSA or Elliptic Curve key."
-      - "Mutually exclusive with C(account_key_src)."
-      - "Required if C(account_key_src) is not used."
-      - "B(Warning:) the content will be written into a temporary file, which will
-         be deleted by Ansible when the module completes. Since this is an
-         important private key — it can be used to change the account key,
-         or to revoke your certificates without knowing their private keys
-         —, this might not be acceptable."
-      - "In case C(cryptography) is used, the content is not written into a
-         temporary file. It can still happen that it is written to disk by
-         Ansible in the process of moving the module with its argument to
-         the node where it is executed."
+      - Content of the ACME account RSA or Elliptic Curve key.
+      - Mutually exclusive with O(account_key_src).
+      - Required if O(account_key_src) is not used.
+      - B(Warning:) the content will be written into a temporary file, which will be deleted by Ansible when the module completes.
+        Since this is an important private key — it can be used to change the account key, or to revoke your certificates
+        without knowing their private keys —, this might not be acceptable.
+      - In case C(cryptography) is used, the content is not written into a temporary file. It can still happen that it is
+        written to disk by Ansible in the process of moving the module with its argument to the node where it is executed.
     type: str
   account_key_passphrase:
     description:
       - Phassphrase to use to decode the account key.
-      - "B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend."
+      - B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend.
     type: str
     version_added: 1.6.0
   account_uri:
     description:
-      - "If specified, assumes that the account URI is as given. If the
-         account key does not match this account, or an account with this
-         URI does not exist, the module fails."
+      - If specified, assumes that the account URI is as given. If the account key does not match this account, or an account
+        with this URI does not exist, the module fails.
     type: str
   acme_version:
     description:
-      - "The ACME version of the endpoint."
-      - "Must be C(1) for the classic Let's Encrypt and Buypass ACME endpoints,
-         or C(2) for standardized ACME v2 endpoints."
-      - "The default value is C(1). Note that in community.crypto 2.0.0, this
-         option B(will be required) and will no longer have a default."
-      - "Please also note that we will deprecate ACME v1 support eventually."
+      - The ACME version of the endpoint.
+      - Must be V(1) for the classic Let's Encrypt and Buypass ACME endpoints, or V(2) for standardized ACME v2 endpoints.
+      - The value V(1) is deprecated since community.crypto 2.0.0 and will be removed from community.crypto 3.0.0.
+    required: true
     type: int
-    choices: [ 1, 2 ]
+    choices: [1, 2]
   acme_directory:
     description:
-      - "The ACME directory to use. This is the entry point URL to access
-         the ACME CA server API."
-      - "For safety reasons the default is set to the Let's Encrypt staging
-         server (for the ACME v1 protocol). This will create technically correct,
-         but untrusted certificates."
-      - "The default value is C(https://acme-staging.api.letsencrypt.org/directory).
-         Note that in community.crypto 2.0.0, this option B(will be required) and
-         will no longer have a default. Note that the default is the Let's Encrypt
-         staging server for the ACME v1 protocol, which is deprecated and will
-         be disabled in May 2021 (see
-         L(here,https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430/7)
-         for details)."
-      - "For Let's Encrypt, all staging endpoints can be found here:
-         U(https://letsencrypt.org/docs/staging-environment/). For Buypass, all
-         endpoints can be found here:
-         U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)"
-      - "For B(Let's Encrypt), the production directory URL for ACME v2 is
-         U(https://acme-v02.api.letsencrypt.org/directory).
-         (The production directory URL for ACME v1 is
-         U(https://acme-v01.api.letsencrypt.org/directory) and will be
-         disabled in July 2021.)"
-      - "For B(Buypass), the production directory URL for ACME v2 and v1 is
-         U(https://api.buypass.com/acme/directory)."
-      - "For B(ZeroSSL), the production directory URL for ACME v2 is
-         U(https://acme.zerossl.com/v2/DV90)."
-      - "B(Warning:) So far, the ACME modules have only been tested against Let's Encrypt
-         (staging and production), Buypass (staging and production), ZeroSSL (production),
-         and L(Pebble testing server,https://github.com/letsencrypt/Pebble). If you
-         experience problems with another ACME server, please
-         L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
-         to help us supporting it. Feedback that an ACME server not mentioned does work
-         is also appreciated."
+      - The ACME directory to use. This is the entry point URL to access the ACME CA server API.
+      - For safety reasons the default is set to the Let's Encrypt staging server (for the ACME v1 protocol). This will create
+        technically correct, but untrusted certificates.
+      - "For Let's Encrypt, all staging endpoints can be found here: U(https://letsencrypt.org/docs/staging-environment/).
+        For Buypass, all endpoints can be found here: U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)."
+      - For B(Let's Encrypt), the production directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory).
+      - For B(Buypass), the production directory URL for ACME v2 and v1 is U(https://api.buypass.com/acme/directory).
+      - For B(ZeroSSL), the production directory URL for ACME v2 is U(https://acme.zerossl.com/v2/DV90).
+      - For B(Sectigo), the production directory URL for ACME v2 is U(https://acme-qa.secure.trust-provider.com/v2/DV).
+      - The notes for this module contain a list of ACME services this module has been tested against.
+    required: true
     type: str
   validate_certs:
     description:
       - Whether calls to the ACME directory will validate TLS certificates.
-      - "B(Warning:) Should B(only ever) be set to C(no) for testing purposes,
-         for example when testing against a local Pebble server."
+      - B(Warning:) Should B(only ever) be set to V(false) for testing purposes, for example when testing against a local
+        Pebble server.
     type: bool
-    default: yes
+    default: true
   select_crypto_backend:
     description:
       - Determines which crypto backend to use.
-      - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to
-        C(openssl).
-      - If set to C(openssl), will try to use the C(openssl) binary.
-      - If set to C(cryptography), will try to use the
-        L(cryptography,https://cryptography.io/) library.
+      - The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to C(openssl).
+      - If set to V(openssl), will try to use the C(openssl) binary.
+      - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
     type: str
     default: auto
-    choices: [ auto, cryptography, openssl ]
-'''
+    choices: [auto, cryptography, openssl]
+  request_timeout:
+    description:
+      - The time Ansible should wait for a response from the ACME API.
+      - This timeout is applied to all HTTP(S) requests (HEAD, GET, POST).
+    type: int
+    default: 10
+    version_added: 2.3.0
+"""
+
+    # Basic documentation fragment without account data
+    BASIC = r"""
+notes:
+  - Although the defaults are chosen so that the module can be used with the L(Let's Encrypt,https://letsencrypt.org/) CA,
+    the module can in principle be used with any CA providing an ACME endpoint, such as L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme).
+  - So far, the ACME modules have only been tested by the developers against Let's Encrypt (staging and production), Buypass
+    (staging and production), ZeroSSL (production), and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We
+    have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with
+    another ACME server, please L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
+    to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
+requirements:
+  - either openssl or L(cryptography,https://cryptography.io/) >= 1.5
+  - ipaddress
+options:
+  acme_version:
+    description:
+      - The ACME version of the endpoint.
+      - Must be V(1) for the classic Let's Encrypt and Buypass ACME endpoints, or V(2) for standardized ACME v2 endpoints.
+      - The value V(1) is deprecated since community.crypto 2.0.0 and will be removed from community.crypto 3.0.0.
+    required: true
+    type: int
+    choices: [1, 2]
+  acme_directory:
+    description:
+      - The ACME directory to use. This is the entry point URL to access the ACME CA server API.
+      - For safety reasons the default is set to the Let's Encrypt staging server (for the ACME v1 protocol). This will create
+        technically correct, but untrusted certificates.
+      - "For Let's Encrypt, all staging endpoints can be found here: U(https://letsencrypt.org/docs/staging-environment/).
+        For Buypass, all endpoints can be found here: U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)."
+      - For B(Let's Encrypt), the production directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory).
+      - For B(Buypass), the production directory URL for ACME v2 and v1 is U(https://api.buypass.com/acme/directory).
+      - For B(ZeroSSL), the production directory URL for ACME v2 is U(https://acme.zerossl.com/v2/DV90).
+      - For B(Sectigo), the production directory URL for ACME v2 is U(https://acme-qa.secure.trust-provider.com/v2/DV).
+      - For B(HARICA), the production directory URL for ACME v2 is U(https://acme.harica.gr/XXX/directory) with XXX being specific to your account.
+      - The notes for this module contain a list of ACME services this module has been tested against.
+    required: true
+    type: str
+  validate_certs:
+    description:
+      - Whether calls to the ACME directory will validate TLS certificates.
+      - B(Warning:) Should B(only ever) be set to V(false) for testing purposes, for example when testing against a local
+        Pebble server.
+    type: bool
+    default: true
+  select_crypto_backend:
+    description:
+      - Determines which crypto backend to use.
+      - The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to C(openssl).
+      - If set to V(openssl), will try to use the C(openssl) binary.
+      - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+    type: str
+    default: auto
+    choices: [auto, cryptography, openssl]
+  request_timeout:
+    description:
+      - The time Ansible should wait for a response from the ACME API.
+      - This timeout is applied to all HTTP(S) requests (HEAD, GET, POST).
+    type: int
+    default: 10
+    version_added: 2.3.0
+"""
+
+    # Account data documentation fragment
+    ACCOUNT = r"""
+notes:
+  - If a new enough version of the C(cryptography) library is available (see Requirements for details), it will be used instead
+    of the C(openssl) binary. This can be explicitly disabled or enabled with the O(select_crypto_backend) option. Note that
+    using the C(openssl) binary will be slower and less secure, as private key contents always have to be stored on disk (see
+    O(account_key_content)).
+options:
+  account_key_src:
+    description:
+      - Path to a file containing the ACME account RSA or Elliptic Curve key.
+      - "For Elliptic Curve keys only the following curves are supported: V(secp256r1), V(secp384r1), and V(secp521r1)."
+      - 'Private keys can be created with the M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
+        modules. If the requisite (cryptography) is not available, keys can also be created directly with the C(openssl) command
+        line tool: RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys can be created with C(openssl ecparam
+        -genkey ...). Any other tool creating private keys in PEM format can be used as well.'
+      - Mutually exclusive with O(account_key_content).
+      - Required if O(account_key_content) is not used.
+    type: path
+    aliases:
+      - account_key
+  account_key_content:
+    description:
+      - Content of the ACME account RSA or Elliptic Curve key.
+      - "For Elliptic Curve keys only the following curves are supported: V(secp256r1), V(secp384r1), and V(secp521r1)."
+      - Mutually exclusive with O(account_key_src).
+      - Required if O(account_key_src) is not used.
+      - B(Warning:) the content will be written into a temporary file, which will be deleted by Ansible when the module completes.
+        Since this is an important private key — it can be used to change the account key, or to revoke your certificates
+        without knowing their private keys —, this might not be acceptable.
+      - In case C(cryptography) is used, the content is not written into a temporary file. It can still happen that it is
+        written to disk by Ansible in the process of moving the module with its argument to the node where it is executed.
+    type: str
+  account_key_passphrase:
+    description:
+      - Phassphrase to use to decode the account key.
+      - B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend.
+    type: str
+    version_added: 1.6.0
+  account_uri:
+    description:
+      - If specified, assumes that the account URI is as given. If the account key does not match this account, or an account
+        with this URI does not exist, the module fails.
+    type: str
+"""
+
+    # No account data documentation fragment
+    NO_ACCOUNT = r"""
+notes:
+  - "If a new enough version of the C(cryptography) library
+     is available (see Requirements for details), it will be used
+     instead of the C(openssl) binary. This can be explicitly disabled
+     or enabled with the O(select_crypto_backend) option. Note that using
+     the C(openssl) binary will be slower."
+options: {}
+"""
+
+    CERTIFICATE = r"""
+options:
+  csr:
+    description:
+      - File containing the CSR for the new certificate.
+      - Can be created with M(community.crypto.openssl_csr).
+      - The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must
+        be fulfilled for the CSR to be signed.
+      - 'B(Note): the private key used to create the CSR B(must not) be the account key. This is a bad idea from a security
+        point of view, and the CA should not accept the CSR. The ACME server should return an error in this case.'
+      - Precisely one of O(csr) or O(csr_content) must be specified.
+    type: path
+  csr_content:
+    description:
+      - Content of the CSR for the new certificate.
+      - Can be created with M(community.crypto.openssl_csr_pipe).
+      - The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must
+        be fulfilled for the CSR to be signed.
+      - 'B(Note): the private key used to create the CSR B(must not) be the account key. This is a bad idea from a security
+        point of view, and the CA should not accept the CSR. The ACME server should return an error in this case.'
+      - Precisely one of O(csr) or O(csr_content) must be specified.
+    type: str
+"""

plugins/doc_fragments/attributes.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    # Standard documentation fragment
+    DOCUMENTATION = r"""
+options: {}
+attributes:
+  check_mode:
+    description: Can run in C(check_mode) and return changed status prediction without modifying target.
+  diff_mode:
+    description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+  idempotent:
+    description:
+      - When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.
+      - This assumes that the system controlled/queried by the module has not changed in a relevant way.
+"""
+
+    # Should be used together with the standard fragment
+    IDEMPOTENT_NOT_MODIFY_STATE = r"""
+options: {}
+attributes:
+  idempotent:
+    support: full
+    details:
+      - This action does not modify state.
+"""
+
+    # Should be used together with the standard fragment
+    INFO_MODULE = r"""
+options: {}
+attributes:
+  check_mode:
+    support: full
+    details:
+      - This action does not modify state.
+  diff_mode:
+    support: N/A
+    details:
+      - This action does not modify state.
+"""
+
+    ACTIONGROUP_ACME = r"""
+options: {}
+attributes:
+  action_group:
+    description: Use C(group/acme) or C(group/community.crypto.acme) in C(module_defaults) to set defaults for this module.
+    support: full
+    membership:
+      - community.crypto.acme
+      - acme
+"""
+
+    FACTS = r"""
+options: {}
+attributes:
+  facts:
+    description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
+"""
+
+    # Should be used together with the standard fragment and the FACTS fragment
+    FACTS_MODULE = r"""
+options: {}
+attributes:
+  check_mode:
+    support: full
+    details:
+      - This action does not modify state.
+  diff_mode:
+    support: N/A
+    details:
+      - This action does not modify state.
+  facts:
+    support: full
+"""
+
+    FILES = r"""
+options: {}
+attributes:
+  safe_file_operations:
+    description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
+"""
+
+    FLOW = r"""
+options: {}
+attributes:
+  action:
+    description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
+  async:
+    description: Supports being used with the C(async) keyword.
+"""

plugins/doc_fragments/ecs_credential.py

@@ -1,43 +1,46 @@
 # -*- coding: utf-8 -*-
 
 # Copyright (c), Entrust Datacard Corporation, 2019
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
 
-from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 
 class ModuleDocFragment(object):
 
     # Plugin options for Entrust Certificate Services (ECS) credentials
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 options:
-    entrust_api_user:
-        description:
-            - The username for authentication to the Entrust Certificate Services (ECS) API.
-        type: str
-        required: true
-    entrust_api_key:
-        description:
-            - The key (password) for authentication to the Entrust Certificate Services (ECS) API.
-        type: str
-        required: true
-    entrust_api_client_cert_path:
-        description:
-            - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
-        type: path
-        required: true
-    entrust_api_client_cert_key_path:
-        description:
-            - The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
-        type: path
-        required: true
-    entrust_api_specification_path:
-        description:
-            - The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
-            - You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
-        type: path
-        default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
+  entrust_api_user:
+    description:
+      - The username for authentication to the Entrust Certificate Services (ECS) API.
+    type: str
+    required: true
+  entrust_api_key:
+    description:
+      - The key (password) for authentication to the Entrust Certificate Services (ECS) API.
+    type: str
+    required: true
+  entrust_api_client_cert_path:
+    description:
+      - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+    type: path
+    required: true
+  entrust_api_client_cert_key_path:
+    description:
+      - The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+    type: path
+    required: true
+  entrust_api_specification_path:
+    description:
+      - The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
+      - You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
+    type: path
+    default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
 requirements:
-    - "PyYAML >= 3.11"
-'''
+  - "PyYAML >= 3.11"
+"""

plugins/doc_fragments/module_certificate.py

@@ -1,587 +1,415 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
-# Copyright: (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 description:
-    - This module allows one to (re)generate OpenSSL certificates.
-    - 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)).
-      Please note that the PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in community.crypto 2.0.0.
+  - This module allows one to (re)generate OpenSSL certificates.
+  - It uses the cryptography python library to interact with OpenSSL.
+attributes:
+  diff_mode:
+    support: full
+  idempotent:
+    support: partial
+    details:
+      - If relative timestamps are used and O(ignore_timestamps=false), the module is not idempotent.
+      - The option O(force=true) generally disables idempotency.
 requirements:
-    - PyOpenSSL >= 0.15 or cryptography >= 1.6 (if using C(selfsigned), C(ownca) or C(assertonly) provider)
+  - cryptography >= 1.6 (if using V(selfsigned) or V(ownca) provider)
 options:
-    force:
-        description:
-            - Generate the certificate, even if it already exists.
-        type: bool
-        default: no
+  force:
+    description:
+      - Generate the certificate, even if it already exists.
+    type: bool
+    default: false
 
-    csr_path:
-        description:
-            - Path to the Certificate Signing Request (CSR) used to generate this certificate.
-            - This is mutually exclusive with I(csr_content).
-        type: path
-    csr_content:
-        description:
-            - Content of the Certificate Signing Request (CSR) used to generate this certificate.
-            - This is mutually exclusive with I(csr_path).
-        type: str
+  csr_path:
+    description:
+      - Path to the Certificate Signing Request (CSR) used to generate this certificate.
+      - This is mutually exclusive with O(csr_content).
+    type: path
+  csr_content:
+    description:
+      - Content of the Certificate Signing Request (CSR) used to generate this certificate.
+      - This is mutually exclusive with O(csr_path).
+    type: str
 
-    privatekey_path:
-        description:
-            - Path to the private key to use when signing the certificate.
-            - This is mutually exclusive with I(privatekey_content).
-        type: path
-    privatekey_content:
-        description:
-            - Path to the private key to use when signing the certificate.
-            - This is mutually exclusive with I(privatekey_path).
-        type: str
+  privatekey_path:
+    description:
+      - Path to the private key to use when signing the certificate.
+      - This is mutually exclusive with O(privatekey_content).
+    type: path
+  privatekey_content:
+    description:
+      - Content of the private key to use when signing the certificate.
+      - This is mutually exclusive with O(privatekey_path).
+    type: str
 
-    privatekey_passphrase:
-        description:
-            - The passphrase for the I(privatekey_path) resp. I(privatekey_content).
-            - This is required if the private key is password protected.
-        type: str
+  privatekey_passphrase:
+    description:
+      - The passphrase for the O(privatekey_path) resp. O(privatekey_content).
+      - This is required if the private key is password protected.
+    type: str
 
-    select_crypto_backend:
-        description:
-            - Determines which crypto backend to use.
-            - 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 community.crypto 2.0.0.
-              From that point on, only the C(cryptography) backend will be available.
-        type: str
-        default: auto
-        choices: [ auto, cryptography, pyopenssl ]
+  ignore_timestamps:
+    description:
+      - Whether the "not before" and "not after" timestamps should be ignored for idempotency checks.
+      - It is better to keep the default value V(true) when using relative timestamps (like V(+0s) for now).
+    type: bool
+    default: true
+    version_added: 2.0.0
+
+  select_crypto_backend:
+    description:
+      - Determines which crypto backend to use.
+      - The default choice is V(auto), which tries to use C(cryptography) if available.
+      - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+    type: str
+    default: auto
+    choices: [auto, cryptography]
 
 notes:
-    - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
-    - Date specified should be UTC. Minutes and seconds are mandatory.
-    - For security reason, when you use C(ownca) provider, you should NOT run
-      M(community.crypto.x509_certificate) on a target machine, but on a dedicated CA machine. It
-      is recommended not to store the CA private key on the target machine. Once signed, the
-      certificate can be moved to the target machine.
+  - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
+  - Date specified should be UTC. Minutes and seconds are mandatory.
+  - For security reason, when you use V(ownca) provider, you should NOT run M(community.crypto.x509_certificate) on a target
+    machine, but on a dedicated CA machine. It is recommended not to store the CA private key on the target machine. Once
+    signed, the certificate can be moved to the target machine.
 seealso:
-- module: community.crypto.openssl_csr
-- module: community.crypto.openssl_csr_pipe
-- module: community.crypto.openssl_dhparam
-- module: community.crypto.openssl_pkcs12
-- module: community.crypto.openssl_privatekey
-- module: community.crypto.openssl_privatekey_pipe
-- module: community.crypto.openssl_publickey
-'''
+  - module: community.crypto.openssl_csr
+  - module: community.crypto.openssl_csr_pipe
+  - module: community.crypto.openssl_dhparam
+  - module: community.crypto.openssl_pkcs12
+  - module: community.crypto.openssl_privatekey
+  - module: community.crypto.openssl_privatekey_pipe
+  - module: community.crypto.openssl_publickey
+"""
 
-    BACKEND_ACME_DOCUMENTATION = r'''
+    BACKEND_ACME_DOCUMENTATION = r"""
 description:
-    - This module allows one to (re)generate OpenSSL certificates.
+  - This module allows one to (re)generate OpenSSL certificates.
 requirements:
-    - acme-tiny >= 4.0.0 (if using the C(acme) provider)
+  - acme-tiny >= 4.0.0 (if using the V(acme) provider)
 options:
-    acme_accountkey_path:
-        description:
-            - The path to the accountkey for the C(acme) provider.
-            - This is only used by the C(acme) provider.
-        type: path
+  acme_accountkey_path:
+    description:
+      - The path to the accountkey for the V(acme) provider.
+      - This is only used by the V(acme) provider.
+    type: path
 
-    acme_challenge_path:
-        description:
-            - The path to the ACME challenge directory that is served on U(http://<HOST>:80/.well-known/acme-challenge/)
-            - This is only used by the C(acme) provider.
-        type: path
+  acme_challenge_path:
+    description:
+      - The path to the ACME challenge directory that is served on U(http://<HOST>:80/.well-known/acme-challenge/)
+      - This is only used by the V(acme) provider.
+    type: path
 
-    acme_chain:
-        description:
-            - Include the intermediate certificate to the generated certificate
-            - This is only used by the C(acme) provider.
-            - Note that this is only available for older versions of C(acme-tiny).
-              New versions include the chain automatically, and setting I(acme_chain) to C(yes) results in an error.
-        type: bool
-        default: no
+  acme_chain:
+    description:
+      - Include the intermediate certificate to the generated certificate
+      - This is only used by the V(acme) provider.
+      - Note that this is only available for older versions of C(acme-tiny).
+        New versions include the chain automatically, and setting O(acme_chain) to V(true) results in an error.
+    type: bool
+    default: false
 
-    acme_directory:
-        description:
-            - "The ACME directory to use. You can use any directory that supports the ACME protocol, such as Buypass or Let's Encrypt."
-            - "Let's Encrypt recommends using their staging server while developing jobs. U(https://letsencrypt.org/docs/staging-environment/)."
-        type: str
-        default: https://acme-v02.api.letsencrypt.org/directory
-'''
+  acme_directory:
+    description:
+      - "The ACME directory to use. You can use any directory that supports the ACME protocol, such as Buypass or Let's Encrypt."
+      - "Let's Encrypt recommends using their staging server while developing jobs. U(https://letsencrypt.org/docs/staging-environment/)."
+    type: str
+    default: https://acme-v02.api.letsencrypt.org/directory
+"""
 
-    BACKEND_ASSERTONLY_DOCUMENTATION = r'''
+    BACKEND_ENTRUST_DOCUMENTATION = r"""
+options:
+  entrust_cert_type:
+    description:
+      - Specify the type of certificate requested.
+      - This is only used by the V(entrust) provider.
+    type: str
+    default: STANDARD_SSL
+    choices: [STANDARD_SSL, ADVANTAGE_SSL, UC_SSL, EV_SSL, WILDCARD_SSL, PRIVATE_SSL, PD_SSL, CDS_ENT_LITE, CDS_ENT_PRO, SMIME_ENT]
+
+  entrust_requester_email:
+    description:
+      - The email of the requester of the certificate (for tracking purposes).
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: str
+
+  entrust_requester_name:
+    description:
+      - The name of the requester of the certificate (for tracking purposes).
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: str
+
+  entrust_requester_phone:
+    description:
+      - The phone number of the requester of the certificate (for tracking purposes).
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: str
+
+  entrust_api_user:
+    description:
+      - The username for authentication to the Entrust Certificate Services (ECS) API.
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: str
+
+  entrust_api_key:
+    description:
+      - The key (password) for authentication to the Entrust Certificate Services (ECS) API.
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: str
+
+  entrust_api_client_cert_path:
+    description:
+      - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: path
+
+  entrust_api_client_cert_key_path:
+    description:
+      - The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
+      - This is only used by the V(entrust) provider.
+      - This is required if the provider is V(entrust).
+    type: path
+
+  entrust_not_after:
+    description:
+      - The point in time at which the certificate stops being valid.
+      - Time can be specified either as relative time or as an absolute timestamp.
+      - A valid absolute time format is C(ASN.1 TIME) such as V(2019-06-18).
+      - A valid relative time format is V([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as V(+365d) or V(+32w1d2h)).
+      - Time will always be interpreted as UTC.
+      - Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate.
+      - The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day
+        earlier than expected if a relative time is used.
+      - The minimum certificate lifetime is 90 days, and maximum is three years.
+      - If this value is not specified, the certificate will stop being valid 365 days the date of issue.
+      - This is only used by the V(entrust) provider.
+      - Please note that this value is B(not) covered by the O(ignore_timestamps) option.
+    type: str
+    default: +365d
+
+  entrust_api_specification_path:
+    description:
+      - The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
+      - You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
+      - This is only used by the V(entrust) provider.
+    type: path
+    default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
+"""
+
+    BACKEND_OWNCA_DOCUMENTATION = r"""
 description:
-    - The C(assertonly) provider is intended for use cases where one is only interested in
-      checking properties of a supplied certificate. Please note that this provider has been
-      deprecated in Ansible 2.9 and will be removed in community.crypto 2.0.0. See the examples on how
-      to emulate C(assertonly) usage with M(community.crypto.x509_certificate_info),
-      M(community.crypto.openssl_csr_info), M(community.crypto.openssl_privatekey_info) and
-      M(ansible.builtin.assert). This also allows more flexible checks than
-      the ones offered by the C(assertonly) provider.
-    - Many properties that can be specified in this module are for validation of an
-      existing or newly generated certificate. The proper place to specify them, if you
-      want to receive a certificate with these properties is a CSR (Certificate Signing Request).
+  - The V(ownca) provider is intended for generating an OpenSSL certificate signed with your own
+    CA (Certificate Authority) certificate (self-signed certificate).
 options:
-    csr_path:
-        description:
-            - This is not required for the C(assertonly) provider.
+  ownca_path:
+    description:
+      - Remote absolute path of the CA (Certificate Authority) certificate.
+      - This is only used by the V(ownca) provider.
+      - This is mutually exclusive with O(ownca_content).
+    type: path
+  ownca_content:
+    description:
+      - Content of the CA (Certificate Authority) certificate.
+      - This is only used by the V(ownca) provider.
+      - This is mutually exclusive with O(ownca_path).
+    type: str
 
-    csr_content:
-        description:
-            - This is not required for the C(assertonly) provider.
+  ownca_privatekey_path:
+    description:
+      - Path to the CA (Certificate Authority) private key to use when signing the certificate.
+      - This is only used by the V(ownca) provider.
+      - This is mutually exclusive with O(ownca_privatekey_content).
+    type: path
+  ownca_privatekey_content:
+    description:
+      - Content of the CA (Certificate Authority) private key to use when signing the certificate.
+      - This is only used by the V(ownca) provider.
+      - This is mutually exclusive with O(ownca_privatekey_path).
+    type: str
 
-    signature_algorithms:
-        description:
-            - A list of algorithms that you would accept the certificate to be signed with
-              (e.g. ['sha256WithRSAEncryption', 'sha512WithRSAEncryption']).
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: list
-        elements: str
+  ownca_privatekey_passphrase:
+    description:
+      - The passphrase for the O(ownca_privatekey_path) resp. O(ownca_privatekey_content).
+      - This is only used by the V(ownca) provider.
+    type: str
 
-    issuer:
-        description:
-            - The key/value pairs that must be present in the issuer name field of the certificate.
-            - If you need to specify more than one value with the same key, use a list as value.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: dict
+  ownca_digest:
+    description:
+      - The digest algorithm to be used for the V(ownca) certificate.
+      - This is only used by the V(ownca) provider.
+    type: str
+    default: sha256
 
-    issuer_strict:
-        description:
-            - If set to C(yes), the I(issuer) field must contain only these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: bool
-        default: no
+  ownca_version:
+    description:
+      - The version of the V(ownca) certificate.
+      - Nowadays it should almost always be V(3).
+      - This is only used by the V(ownca) provider.
+    type: int
+    default: 3
 
-    subject:
-        description:
-            - The key/value pairs that must be present in the subject name field of the certificate.
-            - If you need to specify more than one value with the same key, use a list as value.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: dict
+  ownca_not_before:
+    description:
+      - The point in time the certificate is valid from.
+      - Time can be specified either as relative time or as absolute timestamp.
+      - Time will always be interpreted as UTC.
+      - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+        + C([w | d | h | m | s]) (for example V(+32w1d2h)).
+      - If this value is not specified, the certificate will start being valid from now.
+      - Note that this value is B(not used to determine whether an existing certificate should be regenerated).
+        This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
+        avoid relative timestamps when setting O(ignore_timestamps=false).
+      - This is only used by the V(ownca) provider.
+    type: str
+    default: +0s
 
-    subject_strict:
-        description:
-            - If set to C(yes), the I(subject) field must contain only these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: bool
-        default: no
+  ownca_not_after:
+    description:
+      - The point in time at which the certificate stops being valid.
+      - Time can be specified either as relative time or as absolute timestamp.
+      - Time will always be interpreted as UTC.
+      - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+        + C([w | d | h | m | s]) (for example V(+32w1d2h)).
+      - If this value is not specified, the certificate will stop being valid 10 years from now.
+      - Note that this value is B(not used to determine whether an existing certificate should be regenerated).
+        This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
+        avoid relative timestamps when setting O(ignore_timestamps=false).
+      - This is only used by the V(ownca) provider.
+      - On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
+        Please see U(https://support.apple.com/en-us/HT210176) for more details.
+    type: str
+    default: +3650d
 
-    has_expired:
-        description:
-            - Checks if the certificate is expired/not expired at the time the module is executed.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: bool
-        default: no
+  ownca_create_subject_key_identifier:
+    description:
+      - Whether to create the Subject Key Identifier (SKI) from the public key.
+      - A value of V(create_if_not_provided) (default) only creates a SKI when the CSR does not
+        provide one.
+      - A value of V(always_create) always creates a SKI. If the CSR provides one, that one is
+        ignored.
+      - A value of V(never_create) never creates a SKI. If the CSR provides one, that one is used.
+      - This is only used by the V(ownca) provider.
+      - Note that this is only supported if the C(cryptography) backend is used!
+    type: str
+    choices: [create_if_not_provided, always_create, never_create]
+    default: create_if_not_provided
 
-    version:
-        description:
-            - The version of the certificate.
-            - Nowadays it should almost always be 3.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: int
+  ownca_create_authority_key_identifier:
+    description:
+      - Create a Authority Key Identifier from the CA's certificate. If the CSR provided
+        a authority key identifier, it is ignored.
+      - The Authority Key Identifier is generated from the CA certificate's Subject Key Identifier,
+        if available. If it is not available, the CA certificate's public key will be used.
+      - This is only used by the V(ownca) provider.
+      - Note that this is only supported if the C(cryptography) backend is used!
+    type: bool
+    default: true
+"""
 
-    valid_at:
-        description:
-            - The certificate must be valid at this point in time.
-            - The timestamp is formatted as an ASN.1 TIME.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: str
-
-    invalid_at:
-        description:
-            - The certificate must be invalid at this point in time.
-            - The timestamp is formatted as an ASN.1 TIME.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: str
-
-    not_before:
-        description:
-            - The certificate must start to become valid at this point in time.
-            - The timestamp is formatted as an ASN.1 TIME.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: str
-        aliases: [ notBefore ]
-
-    not_after:
-        description:
-            - The certificate must expire at this point in time.
-            - The timestamp is formatted as an ASN.1 TIME.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: str
-        aliases: [ notAfter ]
-
-    valid_in:
-        description:
-            - The certificate must still be valid at this relative time offset from now.
-            - Valid format is C([+-]timespec | number_of_seconds) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h).
-            - Note that if using this parameter, this module is NOT idempotent.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: str
-
-    key_usage:
-        description:
-            - The I(key_usage) extension field must contain all these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: list
-        elements: str
-        aliases: [ keyUsage ]
-
-    key_usage_strict:
-        description:
-            - If set to C(yes), the I(key_usage) extension field must contain only these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: bool
-        default: no
-        aliases: [ keyUsage_strict ]
-
-    extended_key_usage:
-        description:
-            - The I(extended_key_usage) extension field must contain all these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: list
-        elements: str
-        aliases: [ extendedKeyUsage ]
-
-    extended_key_usage_strict:
-        description:
-            - If set to C(yes), the I(extended_key_usage) extension field must contain only these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: bool
-        default: no
-        aliases: [ extendedKeyUsage_strict ]
-
-    subject_alt_name:
-        description:
-            - The I(subject_alt_name) extension field must contain these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: list
-        elements: str
-        aliases: [ subjectAltName ]
-
-    subject_alt_name_strict:
-        description:
-            - If set to C(yes), the I(subject_alt_name) extension field must contain only these values.
-            - This is only used by the C(assertonly) provider.
-            - This option is deprecated since Ansible 2.9 and will be removed with the C(assertonly) provider in community.crypto 2.0.0.
-              For alternatives, see the example on replacing C(assertonly).
-        type: bool
-        default: no
-        aliases: [ subjectAltName_strict ]
-'''
-
-    BACKEND_ENTRUST_DOCUMENTATION = r'''
-options:
-    entrust_cert_type:
-        description:
-            - Specify the type of certificate requested.
-            - This is only used by the C(entrust) provider.
-        type: str
-        default: STANDARD_SSL
-        choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT' ]
-
-    entrust_requester_email:
-        description:
-            - The email of the requester of the certificate (for tracking purposes).
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: str
-
-    entrust_requester_name:
-        description:
-            - The name of the requester of the certificate (for tracking purposes).
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: str
-
-    entrust_requester_phone:
-        description:
-            - The phone number of the requester of the certificate (for tracking purposes).
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: str
-
-    entrust_api_user:
-        description:
-            - The username for authentication to the Entrust Certificate Services (ECS) API.
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: str
-
-    entrust_api_key:
-        description:
-            - The key (password) for authentication to the Entrust Certificate Services (ECS) API.
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: str
-
-    entrust_api_client_cert_path:
-        description:
-            - The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: path
-
-    entrust_api_client_cert_key_path:
-        description:
-            - The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
-            - This is only used by the C(entrust) provider.
-            - This is required if the provider is C(entrust).
-        type: path
-
-    entrust_not_after:
-        description:
-            - The point in time at which the certificate stops being valid.
-            - Time can be specified either as relative time or as an absolute timestamp.
-            - A valid absolute time format is C(ASN.1 TIME) such as C(2019-06-18).
-            - A valid relative time format is C([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as C(+365d) or C(+32w1d2h)).
-            - Time will always be interpreted as UTC.
-            - Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate.
-            - The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day
-              earlier than expected if a relative time is used.
-            - The minimum certificate lifetime is 90 days, and maximum is three years.
-            - If this value is not specified, the certificate will stop being valid 365 days the date of issue.
-            - This is only used by the C(entrust) provider.
-        type: str
-        default: +365d
-
-    entrust_api_specification_path:
-        description:
-            - The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
-            - You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
-            - This is only used by the C(entrust) provider.
-        type: path
-        default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
-'''
-
-    BACKEND_OWNCA_DOCUMENTATION = r'''
-description:
-    - The C(ownca) provider is intended for generating an OpenSSL certificate signed with your own
-      CA (Certificate Authority) certificate (self-signed certificate).
-options:
-    ownca_path:
-        description:
-            - Remote absolute path of the CA (Certificate Authority) certificate.
-            - This is only used by the C(ownca) provider.
-            - This is mutually exclusive with I(ownca_content).
-        type: path
-    ownca_content:
-        description:
-            - Content of the CA (Certificate Authority) certificate.
-            - This is only used by the C(ownca) provider.
-            - This is mutually exclusive with I(ownca_path).
-        type: str
-
-    ownca_privatekey_path:
-        description:
-            - Path to the CA (Certificate Authority) private key to use when signing the certificate.
-            - This is only used by the C(ownca) provider.
-            - This is mutually exclusive with I(ownca_privatekey_content).
-        type: path
-    ownca_privatekey_content:
-        description:
-            - Content of the CA (Certificate Authority) private key to use when signing the certificate.
-            - This is only used by the C(ownca) provider.
-            - This is mutually exclusive with I(ownca_privatekey_path).
-        type: str
-
-    ownca_privatekey_passphrase:
-        description:
-            - The passphrase for the I(ownca_privatekey_path) resp. I(ownca_privatekey_content).
-            - This is only used by the C(ownca) provider.
-        type: str
-
-    ownca_digest:
-        description:
-            - The digest algorithm to be used for the C(ownca) certificate.
-            - This is only used by the C(ownca) provider.
-        type: str
-        default: sha256
-
-    ownca_version:
-        description:
-            - The version of the C(ownca) certificate.
-            - Nowadays it should almost always be C(3).
-            - This is only used by the C(ownca) provider.
-        type: int
-        default: 3
-
-    ownca_not_before:
-        description:
-            - The point in time the certificate is valid from.
-            - Time can be specified either as relative time or as absolute timestamp.
-            - Time will always be interpreted as UTC.
-            - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h).
-            - Note that if using relative time this module is NOT idempotent.
-            - If this value is not specified, the certificate will start being valid from now.
-            - This is only used by the C(ownca) provider.
-        type: str
-        default: +0s
-
-    ownca_not_after:
-        description:
-            - The point in time at which the certificate stops being valid.
-            - Time can be specified either as relative time or as absolute timestamp.
-            - Time will always be interpreted as UTC.
-            - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h).
-            - Note that if using relative time this module is NOT idempotent.
-            - If this value is not specified, the certificate will stop being valid 10 years from now.
-            - This is only used by the C(ownca) provider.
-            - On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
-              Please see U(https://support.apple.com/en-us/HT210176) for more details.
-        type: str
-        default: +3650d
-
-    ownca_create_subject_key_identifier:
-        description:
-            - Whether to create the Subject Key Identifier (SKI) from the public key.
-            - A value of C(create_if_not_provided) (default) only creates a SKI when the CSR does not
-              provide one.
-            - A value of C(always_create) always creates a SKI. If the CSR provides one, that one is
-              ignored.
-            - A value of C(never_create) never creates a SKI. If the CSR provides one, that one is used.
-            - This is only used by the C(ownca) provider.
-            - Note that this is only supported if the C(cryptography) backend is used!
-        type: str
-        choices: [create_if_not_provided, always_create, never_create]
-        default: create_if_not_provided
-
-    ownca_create_authority_key_identifier:
-        description:
-            - Create a Authority Key Identifier from the CA's certificate. If the CSR provided
-              a authority key identifier, it is ignored.
-            - The Authority Key Identifier is generated from the CA certificate's Subject Key Identifier,
-              if available. If it is not available, the CA certificate's public key will be used.
-            - This is only used by the C(ownca) provider.
-            - Note that this is only supported if the C(cryptography) backend is used!
-        type: bool
-        default: yes
-'''
-
-    BACKEND_SELFSIGNED_DOCUMENTATION = r'''
+    BACKEND_SELFSIGNED_DOCUMENTATION = r"""
 notes:
-    - For the C(selfsigned) provider, I(csr_path) and I(csr_content) are optional. If not provided, a
-      certificate without any information (Subject, Subject Alternative Names, Key Usage, etc.) is created.
+  - For the V(selfsigned) provider, O(csr_path) and O(csr_content) are optional. If not provided, a
+    certificate without any information (Subject, Subject Alternative Names, Key Usage, etc.) is created.
 
 options:
-    # NOTE: descriptions in options are overwritten, not appended. For that reason, the texts provided
-    #       here for csr_path and csr_content are not visible to the user. That's why this information is
-    #       added to the notes (see above).
+  # NOTE: descriptions in options are overwritten, not appended. For that reason, the texts provided
+  #       here for csr_path and csr_content are not visible to the user. That's why this information is
+  #       added to the notes (see above).
 
-    # csr_path:
-    #     description:
-    #         - This is optional for the C(selfsigned) provider. If not provided, a certificate
-    #           without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
-    #           created.
+  # csr_path:
+  #   description:
+  #     - This is optional for the V(selfsigned) provider. If not provided, a certificate
+  #       without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
+  #       created.
 
-    # csr_content:
-    #     description:
-    #         - This is optional for the C(selfsigned) provider. If not provided, a certificate
-    #           without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
-    #           created.
+  # csr_content:
+  #   description:
+  #     - This is optional for the V(selfsigned) provider. If not provided, a certificate
+  #       without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
+  #       created.
 
-    selfsigned_version:
-        description:
-            - Version of the C(selfsigned) certificate.
-            - Nowadays it should almost always be C(3).
-            - This is only used by the C(selfsigned) provider.
-        type: int
-        default: 3
+  selfsigned_version:
+    description:
+      - Version of the V(selfsigned) certificate.
+      - Nowadays it should almost always be V(3).
+      - This is only used by the V(selfsigned) provider.
+    type: int
+    default: 3
 
-    selfsigned_digest:
-        description:
-            - Digest algorithm to be used when self-signing the certificate.
-            - This is only used by the C(selfsigned) provider.
-        type: str
-        default: sha256
+  selfsigned_digest:
+    description:
+      - Digest algorithm to be used when self-signing the certificate.
+      - This is only used by the V(selfsigned) provider.
+    type: str
+    default: sha256
 
-    selfsigned_not_before:
-        description:
-            - The point in time the certificate is valid from.
-            - Time can be specified either as relative time or as absolute timestamp.
-            - Time will always be interpreted as UTC.
-            - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h).
-            - Note that if using relative time this module is NOT idempotent.
-            - If this value is not specified, the certificate will start being valid from now.
-            - This is only used by the C(selfsigned) provider.
-        type: str
-        default: +0s
-        aliases: [ selfsigned_notBefore ]
+  selfsigned_not_before:
+    description:
+      - The point in time the certificate is valid from.
+      - Time can be specified either as relative time or as absolute timestamp.
+      - Time will always be interpreted as UTC.
+      - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+        + C([w | d | h | m | s]) (for example V(+32w1d2h)).
+      - If this value is not specified, the certificate will start being valid from now.
+      - Note that this value is B(not used to determine whether an existing certificate should be regenerated).
+        This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
+        avoid relative timestamps when setting O(ignore_timestamps=false).
+      - This is only used by the V(selfsigned) provider.
+    type: str
+    default: +0s
+    aliases:
+      - selfsigned_notBefore
 
-    selfsigned_not_after:
-        description:
-            - The point in time at which the certificate stops being valid.
-            - Time can be specified either as relative time or as absolute timestamp.
-            - Time will always be interpreted as UTC.
-            - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
-              + C([w | d | h | m | s]) (e.g. C(+32w1d2h).
-            - Note that if using relative time this module is NOT idempotent.
-            - If this value is not specified, the certificate will stop being valid 10 years from now.
-            - This is only used by the C(selfsigned) provider.
-            - On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
-              Please see U(https://support.apple.com/en-us/HT210176) for more details.
-        type: str
-        default: +3650d
-        aliases: [ selfsigned_notAfter ]
+  selfsigned_not_after:
+    description:
+      - The point in time at which the certificate stops being valid.
+      - Time can be specified either as relative time or as absolute timestamp.
+      - Time will always be interpreted as UTC.
+      - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+        + C([w | d | h | m | s]) (for example V(+32w1d2h)).
+      - If this value is not specified, the certificate will stop being valid 10 years from now.
+      - Note that this value is B(not used to determine whether an existing certificate should be regenerated).
+        This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
+        avoid relative timestamps when setting O(ignore_timestamps=false).
+      - This is only used by the V(selfsigned) provider.
+      - On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
+        Please see U(https://support.apple.com/en-us/HT210176) for more details.
+    type: str
+    default: +3650d
+    aliases:
+      - selfsigned_notAfter
 
-    selfsigned_create_subject_key_identifier:
-        description:
-            - Whether to create the Subject Key Identifier (SKI) from the public key.
-            - A value of C(create_if_not_provided) (default) only creates a SKI when the CSR does not
-              provide one.
-            - A value of C(always_create) always creates a SKI. If the CSR provides one, that one is
-              ignored.
-            - A value of C(never_create) never creates a SKI. If the CSR provides one, that one is used.
-            - This is only used by the C(selfsigned) provider.
-            - Note that this is only supported if the C(cryptography) backend is used!
-        type: str
-        choices: [create_if_not_provided, always_create, never_create]
-        default: create_if_not_provided
-'''
+  selfsigned_create_subject_key_identifier:
+    description:
+      - Whether to create the Subject Key Identifier (SKI) from the public key.
+      - A value of V(create_if_not_provided) (default) only creates a SKI when the CSR does not
+        provide one.
+      - A value of V(always_create) always creates a SKI. If the CSR provides one, that one is
+        ignored.
+      - A value of V(never_create) never creates a SKI. If the CSR provides one, that one is used.
+      - This is only used by the V(selfsigned) provider.
+      - Note that this is only supported if the C(cryptography) backend is used!
+    type: str
+    choices: [create_if_not_provided, always_create, never_create]
+    default: create_if_not_provided
+"""

plugins/doc_fragments/module_csr.py

@@ -1,318 +1,350 @@
 # -*- coding: utf-8 -*-
 
-# Copyrigt: (c) 2017, Yanis Guenane <yanis+ansible@guenane.org>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2017, Yanis Guenane <yanis+ansible@guenane.org>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 description:
-    - This module allows one to (re)generate OpenSSL certificate signing requests.
-    - This module supports the subjectAltName, keyUsage, extendedKeyUsage, basicConstraints and OCSP Must Staple
-      extensions.
-    - "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 community.crypto 2.0.0."
+  - This module allows one to (re)generate OpenSSL certificate signing requests.
+  - This module supports the subjectAltName, keyUsage, extendedKeyUsage, basicConstraints and OCSP Must Staple extensions.
+attributes:
+  diff_mode:
+    support: full
+  idempotent:
+    support: full
 requirements:
-    - Either cryptography >= 1.3
-    - Or pyOpenSSL >= 0.15
+  - cryptography >= 1.3
 options:
-    digest:
+  digest:
+    description:
+      - The digest used when signing the certificate signing request with the private key.
+    type: str
+    default: sha256
+  privatekey_path:
+    description:
+      - The path to the private key to use when signing the certificate signing request.
+      - Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
+    type: path
+  privatekey_content:
+    description:
+      - The content of the private key to use when signing the certificate signing request.
+      - Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
+    type: str
+  privatekey_passphrase:
+    description:
+      - The passphrase for the private key.
+      - This is required if the private key is password protected.
+    type: str
+  version:
+    description:
+      - The version of the certificate signing request.
+      - The only allowed value according to L(RFC 2986,https://tools.ietf.org/html/rfc2986#section-4.1) is 1.
+      - This option no longer accepts unsupported values since community.crypto 2.0.0.
+    type: int
+    default: 1
+    choices:
+      - 1
+  subject:
+    description:
+      - Key/value pairs that will be present in the subject name field of the certificate signing request.
+      - If you need to specify more than one value with the same key, use a list as value.
+      - If the order of the components is important, use O(subject_ordered).
+      - Mutually exclusive with O(subject_ordered).
+    type: dict
+  subject_ordered:
+    description:
+      - A list of dictionaries, where every dictionary must contain one key/value pair. This key/value pair will be present
+        in the subject name field of the certificate signing request.
+      - If you want to specify more than one value with the same key in a row, you can use a list as value.
+      - Mutually exclusive with O(subject), and any other subject field option, such as O(country_name), O(state_or_province_name),
+        O(locality_name), O(organization_name), O(organizational_unit_name), O(common_name), or O(email_address).
+    type: list
+    elements: dict
+    version_added: 2.0.0
+  country_name:
+    description:
+      - The countryName field of the certificate signing request subject.
+    type: str
+    aliases:
+      - C
+      - countryName
+  state_or_province_name:
+    description:
+      - The stateOrProvinceName field of the certificate signing request subject.
+    type: str
+    aliases:
+      - ST
+      - stateOrProvinceName
+  locality_name:
+    description:
+      - The localityName field of the certificate signing request subject.
+    type: str
+    aliases:
+      - L
+      - localityName
+  organization_name:
+    description:
+      - The organizationName field of the certificate signing request subject.
+    type: str
+    aliases:
+      - O
+      - organizationName
+  organizational_unit_name:
+    description:
+      - The organizationalUnitName field of the certificate signing request subject.
+    type: str
+    aliases:
+      - OU
+      - organizationalUnitName
+  common_name:
+    description:
+      - The commonName field of the certificate signing request subject.
+    type: str
+    aliases:
+      - CN
+      - commonName
+  email_address:
+    description:
+      - The emailAddress field of the certificate signing request subject.
+    type: str
+    aliases:
+      - E
+      - emailAddress
+  subject_alt_name:
+    description:
+      - Subject Alternative Name (SAN) extension to attach to the certificate signing request.
+      - Values must be prefixed by their options. (These are C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), C(otherName),
+        and the ones specific to your CA).
+      - Note that if no SAN is specified, but a common name, the common name will be added as a SAN except if O(use_common_name_for_san)
+        is set to V(false).
+      - More at U(https://tools.ietf.org/html/rfc5280#section-4.2.1.6).
+    type: list
+    elements: str
+    aliases:
+      - subjectAltName
+  subject_alt_name_critical:
+    description:
+      - Should the subjectAltName extension be considered as critical.
+    type: bool
+    default: false
+    aliases:
+      - subjectAltName_critical
+  use_common_name_for_san:
+    description:
+      - If set to V(true), the module will fill the common name in for O(subject_alt_name) with C(DNS:) prefix if no SAN is
+        specified.
+    type: bool
+    default: true
+    aliases:
+      - useCommonNameForSAN
+  key_usage:
+    description:
+      - This defines the purpose (for example encipherment, signature, certificate signing) of the key contained in the certificate.
+    type: list
+    elements: str
+    aliases:
+      - keyUsage
+  key_usage_critical:
+    description:
+      - Should the keyUsage extension be considered as critical.
+    type: bool
+    default: false
+    aliases:
+      - keyUsage_critical
+  extended_key_usage:
+    description:
+      - Additional restrictions (for example client authentication, server authentication) on the allowed purposes for which
+        the public key may be used.
+    type: list
+    elements: str
+    aliases:
+      - extKeyUsage
+      - extendedKeyUsage
+  extended_key_usage_critical:
+    description:
+      - Should the extkeyUsage extension be considered as critical.
+    type: bool
+    default: false
+    aliases:
+      - extKeyUsage_critical
+      - extendedKeyUsage_critical
+  basic_constraints:
+    description:
+      - Indicates basic constraints, such as if the certificate is a CA.
+    type: list
+    elements: str
+    aliases:
+      - basicConstraints
+  basic_constraints_critical:
+    description:
+      - Should the basicConstraints extension be considered as critical.
+    type: bool
+    default: false
+    aliases:
+      - basicConstraints_critical
+  ocsp_must_staple:
+    description:
+      - Indicates that the certificate should contain the OCSP Must Staple extension (U(https://tools.ietf.org/html/rfc7633)).
+    type: bool
+    default: false
+    aliases:
+      - ocspMustStaple
+  ocsp_must_staple_critical:
+    description:
+      - Should the OCSP Must Staple extension be considered as critical.
+      - Note that according to the RFC, this extension should not be marked as critical, as old clients not knowing about
+        OCSP Must Staple are required to reject such certificates (see U(https://tools.ietf.org/html/rfc7633#section-4)).
+    type: bool
+    default: false
+    aliases:
+      - ocspMustStaple_critical
+  name_constraints_permitted:
+    description:
+      - For CA certificates, this specifies a list of identifiers which describe subtrees of names that this CA is allowed
+        to issue certificates for.
+      - Values must be prefixed by their options. (That is, C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), C(otherName),
+        and the ones specific to your CA).
+    type: list
+    elements: str
+  name_constraints_excluded:
+    description:
+      - For CA certificates, this specifies a list of identifiers which describe subtrees of names that this CA is B(not)
+        allowed to issue certificates for.
+      - Values must be prefixed by their options. (That is, C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), C(otherName),
+        and the ones specific to your CA).
+    type: list
+    elements: str
+  name_constraints_critical:
+    description:
+      - Should the Name Constraints extension be considered as critical.
+    type: bool
+    default: false
+  select_crypto_backend:
+    description:
+      - Determines which crypto backend to use.
+      - The default choice is V(auto), which tries to use C(cryptography) if available.
+      - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+    type: str
+    default: auto
+    choices: [auto, cryptography]
+  create_subject_key_identifier:
+    description:
+      - Create the Subject Key Identifier from the public key.
+      - Please note that commercial CAs can ignore the value, respectively use a value of their own choice instead. Specifying
+        this option is mostly useful for self-signed certificates or for own CAs.
+      - Note that this is only supported if the C(cryptography) backend is used!
+    type: bool
+    default: false
+  subject_key_identifier:
+    description:
+      - The subject key identifier as a hex string, where two bytes are separated by colons.
+      - 'Example: V(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33).'
+      - Please note that commercial CAs ignore this value, respectively use a value of their own choice. Specifying this option
+        is mostly useful for self-signed certificates or for own CAs.
+      - Note that this option can only be used if O(create_subject_key_identifier) is V(false).
+      - Note that this is only supported if the C(cryptography) backend is used!
+    type: str
+  authority_key_identifier:
+    description:
+      - The authority key identifier as a hex string, where two bytes are separated by colons.
+      - 'Example: V(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33).'
+      - Please note that commercial CAs ignore this value, respectively use a value of their own choice. Specifying this option
+        is mostly useful for self-signed certificates or for own CAs.
+      - Note that this is only supported if the C(cryptography) backend is used!
+      - The C(AuthorityKeyIdentifier) extension will only be added if at least one of O(authority_key_identifier), O(authority_cert_issuer)
+        and O(authority_cert_serial_number) is specified.
+    type: str
+  authority_cert_issuer:
+    description:
+      - Names that will be present in the authority cert issuer field of the certificate signing request.
+      - Values must be prefixed by their options. (That is, C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), C(otherName),
+        and the ones specific to your CA).
+      - 'Example: V(DNS:ca.example.org).'
+      - If specified, O(authority_cert_serial_number) must also be specified.
+      - Please note that commercial CAs ignore this value, respectively use a value of their own choice. Specifying this option
+        is mostly useful for self-signed certificates or for own CAs.
+      - Note that this is only supported if the C(cryptography) backend is used!
+      - The C(AuthorityKeyIdentifier) extension will only be added if at least one of O(authority_key_identifier), O(authority_cert_issuer)
+        and O(authority_cert_serial_number) is specified.
+    type: list
+    elements: str
+  authority_cert_serial_number:
+    description:
+      - The authority cert serial number.
+      - If specified, O(authority_cert_issuer) must also be specified.
+      - Note that this is only supported if the C(cryptography) backend is used!
+      - Please note that commercial CAs ignore this value, respectively use a value of their own choice. Specifying this option
+        is mostly useful for self-signed certificates or for own CAs.
+      - The C(AuthorityKeyIdentifier) extension will only be added if at least one of O(authority_key_identifier), O(authority_cert_issuer)
+        and O(authority_cert_serial_number) is specified.
+      - This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings, such as C(11:22:33),
+        you need to convert them to an integer with P(community.crypto.parse_serial#filter).
+    type: int
+  crl_distribution_points:
+    description:
+      - Allows to specify one or multiple CRL distribution points.
+      - Only supported by the C(cryptography) backend.
+    type: list
+    elements: dict
+    suboptions:
+      full_name:
         description:
-            - The digest used when signing the certificate signing request with the private key.
-        type: str
-        default: sha256
-    privatekey_path:
-        description:
-            - The path to the private key to use when signing the certificate signing request.
-            - Either I(privatekey_path) or I(privatekey_content) must be specified if I(state) is C(present), but not both.
-        type: path
-    privatekey_content:
-        description:
-            - The content of the private key to use when signing the certificate signing request.
-            - Either I(privatekey_path) or I(privatekey_content) must be specified if I(state) is C(present), but not both.
-        type: str
-    privatekey_passphrase:
-        description:
-            - The passphrase for the private key.
-            - This is required if the private key is password protected.
-        type: str
-    version:
-        description:
-            - The version of the certificate signing request.
-            - "The only allowed value according to L(RFC 2986,https://tools.ietf.org/html/rfc2986#section-4.1)
-               is 1."
-            - This option will no longer accept unsupported values from community.crypto 2.0.0 on.
-        type: int
-        default: 1
-    subject:
-        description:
-            - Key/value pairs that will be present in the subject name field of the certificate signing request.
-            - If you need to specify more than one value with the same key, use a list as value.
-        type: dict
-    country_name:
-        description:
-            - The countryName field of the certificate signing request subject.
-        type: str
-        aliases: [ C, countryName ]
-    state_or_province_name:
-        description:
-            - The stateOrProvinceName field of the certificate signing request subject.
-        type: str
-        aliases: [ ST, stateOrProvinceName ]
-    locality_name:
-        description:
-            - The localityName field of the certificate signing request subject.
-        type: str
-        aliases: [ L, localityName ]
-    organization_name:
-        description:
-            - The organizationName field of the certificate signing request subject.
-        type: str
-        aliases: [ O, organizationName ]
-    organizational_unit_name:
-        description:
-            - The organizationalUnitName field of the certificate signing request subject.
-        type: str
-        aliases: [ OU, organizationalUnitName ]
-    common_name:
-        description:
-            - The commonName field of the certificate signing request subject.
-        type: str
-        aliases: [ CN, commonName ]
-    email_address:
-        description:
-            - The emailAddress field of the certificate signing request subject.
-        type: str
-        aliases: [ E, emailAddress ]
-    subject_alt_name:
-        description:
-            - Subject Alternative Name (SAN) extension to attach to the certificate signing request.
-            - This can either be a 'comma separated string' or a YAML list.
-            - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
-              C(otherName) and the ones specific to your CA).
-            - Note that if no SAN is specified, but a common name, the common
-              name will be added as a SAN except if C(useCommonNameForSAN) is
-              set to I(false).
-            - More at U(https://tools.ietf.org/html/rfc5280#section-4.2.1.6).
+          - Describes how the CRL can be retrieved.
+          - Mutually exclusive with O(crl_distribution_points[].relative_name).
+          - 'Example: V(URI:https://ca.example.com/revocations.crl).'
         type: list
         elements: str
-        aliases: [ subjectAltName ]
-    subject_alt_name_critical:
+      relative_name:
         description:
-            - Should the subjectAltName extension be considered as critical.
-        type: bool
-        default: false
-        aliases: [ subjectAltName_critical ]
-    use_common_name_for_san:
-        description:
-            - If set to C(yes), the module will fill the common name in for
-              C(subject_alt_name) with C(DNS:) prefix if no SAN is specified.
-        type: bool
-        default: yes
-        aliases: [ useCommonNameForSAN ]
-    key_usage:
-        description:
-            - This defines the purpose (e.g. encipherment, signature, certificate signing)
-              of the key contained in the certificate.
+          - Describes how the CRL can be retrieved relative to the CRL issuer.
+          - Mutually exclusive with O(crl_distribution_points[].full_name).
+          - 'Example: V(/CN=example.com).'
+          - Can only be used when cryptography >= 1.6 is installed.
         type: list
         elements: str
-        aliases: [ keyUsage ]
-    key_usage_critical:
+      crl_issuer:
         description:
-            - Should the keyUsage extension be considered as critical.
-        type: bool
-        default: false
-        aliases: [ keyUsage_critical ]
-    extended_key_usage:
-        description:
-            - Additional restrictions (e.g. client authentication, server authentication)
-              on the allowed purposes for which the public key may be used.
+          - Information about the issuer of the CRL.
         type: list
         elements: str
-        aliases: [ extKeyUsage, extendedKeyUsage ]
-    extended_key_usage_critical:
+      reasons:
         description:
-            - Should the extkeyUsage extension be considered as critical.
-        type: bool
-        default: false
-        aliases: [ extKeyUsage_critical, extendedKeyUsage_critical ]
-    basic_constraints:
-        description:
-            - Indicates basic constraints, such as if the certificate is a CA.
+          - List of reasons that this distribution point can be used for when performing revocation checks.
         type: list
         elements: str
-        aliases: [ basicConstraints ]
-    basic_constraints_critical:
-        description:
-            - Should the basicConstraints extension be considered as critical.
-        type: bool
-        default: false
-        aliases: [ basicConstraints_critical ]
-    ocsp_must_staple:
-        description:
-            - Indicates that the certificate should contain the OCSP Must Staple
-              extension (U(https://tools.ietf.org/html/rfc7633)).
-        type: bool
-        default: false
-        aliases: [ ocspMustStaple ]
-    ocsp_must_staple_critical:
-        description:
-            - Should the OCSP Must Staple extension be considered as critical.
-            - Note that according to the RFC, this extension should not be marked
-              as critical, as old clients not knowing about OCSP Must Staple
-              are required to reject such certificates
-              (see U(https://tools.ietf.org/html/rfc7633#section-4)).
-        type: bool
-        default: false
-        aliases: [ ocspMustStaple_critical ]
-    name_constraints_permitted:
-        description:
-            - For CA certificates, this specifies a list of identifiers which describe
-              subtrees of names that this CA is allowed to issue certificates for.
-            - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
-              C(otherName) and the ones specific to your CA).
-        type: list
-        elements: str
-    name_constraints_excluded:
-        description:
-            - For CA certificates, this specifies a list of identifiers which describe
-              subtrees of names that this CA is B(not) allowed to issue certificates for.
-            - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
-              C(otherName) and the ones specific to your CA).
-        type: list
-        elements: str
-    name_constraints_critical:
-        description:
-            - Should the Name Constraints extension be considered as critical.
-        type: bool
-        default: false
-    select_crypto_backend:
-        description:
-            - Determines which crypto backend to use.
-            - 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 community.crypto 2.0.0.
-              From that point on, only the C(cryptography) backend will be available.
-        type: str
-        default: auto
-        choices: [ auto, cryptography, pyopenssl ]
-    create_subject_key_identifier:
-        description:
-            - Create the Subject Key Identifier from the public key.
-            - "Please note that commercial CAs can ignore the value, respectively use a value of
-               their own choice instead. Specifying this option is mostly useful for self-signed
-               certificates or for own CAs."
-            - Note that this is only supported if the C(cryptography) backend is used!
-        type: bool
-        default: no
-    subject_key_identifier:
-        description:
-            - The subject key identifier as a hex string, where two bytes are separated by colons.
-            - "Example: C(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33)"
-            - "Please note that commercial CAs ignore this value, respectively use a value of their
-               own choice. Specifying this option is mostly useful for self-signed certificates
-               or for own CAs."
-            - Note that this option can only be used if I(create_subject_key_identifier) is C(no).
-            - Note that this is only supported if the C(cryptography) backend is used!
-        type: str
-    authority_key_identifier:
-        description:
-            - The authority key identifier as a hex string, where two bytes are separated by colons.
-            - "Example: C(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33)"
-            - "Please note that commercial CAs ignore this value, respectively use a value of their
-               own choice. Specifying this option is mostly useful for self-signed certificates
-               or for own CAs."
-            - Note that this is only supported if the C(cryptography) backend is used!
-            - The C(AuthorityKeyIdentifier) extension will only be added if at least one of I(authority_key_identifier),
-              I(authority_cert_issuer) and I(authority_cert_serial_number) is specified.
-        type: str
-    authority_cert_issuer:
-        description:
-            - Names that will be present in the authority cert issuer field of the certificate signing request.
-            - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
-              C(otherName) and the ones specific to your CA)
-            - "Example: C(DNS:ca.example.org)"
-            - If specified, I(authority_cert_serial_number) must also be specified.
-            - "Please note that commercial CAs ignore this value, respectively use a value of their
-               own choice. Specifying this option is mostly useful for self-signed certificates
-               or for own CAs."
-            - Note that this is only supported if the C(cryptography) backend is used!
-            - The C(AuthorityKeyIdentifier) extension will only be added if at least one of I(authority_key_identifier),
-              I(authority_cert_issuer) and I(authority_cert_serial_number) is specified.
-        type: list
-        elements: str
-    authority_cert_serial_number:
-        description:
-            - The authority cert serial number.
-            - If specified, I(authority_cert_issuer) must also be specified.
-            - Note that this is only supported if the C(cryptography) backend is used!
-            - "Please note that commercial CAs ignore this value, respectively use a value of their
-               own choice. Specifying this option is mostly useful for self-signed certificates
-               or for own CAs."
-            - The C(AuthorityKeyIdentifier) extension will only be added if at least one of I(authority_key_identifier),
-              I(authority_cert_issuer) and I(authority_cert_serial_number) is specified.
-        type: int
-    crl_distribution_points:
-        description:
-            - Allows to specify one or multiple CRL distribution points.
-            - Only supported by the C(cryptography) backend.
-        type: list
-        elements: dict
-        suboptions:
-            full_name:
-                description:
-                    - Describes how the CRL can be retrieved.
-                    - Mutually exclusive with I(relative_name).
-                    - "Example: C(URI:https://ca.example.com/revocations.crl)."
-                type: list
-                elements: str
-            relative_name:
-                description:
-                    - Describes how the CRL can be retrieved relative to the CRL issuer.
-                    - Mutually exclusive with I(full_name).
-                    - "Example: C(/CN=example.com)."
-                    - Can only be used when cryptography >= 1.6 is installed.
-                type: list
-                elements: str
-            crl_issuer:
-                description:
-                    - Information about the issuer of the CRL.
-                type: list
-                elements: str
-            reasons:
-                description:
-                    - List of reasons that this distribution point can be used for when performing revocation checks.
-                type: list
-                elements: str
-                choices:
-                    - key_compromise
-                    - ca_compromise
-                    - affiliation_changed
-                    - superseded
-                    - cessation_of_operation
-                    - certificate_hold
-                    - privilege_withdrawn
-                    - aa_compromise
-        version_added: 1.4.0
+        choices:
+          - key_compromise
+          - ca_compromise
+          - affiliation_changed
+          - superseded
+          - cessation_of_operation
+          - certificate_hold
+          - privilege_withdrawn
+          - aa_compromise
+    version_added: 1.4.0
 notes:
-    - If the certificate signing request already exists it will be checked whether subjectAltName,
-      keyUsage, extendedKeyUsage and basicConstraints only contain the requested values, whether
-      OCSP Must Staple is as requested, and if the request was signed by the given private key.
+  - If the certificate signing request already exists it will be checked whether subjectAltName, keyUsage, extendedKeyUsage
+    and basicConstraints only contain the requested values, whether OCSP Must Staple is as requested, and if the request was
+    signed by the given private key.
 seealso:
-- module: community.crypto.x509_certificate
-- module: community.crypto.x509_certificate_pipe
-- module: community.crypto.openssl_dhparam
-- module: community.crypto.openssl_pkcs12
-- module: community.crypto.openssl_privatekey
-- module: community.crypto.openssl_privatekey_pipe
-- module: community.crypto.openssl_publickey
-- module: community.crypto.openssl_csr_info
-'''
+  - module: community.crypto.x509_certificate
+  - module: community.crypto.x509_certificate_pipe
+  - module: community.crypto.openssl_dhparam
+  - module: community.crypto.openssl_pkcs12
+  - module: community.crypto.openssl_privatekey
+  - module: community.crypto.openssl_privatekey_pipe
+  - module: community.crypto.openssl_publickey
+  - module: community.crypto.openssl_csr_info
+  - plugin: community.crypto.parse_serial
+    plugin_type: filter
+"""

plugins/doc_fragments/module_privatekey.py

@@ -1,163 +1,149 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016, Yanis Guenane <yanis+ansible@guenane.org>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016, Yanis Guenane <yanis+ansible@guenane.org>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
-    DOCUMENTATION = r'''
+    DOCUMENTATION = r"""
 description:
-    - One can generate L(RSA,https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29),
-      L(DSA,https://en.wikipedia.org/wiki/Digital_Signature_Algorithm),
-      L(ECC,https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) or
-      L(EdDSA,https://en.wikipedia.org/wiki/EdDSA) private keys.
-    - Keys are generated in PEM format.
-    - "Please note that the module regenerates private keys if they don't match
-      the module's options. In particular, if you provide another passphrase
-      (or specify none), change the keysize, etc., the private key will be
-      regenerated. If you are concerned that this could B(overwrite your private key),
-      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 community.crypto 2.0.0."
+  - One can generate L(RSA,https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29), L(DSA,https://en.wikipedia.org/wiki/Digital_Signature_Algorithm),
+    L(ECC,https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) or L(EdDSA,https://en.wikipedia.org/wiki/EdDSA) private
+    keys.
+  - Keys are generated in PEM format.
+attributes:
+  diff_mode:
+    support: full
+  idempotent:
+    support: partial
+    details:
+      - The option O(regenerate=always) generally disables idempotency.
 requirements:
-    - Either cryptography >= 1.2.3 (older versions might work as well)
-    - Or pyOpenSSL
+  - cryptography >= 1.2.3 (older versions might work as well)
 options:
-    size:
-        description:
-            - Size (in bits) of the TLS/SSL key to generate.
-        type: int
-        default: 4096
-    type:
-        description:
-            - The algorithm used to generate the TLS/SSL private key.
-            - Note that C(ECC), C(X25519), C(X448), C(Ed25519) and C(Ed448) require the C(cryptography) backend.
-              C(X25519) needs cryptography 2.5 or newer, while C(X448), C(Ed25519) and C(Ed448) require
-              cryptography 2.6 or newer. For C(ECC), the minimal cryptography version required depends on the
-              I(curve) option.
-        type: str
-        default: RSA
-        choices: [ DSA, ECC, Ed25519, Ed448, RSA, X25519, X448 ]
-    curve:
-        description:
-            - Note that not all curves are supported by all versions of C(cryptography).
-            - For maximal interoperability, C(secp384r1) or C(secp256r1) should be used.
-            - We use the curve names as defined in the
-              L(IANA registry for TLS,https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8).
-            - Please note that all curves except C(secp224r1), C(secp256k1), C(secp256r1), C(secp384r1) and C(secp521r1)
-              are discouraged for new private keys.
-        type: str
-        choices:
-            - secp224r1
-            - secp256k1
-            - secp256r1
-            - secp384r1
-            - secp521r1
-            - secp192r1
-            - brainpoolP256r1
-            - brainpoolP384r1
-            - brainpoolP512r1
-            - sect163k1
-            - sect163r2
-            - sect233k1
-            - sect233r1
-            - sect283k1
-            - sect283r1
-            - sect409k1
-            - sect409r1
-            - sect571k1
-            - sect571r1
-    passphrase:
-        description:
-            - The passphrase for the private key.
-        type: str
-    cipher:
-        description:
-            - The cipher to encrypt the private key. (Valid values can be found by
-              running `openssl list -cipher-algorithms` or `openssl list-cipher-algorithms`,
-              depending on your OpenSSL version.)
-            - When using the C(cryptography) backend, use C(auto).
-        type: str
-    select_crypto_backend:
-        description:
-            - Determines which crypto backend to use.
-            - 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 community.crypto 2.0.0.
-              From that point on, only the C(cryptography) backend will be available.
-        type: str
-        default: auto
-        choices: [ auto, cryptography, pyopenssl ]
-    format:
-        description:
-            - Determines which format the private key is written in. By default, PKCS1 (traditional OpenSSL format)
-              is used for all keys which support it. Please note that not every key can be exported in any format.
-            - The value C(auto) selects a fromat based on the key format. The value C(auto_ignore) does the same,
-              but for existing private key files, it will not force a regenerate when its format is not the automatically
-              selected one for generation.
-            - Note that if the format for an existing private key mismatches, the key is B(regenerated) by default.
-              To change this behavior, use the I(format_mismatch) option.
-            - The I(format) option is only supported by the C(cryptography) backend. The C(pyopenssl) backend will
-              fail if a value different from C(auto_ignore) is used.
-        type: str
-        default: auto_ignore
-        choices: [ pkcs1, pkcs8, raw, auto, auto_ignore ]
-    format_mismatch:
-        description:
-            - Determines behavior of the module if the format of a private key does not match the expected format, but all
-              other parameters are as expected.
-            - If set to C(regenerate) (default), generates a new private key.
-            - If set to C(convert), the key will be converted to the new format instead.
-            - Only supported by the C(cryptography) backend.
-        type: str
-        default: regenerate
-        choices: [ regenerate, convert ]
-    regenerate:
-        description:
-            - Allows to configure in which situations the module is allowed to regenerate private keys.
-              The module will always generate a new key if the destination file does not exist.
-            - By default, the key will be regenerated when it doesn't match the module's options,
-              except when the key cannot be read or the passphrase does not match. Please note that
-              this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if C(full_idempotence)
-              is specified.
-            - If set to C(never), the module will fail if the key cannot be read or the passphrase
-              isn't matching, and will never regenerate an existing key.
-            - If set to C(fail), the module will fail if the key does not correspond to the module's
-              options.
-            - If set to C(partial_idempotence), the key will be regenerated if it does not conform to
-              the module's options. The key is B(not) regenerated if it cannot be read (broken file),
-              the key is protected by an unknown passphrase, or when they key is not protected by a
-              passphrase, but a passphrase is specified.
-            - If set to C(full_idempotence), the key will be regenerated if it does not conform to the
-              module's options. This is also the case if the key cannot be read (broken file), the key
-              is protected by an unknown passphrase, or when they key is not protected by a passphrase,
-              but a passphrase is specified. Make sure you have a B(backup) when using this option!
-            - If set to C(always), the module will always regenerate the key. This is equivalent to
-              setting I(force) to C(yes).
-            - Note that if I(format_mismatch) is set to C(convert) and everything matches except the
-              format, the key will always be converted, except if I(regenerate) is set to C(always).
-        type: str
-        choices:
-            - never
-            - fail
-            - partial_idempotence
-            - full_idempotence
-            - always
-        default: full_idempotence
+  size:
+    description:
+      - Size (in bits) of the TLS/SSL key to generate.
+    type: int
+    default: 4096
+  type:
+    description:
+      - The algorithm used to generate the TLS/SSL private key.
+      - Note that V(ECC), V(X25519), V(X448), V(Ed25519), and V(Ed448) require the C(cryptography) backend. V(X25519) needs
+        cryptography 2.5 or newer, while V(X448), V(Ed25519), and V(Ed448) require cryptography 2.6 or newer. For V(ECC),
+        the minimal cryptography version required depends on the O(curve) option.
+    type: str
+    default: RSA
+    choices: [DSA, ECC, Ed25519, Ed448, RSA, X25519, X448]
+  curve:
+    description:
+      - Note that not all curves are supported by all versions of C(cryptography).
+      - For maximal interoperability, V(secp384r1) or V(secp256r1) should be used.
+      - We use the curve names as defined in the L(IANA registry for TLS,https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8).
+      - Please note that all curves except V(secp224r1), V(secp256k1), V(secp256r1), V(secp384r1), and V(secp521r1) are discouraged
+        for new private keys.
+    type: str
+    choices:
+      - secp224r1
+      - secp256k1
+      - secp256r1
+      - secp384r1
+      - secp521r1
+      - secp192r1
+      - brainpoolP256r1
+      - brainpoolP384r1
+      - brainpoolP512r1
+      - sect163k1
+      - sect163r2
+      - sect233k1
+      - sect233r1
+      - sect283k1
+      - sect283r1
+      - sect409k1
+      - sect409r1
+      - sect571k1
+      - sect571r1
+  passphrase:
+    description:
+      - The passphrase for the private key.
+    type: str
+  cipher:
+    description:
+      - The cipher to encrypt the private key. This is only used when O(passphrase) is provided.
+      - Must be V(auto).
+    type: str
+    default: auto
+  select_crypto_backend:
+    description:
+      - Determines which crypto backend to use.
+      - The default choice is V(auto), which tries to use C(cryptography) if available.
+      - If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
+    type: str
+    default: auto
+    choices: [auto, cryptography]
+  format:
+    description:
+      - Determines which format the private key is written in. By default, PKCS1 (traditional OpenSSL format) is used for
+        all keys which support it. Please note that not every key can be exported in any format.
+      - The value V(auto) selects a format based on the key format. The value V(auto_ignore) does the same, but for existing
+        private key files, it will not force a regenerate when its format is not the automatically selected one for generation.
+      - Note that if the format for an existing private key mismatches, the key is B(regenerated) by default. To change this
+        behavior, use the O(format_mismatch) option.
+    type: str
+    default: auto_ignore
+    choices: [pkcs1, pkcs8, raw, auto, auto_ignore]
+  format_mismatch:
+    description:
+      - Determines behavior of the module if the format of a private key does not match the expected format, but all other
+        parameters are as expected.
+      - If set to V(regenerate) (default), generates a new private key.
+      - If set to V(convert), the key will be converted to the new format instead.
+      - Only supported by the C(cryptography) backend.
+    type: str
+    default: regenerate
+    choices: [regenerate, convert]
+  regenerate:
+    description:
+      - Allows to configure in which situations the module is allowed to regenerate private keys. The module will always generate
+        a new key if the destination file does not exist.
+      - By default, the key will be regenerated when it does not match the module's options, except when the key cannot be
+        read or the passphrase does not match. Please note that this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior
+        was as if V(full_idempotence) is specified.
+      - If set to V(never), the module will fail if the key cannot be read or the passphrase is not matching, and will never
+        regenerate an existing key.
+      - If set to V(fail), the module will fail if the key does not correspond to the module's options.
+      - If set to V(partial_idempotence), the key will be regenerated if it does not conform to the module's options. The
+        key is B(not) regenerated if it cannot be read (broken file), the key is protected by an unknown passphrase, or when
+        they key is not protected by a passphrase, but a passphrase is specified.
+      - If set to V(full_idempotence), the key will be regenerated if it does not conform to the module's options. This is
+        also the case if the key cannot be read (broken file), the key is protected by an unknown passphrase, or when they
+        key is not protected by a passphrase, but a passphrase is specified. Make sure you have a B(backup) when using this
+        option!
+      - If set to V(always), the module will always regenerate the key. This is equivalent to setting O(force) to V(true).
+      - Note that if O(format_mismatch) is set to V(convert) and everything matches except the format, the key will always
+        be converted, except if O(regenerate) is set to V(always).
+    type: str
+    choices:
+      - never
+      - fail
+      - partial_idempotence
+      - full_idempotence
+      - always
+    default: full_idempotence
 seealso:
-- module: community.crypto.x509_certificate
-- module: community.crypto.x509_certificate_pipe
-- module: community.crypto.openssl_csr
-- module: community.crypto.openssl_csr_pipe
-- module: community.crypto.openssl_dhparam
-- module: community.crypto.openssl_pkcs12
-- module: community.crypto.openssl_publickey
-'''
+  - module: community.crypto.x509_certificate
+  - module: community.crypto.x509_certificate_pipe
+  - module: community.crypto.openssl_csr
+  - module: community.crypto.openssl_csr_pipe
+  - module: community.crypto.openssl_dhparam
+  - module: community.crypto.openssl_pkcs12
+  - module: community.crypto.openssl_publickey
+"""

plugins/doc_fragments/module_privatekey_convert.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    # Standard files documentation fragment
+    DOCUMENTATION = r"""
+requirements:
+  - cryptography >= 1.2.3 (older versions might work as well)
+attributes:
+  diff_mode:
+    support: none
+  idempotent:
+    support: full
+options:
+  src_path:
+    description:
+      - Name of the file containing the OpenSSL private key to convert.
+      - Exactly one of O(src_path) or O(src_content) must be specified.
+    type: path
+  src_content:
+    description:
+      - The content of the file containing the OpenSSL private key to convert.
+      - Exactly one of O(src_path) or O(src_content) must be specified.
+    type: str
+  src_passphrase:
+    description:
+      - The passphrase for the private key to load.
+    type: str
+  dest_passphrase:
+    description:
+      - The passphrase for the private key to store.
+    type: str
+  format:
+    description:
+      - Determines which format the destination private key should be written in.
+      - Please note that not every key can be exported in any format, and that not every format supports encryption.
+    type: str
+    choices: [pkcs1, pkcs8, raw]
+    required: true
+seealso:
+  - module: community.crypto.openssl_privatekey
+  - module: community.crypto.openssl_privatekey_pipe
+  - module: community.crypto.openssl_publickey
+"""

plugins/doc_fragments/name_encoding.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+    DOCUMENTATION = r"""
+options:
+  name_encoding:
+    description:
+      - How to encode names (DNS names, URIs, email addresses) in return values.
+      - V(ignore) will use the encoding returned by the backend.
+      - V(idna) will convert all labels of domain names to IDNA encoding. IDNA2008 will be preferred, and IDNA2003 will be
+        used if IDNA2008 encoding fails.
+      - V(unicode) will convert all labels of domain names to Unicode. IDNA2008 will be preferred, and IDNA2003 will be used
+        if IDNA2008 decoding fails.
+      - B(Note) that V(idna) and V(unicode) require the L(idna Python library,https://pypi.org/project/idna/) to be installed.
+    type: str
+    default: ignore
+    choices:
+      - ignore
+      - idna
+      - unicode
+requirements:
+  - If O(name_encoding) is set to another value than V(ignore), the L(idna Python library,https://pypi.org/project/idna/)
+    needs to be installed.
+"""

plugins/filter/gpg_fingerprint.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2023, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: gpg_fingerprint
+short_description: Retrieve a GPG fingerprint from a GPG public or private key
+author: Felix Fontein (@felixfontein)
+version_added: 2.15.0
+description:
+  - Takes the content of a private or public GPG key as input and returns its fingerprint.
+options:
+  _input:
+    description:
+      - The content of a GPG public or private key.
+    type: string
+    required: true
+requirements:
+  - GnuPG (C(gpg) executable)
+seealso:
+  - plugin: community.crypto.gpg_fingerprint
+    plugin_type: lookup
+"""
+
+EXAMPLES = r"""
+---
+- name: Show fingerprint of GPG public key
+  ansible.builtin.debug:
+    msg: "{{ lookup('file', '/path/to/public_key.gpg') | community.crypto.gpg_fingerprint }}"
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - The fingerprint of the provided public or private GPG key.
+  type: string
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.gnupg.cli import (
+    GPGError,
+    get_fingerprint_from_bytes,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.gnupg import (
+    PluginGPGRunner,
+)
+
+
+def gpg_fingerprint(input):
+    if not isinstance(input, string_types):
+        raise AnsibleFilterError(
+            "The input for the community.crypto.gpg_fingerprint filter must be a string; got {type} instead".format(
+                type=type(input)
+            )
+        )
+    try:
+        gpg = PluginGPGRunner()
+        return get_fingerprint_from_bytes(gpg, to_bytes(input))
+    except GPGError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "gpg_fingerprint": gpg_fingerprint,
+        }

plugins/filter/openssl_csr_info.py

@@ -0,0 +1,329 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: openssl_csr_info
+short_description: Retrieve information from OpenSSL Certificate Signing Requests (CSR)
+version_added: 2.10.0
+author:
+  - Felix Fontein (@felixfontein)
+description:
+  - Provided an OpenSSL Certificate Signing Requests (CSR), retrieve information.
+  - This is a filter version of the M(community.crypto.openssl_csr_info) module.
+options:
+  _input:
+    description:
+      - The content of the OpenSSL CSR.
+    type: string
+    required: true
+extends_documentation_fragment:
+  - community.crypto.name_encoding
+seealso:
+  - module: community.crypto.openssl_csr_info
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
+
+EXAMPLES = r"""
+---
+- name: Show the Subject Alt Names of the CSR
+  ansible.builtin.debug:
+    msg: >-
+      {{
+        (
+          lookup('ansible.builtin.file', '/path/to/cert.csr')
+          | community.crypto.openssl_csr_info
+        ).subject_alt_name | join(', ')
+      }}
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - Information on the certificate.
+  type: dict
+  contains:
+    signature_valid:
+      description:
+        - Whether the CSR's signature is valid.
+        - In case the check returns V(false), the module will fail.
+      returned: success
+      type: bool
+    basic_constraints:
+      description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
+      returned: success
+      type: list
+      elements: str
+      sample: ['CA:TRUE', 'pathlen:1']
+    basic_constraints_critical:
+      description: Whether the C(basic_constraints) extension is critical.
+      returned: success
+      type: bool
+    extended_key_usage:
+      description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
+      returned: success
+      type: list
+      elements: str
+      sample: [Biometric Info, DVCS, Time Stamping]
+    extended_key_usage_critical:
+      description: Whether the C(extended_key_usage) extension is critical.
+      returned: success
+      type: bool
+    extensions_by_oid:
+      description: Returns a dictionary for every extension OID.
+      returned: success
+      type: dict
+      contains:
+        critical:
+          description: Whether the extension is critical.
+          returned: success
+          type: bool
+        value:
+          description:
+            - The Base64 encoded value (in DER format) of the extension.
+            - B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content
+              of the extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
+              This should usually result in exactly the same value, except if the original extension value was malformed.
+          returned: success
+          type: str
+          sample: "MAMCAQU="
+      sample: {"1.3.6.1.5.5.7.1.24": {"critical": false, "value": "MAMCAQU="}}
+    key_usage:
+      description: Entries in the C(key_usage) extension, or V(none) if extension is not present.
+      returned: success
+      type: str
+      sample: [Key Agreement, Data Encipherment]
+    key_usage_critical:
+      description: Whether the C(key_usage) extension is critical.
+      returned: success
+      type: bool
+    subject_alt_name:
+      description:
+        - Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
+        - See O(name_encoding) for how IDNs are handled.
+      returned: success
+      type: list
+      elements: str
+      sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
+    subject_alt_name_critical:
+      description: Whether the C(subject_alt_name) extension is critical.
+      returned: success
+      type: bool
+    ocsp_must_staple:
+      description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
+      returned: success
+      type: bool
+    ocsp_must_staple_critical:
+      description: Whether the C(ocsp_must_staple) extension is critical.
+      returned: success
+      type: bool
+    name_constraints_permitted:
+      description: List of permitted subtrees to sign certificates for.
+      returned: success
+      type: list
+      elements: str
+      sample: ['email:.somedomain.com']
+    name_constraints_excluded:
+      description:
+        - List of excluded subtrees the CA cannot sign certificates for.
+        - Is V(none) if extension is not present.
+        - See O(name_encoding) for how IDNs are handled.
+      returned: success
+      type: list
+      elements: str
+      sample: ['email:.com']
+    name_constraints_critical:
+      description:
+        - Whether the C(name_constraints) extension is critical.
+        - Is V(none) if extension is not present.
+      returned: success
+      type: bool
+    subject:
+      description:
+        - The CSR's subject as a dictionary.
+        - Note that for repeated values, only the last one will be returned.
+      returned: success
+      type: dict
+      sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
+    subject_ordered:
+      description: The CSR's subject as an ordered list of tuples.
+      returned: success
+      type: list
+      elements: list
+      sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
+    public_key:
+      description: CSR's public key in PEM format.
+      returned: success
+      type: str
+      sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
+    public_key_type:
+      description:
+        - The CSR's public key's type.
+        - One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
+        - Will start with C(unknown) if the key type cannot be determined.
+      returned: success
+      type: str
+      sample: RSA
+    public_key_data:
+      description:
+        - Public key data. Depends on the public key's type.
+      returned: success
+      type: dict
+      contains:
+        size:
+          description:
+            - Bit size of modulus (RSA) or prime number (DSA).
+          type: int
+          returned: When RV(_value.public_key_type=RSA) or RV(_value.public_key_type=DSA)
+        modulus:
+          description:
+            - The RSA key's modulus.
+          type: int
+          returned: When RV(_value.public_key_type=RSA)
+        exponent:
+          description:
+            - The RSA key's public exponent.
+          type: int
+          returned: When RV(_value.public_key_type=RSA)
+        p:
+          description:
+            - The C(p) value for DSA.
+            - This is the prime modulus upon which arithmetic takes place.
+          type: int
+          returned: When RV(_value.public_key_type=DSA)
+        q:
+          description:
+            - The C(q) value for DSA.
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
+              group of the prime field used.
+          type: int
+          returned: When RV(_value.public_key_type=DSA)
+        g:
+          description:
+            - The C(g) value for DSA.
+            - This is the element spanning the subgroup of the multiplicative group of the prime field used.
+          type: int
+          returned: When RV(_value.public_key_type=DSA)
+        curve:
+          description:
+            - The curve's name for ECC.
+          type: str
+          returned: When RV(_value.public_key_type=ECC)
+        exponent_size:
+          description:
+            - The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
+          type: int
+          returned: When RV(_value.public_key_type=ECC)
+        x:
+          description:
+            - The C(x) coordinate for the public point on the elliptic curve.
+          type: int
+          returned: When RV(_value.public_key_type=ECC)
+        y:
+          description:
+            - For RV(_value.public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
+            - For RV(_value.public_key_type=DSA), this is the publicly known group element whose discrete logarithm with respect
+              to C(g) is the private key.
+          type: int
+          returned: When RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
+    public_key_fingerprints:
+      description:
+        - Fingerprints of CSR's public key.
+        - For every hash algorithm available, the fingerprint is computed.
+      returned: success
+      type: dict
+      sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
+        'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
+    subject_key_identifier:
+      description:
+        - The CSR's subject key identifier.
+        - The identifier is returned in hexadecimal, with V(:) used to separate bytes.
+        - Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
+      returned: success
+      type: str
+      sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
+    authority_key_identifier:
+      description:
+        - The CSR's authority key identifier.
+        - The identifier is returned in hexadecimal, with V(:) used to separate bytes.
+        - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+      returned: success
+      type: str
+      sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
+    authority_cert_issuer:
+      description:
+        - The CSR's authority cert issuer as a list of general names.
+        - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+        - See O(name_encoding) for how IDNs are handled.
+      returned: success
+      type: list
+      elements: str
+      sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
+    authority_cert_serial_number:
+      description:
+        - The CSR's authority cert serial number.
+        - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
+          you need to convert it to that form with P(community.crypto.to_serial#filter).
+      returned: success
+      type: int
+      sample: 12345
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.csr_info import (
+    get_csr_info,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import (
+    FilterModuleMock,
+)
+
+
+def openssl_csr_info_filter(data, name_encoding="ignore"):
+    """Extract information from X.509 PEM certificate."""
+    if not isinstance(data, string_types):
+        raise AnsibleFilterError(
+            "The community.crypto.openssl_csr_info input must be a text type, not %s"
+            % type(data)
+        )
+    if not isinstance(name_encoding, string_types):
+        raise AnsibleFilterError(
+            "The name_encoding option must be of a text type, not %s"
+            % type(name_encoding)
+        )
+    name_encoding = to_native(name_encoding)
+    if name_encoding not in ("ignore", "idna", "unicode"):
+        raise AnsibleFilterError(
+            'The name_encoding option must be one of the values "ignore", "idna", or "unicode", not "%s"'
+            % name_encoding
+        )
+
+    module = FilterModuleMock({"name_encoding": name_encoding})
+    try:
+        return get_csr_info(
+            module, "cryptography", content=to_bytes(data), validate_signature=True
+        )
+    except OpenSSLObjectError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "openssl_csr_info": openssl_csr_info_filter,
+        }

plugins/filter/openssl_privatekey_info.py

@@ -0,0 +1,211 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: openssl_privatekey_info
+short_description: Retrieve information from OpenSSL private keys
+version_added: 2.10.0
+author:
+  - Felix Fontein (@felixfontein)
+description:
+  - Provided an OpenSSL private keys, retrieve information.
+  - This is a filter version of the M(community.crypto.openssl_privatekey_info) module.
+options:
+  _input:
+    description:
+      - The content of the OpenSSL private key.
+    type: string
+    required: true
+  passphrase:
+    description:
+      - The passphrase for the private key.
+    type: str
+  return_private_key_data:
+    description:
+      - Whether to return private key data.
+      - Only set this to V(true) when you want private information about this key to be extracted.
+      - B(WARNING:) you have to make sure that private key data is not accidentally logged!
+    type: bool
+    default: false
+extends_documentation_fragment:
+  - community.crypto.name_encoding
+seealso:
+  - module: community.crypto.openssl_privatekey_info
+"""
+
+EXAMPLES = r"""
+---
+- name: Show the Subject Alt Names of the CSR
+  ansible.builtin.debug:
+    msg: >-
+      {{
+        (
+          lookup('ansible.builtin.file', '/path/to/cert.csr')
+          | community.crypto.openssl_privatekey_info
+        ).subject_alt_name | join(', ')
+      }}
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - Information on the certificate.
+  type: dict
+  contains:
+    public_key:
+      description: Private key's public key in PEM format.
+      returned: success
+      type: str
+      sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
+    public_key_fingerprints:
+      description:
+        - Fingerprints of private key's public key.
+        - For every hash algorithm available, the fingerprint is computed.
+      returned: success
+      type: dict
+      sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
+        'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
+    type:
+      description:
+        - The key's type.
+        - One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
+        - Will start with V(unknown) if the key type cannot be determined.
+      returned: success
+      type: str
+      sample: RSA
+    public_data:
+      description:
+        - Public key data. Depends on key type.
+      returned: success
+      type: dict
+      contains:
+        size:
+          description:
+            - Bit size of modulus (RSA) or prime number (DSA).
+          type: int
+          returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
+        modulus:
+          description:
+            - The RSA key's modulus.
+          type: int
+          returned: When RV(_value.type=RSA)
+        exponent:
+          description:
+            - The RSA key's public exponent.
+          type: int
+          returned: When RV(_value.type=RSA)
+        p:
+          description:
+            - The C(p) value for DSA.
+            - This is the prime modulus upon which arithmetic takes place.
+          type: int
+          returned: When RV(_value.type=DSA)
+        q:
+          description:
+            - The C(q) value for DSA.
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
+              group of the prime field used.
+          type: int
+          returned: When RV(_value.type=DSA)
+        g:
+          description:
+            - The C(g) value for DSA.
+            - This is the element spanning the subgroup of the multiplicative group of the prime field used.
+          type: int
+          returned: When RV(_value.type=DSA)
+        curve:
+          description:
+            - The curve's name for ECC.
+          type: str
+          returned: When RV(_value.type=ECC)
+        exponent_size:
+          description:
+            - The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
+          type: int
+          returned: When RV(_value.type=ECC)
+        x:
+          description:
+            - The C(x) coordinate for the public point on the elliptic curve.
+          type: int
+          returned: When RV(_value.type=ECC)
+        y:
+          description:
+            - For RV(_value.type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
+            - For RV(_value.type=DSA), this is the publicly known group element whose discrete logarithm with respect to C(g)
+              is the private key.
+          type: int
+          returned: When RV(_value.type=DSA) or RV(_value.type=ECC)
+    private_data:
+      description:
+        - Private key data. Depends on key type.
+      returned: success and when O(return_private_key_data) is set to V(true)
+      type: dict
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.privatekey_info import (
+    PrivateKeyParseError,
+    get_privatekey_info,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import (
+    FilterModuleMock,
+)
+
+
+def openssl_privatekey_info_filter(
+    data, passphrase=None, return_private_key_data=False
+):
+    """Extract information from X.509 PEM certificate."""
+    if not isinstance(data, string_types):
+        raise AnsibleFilterError(
+            "The community.crypto.openssl_privatekey_info input must be a text type, not %s"
+            % type(data)
+        )
+    if passphrase is not None and not isinstance(passphrase, string_types):
+        raise AnsibleFilterError(
+            "The passphrase option must be a text type, not %s" % type(passphrase)
+        )
+    if not isinstance(return_private_key_data, bool):
+        raise AnsibleFilterError(
+            "The return_private_key_data option must be a boolean, not %s"
+            % type(return_private_key_data)
+        )
+
+    module = FilterModuleMock({})
+    try:
+        result = get_privatekey_info(
+            module,
+            "cryptography",
+            content=to_bytes(data),
+            passphrase=passphrase,
+            return_private_key_data=return_private_key_data,
+        )
+        result.pop("can_parse_key", None)
+        result.pop("key_is_consistent", None)
+        return result
+    except PrivateKeyParseError as exc:
+        raise AnsibleFilterError(exc.error_message)
+    except OpenSSLObjectError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "openssl_privatekey_info": openssl_privatekey_info_filter,
+        }

plugins/filter/openssl_publickey_info.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: openssl_publickey_info
+short_description: Retrieve information from OpenSSL public keys in PEM format
+version_added: 2.10.0
+author:
+  - Felix Fontein (@felixfontein)
+description:
+  - Provided a public key in OpenSSL PEM format, retrieve information.
+  - This is a filter version of the M(community.crypto.openssl_publickey_info) module.
+options:
+  _input:
+    description:
+      - The content of the OpenSSL PEM public key.
+    type: string
+    required: true
+seealso:
+  - module: community.crypto.openssl_publickey_info
+"""
+
+EXAMPLES = r"""
+---
+- name: Show the type of a public key
+  ansible.builtin.debug:
+    msg: >-
+      {{
+        (
+          lookup('ansible.builtin.file', '/path/to/public-key.pem')
+          | community.crypto.openssl_publickey_info
+        ).type
+      }}
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - Information on the public key.
+  type: dict
+  contains:
+    fingerprints:
+      description:
+        - Fingerprints of public key.
+        - For every hash algorithm available, the fingerprint is computed.
+      returned: success
+      type: dict
+      sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
+        'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
+    type:
+      description:
+        - The key's type.
+        - One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
+        - Will start with V(unknown) if the key type cannot be determined.
+      returned: success
+      type: str
+      sample: RSA
+    public_data:
+      description:
+        - Public key data. Depends on key type.
+      returned: success
+      type: dict
+      contains:
+        size:
+          description:
+            - Bit size of modulus (RSA) or prime number (DSA).
+          type: int
+          returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
+        modulus:
+          description:
+            - The RSA key's modulus.
+          type: int
+          returned: When RV(_value.type=RSA)
+        exponent:
+          description:
+            - The RSA key's public exponent.
+          type: int
+          returned: When RV(_value.type=RSA)
+        p:
+          description:
+            - The C(p) value for DSA.
+            - This is the prime modulus upon which arithmetic takes place.
+          type: int
+          returned: When RV(_value.type=DSA)
+        q:
+          description:
+            - The C(q) value for DSA.
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
+              group of the prime field used.
+          type: int
+          returned: When RV(_value.type=DSA)
+        g:
+          description:
+            - The C(g) value for DSA.
+            - This is the element spanning the subgroup of the multiplicative group of the prime field used.
+          type: int
+          returned: When RV(_value.type=DSA)
+        curve:
+          description:
+            - The curve's name for ECC.
+          type: str
+          returned: When RV(_value.type=ECC)
+        exponent_size:
+          description:
+            - The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
+          type: int
+          returned: When RV(_value.type=ECC)
+        x:
+          description:
+            - The C(x) coordinate for the public point on the elliptic curve.
+          type: int
+          returned: When RV(_value.type=ECC)
+        y:
+          description:
+            - For RV(_value.type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
+            - For RV(_value.type=DSA), this is the publicly known group element whose discrete logarithm with respect to C(g)
+              is the private key.
+          type: int
+          returned: When RV(_value.type=DSA) or RV(_value.type=ECC)
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.publickey_info import (
+    PublicKeyParseError,
+    get_publickey_info,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import (
+    FilterModuleMock,
+)
+
+
+def openssl_publickey_info_filter(data):
+    """Extract information from OpenSSL PEM public key."""
+    if not isinstance(data, string_types):
+        raise AnsibleFilterError(
+            "The community.crypto.openssl_publickey_info input must be a text type, not %s"
+            % type(data)
+        )
+
+    module = FilterModuleMock({})
+    try:
+        return get_publickey_info(module, "cryptography", content=to_bytes(data))
+    except PublicKeyParseError as exc:
+        raise AnsibleFilterError(exc.error_message)
+    except OpenSSLObjectError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "openssl_publickey_info": openssl_publickey_info_filter,
+        }

plugins/filter/parse_serial.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: parse_serial
+short_description: Convert a serial number as a colon-separated list of hex numbers to an integer
+author: Felix Fontein (@felixfontein)
+version_added: 2.18.0
+description:
+  - Parses a colon-separated list of hex numbers of the form C(00:11:22:33) and returns the corresponding integer.
+options:
+  _input:
+    description:
+      - A serial number represented as a colon-separated list of hex numbers between 0 and 255.
+      - These numbers are interpreted as the byte presentation of an unsigned integer in network byte order. That is, C(01:00)
+        is interpreted as the integer 256.
+    type: string
+    required: true
+seealso:
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
+
+EXAMPLES = r"""
+---
+- name: Parse serial number
+  ansible.builtin.debug:
+    msg: "{{ '11:22:33' | community.crypto.parse_serial }}"
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - The serial number as an integer.
+  type: int
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.serial import (
+    parse_serial,
+)
+
+
+def parse_serial_filter(input):
+    if not isinstance(input, string_types):
+        raise AnsibleFilterError(
+            "The input for the community.crypto.parse_serial filter must be a string; got {type} instead".format(
+                type=type(input)
+            )
+        )
+    try:
+        return parse_serial(to_native(input))
+    except ValueError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "parse_serial": parse_serial_filter,
+        }

plugins/filter/split_pem.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: split_pem
+short_description: Split PEM file contents into multiple objects
+version_added: 2.10.0
+author:
+  - Felix Fontein (@felixfontein)
+description:
+  - Split PEM file contents into multiple PEM objects. Comments or invalid parts are ignored.
+options:
+  _input:
+    description:
+      - The PEM contents to split.
+    type: string
+    required: true
+"""
+
+EXAMPLES = r"""
+---
+- name: Print all CA certificates
+  ansible.builtin.debug:
+    msg: '{{ item }}'
+  loop: >-
+    {{ lookup('ansible.builtin.file', '/path/to/ca-bundle.pem') | community.crypto.split_pem }}
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - A list of PEM file contents.
+  type: list
+  elements: string
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_text
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import (
+    split_pem_list,
+)
+
+
+def split_pem_filter(data):
+    """Split PEM file."""
+    if not isinstance(data, string_types):
+        raise AnsibleFilterError(
+            "The community.crypto.split_pem input must be a text type, not %s"
+            % type(data)
+        )
+
+    data = to_text(data)
+    return split_pem_list(data)
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "split_pem": split_pem_filter,
+        }

plugins/filter/to_serial.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: to_serial
+short_description: Convert an integer to a colon-separated list of hex numbers
+author: Felix Fontein (@felixfontein)
+version_added: 2.18.0
+description:
+  - Converts an integer to a colon-separated list of hex numbers of the form C(00:11:22:33).
+options:
+  _input:
+    description:
+      - The non-negative integer to convert.
+    type: int
+    required: true
+seealso:
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
+
+EXAMPLES = r"""
+---
+- name: Convert integer to serial number
+  ansible.builtin.debug:
+    msg: "{{ 1234567 | community.crypto.to_serial }}"
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - A colon-separated list of hexadecimal numbers.
+    - Letters are upper-case, and all numbers have exactly two digits.
+    - The string is never empty. The representation of C(0) is C("00").
+  type: string
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_native
+from ansible.module_utils.six import integer_types
+from ansible_collections.community.crypto.plugins.module_utils.serial import to_serial
+
+
+def to_serial_filter(input):
+    if not isinstance(input, integer_types):
+        raise AnsibleFilterError(
+            "The input for the community.crypto.to_serial filter must be an integer; got {type} instead".format(
+                type=type(input)
+            )
+        )
+    if input < 0:
+        raise AnsibleFilterError(
+            "The input for the community.crypto.to_serial filter must not be negative"
+        )
+    try:
+        return to_serial(input)
+    except ValueError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "to_serial": to_serial_filter,
+        }

plugins/filter/x509_certificate_info.py

@@ -0,0 +1,361 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: x509_certificate_info
+short_description: Retrieve information from X.509 certificates in PEM format
+version_added: 2.10.0
+author:
+  - Felix Fontein (@felixfontein)
+description:
+  - Provided a X.509 certificate in PEM format, retrieve information.
+  - This is a filter version of the M(community.crypto.x509_certificate_info) module.
+options:
+  _input:
+    description:
+      - The content of the X.509 certificate in PEM format.
+    type: string
+    required: true
+extends_documentation_fragment:
+  - community.crypto.name_encoding
+seealso:
+  - module: community.crypto.x509_certificate_info
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
+
+EXAMPLES = r"""
+---
+- name: Show the Subject Alt Names of the certificate
+  ansible.builtin.debug:
+    msg: >-
+      {{
+        (
+          lookup('ansible.builtin.file', '/path/to/cert.pem')
+          | community.crypto.x509_certificate_info
+        ).subject_alt_name | join(', ')
+      }}
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - Information on the certificate.
+  type: dict
+  contains:
+    expired:
+      description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
+      returned: success
+      type: bool
+    basic_constraints:
+      description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
+      returned: success
+      type: list
+      elements: str
+      sample: ["CA:TRUE", "pathlen:1"]
+    basic_constraints_critical:
+      description: Whether the C(basic_constraints) extension is critical.
+      returned: success
+      type: bool
+    extended_key_usage:
+      description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
+      returned: success
+      type: list
+      elements: str
+      sample: [Biometric Info, DVCS, Time Stamping]
+    extended_key_usage_critical:
+      description: Whether the C(extended_key_usage) extension is critical.
+      returned: success
+      type: bool
+    extensions_by_oid:
+      description: Returns a dictionary for every extension OID.
+      returned: success
+      type: dict
+      contains:
+        critical:
+          description: Whether the extension is critical.
+          returned: success
+          type: bool
+        value:
+          description:
+            - The Base64 encoded value (in DER format) of the extension.
+            - B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content
+              of the extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
+              This should usually result in exactly the same value, except if the original extension value was malformed.
+          returned: success
+          type: str
+          sample: "MAMCAQU="
+      sample: {"1.3.6.1.5.5.7.1.24": {"critical": false, "value": "MAMCAQU="}}
+    key_usage:
+      description: Entries in the C(key_usage) extension, or V(none) if extension is not present.
+      returned: success
+      type: str
+      sample: [Key Agreement, Data Encipherment]
+    key_usage_critical:
+      description: Whether the C(key_usage) extension is critical.
+      returned: success
+      type: bool
+    subject_alt_name:
+      description:
+        - Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
+        - See O(name_encoding) for how IDNs are handled.
+      returned: success
+      type: list
+      elements: str
+      sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
+    subject_alt_name_critical:
+      description: Whether the C(subject_alt_name) extension is critical.
+      returned: success
+      type: bool
+    ocsp_must_staple:
+      description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
+      returned: success
+      type: bool
+    ocsp_must_staple_critical:
+      description: Whether the C(ocsp_must_staple) extension is critical.
+      returned: success
+      type: bool
+    issuer:
+      description:
+        - The certificate's issuer.
+        - Note that for repeated values, only the last one will be returned.
+      returned: success
+      type: dict
+      sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
+    issuer_ordered:
+      description: The certificate's issuer as an ordered list of tuples.
+      returned: success
+      type: list
+      elements: list
+      sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
+    subject:
+      description:
+        - The certificate's subject as a dictionary.
+        - Note that for repeated values, only the last one will be returned.
+      returned: success
+      type: dict
+      sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
+    subject_ordered:
+      description: The certificate's subject as an ordered list of tuples.
+      returned: success
+      type: list
+      elements: list
+      sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
+    not_after:
+      description: C(notAfter) date as ASN.1 TIME.
+      returned: success
+      type: str
+      sample: '20190413202428Z'
+    not_before:
+      description: C(notBefore) date as ASN.1 TIME.
+      returned: success
+      type: str
+      sample: '20190331202428Z'
+    public_key:
+      description: Certificate's public key in PEM format.
+      returned: success
+      type: str
+      sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
+    public_key_type:
+      description:
+        - The certificate's public key's type.
+        - One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
+        - Will start with V(unknown) if the key type cannot be determined.
+      returned: success
+      type: str
+      sample: RSA
+    public_key_data:
+      description:
+        - Public key data. Depends on the public key's type.
+      returned: success
+      type: dict
+      contains:
+        size:
+          description:
+            - Bit size of modulus (RSA) or prime number (DSA).
+          type: int
+          returned: When RV(_value.public_key_type=RSA) or RV(_value.public_key_type=DSA)
+        modulus:
+          description:
+            - The RSA key's modulus.
+          type: int
+          returned: When RV(_value.public_key_type=RSA)
+        exponent:
+          description:
+            - The RSA key's public exponent.
+          type: int
+          returned: When RV(_value.public_key_type=RSA)
+        p:
+          description:
+            - The C(p) value for DSA.
+            - This is the prime modulus upon which arithmetic takes place.
+          type: int
+          returned: When RV(_value.public_key_type=DSA)
+        q:
+          description:
+            - The C(q) value for DSA.
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
+              group of the prime field used.
+          type: int
+          returned: When RV(_value.public_key_type=DSA)
+        g:
+          description:
+            - The C(g) value for DSA.
+            - This is the element spanning the subgroup of the multiplicative group of the prime field used.
+          type: int
+          returned: When RV(_value.public_key_type=DSA)
+        curve:
+          description:
+            - The curve's name for ECC.
+          type: str
+          returned: When RV(_value.public_key_type=ECC)
+        exponent_size:
+          description:
+            - The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
+          type: int
+          returned: When RV(_value.public_key_type=ECC)
+        x:
+          description:
+            - The C(x) coordinate for the public point on the elliptic curve.
+          type: int
+          returned: When RV(_value.public_key_type=ECC)
+        y:
+          description:
+            - For RV(_value.public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
+            - For RV(_value.public_key_type=DSA), this is the publicly known group element whose discrete logarithm with respect
+              to C(g) is the private key.
+          type: int
+          returned: When RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
+    public_key_fingerprints:
+      description:
+        - Fingerprints of certificate's public key.
+        - For every hash algorithm available, the fingerprint is computed.
+      returned: success
+      type: dict
+      sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
+        'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
+    fingerprints:
+      description:
+        - Fingerprints of the DER-encoded form of the whole certificate.
+        - For every hash algorithm available, the fingerprint is computed.
+      returned: success
+      type: dict
+      sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
+        'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
+    signature_algorithm:
+      description: The signature algorithm used to sign the certificate.
+      returned: success
+      type: str
+      sample: sha256WithRSAEncryption
+    serial_number:
+      description:
+        - The certificate's serial number.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
+          you need to convert it to that form with P(community.crypto.to_serial#filter).
+      returned: success
+      type: int
+      sample: 1234
+    version:
+      description: The certificate version.
+      returned: success
+      type: int
+      sample: 3
+    subject_key_identifier:
+      description:
+        - The certificate's subject key identifier.
+        - The identifier is returned in hexadecimal, with V(:) used to separate bytes.
+        - Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
+      returned: success
+      type: str
+      sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
+    authority_key_identifier:
+      description:
+        - The certificate's authority key identifier.
+        - The identifier is returned in hexadecimal, with V(:) used to separate bytes.
+        - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+      returned: success
+      type: str
+      sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
+    authority_cert_issuer:
+      description:
+        - The certificate's authority cert issuer as a list of general names.
+        - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+        - See O(name_encoding) for how IDNs are handled.
+      returned: success
+      type: list
+      elements: str
+      sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
+    authority_cert_serial_number:
+      description:
+        - The certificate's authority cert serial number.
+        - Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
+        - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
+          you need to convert it to that form with P(community.crypto.to_serial#filter).
+      returned: success
+      type: int
+      sample: 12345
+    ocsp_uri:
+      description: The OCSP responder URI, if included in the certificate. Will be V(none) if no OCSP responder URI is included.
+      returned: success
+      type: str
+    issuer_uri:
+      description: The Issuer URI, if included in the certificate. Will be V(none) if no issuer URI is included.
+      returned: success
+      type: str
+"""
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate_info import (
+    get_certificate_info,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import (
+    FilterModuleMock,
+)
+
+
+def x509_certificate_info_filter(data, name_encoding="ignore"):
+    """Extract information from X.509 PEM certificate."""
+    if not isinstance(data, string_types):
+        raise AnsibleFilterError(
+            "The community.crypto.x509_certificate_info input must be a text type, not %s"
+            % type(data)
+        )
+    if not isinstance(name_encoding, string_types):
+        raise AnsibleFilterError(
+            "The name_encoding option must be of a text type, not %s"
+            % type(name_encoding)
+        )
+    name_encoding = to_native(name_encoding)
+    if name_encoding not in ("ignore", "idna", "unicode"):
+        raise AnsibleFilterError(
+            'The name_encoding option must be one of the values "ignore", "idna", or "unicode", not "%s"'
+            % name_encoding
+        )
+
+    module = FilterModuleMock({"name_encoding": name_encoding})
+    try:
+        return get_certificate_info(module, "cryptography", content=to_bytes(data))
+    except OpenSSLObjectError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "x509_certificate_info": x509_certificate_info_filter,
+        }

plugins/filter/x509_crl_info.py

@@ -0,0 +1,226 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2022, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: x509_crl_info
+short_description: Retrieve information from X.509 CRLs in PEM format
+version_added: 2.10.0
+author:
+  - Felix Fontein (@felixfontein)
+description:
+  - Provided a X.509 crl in PEM format, retrieve information.
+  - This is a filter version of the M(community.crypto.x509_crl_info) module.
+options:
+  _input:
+    description:
+      - The content of the X.509 CRL in PEM format.
+    type: string
+    required: true
+  list_revoked_certificates:
+    description:
+      - If set to V(false), the list of revoked certificates is not included in the result.
+      - This is useful when retrieving information on large CRL files. Enumerating all revoked certificates can take some
+        time, including serializing the result as JSON, sending it to the Ansible controller, and decoding it again.
+    type: bool
+    default: true
+    version_added: 1.7.0
+extends_documentation_fragment:
+  - community.crypto.name_encoding
+seealso:
+  - module: community.crypto.x509_crl_info
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
+
+EXAMPLES = r"""
+---
+- name: Show the Organization Name of the CRL's subject
+  ansible.builtin.debug:
+    msg: >-
+      {{
+        (
+          lookup('ansible.builtin.file', '/path/to/cert.pem')
+          | community.crypto.x509_crl_info
+        ).issuer.organizationName
+      }}
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - Information on the CRL.
+  type: dict
+  contains:
+    format:
+      description:
+        - Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
+      returned: success
+      type: str
+      sample: pem
+      choices:
+        - pem
+        - der
+    issuer:
+      description:
+        - The CRL's issuer.
+        - Note that for repeated values, only the last one will be returned.
+        - See O(name_encoding) for how IDNs are handled.
+      returned: success
+      type: dict
+      sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
+    issuer_ordered:
+      description: The CRL's issuer as an ordered list of tuples.
+      returned: success
+      type: list
+      elements: list
+      sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
+    last_update:
+      description: The point in time from which this CRL can be trusted as ASN.1 TIME.
+      returned: success
+      type: str
+      sample: '20190413202428Z'
+    next_update:
+      description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
+      returned: success
+      type: str
+      sample: '20190413202428Z'
+    digest:
+      description: The signature algorithm used to sign the CRL.
+      returned: success
+      type: str
+      sample: sha256WithRSAEncryption
+    revoked_certificates:
+      description: List of certificates to be revoked.
+      returned: success if O(list_revoked_certificates=true)
+      type: list
+      elements: dict
+      contains:
+        serial_number:
+          description:
+            - Serial number of the certificate.
+            - This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as
+              C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
+          type: int
+          sample: 1234
+        revocation_date:
+          description: The point in time the certificate was revoked as ASN.1 TIME.
+          type: str
+          sample: '20190413202428Z'
+        issuer:
+          description:
+            - The certificate's issuer.
+            - See O(name_encoding) for how IDNs are handled.
+          type: list
+          elements: str
+          sample: ["DNS:ca.example.org"]
+        issuer_critical:
+          description: Whether the certificate issuer extension is critical.
+          type: bool
+          sample: false
+        reason:
+          description:
+            - The value for the revocation reason extension.
+          type: str
+          sample: key_compromise
+          choices:
+            - unspecified
+            - key_compromise
+            - ca_compromise
+            - affiliation_changed
+            - superseded
+            - cessation_of_operation
+            - certificate_hold
+            - privilege_withdrawn
+            - aa_compromise
+            - remove_from_crl
+        reason_critical:
+          description: Whether the revocation reason extension is critical.
+          type: bool
+          sample: false
+        invalidity_date:
+          description: |-
+            The point in time it was known/suspected that the private key was compromised
+            or that the certificate otherwise became invalid as ASN.1 TIME.
+          type: str
+          sample: '20190413202428Z'
+        invalidity_date_critical:
+          description: Whether the invalidity date extension is critical.
+          type: bool
+          sample: false
+"""
+
+import base64
+import binascii
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.crl_info import (
+    get_crl_info,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import (
+    identify_pem_format,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import (
+    FilterModuleMock,
+)
+
+
+def x509_crl_info_filter(data, name_encoding="ignore", list_revoked_certificates=True):
+    """Extract information from X.509 PEM certificate."""
+    if not isinstance(data, string_types):
+        raise AnsibleFilterError(
+            "The community.crypto.x509_crl_info input must be a text type, not %s"
+            % type(data)
+        )
+    if not isinstance(name_encoding, string_types):
+        raise AnsibleFilterError(
+            "The name_encoding option must be of a text type, not %s"
+            % type(name_encoding)
+        )
+    if not isinstance(list_revoked_certificates, bool):
+        raise AnsibleFilterError(
+            "The list_revoked_certificates option must be a boolean, not %s"
+            % type(list_revoked_certificates)
+        )
+    name_encoding = to_native(name_encoding)
+    if name_encoding not in ("ignore", "idna", "unicode"):
+        raise AnsibleFilterError(
+            'The name_encoding option must be one of the values "ignore", "idna", or "unicode", not "%s"'
+            % name_encoding
+        )
+
+    data = to_bytes(data)
+    if not identify_pem_format(data):
+        try:
+            data = base64.b64decode(to_native(data))
+        except (binascii.Error, TypeError, ValueError, UnicodeEncodeError):
+            pass
+
+    module = FilterModuleMock({"name_encoding": name_encoding})
+    try:
+        return get_crl_info(
+            module, content=data, list_revoked_certificates=list_revoked_certificates
+        )
+    except OpenSSLObjectError as exc:
+        raise AnsibleFilterError(to_native(exc))
+
+
+class FilterModule(object):
+    """Ansible jinja2 filters"""
+
+    def filters(self):
+        return {
+            "x509_crl_info": x509_crl_info_filter,
+        }

plugins/lookup/gpg_fingerprint.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2023, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+name: gpg_fingerprint
+short_description: Retrieve a GPG fingerprint from a GPG public or private key file
+author: Felix Fontein (@felixfontein)
+version_added: 2.15.0
+description:
+  - Takes a list of filenames pointing to GPG public or private key files. Returns the fingerprints for each of these keys.
+options:
+  _terms:
+    description:
+      - A path to a GPG public or private key.
+    type: list
+    elements: path
+    required: true
+requirements:
+  - GnuPG (C(gpg) executable)
+seealso:
+  - plugin: community.crypto.gpg_fingerprint
+    plugin_type: filter
+"""
+
+EXAMPLES = r"""
+---
+- name: Show fingerprint of GPG public key
+  ansible.builtin.debug:
+    msg: "{{ lookup('community.crypto.gpg_fingerprint', '/path/to/public_key.gpg') }}"
+"""
+
+RETURN = r"""
+_value:
+  description:
+    - The fingerprints of the provided public or private GPG keys.
+    - The list has one entry for every path provided.
+  type: list
+  elements: string
+"""
+
+from ansible.errors import AnsibleLookupError
+from ansible.module_utils.common.text.converters import to_native
+from ansible.plugins.lookup import LookupBase
+from ansible_collections.community.crypto.plugins.module_utils.gnupg.cli import (
+    GPGError,
+    get_fingerprint_from_file,
+)
+from ansible_collections.community.crypto.plugins.plugin_utils.gnupg import (
+    PluginGPGRunner,
+)
+
+
+class LookupModule(LookupBase):
+    def run(self, terms, variables=None, **kwargs):
+        self.set_options(direct=kwargs)
+
+        try:
+            gpg = PluginGPGRunner(cwd=self._loader.get_basedir())
+            result = []
+            for path in terms:
+                result.append(get_fingerprint_from_file(gpg, path))
+            return result
+        except GPGError as exc:
+            raise AnsibleLookupError(to_native(exc))

plugins/module_utils/_version.py

@@ -0,0 +1,348 @@
+# Vendored copy of distutils/version.py from CPython 3.9.5
+#
+# Implements multiple version numbering conventions for the
+# Python Module Distribution Utilities.
+#
+# Copyright (c) 2001-2022 Python Software Foundation.  All rights reserved.
+# PSF License (see LICENSES/PSF-2.0.txt or https://opensource.org/licenses/Python-2.0)
+# SPDX-License-Identifier: PSF-2.0
+#
+
+"""Provides classes to represent module version numbers (one class for
+each style of version numbering).  There are currently two such classes
+implemented: StrictVersion and LooseVersion.
+
+Every version number class implements the following interface:
+  * the 'parse' method takes a string and parses it to some internal
+    representation; if the string is an invalid version number,
+    'parse' raises a ValueError exception
+  * the class constructor takes an optional string argument which,
+    if supplied, is passed to 'parse'
+  * __str__ reconstructs the string that was passed to 'parse' (or
+    an equivalent string -- ie. one that will generate an equivalent
+    version number instance)
+  * __repr__ generates Python code to recreate the version number instance
+  * _cmp compares the current instance with either another instance
+    of the same class or a string (which will be parsed to an instance
+    of the same class, thus must follow the same rules)
+"""
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+import re
+
+
+try:
+    RE_FLAGS = re.VERBOSE | re.ASCII
+except AttributeError:
+    RE_FLAGS = re.VERBOSE
+
+
+class Version:
+    """Abstract base class for version numbering classes.  Just provides
+    constructor (__init__) and reproducer (__repr__), because those
+    seem to be the same for all version numbering classes; and route
+    rich comparisons to _cmp.
+    """
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def __repr__(self):
+        return "%s ('%s')" % (self.__class__.__name__, str(self))
+
+    def __eq__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c == 0
+
+    def __lt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c < 0
+
+    def __le__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c <= 0
+
+    def __gt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c > 0
+
+    def __ge__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c >= 0
+
+
+# Interface for version-number classes -- must be implemented
+# by the following classes (the concrete ones -- Version should
+# be treated as an abstract class).
+#    __init__ (string) - create and take same action as 'parse'
+#                        (string parameter is optional)
+#    parse (string)    - convert a string representation to whatever
+#                        internal representation is appropriate for
+#                        this style of version numbering
+#    __str__ (self)    - convert back to a string; should be very similar
+#                        (if not identical to) the string supplied to parse
+#    __repr__ (self)   - generate Python code to recreate
+#                        the instance
+#    _cmp (self, other) - compare two version numbers ('other' may
+#                        be an unparsed version string, or another
+#                        instance of your version class)
+
+
+class StrictVersion(Version):
+    """Version numbering for anal retentives and software idealists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of two or three
+    dot-separated numeric components, with an optional "pre-release" tag
+    on the end.  The pre-release tag consists of the letter 'a' or 'b'
+    followed by a number.  If the numeric components of two version
+    numbers are equal, then one with a pre-release tag will always
+    be deemed earlier (lesser) than one without.
+
+    The following are valid version numbers (shown in the order that
+    would be obtained by sorting according to the supplied cmp function):
+
+        0.4       0.4.0  (these two are equivalent)
+        0.4.1
+        0.5a1
+        0.5b3
+        0.5
+        0.9.6
+        1.0
+        1.0.4a3
+        1.0.4b1
+        1.0.4
+
+    The following are examples of invalid version numbers:
+
+        1
+        2.7.2.2
+        1.3.a4
+        1.3pl1
+        1.3c4
+
+    The rationale for this version numbering system will be explained
+    in the distutils documentation.
+    """
+
+    version_re = re.compile(r'^(\d+) \. (\d+) (\. (\d+))? ([ab](\d+))?$',
+                            RE_FLAGS)
+
+    def parse(self, vstring):
+        match = self.version_re.match(vstring)
+        if not match:
+            raise ValueError("invalid version number '%s'" % vstring)
+
+        (major, minor, patch, prerelease, prerelease_num) = \
+            match.group(1, 2, 4, 5, 6)
+
+        if patch:
+            self.version = tuple(map(int, [major, minor, patch]))
+        else:
+            self.version = tuple(map(int, [major, minor])) + (0,)
+
+        if prerelease:
+            self.prerelease = (prerelease[0], int(prerelease_num))
+        else:
+            self.prerelease = None
+
+    def __str__(self):
+        if self.version[2] == 0:
+            vstring = '.'.join(map(str, self.version[0:2]))
+        else:
+            vstring = '.'.join(map(str, self.version))
+
+        if self.prerelease:
+            vstring = vstring + self.prerelease[0] + str(self.prerelease[1])
+
+        return vstring
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = StrictVersion(other)
+        elif not isinstance(other, StrictVersion):
+            return NotImplemented
+
+        if self.version != other.version:
+            # numeric versions don't match
+            # prerelease stuff doesn't matter
+            if self.version < other.version:
+                return -1
+            else:
+                return 1
+
+        # have to compare prerelease
+        # case 1: neither has prerelease; they're equal
+        # case 2: self has prerelease, other doesn't; other is greater
+        # case 3: self doesn't have prerelease, other does: self is greater
+        # case 4: both have prerelease: must compare them!
+
+        if (not self.prerelease and not other.prerelease):
+            return 0
+        elif (self.prerelease and not other.prerelease):
+            return -1
+        elif (not self.prerelease and other.prerelease):
+            return 1
+        elif (self.prerelease and other.prerelease):
+            if self.prerelease == other.prerelease:
+                return 0
+            elif self.prerelease < other.prerelease:
+                return -1
+            else:
+                return 1
+        else:
+            raise AssertionError("never get here")
+
+# end class StrictVersion
+
+# The rules according to Greg Stein:
+# 1) a version number has 1 or more numbers separated by a period or by
+#    sequences of letters. If only periods, then these are compared
+#    left-to-right to determine an ordering.
+# 2) sequences of letters are part of the tuple for comparison and are
+#    compared lexicographically
+# 3) recognize the numeric components may have leading zeroes
+#
+# The LooseVersion class below implements these rules: a version number
+# string is split up into a tuple of integer and string components, and
+# comparison is a simple tuple comparison.  This means that version
+# numbers behave in a predictable and obvious way, but a way that might
+# not necessarily be how people *want* version numbers to behave.  There
+# wouldn't be a problem if people could stick to purely numeric version
+# numbers: just split on period and compare the numbers as tuples.
+# However, people insist on putting letters into their version numbers;
+# the most common purpose seems to be:
+#   - indicating a "pre-release" version
+#     ('alpha', 'beta', 'a', 'b', 'pre', 'p')
+#   - indicating a post-release patch ('p', 'pl', 'patch')
+# but of course this can't cover all version number schemes, and there's
+# no way to know what a programmer means without asking him.
+#
+# The problem is what to do with letters (and other non-numeric
+# characters) in a version number.  The current implementation does the
+# obvious and predictable thing: keep them as strings and compare
+# lexically within a tuple comparison.  This has the desired effect if
+# an appended letter sequence implies something "post-release":
+# eg. "0.99" < "0.99pl14" < "1.0", and "5.001" < "5.001m" < "5.002".
+#
+# However, if letters in a version number imply a pre-release version,
+# the "obvious" thing isn't correct.  Eg. you would expect that
+# "1.5.1" < "1.5.2a2" < "1.5.2", but under the tuple/lexical comparison
+# implemented here, this just isn't so.
+#
+# Two possible solutions come to mind.  The first is to tie the
+# comparison algorithm to a particular set of semantic rules, as has
+# been done in the StrictVersion class above.  This works great as long
+# as everyone can go along with bondage and discipline.  Hopefully a
+# (large) subset of Python module programmers will agree that the
+# particular flavour of bondage and discipline provided by StrictVersion
+# provides enough benefit to be worth using, and will submit their
+# version numbering scheme to its domination.  The free-thinking
+# anarchists in the lot will never give in, though, and something needs
+# to be done to accommodate them.
+#
+# Perhaps a "moderately strict" version class could be implemented that
+# lets almost anything slide (syntactically), and makes some heuristic
+# assumptions about non-digits in version number strings.  This could
+# sink into special-case-hell, though; if I was as talented and
+# idiosyncratic as Larry Wall, I'd go ahead and implement a class that
+# somehow knows that "1.2.1" < "1.2.2a2" < "1.2.2" < "1.2.2pl3", and is
+# just as happy dealing with things like "2g6" and "1.13++".  I don't
+# think I'm smart enough to do it right though.
+#
+# In any case, I've coded the test suite for this module (see
+# ../test/test_version.py) specifically to fail on things like comparing
+# "1.2a2" and "1.2".  That's not because the *code* is doing anything
+# wrong, it's because the simple, obvious design doesn't match my
+# complicated, hairy expectations for real-world version numbers.  It
+# would be a snap to fix the test suite to say, "Yep, LooseVersion does
+# the Right Thing" (ie. the code matches the conception).  But I'd rather
+# have a conception that matches common notions about version numbers.
+
+
+class LooseVersion(Version):
+    """Version numbering for anarchists and software realists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of a series of numbers,
+    separated by either periods or strings of letters.  When comparing
+    version numbers, the numeric components will be compared
+    numerically, and the alphabetic components lexically.  The following
+    are all valid version numbers, in no particular order:
+
+        1.5.1
+        1.5.2b2
+        161
+        3.10a
+        8.02
+        3.4j
+        1996.07.12
+        3.2.pl0
+        3.1.1.6
+        2g6
+        11g
+        0.960923
+        2.2beta29
+        1.13++
+        5.5.kw
+        2.0b1pl0
+
+    In fact, there is no such thing as an invalid version number under
+    this scheme; the rules for comparison are simple and predictable,
+    but may not always give the results you want (for some definition
+    of "want").
+    """
+
+    component_re = re.compile(r'(\d+ | [a-z]+ | \.)', re.VERBOSE)
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def parse(self, vstring):
+        # I've given up on thinking I can reconstruct the version string
+        # from the parsed tuple -- so I just store the string here for
+        # use by __str__
+        self.vstring = vstring
+        components = [x for x in self.component_re.split(vstring) if x and x != '.']
+        for i, obj in enumerate(components):
+            try:
+                components[i] = int(obj)
+            except ValueError:
+                pass
+
+        self.version = components
+
+    def __str__(self):
+        return self.vstring
+
+    def __repr__(self):
+        return "LooseVersion ('%s')" % str(self)
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = LooseVersion(other)
+        elif not isinstance(other, LooseVersion):
+            return NotImplemented
+
+        if self.version == other.version:
+            return 0
+        if self.version < other.version:
+            return -1
+        if self.version > other.version:
+            return 1
+
+# end class LooseVersion

plugins/module_utils/acme/__init__.py

@@ -1,90 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
-
-
-import base64
-import binascii
-import copy
-import datetime
-import hashlib
-import json
-import locale
-import os
-import re
-import shutil
-import sys
-import tempfile
-import traceback
-
-from ansible.module_utils.basic import missing_required_lib
-from ansible.module_utils.urls import fetch_url
-from ansible.module_utils.six.moves.urllib.parse import unquote
-from ansible.module_utils.common.text.converters import to_native, to_text, to_bytes
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
-    get_default_argspec,
-    ACMEDirectory,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.backend_cryptography import (
-    CryptographyBackend,
-    CRYPTOGRAPHY_VERSION,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.backend_openssl_cli import (
-    OpenSSLCLIBackend,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme._compatibility import (
-    handle_standard_module_arguments,
-    set_crypto_backend,
-    HAS_CURRENT_CRYPTOGRAPHY,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme._compatibility import ACMELegacyAccount as ACMEAccount
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.errors import ModuleFailException
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.io import (
-    read_file,
-    write_file,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
-    nopad_b64,
-    pem_to_der,
-    process_links,
-)
-
-
-def openssl_get_csr_identifiers(openssl_binary, module, csr_filename, csr_content=None):
-    module.deprecate(
-        'Please adjust your custom module/plugin to the ACME module_utils refactor '
-        '(https://github.com/ansible-collections/community.crypto/pull/184). The '
-        'compatibility layer will be removed in community.crypto 2.0.0, thus breaking '
-        'your code', version='2.0.0', collection_name='community.crypto')
-    return OpenSSLCLIBackend(module, openssl_binary=openssl_binary).get_csr_identifiers(csr_filename=csr_filename, csr_content=csr_content)
-
-
-def cryptography_get_csr_identifiers(module, csr_filename, csr_content=None):
-    module.deprecate(
-        'Please adjust your custom module/plugin to the ACME module_utils refactor '
-        '(https://github.com/ansible-collections/community.crypto/pull/184). The '
-        'compatibility layer will be removed in community.crypto 2.0.0, thus breaking '
-        'your code', version='2.0.0', collection_name='community.crypto')
-    return CryptographyBackend(module).get_csr_identifiers(csr_filename=csr_filename, csr_content=csr_content)
-
-
-def cryptography_get_cert_days(module, cert_file, now=None):
-    module.deprecate(
-        'Please adjust your custom module/plugin to the ACME module_utils refactor '
-        '(https://github.com/ansible-collections/community.crypto/pull/184). The '
-        'compatibility layer will be removed in community.crypto 2.0.0, thus breaking '
-        'your code', version='2.0.0', collection_name='community.crypto')
-    return CryptographyBackend(module).get_cert_days(cert_filename=cert_file, now=now)

plugins/module_utils/acme/_compatibility.py

@@ -1,267 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
-
-
-import locale
-
-from ansible.module_utils.basic import missing_required_lib
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.backend_cryptography import HAS_CURRENT_CRYPTOGRAPHY as _ORIGINAL_HAS_CURRENT_CRYPTOGRAPHY
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.backend_cryptography import (
-    CryptographyBackend,
-    CRYPTOGRAPHY_VERSION,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.backend_openssl_cli import (
-    OpenSSLCLIBackend,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
-    ACMEClient,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.account import (
-    ACMEAccount,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.challenges import (
-    create_key_authorization,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
-    KeyParsingError,
-)
-
-
-HAS_CURRENT_CRYPTOGRAPHY = _ORIGINAL_HAS_CURRENT_CRYPTOGRAPHY
-
-
-def set_crypto_backend(module):
-    '''
-    Sets which crypto backend to use (default: auto detection).
-
-    Does not care whether a new enough cryptoraphy is available or not. Must
-    be called before any real stuff is done which might evaluate
-    ``HAS_CURRENT_CRYPTOGRAPHY``.
-    '''
-    global HAS_CURRENT_CRYPTOGRAPHY
-
-    module.deprecate(
-        'Please adjust your custom module/plugin to the ACME module_utils refactor '
-        '(https://github.com/ansible-collections/community.crypto/pull/184). The '
-        'compatibility layer will be removed in community.crypto 2.0.0, thus breaking '
-        'your code', version='2.0.0', collection_name='community.crypto')
-
-    # Choose backend
-    backend = module.params['select_crypto_backend']
-    if backend == 'auto':
-        pass
-    elif backend == 'openssl':
-        HAS_CURRENT_CRYPTOGRAPHY = False
-    elif backend == 'cryptography':
-        if not _ORIGINAL_HAS_CURRENT_CRYPTOGRAPHY:
-            module.fail_json(msg=missing_required_lib('cryptography'))
-        HAS_CURRENT_CRYPTOGRAPHY = True
-    else:
-        module.fail_json(msg='Unknown crypto backend "{0}"!'.format(backend))
-    # Inform about choices
-    if HAS_CURRENT_CRYPTOGRAPHY:
-        module.debug('Using cryptography backend (library version {0})'.format(CRYPTOGRAPHY_VERSION))
-        return 'cryptography'
-    else:
-        module.debug('Using OpenSSL binary backend')
-        return 'openssl'
-
-
-def handle_standard_module_arguments(module, needs_acme_v2=False):
-    '''
-    Do standard module setup, argument handling and warning emitting.
-    '''
-    backend = set_crypto_backend(module)
-
-    if not module.params['validate_certs']:
-        module.warn(
-            'Disabling certificate validation for communications with ACME endpoint. '
-            'This should only be done for testing against a local ACME server for '
-            'development purposes, but *never* for production purposes.'
-        )
-
-    if module.params['acme_version'] is None:
-        module.params['acme_version'] = 1
-        module.deprecate("The option 'acme_version' will be required from community.crypto 2.0.0 on",
-                         version='2.0.0', collection_name='community.crypto')
-
-    if module.params['acme_directory'] is None:
-        module.params['acme_directory'] = 'https://acme-staging.api.letsencrypt.org/directory'
-        module.deprecate("The option 'acme_directory' will be required from community.crypto 2.0.0 on",
-                         version='2.0.0', collection_name='community.crypto')
-
-    if needs_acme_v2 and module.params['acme_version'] < 2:
-        module.fail_json(msg='The {0} module requires the ACME v2 protocol!'.format(module._name))
-
-    # AnsibleModule() changes the locale, so change it back to C because we rely on time.strptime() when parsing certificate dates.
-    module.run_command_environ_update = dict(LANG='C', LC_ALL='C', LC_MESSAGES='C', LC_CTYPE='C')
-    locale.setlocale(locale.LC_ALL, 'C')
-
-    return backend
-
-
-def get_compatibility_backend(module):
-    if HAS_CURRENT_CRYPTOGRAPHY:
-        return CryptographyBackend(module)
-    else:
-        return OpenSSLCLIBackend(module)
-
-
-class ACMELegacyAccount(object):
-    '''
-    ACME account object. Handles the authorized communication with the
-    ACME server. Provides access to account bound information like
-    the currently active authorizations and valid certificates
-    '''
-
-    def __init__(self, module):
-        module.deprecate(
-            'Please adjust your custom module/plugin to the ACME module_utils refactor '
-            '(https://github.com/ansible-collections/community.crypto/pull/184). The '
-            'compatibility layer will be removed in community.crypto 2.0.0, thus breaking '
-            'your code', version='2.0.0', collection_name='community.crypto')
-        backend = get_compatibility_backend(module)
-        self.client = ACMEClient(module, backend)
-        self.account = ACMEAccount(self.client)
-        self.key = self.client.account_key_file
-        self.key_content = self.client.account_key_content
-        self.uri = self.client.account_uri
-        self.key_data = self.client.account_key_data
-        self.jwk = self.client.account_jwk
-        self.jws_header = self.client.account_jws_header
-        self.directory = self.client.directory
-
-    def get_keyauthorization(self, token):
-        '''
-        Returns the key authorization for the given token
-        https://tools.ietf.org/html/rfc8555#section-8.1
-        '''
-        return create_key_authorization(self.client, token)
-
-    def parse_key(self, key_file=None, key_content=None):
-        '''
-        Parses an RSA or Elliptic Curve key file in PEM format and returns a pair
-        (error, key_data).
-        '''
-        try:
-            return None, self.client.parse_key(key_file=key_file, key_content=key_content)
-        except KeyParsingError as e:
-            return e.msg, {}
-
-    def sign_request(self, protected, payload, key_data, encode_payload=True):
-        return self.client.sign_request(protected, payload, key_data, encode_payload=encode_payload)
-
-    def send_signed_request(self, url, payload, key_data=None, jws_header=None, parse_json_result=True, encode_payload=True):
-        '''
-        Sends a JWS signed HTTP POST request to the ACME server and returns
-        the response as dictionary
-        https://tools.ietf.org/html/rfc8555#section-6.2
-
-        If payload is None, a POST-as-GET is performed.
-        (https://tools.ietf.org/html/rfc8555#section-6.3)
-        '''
-        return self.client.send_signed_request(
-            url,
-            payload,
-            key_data=key_data,
-            jws_header=jws_header,
-            parse_json_result=parse_json_result,
-            encode_payload=encode_payload,
-            fail_on_error=False,
-        )
-
-    def get_request(self, uri, parse_json_result=True, headers=None, get_only=False, fail_on_error=True):
-        '''
-        Perform a GET-like request. Will try POST-as-GET for ACMEv2, with fallback
-        to GET if server replies with a status code of 405.
-        '''
-        return self.client.get_request(
-            uri,
-            parse_json_result=parse_json_result,
-            headers=headers,
-            get_only=get_only,
-            fail_on_error=fail_on_error,
-        )
-
-    def set_account_uri(self, uri):
-        '''
-        Set account URI. For ACME v2, it needs to be used to sending signed
-        requests.
-        '''
-        self.client.set_account_uri(uri)
-        self.uri = self.client.account_uri
-
-    def get_account_data(self):
-        '''
-        Retrieve account information. Can only be called when the account
-        URI is already known (such as after calling setup_account).
-        Return None if the account was deactivated, or a dict otherwise.
-        '''
-        return self.account.get_account_data()
-
-    def setup_account(self, contact=None, agreement=None, terms_agreed=False,
-                      allow_creation=True, remove_account_uri_if_not_exists=False,
-                      external_account_binding=None):
-        '''
-        Detect or create an account on the ACME server. For ACME v1,
-        as the only way (without knowing an account URI) to test if an
-        account exists is to try and create one with the provided account
-        key, this method will always result in an account being present
-        (except on error situations). For ACME v2, a new account will
-        only be created if ``allow_creation`` is set to True.
-
-        For ACME v2, ``check_mode`` is fully respected. For ACME v1, the
-        account might be created if it does not yet exist.
-
-        Return a pair ``(created, account_data)``. Here, ``created`` will
-        be ``True`` in case the account was created or would be created
-        (check mode). ``account_data`` will be the current account data,
-        or ``None`` if the account does not exist.
-
-        The account URI will be stored in ``self.uri``; if it is ``None``,
-        the account does not exist.
-
-        If specified, ``external_account_binding`` should be a dictionary
-        with keys ``kid``, ``alg`` and ``key``
-        (https://tools.ietf.org/html/rfc8555#section-7.3.4).
-
-        https://tools.ietf.org/html/rfc8555#section-7.3
-        '''
-        result = self.account.setup_account(
-            contact=contact,
-            agreement=agreement,
-            terms_agreed=terms_agreed,
-            allow_creation=allow_creation,
-            remove_account_uri_if_not_exists=remove_account_uri_if_not_exists,
-            external_account_binding=external_account_binding,
-        )
-        self.uri = self.client.account_uri
-        return result
-
-    def update_account(self, account_data, contact=None):
-        '''
-        Update an account on the ACME server. Check mode is fully respected.
-
-        The current account data must be provided as ``account_data``.
-
-        Return a pair ``(updated, account_data)``, where ``updated`` is
-        ``True`` in case something changed (contact info updated) or
-        would be changed (check mode), and ``account_data`` the updated
-        account data.
-
-        https://tools.ietf.org/html/rfc8555#section-7.3.2
-        '''
-        return self.account.update_account(account_data, contact=contact)

plugins/module_utils/acme/account.py

@@ -1,13 +1,17 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
+from ansible.module_utils.common._collections_compat import Mapping
 from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
     ACMEProtocolException,
     ModuleFailException,
@@ -15,10 +19,10 @@ from ansible_collections.community.crypto.plugins.module_utils.acme.errors impor
 
 
 class ACMEAccount(object):
-    '''
+    """
     ACME account object. Allows to create new accounts, check for existence of accounts,
     retrieve account data.
-    '''
+    """
 
     def __init__(self, client):
         # Set to true to enable logging of all signed requests
@@ -26,9 +30,15 @@ class ACMEAccount(object):
 
         self.client = client
 
-    def _new_reg(self, contact=None, agreement=None, terms_agreed=False, allow_creation=True,
-                 external_account_binding=None):
-        '''
+    def _new_reg(
+        self,
+        contact=None,
+        agreement=None,
+        terms_agreed=False,
+        allow_creation=True,
+        external_account_binding=None,
+    ):
+        """
         Registers a new ACME account. Returns a pair ``(created, data)``.
         Here, ``created`` is ``True`` if the account was created and
         ``False`` if it already existed (e.g. it was not newly created),
@@ -40,70 +50,99 @@ class ACMEAccount(object):
         (https://tools.ietf.org/html/rfc8555#section-7.3.4).
 
         https://tools.ietf.org/html/rfc8555#section-7.3
-        '''
+        """
         contact = contact or []
 
         if self.client.version == 1:
-            new_reg = {
-                'resource': 'new-reg',
-                'contact': contact
-            }
+            new_reg = {"resource": "new-reg", "contact": contact}
             if agreement:
-                new_reg['agreement'] = agreement
+                new_reg["agreement"] = agreement
             else:
-                new_reg['agreement'] = self.client.directory['meta']['terms-of-service']
+                new_reg["agreement"] = self.client.directory["meta"]["terms-of-service"]
             if external_account_binding is not None:
-                raise ModuleFailException('External account binding is not supported for ACME v1')
-            url = self.client.directory['new-reg']
+                raise ModuleFailException(
+                    "External account binding is not supported for ACME v1"
+                )
+            url = self.client.directory["new-reg"]
         else:
-            if (external_account_binding is not None or self.client.directory['meta'].get('externalAccountRequired')) and allow_creation:
+            if (
+                external_account_binding is not None
+                or self.client.directory["meta"].get("externalAccountRequired")
+            ) and allow_creation:
                 # Some ACME servers such as ZeroSSL do not like it when you try to register an existing account
                 # and provide external_account_binding credentials. Thus we first send a request with allow_creation=False
                 # to see whether the account already exists.
 
-                # Note that we pass contact here: ZeroSSL does not accept regisration calls without contacts, even
-                # if onlyReturnExisting is set to true.
-                created, data = self._new_reg(contact=contact, allow_creation=False)
-                if data:
-                    # An account already exists! Return data
-                    return created, data
-                # An account does not yet exist. Try to create one next.
+                # Unfortunately, for other ACME servers it's the other way around: (at least some) HARICA endpoints
+                # do not allow *any* access without external account data. That's why we catch errors and check
+                # for 'externalAccountRequired'.
+                try:
+                    # Note that we pass contact here: ZeroSSL does not accept registration calls without contacts, even
+                    # if onlyReturnExisting is set to true.
+                    created, data = self._new_reg(contact=contact, allow_creation=False)
+                    if data:
+                        # An account already exists! Return data
+                        return created, data
+                    # An account does not yet exist. Try to create one next.
+                except ACMEProtocolException as exc:
+                    if (
+                        exc.error_type
+                        != "urn:ietf:params:acme:error:externalAccountRequired"
+                        or external_account_binding is None
+                    ):
+                        # Either another error happened, or we got 'externalAccountRequired' and external account data was not supplied
+                        # => re-raise exception!
+                        raise
+                    # In this case, the server really wants external account data.
+                    # The below code tries to create the account with external account data present.
 
-            new_reg = {
-                'contact': contact
-            }
+            new_reg = {"contact": contact}
             if not allow_creation:
                 # https://tools.ietf.org/html/rfc8555#section-7.3.1
-                new_reg['onlyReturnExisting'] = True
+                new_reg["onlyReturnExisting"] = True
             if terms_agreed:
-                new_reg['termsOfServiceAgreed'] = True
-            url = self.client.directory['newAccount']
+                new_reg["termsOfServiceAgreed"] = True
+            url = self.client.directory["newAccount"]
             if external_account_binding is not None:
-                new_reg['externalAccountBinding'] = self.client.sign_request(
+                new_reg["externalAccountBinding"] = self.client.sign_request(
                     {
-                        'alg': external_account_binding['alg'],
-                        'kid': external_account_binding['kid'],
-                        'url': url,
+                        "alg": external_account_binding["alg"],
+                        "kid": external_account_binding["kid"],
+                        "url": url,
                     },
                     self.client.account_jwk,
-                    self.client.backend.create_mac_key(external_account_binding['alg'], external_account_binding['key'])
+                    self.client.backend.create_mac_key(
+                        external_account_binding["alg"], external_account_binding["key"]
+                    ),
                 )
-            elif self.client.directory['meta'].get('externalAccountRequired') and allow_creation:
+            elif (
+                self.client.directory["meta"].get("externalAccountRequired")
+                and allow_creation
+            ):
                 raise ModuleFailException(
-                    'To create an account, an external account binding must be specified. '
-                    'Use the acme_account module with the external_account_binding option.'
+                    "To create an account, an external account binding must be specified. "
+                    "Use the acme_account module with the external_account_binding option."
                 )
 
-        result, info = self.client.send_signed_request(url, new_reg, fail_on_error=False)
+        result, info = self.client.send_signed_request(
+            url, new_reg, fail_on_error=False
+        )
+        if not isinstance(result, Mapping):
+            raise ACMEProtocolException(
+                self.client.module,
+                msg="Invalid account creation reply from ACME server",
+                info=info,
+                content=result,
+            )
 
-        if info['status'] in ([200, 201] if self.client.version == 1 else [201]):
+        if info["status"] in ([200, 201] if self.client.version == 1 else [201]):
             # Account did not exist
-            if 'location' in info:
-                self.client.set_account_uri(info['location'])
+            if "location" in info:
+                self.client.set_account_uri(info["location"])
             return True, result
-        elif info['status'] == (409 if self.client.version == 1 else 200):
+        elif info["status"] == (409 if self.client.version == 1 else 200):
             # Account did exist
-            if result.get('status') == 'deactivated':
+            if result.get("status") == "deactivated":
                 # A bug in Pebble (https://github.com/letsencrypt/pebble/issues/179) and
                 # Boulder (https://github.com/letsencrypt/boulder/issues/3971): this should
                 # not return a valid account object according to
@@ -114,14 +153,24 @@ class ACMEAccount(object):
                     return False, None
                 else:
                     raise ModuleFailException("Account is deactivated")
-            if 'location' in info:
-                self.client.set_account_uri(info['location'])
+            if "location" in info:
+                self.client.set_account_uri(info["location"])
             return False, result
-        elif info['status'] == 400 and result['type'] == 'urn:ietf:params:acme:error:accountDoesNotExist' and not allow_creation:
-            # Account does not exist (and we didn't try to create it)
+        elif (
+            info["status"] in (400, 404)
+            and result["type"] == "urn:ietf:params:acme:error:accountDoesNotExist"
+            and not allow_creation
+        ):
+            # Account does not exist (and we did not try to create it)
+            # (According to RFC 8555, Section 7.3.1, the HTTP status code MUST be 400.
+            # Unfortunately Digicert does not care and sends 404 instead.)
             return False, None
-        elif info['status'] == 403 and result['type'] == 'urn:ietf:params:acme:error:unauthorized' and 'deactivated' in (result.get('detail') or ''):
-            # Account has been deactivated; currently works for Pebble; hasn't been
+        elif (
+            info["status"] == 403
+            and result["type"] == "urn:ietf:params:acme:error:unauthorized"
+            and "deactivated" in (result.get("detail") or "")
+        ):
+            # Account has been deactivated; currently works for Pebble; has not been
             # implemented for Boulder (https://github.com/letsencrypt/boulder/issues/3971),
             # might need adjustment in error detection.
             if not allow_creation:
@@ -130,44 +179,80 @@ class ACMEAccount(object):
                 raise ModuleFailException("Account is deactivated")
         else:
             raise ACMEProtocolException(
-                self.client.module, msg='Registering ACME account failed', info=info, content_json=result)
+                self.client.module,
+                msg="Registering ACME account failed",
+                info=info,
+                content_json=result,
+            )
 
     def get_account_data(self):
-        '''
+        """
         Retrieve account information. Can only be called when the account
         URI is already known (such as after calling setup_account).
         Return None if the account was deactivated, or a dict otherwise.
-        '''
+        """
         if self.client.account_uri is None:
             raise ModuleFailException("Account URI unknown")
         if self.client.version == 1:
             data = {}
-            data['resource'] = 'reg'
-            result, info = self.client.send_signed_request(self.client.account_uri, data, fail_on_error=False)
+            data["resource"] = "reg"
+            result, info = self.client.send_signed_request(
+                self.client.account_uri, data, fail_on_error=False
+            )
         else:
             # try POST-as-GET first (draft-15 or newer)
             data = None
-            result, info = self.client.send_signed_request(self.client.account_uri, data, fail_on_error=False)
+            result, info = self.client.send_signed_request(
+                self.client.account_uri, data, fail_on_error=False
+            )
             # check whether that failed with a malformed request error
-            if info['status'] >= 400 and result.get('type') == 'urn:ietf:params:acme:error:malformed':
+            if (
+                info["status"] >= 400
+                and result.get("type") == "urn:ietf:params:acme:error:malformed"
+            ):
                 # retry as a regular POST (with no changed data) for pre-draft-15 ACME servers
                 data = {}
-                result, info = self.client.send_signed_request(self.client.account_uri, data, fail_on_error=False)
-        if info['status'] in (400, 403) and result.get('type') == 'urn:ietf:params:acme:error:unauthorized':
+                result, info = self.client.send_signed_request(
+                    self.client.account_uri, data, fail_on_error=False
+                )
+        if not isinstance(result, Mapping):
+            raise ACMEProtocolException(
+                self.client.module,
+                msg="Invalid account data retrieved from ACME server",
+                info=info,
+                content=result,
+            )
+        if (
+            info["status"] in (400, 403)
+            and result.get("type") == "urn:ietf:params:acme:error:unauthorized"
+        ):
             # Returned when account is deactivated
             return None
-        if info['status'] in (400, 404) and result.get('type') == 'urn:ietf:params:acme:error:accountDoesNotExist':
+        if (
+            info["status"] in (400, 404)
+            and result.get("type") == "urn:ietf:params:acme:error:accountDoesNotExist"
+        ):
             # Returned when account does not exist
             return None
-        if info['status'] < 200 or info['status'] >= 300:
+        if info["status"] < 200 or info["status"] >= 300:
             raise ACMEProtocolException(
-                self.client.module, msg='Error retrieving account data', info=info, content_json=result)
+                self.client.module,
+                msg="Error retrieving account data",
+                info=info,
+                content_json=result,
+            )
         return result
 
-    def setup_account(self, contact=None, agreement=None, terms_agreed=False,
-                      allow_creation=True, remove_account_uri_if_not_exists=False,
-                      external_account_binding=None):
-        '''
+    def setup_account(
+        self,
+        contact=None,
+        agreement=None,
+        terms_agreed=False,
+        allow_creation=True,
+        remove_account_uri_if_not_exists=False,
+        external_account_binding=None,
+    ):
+        """
         Detect or create an account on the ACME server. For ACME v1,
         as the only way (without knowing an account URI) to test if an
         account exists is to try and create one with the provided account
@@ -191,7 +276,7 @@ class ACMEAccount(object):
         (https://tools.ietf.org/html/rfc8555#section-7.3.4).
 
         https://tools.ietf.org/html/rfc8555#section-7.3
-        '''
+        """
 
         if self.client.account_uri is not None:
             created = False
@@ -202,7 +287,9 @@ class ACMEAccount(object):
                 if remove_account_uri_if_not_exists and not allow_creation:
                     self.client.account_uri = None
                 else:
-                    raise ModuleFailException("Account is deactivated or does not exist!")
+                    raise ModuleFailException(
+                        "Account is deactivated or does not exist!"
+                    )
         else:
             created, account_data = self._new_reg(
                 contact,
@@ -211,15 +298,17 @@ class ACMEAccount(object):
                 allow_creation=allow_creation and not self.client.module.check_mode,
                 external_account_binding=external_account_binding,
             )
-            if self.client.module.check_mode and self.client.account_uri is None and allow_creation:
+            if (
+                self.client.module.check_mode
+                and self.client.account_uri is None
+                and allow_creation
+            ):
                 created = True
-                account_data = {
-                    'contact': contact or []
-                }
+                account_data = {"contact": contact or []}
         return created, account_data
 
     def update_account(self, account_data, contact=None):
-        '''
+        """
         Update an account on the ACME server. Check mode is fully respected.
 
         The current account data must be provided as ``account_data``.
@@ -230,11 +319,11 @@ class ACMEAccount(object):
         account data.
 
         https://tools.ietf.org/html/rfc8555#section-7.3.2
-        '''
+        """
         # Create request
         update_request = {}
-        if contact is not None and account_data.get('contact', []) != contact:
-            update_request['contact'] = list(contact)
+        if contact is not None and account_data.get("contact", []) != contact:
+            update_request["contact"] = list(contact)
 
         # No change?
         if not update_request:
@@ -246,6 +335,16 @@ class ACMEAccount(object):
             account_data.update(update_request)
         else:
             if self.client.version == 1:
-                update_request['resource'] = 'reg'
-            account_data, dummy = self.client.send_signed_request(self.client.account_uri, update_request)
+                update_request["resource"] = "reg"
+            account_data, info = self.client.send_signed_request(
+                self.client.account_uri, update_request
+            )
+            if not isinstance(account_data, Mapping):
+                raise ACMEProtocolException(
+                    self.client.module,
+                    msg="Invalid account updating reply from ACME server",
+                    info=info,
+                    content=account_data,
+                )
+
         return True, account_data

plugins/module_utils/acme/acme.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
@@ -12,98 +15,201 @@ import copy
 import datetime
 import json
 import locale
+import time
+import traceback
 
 from ansible.module_utils.basic import missing_required_lib
-from ansible.module_utils.urls import fetch_url
 from ansible.module_utils.common.text.converters import to_bytes
-
+from ansible.module_utils.six import PY3
+from ansible.module_utils.urls import fetch_url
+from ansible_collections.community.crypto.plugins.module_utils.acme.backend_cryptography import (
+    CRYPTOGRAPHY_ERROR,
+    CRYPTOGRAPHY_MINIMAL_VERSION,
+    CRYPTOGRAPHY_VERSION,
+    HAS_CURRENT_CRYPTOGRAPHY,
+    CryptographyBackend,
+)
 from ansible_collections.community.crypto.plugins.module_utils.acme.backend_openssl_cli import (
     OpenSSLCLIBackend,
 )
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.backend_cryptography import (
-    CryptographyBackend,
-    CRYPTOGRAPHY_VERSION,
-    HAS_CURRENT_CRYPTOGRAPHY,
-)
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
     ACMEProtocolException,
-    NetworkException,
-    ModuleFailException,
     KeyParsingError,
+    ModuleFailException,
+    NetworkException,
+    format_http_status,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
+    compute_cert_id,
     nopad_b64,
+    parse_retry_after,
+)
+from ansible_collections.community.crypto.plugins.module_utils.argspec import (
+    ArgumentSpec,
 )
 
 
-def _assert_fetch_url_success(module, response, info, allow_redirect=False, allow_client_error=True, allow_server_error=True):
-    if info['status'] < 0:
-        raise NetworkException(msg="Failure downloading %s, %s" % (info['url'], info['msg']))
+try:
+    import ipaddress  # noqa: F401, pylint: disable=unused-import
+except ImportError:
+    HAS_IPADDRESS = False
+    IPADDRESS_IMPORT_ERROR = traceback.format_exc()
+else:
+    HAS_IPADDRESS = True
+    IPADDRESS_IMPORT_ERROR = None
 
-    if (300 <= info['status'] < 400 and not allow_redirect) or \
-       (400 <= info['status'] < 500 and not allow_client_error) or \
-       (info['status'] >= 500 and not allow_server_error):
+
+# -1 usually means connection problems
+RETRY_STATUS_CODES = (-1, 408, 429, 503)
+
+RETRY_COUNT = 10
+
+
+def _decode_retry(module, response, info, retry_count):
+    if info["status"] not in RETRY_STATUS_CODES:
+        return False
+
+    if retry_count >= RETRY_COUNT:
+        raise ACMEProtocolException(
+            module,
+            msg="Giving up after {retry} retries".format(retry=RETRY_COUNT),
+            info=info,
+            response=response,
+        )
+
+    # 429 and 503 should have a Retry-After header (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)
+    try:
+        retry_after = min(max(1, int(info.get("retry-after"))), 60)
+    except (TypeError, ValueError):
+        retry_after = 10
+    module.log(
+        "Retrieved a %s HTTP status on %s, retrying in %s seconds"
+        % (format_http_status(info["status"]), info["url"], retry_after)
+    )
+
+    time.sleep(retry_after)
+    return True
+
+
+def _assert_fetch_url_success(
+    module,
+    response,
+    info,
+    allow_redirect=False,
+    allow_client_error=True,
+    allow_server_error=True,
+):
+    if info["status"] < 0:
+        raise NetworkException(
+            msg="Failure downloading %s, %s" % (info["url"], info["msg"])
+        )
+
+    if (
+        (300 <= info["status"] < 400 and not allow_redirect)
+        or (400 <= info["status"] < 500 and not allow_client_error)
+        or (info["status"] >= 500 and not allow_server_error)
+    ):
         raise ACMEProtocolException(module, info=info, response=response)
 
 
 def _is_failed(info, expected_status_codes=None):
-    if info['status'] < 200 or info['status'] >= 400:
+    if info["status"] < 200 or info["status"] >= 400:
         return True
-    if expected_status_codes is not None and info['status'] not in expected_status_codes:
+    if (
+        expected_status_codes is not None
+        and info["status"] not in expected_status_codes
+    ):
         return True
     return False
 
 
 class ACMEDirectory(object):
-    '''
+    """
     The ACME server directory. Gives access to the available resources,
     and allows to obtain a Replay-Nonce. The acme_directory URL
     needs to support unauthenticated GET requests; ACME endpoints
     requiring authentication are not supported.
     https://tools.ietf.org/html/rfc8555#section-7.1.1
-    '''
+    """
 
     def __init__(self, module, account):
         self.module = module
-        self.directory_root = module.params['acme_directory']
-        self.version = module.params['acme_version']
+        self.directory_root = module.params["acme_directory"]
+        self.version = module.params["acme_version"]
 
         self.directory, dummy = account.get_request(self.directory_root, get_only=True)
 
+        self.request_timeout = module.params["request_timeout"]
+
         # Check whether self.version matches what we expect
         if self.version == 1:
-            for key in ('new-reg', 'new-authz', 'new-cert'):
+            for key in ("new-reg", "new-authz", "new-cert"):
                 if key not in self.directory:
-                    raise ModuleFailException("ACME directory does not seem to follow protocol ACME v1")
+                    raise ModuleFailException(
+                        "ACME directory does not seem to follow protocol ACME v1"
+                    )
         if self.version == 2:
-            for key in ('newNonce', 'newAccount', 'newOrder'):
+            for key in ("newNonce", "newAccount", "newOrder"):
                 if key not in self.directory:
-                    raise ModuleFailException("ACME directory does not seem to follow protocol ACME v2")
+                    raise ModuleFailException(
+                        "ACME directory does not seem to follow protocol ACME v2"
+                    )
             # Make sure that 'meta' is always available
-            if 'meta' not in self.directory:
-                self.directory['meta'] = {}
+            if "meta" not in self.directory:
+                self.directory["meta"] = {}
 
     def __getitem__(self, key):
         return self.directory[key]
 
+    def __contains__(self, key):
+        return key in self.directory
+
+    def get(self, key, default_value=None):
+        return self.directory.get(key, default_value)
+
     def get_nonce(self, resource=None):
-        url = self.directory_root if self.version == 1 else self.directory['newNonce']
+        url = self.directory_root if self.version == 1 else self.directory["newNonce"]
         if resource is not None:
             url = resource
-        dummy, info = fetch_url(self.module, url, method='HEAD')
-        if info['status'] not in (200, 204):
-            raise NetworkException("Failed to get replay-nonce, got status {0}".format(info['status']))
-        return info['replay-nonce']
+        retry_count = 0
+        while True:
+            response, info = fetch_url(
+                self.module, url, method="HEAD", timeout=self.request_timeout
+            )
+            if _decode_retry(self.module, response, info, retry_count):
+                retry_count += 1
+                continue
+            if info["status"] not in (200, 204):
+                raise NetworkException(
+                    "Failed to get replay-nonce, got status {0}".format(
+                        format_http_status(info["status"])
+                    )
+                )
+            if "replay-nonce" in info:
+                return info["replay-nonce"]
+            self.module.log(
+                "HEAD to {0} did return status {1}, but no replay-nonce header!".format(
+                    url, format_http_status(info["status"])
+                )
+            )
+            if retry_count >= 5:
+                raise ACMEProtocolException(
+                    self.module,
+                    msg="Was not able to obtain nonce, giving up after 5 retries",
+                    info=info,
+                    response=response,
+                )
+            retry_count += 1
+
+    def has_renewal_info_endpoint(self):
+        return "renewalInfo" in self.directory
 
 
 class ACMEClient(object):
-    '''
+    """
     ACME client object. Handles the authorized communication with the
     ACME server.
-    '''
+    """
 
     def __init__(self, module, backend):
         # Set to true to enable logging of all signed requests
@@ -111,15 +217,17 @@ class ACMEClient(object):
 
         self.module = module
         self.backend = backend
-        self.version = module.params['acme_version']
+        self.version = module.params["acme_version"]
         # account_key path and content are mutually exclusive
-        self.account_key_file = module.params['account_key_src']
-        self.account_key_content = module.params['account_key_content']
-        self.account_key_passphrase = module.params['account_key_passphrase']
+        self.account_key_file = module.params.get("account_key_src")
+        self.account_key_content = module.params.get("account_key_content")
+        self.account_key_passphrase = module.params.get("account_key_passphrase")
 
         # Grab account URI from module parameters.
         # Make sure empty string is treated as None.
-        self.account_uri = module.params.get('account_uri') or None
+        self.account_uri = module.params.get("account_uri") or None
+
+        self.request_timeout = module.params["request_timeout"]
 
         self.account_key_data = None
         self.account_jwk = None
@@ -129,12 +237,15 @@ class ACMEClient(object):
                 self.account_key_data = self.parse_key(
                     key_file=self.account_key_file,
                     key_content=self.account_key_content,
-                    passphrase=self.account_key_passphrase)
+                    passphrase=self.account_key_passphrase,
+                )
             except KeyParsingError as e:
-                raise ModuleFailException("Error while parsing account key: {msg}".format(msg=e.msg))
-            self.account_jwk = self.account_key_data['jwk']
+                raise ModuleFailException(
+                    "Error while parsing account key: {msg}".format(msg=e.msg)
+                )
+            self.account_jwk = self.account_key_data["jwk"]
             self.account_jws_header = {
-                "alg": self.account_key_data['alg'],
+                "alg": self.account_key_data["alg"],
                 "jwk": self.account_jwk,
             }
             if self.account_uri:
@@ -144,56 +255,76 @@ class ACMEClient(object):
         self.directory = ACMEDirectory(module, self)
 
     def set_account_uri(self, uri):
-        '''
+        """
         Set account URI. For ACME v2, it needs to be used to sending signed
         requests.
-        '''
+        """
         self.account_uri = uri
         if self.version != 1:
-            self.account_jws_header.pop('jwk')
-            self.account_jws_header['kid'] = self.account_uri
+            self.account_jws_header.pop("jwk")
+            self.account_jws_header["kid"] = self.account_uri
 
     def parse_key(self, key_file=None, key_content=None, passphrase=None):
-        '''
+        """
         Parses an RSA or Elliptic Curve key file in PEM format and returns key_data.
         In case of an error, raises KeyParsingError.
-        '''
+        """
         if key_file is None and key_content is None:
-            raise AssertionError('One of key_file and key_content must be specified!')
+            raise AssertionError("One of key_file and key_content must be specified!")
         return self.backend.parse_key(key_file, key_content, passphrase=passphrase)
 
     def sign_request(self, protected, payload, key_data, encode_payload=True):
-        '''
+        """
         Signs an ACME request.
-        '''
+        """
         try:
             if payload is None:
                 # POST-as-GET
-                payload64 = ''
+                payload64 = ""
             else:
                 # POST
                 if encode_payload:
-                    payload = self.module.jsonify(payload).encode('utf8')
+                    payload = self.module.jsonify(payload).encode("utf8")
                 payload64 = nopad_b64(to_bytes(payload))
-            protected64 = nopad_b64(self.module.jsonify(protected).encode('utf8'))
+            protected64 = nopad_b64(self.module.jsonify(protected).encode("utf8"))
         except Exception as e:
-            raise ModuleFailException("Failed to encode payload / headers as JSON: {0}".format(e))
+            raise ModuleFailException(
+                "Failed to encode payload / headers as JSON: {0}".format(e)
+            )
 
         return self.backend.sign(payload64, protected64, key_data)
 
     def _log(self, msg, data=None):
-        '''
+        """
         Write arguments to acme.log when logging is enabled.
-        '''
+        """
         if self._debug:
-            with open('acme.log', 'ab') as f:
-                f.write('[{0}] {1}\n'.format(datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S.%s'), msg).encode('utf-8'))
+            with open("acme.log", "ab") as f:
+                f.write(
+                    "[{0}] {1}\n".format(
+                        datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S.%s"), msg
+                    ).encode("utf-8")
+                )
                 if data is not None:
-                    f.write('{0}\n\n'.format(json.dumps(data, indent=2, sort_keys=True)).encode('utf-8'))
+                    f.write(
+                        "{0}\n\n".format(
+                            json.dumps(data, indent=2, sort_keys=True)
+                        ).encode("utf-8")
+                    )
 
-    def send_signed_request(self, url, payload, key_data=None, jws_header=None, parse_json_result=True,
-                            encode_payload=True, fail_on_error=True, error_msg=None, expected_status_codes=None):
-        '''
+    def send_signed_request(
+        self,
+        url,
+        payload,
+        key_data=None,
+        jws_header=None,
+        parse_json_result=True,
+        encode_payload=True,
+        fail_on_error=True,
+        error_msg=None,
+        expected_status_codes=None,
+    ):
+        """
         Sends a JWS signed HTTP POST request to the ACME server and returns
         the response as dictionary (if parse_json_result is True) or in raw form
         (if parse_json_result is False).
@@ -201,7 +332,7 @@ class ACMEClient(object):
 
         If payload is None, a POST-as-GET is performed.
         (https://tools.ietf.org/html/rfc8555#section-6.3)
-        '''
+        """
         key_data = key_data or self.account_key_data
         jws_header = jws_header or self.account_jws_header
         failed_tries = 0
@@ -211,40 +342,63 @@ class ACMEClient(object):
             if self.version != 1:
                 protected["url"] = url
 
-            self._log('URL', url)
-            self._log('protected', protected)
-            self._log('payload', payload)
-            data = self.sign_request(protected, payload, key_data, encode_payload=encode_payload)
+            self._log("URL", url)
+            self._log("protected", protected)
+            self._log("payload", payload)
+            data = self.sign_request(
+                protected, payload, key_data, encode_payload=encode_payload
+            )
             if self.version == 1:
                 data["header"] = jws_header.copy()
                 for k, v in protected.items():
-                    dummy = data["header"].pop(k, None)
-            self._log('signed request', data)
+                    data["header"].pop(k, None)
+            self._log("signed request", data)
             data = self.module.jsonify(data)
 
             headers = {
-                'Content-Type': 'application/jose+json',
+                "Content-Type": "application/jose+json",
             }
-            resp, info = fetch_url(self.module, url, data=data, headers=headers, method='POST')
+            resp, info = fetch_url(
+                self.module,
+                url,
+                data=data,
+                headers=headers,
+                method="POST",
+                timeout=self.request_timeout,
+            )
+            if _decode_retry(self.module, resp, info, failed_tries):
+                failed_tries += 1
+                continue
             _assert_fetch_url_success(self.module, resp, info)
             result = {}
+
             try:
+                # In Python 2, reading from a closed response yields a TypeError.
+                # In Python 3, read() simply returns ''
+                if PY3 and resp.closed:
+                    raise TypeError
                 content = resp.read()
-            except AttributeError:
-                content = info.pop('body', None)
+            except (AttributeError, TypeError):
+                content = info.pop("body", None)
 
             if content or not parse_json_result:
-                if (parse_json_result and info['content-type'].startswith('application/json')) or 400 <= info['status'] < 600:
+                if (
+                    parse_json_result
+                    and info["content-type"].startswith("application/json")
+                ) or 400 <= info["status"] < 600:
                     try:
-                        decoded_result = self.module.from_json(content.decode('utf8'))
-                        self._log('parsed result', decoded_result)
+                        decoded_result = self.module.from_json(content.decode("utf8"))
+                        self._log("parsed result", decoded_result)
                         # In case of badNonce error, try again (up to 5 times)
                         # (https://tools.ietf.org/html/rfc8555#section-6.7)
-                        if all((
-                            400 <= info['status'] < 600,
-                            decoded_result.get('type') == 'urn:ietf:params:acme:error:badNonce',
-                            failed_tries <= 5,
-                        )):
+                        if all(
+                            (
+                                400 <= info["status"] < 600,
+                                decoded_result.get("type")
+                                == "urn:ietf:params:acme:error:badNonce",
+                                failed_tries <= 5,
+                            )
+                        ):
                             failed_tries += 1
                             continue
                         if parse_json_result:
@@ -252,25 +406,46 @@ class ACMEClient(object):
                         else:
                             result = content
                     except ValueError:
-                        raise NetworkException("Failed to parse the ACME response: {0} {1}".format(url, content))
+                        raise NetworkException(
+                            "Failed to parse the ACME response: {0} {1}".format(
+                                url, content
+                            )
+                        )
                 else:
                     result = content
 
-            if fail_on_error and _is_failed(info, expected_status_codes=expected_status_codes):
+            if fail_on_error and _is_failed(
+                info, expected_status_codes=expected_status_codes
+            ):
                 raise ACMEProtocolException(
-                    self.module, msg=error_msg, info=info, content=content, content_json=result if parse_json_result else None)
+                    self.module,
+                    msg=error_msg,
+                    info=info,
+                    content=content,
+                    content_json=result if parse_json_result else None,
+                )
             return result, info
 
-    def get_request(self, uri, parse_json_result=True, headers=None, get_only=False,
-                    fail_on_error=True, error_msg=None, expected_status_codes=None):
-        '''
+    def get_request(
+        self,
+        uri,
+        parse_json_result=True,
+        headers=None,
+        get_only=False,
+        fail_on_error=True,
+        error_msg=None,
+        expected_status_codes=None,
+    ):
+        """
         Perform a GET-like request. Will try POST-as-GET for ACMEv2, with fallback
         to GET if server replies with a status code of 405.
-        '''
+        """
         if not get_only and self.version != 1:
             # Try POST-as-GET
-            content, info = self.send_signed_request(uri, None, parse_json_result=False, fail_on_error=False)
-            if info['status'] == 405:
+            content, info = self.send_signed_request(
+                uri, None, parse_json_result=False, fail_on_error=False
+            )
+            if info["status"] == 405:
                 # Instead, do unauthenticated GET
                 get_only = True
         else:
@@ -279,95 +454,232 @@ class ACMEClient(object):
 
         if get_only:
             # Perform unauthenticated GET
-            resp, info = fetch_url(self.module, uri, method='GET', headers=headers)
+            retry_count = 0
+            while True:
+                resp, info = fetch_url(
+                    self.module,
+                    uri,
+                    method="GET",
+                    headers=headers,
+                    timeout=self.request_timeout,
+                )
+                if not _decode_retry(self.module, resp, info, retry_count):
+                    break
+                retry_count += 1
 
             _assert_fetch_url_success(self.module, resp, info)
 
             try:
+                # In Python 2, reading from a closed response yields a TypeError.
+                # In Python 3, read() simply returns ''
+                if PY3 and resp.closed:
+                    raise TypeError
                 content = resp.read()
-            except AttributeError:
-                content = info.pop('body', None)
+            except (AttributeError, TypeError):
+                content = info.pop("body", None)
 
         # Process result
         parsed_json_result = False
         if parse_json_result:
             result = {}
             if content:
-                if info['content-type'].startswith('application/json'):
+                if info["content-type"].startswith("application/json"):
                     try:
-                        result = self.module.from_json(content.decode('utf8'))
+                        result = self.module.from_json(content.decode("utf8"))
                         parsed_json_result = True
                     except ValueError:
-                        raise NetworkException("Failed to parse the ACME response: {0} {1}".format(uri, content))
+                        raise NetworkException(
+                            "Failed to parse the ACME response: {0} {1}".format(
+                                uri, content
+                            )
+                        )
                 else:
                     result = content
         else:
             result = content
 
-        if fail_on_error and _is_failed(info, expected_status_codes=expected_status_codes):
+        if fail_on_error and _is_failed(
+            info, expected_status_codes=expected_status_codes
+        ):
             raise ACMEProtocolException(
-                self.module, msg=error_msg, info=info, content=content, content_json=result if parsed_json_result else None)
+                self.module,
+                msg=error_msg,
+                info=info,
+                content=content,
+                content_json=result if parsed_json_result else None,
+            )
         return result, info
 
+    def get_renewal_info(
+        self,
+        cert_id=None,
+        cert_info=None,
+        cert_filename=None,
+        cert_content=None,
+        include_retry_after=False,
+        retry_after_relative_with_timezone=True,
+    ):
+        if not self.directory.has_renewal_info_endpoint():
+            raise ModuleFailException(
+                "The ACME endpoint does not support ACME Renewal Information retrieval"
+            )
+
+        if cert_id is None:
+            cert_id = compute_cert_id(
+                self.backend,
+                cert_info=cert_info,
+                cert_filename=cert_filename,
+                cert_content=cert_content,
+            )
+        url = "{base}/{cert_id}".format(
+            base=self.directory.directory["renewalInfo"].rstrip("/"), cert_id=cert_id
+        )
+
+        data, info = self.get_request(
+            url, parse_json_result=True, fail_on_error=True, get_only=True
+        )
+
+        # Include Retry-After header if asked for
+        if include_retry_after and "retry-after" in info:
+            try:
+                data["retryAfter"] = parse_retry_after(
+                    info["retry-after"],
+                    relative_with_timezone=retry_after_relative_with_timezone,
+                )
+            except ValueError:
+                pass
+        return data
+
 
 def get_default_argspec():
-    '''
+    """
     Provides default argument spec for the options documented in the acme doc fragment.
-    '''
+
+    DEPRECATED: will be removed in community.crypto 3.0.0
+    """
     return dict(
-        account_key_src=dict(type='path', aliases=['account_key']),
-        account_key_content=dict(type='str', no_log=True),
-        account_key_passphrase=dict(type='str', no_log=True),
-        account_uri=dict(type='str'),
-        acme_directory=dict(type='str'),
-        acme_version=dict(type='int', choices=[1, 2]),
-        validate_certs=dict(type='bool', default=True),
-        select_crypto_backend=dict(type='str', default='auto', choices=['auto', 'openssl', 'cryptography']),
+        acme_directory=dict(type="str", required=True),
+        acme_version=dict(type="int", required=True, choices=[1, 2]),
+        validate_certs=dict(type="bool", default=True),
+        select_crypto_backend=dict(
+            type="str", default="auto", choices=["auto", "openssl", "cryptography"]
+        ),
+        request_timeout=dict(type="int", default=10),
+        account_key_src=dict(type="path", aliases=["account_key"]),
+        account_key_content=dict(type="str", no_log=True),
+        account_key_passphrase=dict(type="str", no_log=True),
+        account_uri=dict(type="str"),
     )
 
 
+def create_default_argspec(
+    with_account=True,
+    require_account_key=True,
+    with_certificate=False,
+):
+    """
+    Provides default argument spec for the options documented in the acme doc fragment.
+    """
+    result = ArgumentSpec(
+        argument_spec=dict(
+            acme_directory=dict(type="str", required=True),
+            acme_version=dict(type="int", required=True, choices=[1, 2]),
+            validate_certs=dict(type="bool", default=True),
+            select_crypto_backend=dict(
+                type="str", default="auto", choices=["auto", "openssl", "cryptography"]
+            ),
+            request_timeout=dict(type="int", default=10),
+        ),
+    )
+    if with_account:
+        result.update_argspec(
+            account_key_src=dict(type="path", aliases=["account_key"]),
+            account_key_content=dict(type="str", no_log=True),
+            account_key_passphrase=dict(type="str", no_log=True),
+            account_uri=dict(type="str"),
+        )
+        if require_account_key:
+            result.update(required_one_of=[["account_key_src", "account_key_content"]])
+        result.update(mutually_exclusive=[["account_key_src", "account_key_content"]])
+    if with_certificate:
+        result.update_argspec(
+            csr=dict(type="path"),
+            csr_content=dict(type="str"),
+        )
+        result.update(
+            required_one_of=[["csr", "csr_content"]],
+            mutually_exclusive=[["csr", "csr_content"]],
+        )
+    return result
+
+
 def create_backend(module, needs_acme_v2):
-    backend = module.params['select_crypto_backend']
+    if not HAS_IPADDRESS:
+        module.fail_json(
+            msg=missing_required_lib("ipaddress"), exception=IPADDRESS_IMPORT_ERROR
+        )
+
+    backend = module.params["select_crypto_backend"]
 
     # Backend autodetect
-    if backend == 'auto':
-        backend = 'cryptography' if HAS_CURRENT_CRYPTOGRAPHY else 'openssl'
+    if backend == "auto":
+        backend = "cryptography" if HAS_CURRENT_CRYPTOGRAPHY else "openssl"
 
     # Create backend object
-    if backend == 'cryptography':
+    if backend == "cryptography":
+        if CRYPTOGRAPHY_ERROR is not None:
+            # Either we could not import cryptography at all, or there was an unexpected error
+            if CRYPTOGRAPHY_VERSION is None:
+                msg = missing_required_lib("cryptography")
+            else:
+                msg = "Unexpected error while preparing cryptography: {0}".format(
+                    CRYPTOGRAPHY_ERROR.splitlines()[-1]
+                )
+            module.fail_json(msg=msg, exception=CRYPTOGRAPHY_ERROR)
         if not HAS_CURRENT_CRYPTOGRAPHY:
-            module.fail_json(msg=missing_required_lib('cryptography'))
-        module.debug('Using cryptography backend (library version {0})'.format(CRYPTOGRAPHY_VERSION))
+            # We succeeded importing cryptography, but its version is too old.
+            module.fail_json(
+                msg="Found cryptography, but only version {0}. {1}".format(
+                    CRYPTOGRAPHY_VERSION,
+                    missing_required_lib(
+                        "cryptography >= {0}".format(CRYPTOGRAPHY_MINIMAL_VERSION)
+                    ),
+                )
+            )
+        module.debug(
+            "Using cryptography backend (library version {0})".format(
+                CRYPTOGRAPHY_VERSION
+            )
+        )
         module_backend = CryptographyBackend(module)
-    elif backend == 'openssl':
-        module.debug('Using OpenSSL binary backend')
+    elif backend == "openssl":
+        module.debug("Using OpenSSL binary backend")
         module_backend = OpenSSLCLIBackend(module)
     else:
         module.fail_json(msg='Unknown crypto backend "{0}"!'.format(backend))
 
     # Check common module parameters
-    if not module.params['validate_certs']:
+    if not module.params["validate_certs"]:
         module.warn(
-            'Disabling certificate validation for communications with ACME endpoint. '
-            'This should only be done for testing against a local ACME server for '
-            'development purposes, but *never* for production purposes.'
+            "Disabling certificate validation for communications with ACME endpoint. "
+            "This should only be done for testing against a local ACME server for "
+            "development purposes, but *never* for production purposes."
         )
 
-    if module.params['acme_version'] is None:
-        module.params['acme_version'] = 1
-        module.deprecate("The option 'acme_version' will be required from community.crypto 2.0.0 on",
-                         version='2.0.0', collection_name='community.crypto')
+    if needs_acme_v2 and module.params["acme_version"] < 2:
+        module.fail_json(
+            msg="The {0} module requires the ACME v2 protocol!".format(module._name)
+        )
 
-    if module.params['acme_directory'] is None:
-        module.params['acme_directory'] = 'https://acme-staging.api.letsencrypt.org/directory'
-        module.deprecate("The option 'acme_directory' will be required from community.crypto 2.0.0 on",
-                         version='2.0.0', collection_name='community.crypto')
-
-    if needs_acme_v2 and module.params['acme_version'] < 2:
-        module.fail_json(msg='The {0} module requires the ACME v2 protocol!'.format(module._name))
+    if module.params["acme_version"] == 1:
+        module.deprecate(
+            "The value 1 for 'acme_version' is deprecated. Please switch to ACME v2",
+            version="3.0.0",
+            collection_name="community.crypto",
+        )
 
     # AnsibleModule() changes the locale, so change it back to C because we rely
     # on datetime.datetime.strptime() when parsing certificate dates.
-    locale.setlocale(locale.LC_ALL, 'C')
+    locale.setlocale(locale.LC_ALL, "C")
 
     return module_backend

plugins/module_utils/acme/backend_cryptography.py

@@ -1,100 +1,91 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import base64
 import binascii
-import datetime
 import os
-import sys
-
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+import traceback
 
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible_collections.community.crypto.plugins.module_utils.acme.backends import (
+    CertificateInformation,
     CryptoBackend,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.certificates import (
     ChainMatcher,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
     BackendException,
     KeyParsingError,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.io import read_file
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.utils import nopad_b64
-
+from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
+    nopad_b64,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_name_to_oid,
+    cryptography_serial_number_of_cert,
+    get_not_valid_after,
+    get_not_valid_before,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.math import (
+    convert_int_to_bytes,
+    convert_int_to_hex,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import (
+    extract_first_pem,
+)
 from ansible_collections.community.crypto.plugins.module_utils.crypto.support import (
     parse_name_field,
 )
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.cryptography_support import (
-    cryptography_name_to_oid,
+from ansible_collections.community.crypto.plugins.module_utils.time import (
+    add_or_remove_timezone,
+)
+from ansible_collections.community.crypto.plugins.module_utils.version import (
+    LooseVersion,
 )
 
+
+CRYPTOGRAPHY_MINIMAL_VERSION = "1.5"
+
+CRYPTOGRAPHY_ERROR = None
 try:
     import cryptography
     import cryptography.hazmat.backends
-    import cryptography.hazmat.primitives.hashes
-    import cryptography.hazmat.primitives.hmac
     import cryptography.hazmat.primitives.asymmetric.ec
     import cryptography.hazmat.primitives.asymmetric.padding
     import cryptography.hazmat.primitives.asymmetric.rsa
     import cryptography.hazmat.primitives.asymmetric.utils
+    import cryptography.hazmat.primitives.hashes
+    import cryptography.hazmat.primitives.hmac
     import cryptography.hazmat.primitives.serialization
     import cryptography.x509
     import cryptography.x509.oid
-    from distutils.version import LooseVersion
-    CRYPTOGRAPHY_VERSION = cryptography.__version__
-    HAS_CURRENT_CRYPTOGRAPHY = (LooseVersion(CRYPTOGRAPHY_VERSION) >= LooseVersion('1.5'))
-    if HAS_CURRENT_CRYPTOGRAPHY:
-        _cryptography_backend = cryptography.hazmat.backends.default_backend()
-except Exception as dummy:
+except ImportError:
     HAS_CURRENT_CRYPTOGRAPHY = False
     CRYPTOGRAPHY_VERSION = None
-
-
-if sys.version_info[0] >= 3:
-    # Python 3 (and newer)
-    def _count_bytes(n):
-        return (n.bit_length() + 7) // 8 if n > 0 else 0
-
-    def _convert_int_to_bytes(count, no):
-        return no.to_bytes(count, byteorder='big')
-
-    def _pad_hex(n, digits):
-        res = hex(n)[2:]
-        if len(res) < digits:
-            res = '0' * (digits - len(res)) + res
-        return res
+    CRYPTOGRAPHY_ERROR = traceback.format_exc()
 else:
-    # Python 2
-    def _count_bytes(n):
-        if n <= 0:
-            return 0
-        h = '%x' % n
-        return (len(h) + 1) // 2
-
-    def _convert_int_to_bytes(count, n):
-        h = '%x' % n
-        if len(h) > 2 * count:
-            raise Exception('Number {1} needs more than {0} bytes!'.format(count, n))
-        return ('0' * (2 * count - len(h)) + h).decode('hex')
-
-    def _pad_hex(n, digits):
-        h = '%x' % n
-        if len(h) < digits:
-            h = '0' * (digits - len(h)) + h
-        return h
+    CRYPTOGRAPHY_VERSION = cryptography.__version__
+    HAS_CURRENT_CRYPTOGRAPHY = LooseVersion(CRYPTOGRAPHY_VERSION) >= LooseVersion(
+        CRYPTOGRAPHY_MINIMAL_VERSION
+    )
+    try:
+        if HAS_CURRENT_CRYPTOGRAPHY:
+            _cryptography_backend = cryptography.hazmat.backends.default_backend()
+    except Exception:
+        CRYPTOGRAPHY_ERROR = traceback.format_exc()
 
 
 class CryptographyChainMatcher(ChainMatcher):
@@ -102,13 +93,19 @@ class CryptographyChainMatcher(ChainMatcher):
     def _parse_key_identifier(key_identifier, name, criterium_idx, module):
         if key_identifier:
             try:
-                return binascii.unhexlify(key_identifier.replace(':', ''))
+                return binascii.unhexlify(key_identifier.replace(":", ""))
             except Exception:
                 if criterium_idx is None:
-                    module.warn('Criterium has invalid {0} value. Ignoring criterium.'.format(name))
+                    module.warn(
+                        "Criterium has invalid {0} value. Ignoring criterium.".format(
+                            name
+                        )
+                    )
                 else:
-                    module.warn('Criterium {0} in select_chain has invalid {1} value. '
-                                'Ignoring criterium.'.format(criterium_idx, name))
+                    module.warn(
+                        "Criterium {0} in select_chain has invalid {1} value. "
+                        "Ignoring criterium.".format(criterium_idx, name)
+                    )
         return None
 
     def __init__(self, criterium, module):
@@ -118,16 +115,26 @@ class CryptographyChainMatcher(ChainMatcher):
         self.issuer = []
         if criterium.subject:
             self.subject = [
-                (cryptography_name_to_oid(k), to_native(v)) for k, v in parse_name_field(criterium.subject)
+                (cryptography_name_to_oid(k), to_native(v))
+                for k, v in parse_name_field(criterium.subject, "subject")
             ]
         if criterium.issuer:
             self.issuer = [
-                (cryptography_name_to_oid(k), to_native(v)) for k, v in parse_name_field(criterium.issuer)
+                (cryptography_name_to_oid(k), to_native(v))
+                for k, v in parse_name_field(criterium.issuer, "issuer")
             ]
         self.subject_key_identifier = CryptographyChainMatcher._parse_key_identifier(
-            criterium.subject_key_identifier, 'subject_key_identifier', criterium.index, module)
+            criterium.subject_key_identifier,
+            "subject_key_identifier",
+            criterium.index,
+            module,
+        )
         self.authority_key_identifier = CryptographyChainMatcher._parse_key_identifier(
-            criterium.authority_key_identifier, 'authority_key_identifier', criterium.index, module)
+            criterium.authority_key_identifier,
+            "authority_key_identifier",
+            criterium.index,
+            module,
+        )
 
     def _match_subject(self, x509_subject, match_subject):
         for oid, value in match_subject:
@@ -141,17 +148,19 @@ class CryptographyChainMatcher(ChainMatcher):
         return True
 
     def match(self, certificate):
-        '''
+        """
         Check whether an alternate chain matches the specified criterium.
-        '''
+        """
         chain = certificate.chain
-        if self.test_certificates == 'last':
+        if self.test_certificates == "last":
             chain = chain[-1:]
-        elif self.test_certificates == 'first':
+        elif self.test_certificates == "first":
             chain = chain[:1]
         for cert in chain:
             try:
-                x509 = cryptography.x509.load_pem_x509_certificate(to_bytes(cert), cryptography.hazmat.backends.default_backend())
+                x509 = cryptography.x509.load_pem_x509_certificate(
+                    to_bytes(cert), cryptography.hazmat.backends.default_backend()
+                )
                 matches = True
                 if not self._match_subject(x509.subject, self.subject):
                     matches = False
@@ -159,14 +168,18 @@ class CryptographyChainMatcher(ChainMatcher):
                     matches = False
                 if self.subject_key_identifier:
                     try:
-                        ext = x509.extensions.get_extension_for_class(cryptography.x509.SubjectKeyIdentifier)
+                        ext = x509.extensions.get_extension_for_class(
+                            cryptography.x509.SubjectKeyIdentifier
+                        )
                         if self.subject_key_identifier != ext.value.digest:
                             matches = False
                     except cryptography.x509.ExtensionNotFound:
                         matches = False
                 if self.authority_key_identifier:
                     try:
-                        ext = x509.extensions.get_extension_for_class(cryptography.x509.AuthorityKeyIdentifier)
+                        ext = x509.extensions.get_extension_for_class(
+                            cryptography.x509.AuthorityKeyIdentifier
+                        )
                         if self.authority_key_identifier != ext.value.key_identifier:
                             matches = False
                     except cryptography.x509.ExtensionNotFound:
@@ -174,20 +187,24 @@ class CryptographyChainMatcher(ChainMatcher):
                 if matches:
                     return True
             except Exception as e:
-                self.module.warn('Error while loading certificate {0}: {1}'.format(cert, e))
+                self.module.warn(
+                    "Error while loading certificate {0}: {1}".format(cert, e)
+                )
         return False
 
 
 class CryptographyBackend(CryptoBackend):
     def __init__(self, module):
-        super(CryptographyBackend, self).__init__(module)
+        super(CryptographyBackend, self).__init__(
+            module, with_timezone=CRYPTOGRAPHY_TIMEZONE
+        )
 
     def parse_key(self, key_file=None, key_content=None, passphrase=None):
-        '''
+        """
         Parses an RSA or Elliptic Curve key file in PEM format and returns key_data.
         Raises KeyParsingError in case of errors.
-        '''
-        # If key_content isn't given, read key_file
+        """
+        # If key_content is not given, read key_file
         if key_content is None:
             key_content = read_file(key_file)
         else:
@@ -197,84 +214,97 @@ class CryptographyBackend(CryptoBackend):
             key = cryptography.hazmat.primitives.serialization.load_pem_private_key(
                 key_content,
                 password=to_bytes(passphrase) if passphrase is not None else None,
-                backend=_cryptography_backend)
+                backend=_cryptography_backend,
+            )
         except Exception as e:
-            raise KeyParsingError('error while loading key: {0}'.format(e))
+            raise KeyParsingError("error while loading key: {0}".format(e))
         if isinstance(key, cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey):
             pk = key.public_key().public_numbers()
             return {
-                'key_obj': key,
-                'type': 'rsa',
-                'alg': 'RS256',
-                'jwk': {
+                "key_obj": key,
+                "type": "rsa",
+                "alg": "RS256",
+                "jwk": {
                     "kty": "RSA",
-                    "e": nopad_b64(_convert_int_to_bytes(_count_bytes(pk.e), pk.e)),
-                    "n": nopad_b64(_convert_int_to_bytes(_count_bytes(pk.n), pk.n)),
+                    "e": nopad_b64(convert_int_to_bytes(pk.e)),
+                    "n": nopad_b64(convert_int_to_bytes(pk.n)),
                 },
-                'hash': 'sha256',
+                "hash": "sha256",
             }
-        elif isinstance(key, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey):
+        elif isinstance(
+            key, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
+        ):
             pk = key.public_key().public_numbers()
-            if pk.curve.name == 'secp256r1':
+            if pk.curve.name == "secp256r1":
                 bits = 256
-                alg = 'ES256'
-                hashalg = 'sha256'
+                alg = "ES256"
+                hashalg = "sha256"
                 point_size = 32
-                curve = 'P-256'
-            elif pk.curve.name == 'secp384r1':
+                curve = "P-256"
+            elif pk.curve.name == "secp384r1":
                 bits = 384
-                alg = 'ES384'
-                hashalg = 'sha384'
+                alg = "ES384"
+                hashalg = "sha384"
                 point_size = 48
-                curve = 'P-384'
-            elif pk.curve.name == 'secp521r1':
+                curve = "P-384"
+            elif pk.curve.name == "secp521r1":
                 # Not yet supported on Let's Encrypt side, see
                 # https://github.com/letsencrypt/boulder/issues/2217
                 bits = 521
-                alg = 'ES512'
-                hashalg = 'sha512'
+                alg = "ES512"
+                hashalg = "sha512"
                 point_size = 66
-                curve = 'P-521'
+                curve = "P-521"
             else:
-                raise KeyParsingError('unknown elliptic curve: {0}'.format(pk.curve.name))
+                raise KeyParsingError(
+                    "unknown elliptic curve: {0}".format(pk.curve.name)
+                )
             num_bytes = (bits + 7) // 8
             return {
-                'key_obj': key,
-                'type': 'ec',
-                'alg': alg,
-                'jwk': {
+                "key_obj": key,
+                "type": "ec",
+                "alg": alg,
+                "jwk": {
                     "kty": "EC",
                     "crv": curve,
-                    "x": nopad_b64(_convert_int_to_bytes(num_bytes, pk.x)),
-                    "y": nopad_b64(_convert_int_to_bytes(num_bytes, pk.y)),
+                    "x": nopad_b64(convert_int_to_bytes(pk.x, count=num_bytes)),
+                    "y": nopad_b64(convert_int_to_bytes(pk.y, count=num_bytes)),
                 },
-                'hash': hashalg,
-                'point_size': point_size,
+                "hash": hashalg,
+                "point_size": point_size,
             }
         else:
             raise KeyParsingError('unknown key type "{0}"'.format(type(key)))
 
     def sign(self, payload64, protected64, key_data):
-        sign_payload = "{0}.{1}".format(protected64, payload64).encode('utf8')
-        if 'mac_obj' in key_data:
-            mac = key_data['mac_obj']()
+        sign_payload = "{0}.{1}".format(protected64, payload64).encode("utf8")
+        if "mac_obj" in key_data:
+            mac = key_data["mac_obj"]()
             mac.update(sign_payload)
             signature = mac.finalize()
-        elif isinstance(key_data['key_obj'], cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey):
+        elif isinstance(
+            key_data["key_obj"],
+            cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey,
+        ):
             padding = cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15()
             hashalg = cryptography.hazmat.primitives.hashes.SHA256
-            signature = key_data['key_obj'].sign(sign_payload, padding, hashalg())
-        elif isinstance(key_data['key_obj'], cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey):
-            if key_data['hash'] == 'sha256':
+            signature = key_data["key_obj"].sign(sign_payload, padding, hashalg())
+        elif isinstance(
+            key_data["key_obj"],
+            cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey,
+        ):
+            if key_data["hash"] == "sha256":
                 hashalg = cryptography.hazmat.primitives.hashes.SHA256
-            elif key_data['hash'] == 'sha384':
+            elif key_data["hash"] == "sha384":
                 hashalg = cryptography.hazmat.primitives.hashes.SHA384
-            elif key_data['hash'] == 'sha512':
+            elif key_data["hash"] == "sha512":
                 hashalg = cryptography.hazmat.primitives.hashes.SHA512
             ecdsa = cryptography.hazmat.primitives.asymmetric.ec.ECDSA(hashalg())
-            r, s = cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature(key_data['key_obj'].sign(sign_payload, ecdsa))
-            rr = _pad_hex(r, 2 * key_data['point_size'])
-            ss = _pad_hex(s, 2 * key_data['point_size'])
+            r, s = cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature(
+                key_data["key_obj"].sign(sign_payload, ecdsa)
+            )
+            rr = convert_int_to_hex(r, 2 * key_data["point_size"])
+            ss = convert_int_to_hex(s, 2 * key_data["point_size"])
             signature = binascii.unhexlify(rr) + binascii.unhexlify(ss)
 
         return {
@@ -284,69 +314,104 @@ class CryptographyBackend(CryptoBackend):
         }
 
     def create_mac_key(self, alg, key):
-        '''Create a MAC key.'''
-        if alg == 'HS256':
+        """Create a MAC key."""
+        if alg == "HS256":
             hashalg = cryptography.hazmat.primitives.hashes.SHA256
             hashbytes = 32
-        elif alg == 'HS384':
+        elif alg == "HS384":
             hashalg = cryptography.hazmat.primitives.hashes.SHA384
             hashbytes = 48
-        elif alg == 'HS512':
+        elif alg == "HS512":
             hashalg = cryptography.hazmat.primitives.hashes.SHA512
             hashbytes = 64
         else:
-            raise BackendException('Unsupported MAC key algorithm for cryptography backend: {0}'.format(alg))
+            raise BackendException(
+                "Unsupported MAC key algorithm for cryptography backend: {0}".format(
+                    alg
+                )
+            )
         key_bytes = base64.urlsafe_b64decode(key)
         if len(key_bytes) < hashbytes:
             raise BackendException(
-                '{0} key must be at least {1} bytes long (after Base64 decoding)'.format(alg, hashbytes))
+                "{0} key must be at least {1} bytes long (after Base64 decoding)".format(
+                    alg, hashbytes
+                )
+            )
         return {
-            'mac_obj': lambda: cryptography.hazmat.primitives.hmac.HMAC(
-                key_bytes,
-                hashalg(),
-                _cryptography_backend),
-            'type': 'hmac',
-            'alg': alg,
-            'jwk': {
-                'kty': 'oct',
-                'k': key,
+            "mac_obj": lambda: cryptography.hazmat.primitives.hmac.HMAC(
+                key_bytes, hashalg(), _cryptography_backend
+            ),
+            "type": "hmac",
+            "alg": alg,
+            "jwk": {
+                "kty": "oct",
+                "k": key,
             },
         }
 
-    def get_csr_identifiers(self, csr_filename=None, csr_content=None):
-        '''
-        Return a set of requested identifiers (CN and SANs) for the CSR.
+    def get_ordered_csr_identifiers(self, csr_filename=None, csr_content=None):
+        """
+        Return a list of requested identifiers (CN and SANs) for the CSR.
         Each identifier is a pair (type, identifier), where type is either
         'dns' or 'ip'.
-        '''
-        identifiers = set([])
+
+        The list is deduplicated, and if a CNAME is present, it will be returned
+        as the first element in the result.
+        """
         if csr_content is None:
             csr_content = read_file(csr_filename)
         else:
             csr_content = to_bytes(csr_content)
         csr = cryptography.x509.load_pem_x509_csr(csr_content, _cryptography_backend)
+
+        identifiers = set()
+        result = []
+
+        def add_identifier(identifier):
+            if identifier in identifiers:
+                return
+            identifiers.add(identifier)
+            result.append(identifier)
+
         for sub in csr.subject:
             if sub.oid == cryptography.x509.oid.NameOID.COMMON_NAME:
-                identifiers.add(('dns', sub.value))
+                add_identifier(("dns", sub.value))
         for extension in csr.extensions:
-            if extension.oid == cryptography.x509.oid.ExtensionOID.SUBJECT_ALTERNATIVE_NAME:
+            if (
+                extension.oid
+                == cryptography.x509.oid.ExtensionOID.SUBJECT_ALTERNATIVE_NAME
+            ):
                 for name in extension.value:
                     if isinstance(name, cryptography.x509.DNSName):
-                        identifiers.add(('dns', name.value))
+                        add_identifier(("dns", name.value))
                     elif isinstance(name, cryptography.x509.IPAddress):
-                        identifiers.add(('ip', name.value.compressed))
+                        add_identifier(("ip", name.value.compressed))
                     else:
-                        raise BackendException('Found unsupported SAN identifier {0}'.format(name))
-        return identifiers
+                        raise BackendException(
+                            "Found unsupported SAN identifier {0}".format(name)
+                        )
+        return result
+
+    def get_csr_identifiers(self, csr_filename=None, csr_content=None):
+        """
+        Return a set of requested identifiers (CN and SANs) for the CSR.
+        Each identifier is a pair (type, identifier), where type is either
+        'dns' or 'ip'.
+        """
+        return set(
+            self.get_ordered_csr_identifiers(
+                csr_filename=csr_filename, csr_content=csr_content
+            )
+        )
 
     def get_cert_days(self, cert_filename=None, cert_content=None, now=None):
-        '''
+        """
         Return the days the certificate in cert_filename remains valid and -1
         if the file was not found. If cert_filename contains more than one
         certificate, only the first one will be considered.
 
         If now is not specified, datetime.datetime.now() is used.
-        '''
+        """
         if cert_filename is not None:
             cert_content = None
             if os.path.exists(cert_filename):
@@ -357,19 +422,77 @@ class CryptographyBackend(CryptoBackend):
         if cert_content is None:
             return -1
 
+        # Make sure we have at most one PEM. Otherwise cryptography 36.0.0 will barf.
+        cert_content = to_bytes(extract_first_pem(to_text(cert_content)) or "")
+
         try:
-            cert = cryptography.x509.load_pem_x509_certificate(cert_content, _cryptography_backend)
+            cert = cryptography.x509.load_pem_x509_certificate(
+                cert_content, _cryptography_backend
+            )
         except Exception as e:
             if cert_filename is None:
-                raise BackendException('Cannot parse certificate: {0}'.format(e))
-            raise BackendException('Cannot parse certificate {0}: {1}'.format(cert_filename, e))
+                raise BackendException("Cannot parse certificate: {0}".format(e))
+            raise BackendException(
+                "Cannot parse certificate {0}: {1}".format(cert_filename, e)
+            )
 
         if now is None:
-            now = datetime.datetime.now()
-        return (cert.not_valid_after - now).days
+            now = self.get_now()
+        else:
+            now = add_or_remove_timezone(now, with_timezone=CRYPTOGRAPHY_TIMEZONE)
+        return (get_not_valid_after(cert) - now).days
 
     def create_chain_matcher(self, criterium):
-        '''
+        """
         Given a Criterium object, creates a ChainMatcher object.
-        '''
+        """
         return CryptographyChainMatcher(criterium, self.module)
+
+    def get_cert_information(self, cert_filename=None, cert_content=None):
+        """
+        Return some information on a X.509 certificate as a CertificateInformation object.
+        """
+        if cert_filename is not None:
+            cert_content = read_file(cert_filename)
+        else:
+            cert_content = to_bytes(cert_content)
+
+        # Make sure we have at most one PEM. Otherwise cryptography 36.0.0 will barf.
+        cert_content = to_bytes(extract_first_pem(to_text(cert_content)) or "")
+
+        try:
+            cert = cryptography.x509.load_pem_x509_certificate(
+                cert_content, _cryptography_backend
+            )
+        except Exception as e:
+            if cert_filename is None:
+                raise BackendException("Cannot parse certificate: {0}".format(e))
+            raise BackendException(
+                "Cannot parse certificate {0}: {1}".format(cert_filename, e)
+            )
+
+        ski = None
+        try:
+            ext = cert.extensions.get_extension_for_class(
+                cryptography.x509.SubjectKeyIdentifier
+            )
+            ski = ext.value.digest
+        except cryptography.x509.ExtensionNotFound:
+            pass
+
+        aki = None
+        try:
+            ext = cert.extensions.get_extension_for_class(
+                cryptography.x509.AuthorityKeyIdentifier
+            )
+            aki = ext.value.key_identifier
+        except cryptography.x509.ExtensionNotFound:
+            pass
+
+        return CertificateInformation(
+            not_valid_after=get_not_valid_after(cert),
+            not_valid_before=get_not_valid_before(cert),
+            serial_number=cryptography_serial_number_of_cert(cert),
+            subject_key_identifier=ski,
+            authority_key_identifier=aki,
+        )

plugins/module_utils/acme/backend_openssl_cli.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
@@ -16,59 +19,115 @@ import re
 import tempfile
 import traceback
 
-from ansible.module_utils.common.text.converters import to_native, to_text, to_bytes
-
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible_collections.community.crypto.plugins.module_utils.acme.backends import (
+    CertificateInformation,
     CryptoBackend,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
     BackendException,
     KeyParsingError,
 )
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.utils import nopad_b64
-
-from ansible_collections.community.crypto.plugins.module_utils.compat import ipaddress as compat_ipaddress
+from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
+    nopad_b64,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.math import (
+    convert_bytes_to_int,
+)
+from ansible_collections.community.crypto.plugins.module_utils.time import (
+    ensure_utc_timezone,
+)
 
 
-_OPENSSL_ENVIRONMENT_UPDATE = dict(LANG='C', LC_ALL='C', LC_MESSAGES='C', LC_CTYPE='C')
+try:
+    import ipaddress
+except ImportError:
+    pass
+
+
+_OPENSSL_ENVIRONMENT_UPDATE = dict(LANG="C", LC_ALL="C", LC_MESSAGES="C", LC_CTYPE="C")
+
+
+def _extract_date(out_text, name, cert_filename_suffix=""):
+    try:
+        date_str = re.search(r"\s+%s\s*:\s+(.*)" % name, out_text).group(1)
+        # For some reason Python's strptime() does not return any timezone information,
+        # even though the information is there and a supported timezone for all supported
+        # Python implementations (GMT). So we have to modify the datetime object by
+        # replacing it by UTC.
+        return ensure_utc_timezone(
+            datetime.datetime.strptime(date_str, "%b %d %H:%M:%S %Y %Z")
+        )
+    except AttributeError:
+        raise BackendException(
+            "No '{0}' date found{1}".format(name, cert_filename_suffix)
+        )
+    except ValueError as exc:
+        raise BackendException(
+            "Failed to parse '{0}' date{1}: {2}".format(name, cert_filename_suffix, exc)
+        )
+
+
+def _decode_octets(octets_text):
+    return binascii.unhexlify(re.sub(r"(\s|:)", "", octets_text).encode("utf-8"))
+
+
+def _extract_octets(out_text, name, required=True, potential_prefixes=None):
+    regexp = r"\s+%s:\s*\n\s+%s([A-Fa-f0-9]{2}(?::[A-Fa-f0-9]{2})*)\s*\n" % (
+        name,
+        (
+            ("(?:%s)" % "|".join(re.escape(pp) for pp in potential_prefixes))
+            if potential_prefixes
+            else ""
+        ),
+    )
+    match = re.search(regexp, out_text, re.MULTILINE | re.DOTALL)
+    if match is not None:
+        return _decode_octets(match.group(1))
+    if not required:
+        return None
+    raise BackendException("No '{0}' octet string found".format(name))
 
 
 class OpenSSLCLIBackend(CryptoBackend):
     def __init__(self, module, openssl_binary=None):
-        super(OpenSSLCLIBackend, self).__init__(module)
+        super(OpenSSLCLIBackend, self).__init__(module, with_timezone=True)
         if openssl_binary is None:
-            openssl_binary = module.get_bin_path('openssl', True)
+            openssl_binary = module.get_bin_path("openssl", True)
         self.openssl_binary = openssl_binary
 
     def parse_key(self, key_file=None, key_content=None, passphrase=None):
-        '''
+        """
         Parses an RSA or Elliptic Curve key file in PEM format and returns key_data.
         Raises KeyParsingError in case of errors.
-        '''
+        """
         if passphrase is not None:
-            raise KeyParsingError('openssl backend does not support key passphrases')
-        # If key_file isn't given, but key_content, write that to a temporary file
+            raise KeyParsingError("openssl backend does not support key passphrases")
+        # If key_file is not given, but key_content, write that to a temporary file
         if key_file is None:
             fd, tmpsrc = tempfile.mkstemp()
             self.module.add_cleanup_file(tmpsrc)  # Ansible will delete the file on exit
-            f = os.fdopen(fd, 'wb')
+            f = os.fdopen(fd, "wb")
             try:
-                f.write(key_content.encode('utf-8'))
+                f.write(key_content.encode("utf-8"))
                 key_file = tmpsrc
             except Exception as err:
                 try:
                     f.close()
-                except Exception as dummy:
+                except Exception:
                     pass
-                raise KeyParsingError("failed to create temporary content file: %s" % to_native(err), exception=traceback.format_exc())
+                raise KeyParsingError(
+                    "failed to create temporary content file: %s" % to_native(err),
+                    exception=traceback.format_exc(),
+                )
             f.close()
         # Parse key
         account_key_type = None
         with open(key_file, "rt") as f:
             for line in f:
-                m = re.match(r"^\s*-{5,}BEGIN\s+(EC|RSA)\s+PRIVATE\s+KEY-{5,}\s*$", line)
+                m = re.match(
+                    r"^\s*-{5,}BEGIN\s+(EC|RSA)\s+PRIVATE\s+KEY-{5,}\s*$", line
+                )
                 if m is not None:
                     account_key_type = m.group(1).lower()
                     break
@@ -81,103 +140,162 @@ class OpenSSLCLIBackend(CryptoBackend):
         if account_key_type not in ("rsa", "ec"):
             raise KeyParsingError('unknown key type "%s"' % account_key_type)
 
-        openssl_keydump_cmd = [self.openssl_binary, account_key_type, "-in", key_file, "-noout", "-text"]
-        dummy, out, dummy = self.module.run_command(
-            openssl_keydump_cmd, check_rc=True, environ_update=_OPENSSL_ENVIRONMENT_UPDATE)
+        openssl_keydump_cmd = [
+            self.openssl_binary,
+            account_key_type,
+            "-in",
+            key_file,
+            "-noout",
+            "-text",
+        ]
+        rc, out, err = self.module.run_command(
+            openssl_keydump_cmd,
+            check_rc=False,
+            environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+        )
+        if rc != 0:
+            raise BackendException(
+                "Error while running {cmd}: {stderr}".format(
+                    cmd=" ".join(openssl_keydump_cmd), stderr=to_text(err)
+                )
+            )
 
-        if account_key_type == 'rsa':
-            pub_hex, pub_exp = re.search(
-                r"modulus:\n\s+00:([a-f0-9\:\s]+?)\npublicExponent: ([0-9]+)",
-                to_text(out, errors='surrogate_or_strict'), re.MULTILINE | re.DOTALL).groups()
+        out_text = to_text(out, errors="surrogate_or_strict")
+
+        if account_key_type == "rsa":
+            pub_hex = re.search(
+                r"modulus:\n\s+00:([a-f0-9\:\s]+?)\npublicExponent",
+                out_text,
+                re.MULTILINE | re.DOTALL,
+            ).group(1)
+
+            pub_exp = re.search(
+                r"\npublicExponent: ([0-9]+)", out_text, re.MULTILINE | re.DOTALL
+            ).group(1)
             pub_exp = "{0:x}".format(int(pub_exp))
             if len(pub_exp) % 2:
                 pub_exp = "0{0}".format(pub_exp)
 
             return {
-                'key_file': key_file,
-                'type': 'rsa',
-                'alg': 'RS256',
-                'jwk': {
+                "key_file": key_file,
+                "type": "rsa",
+                "alg": "RS256",
+                "jwk": {
                     "kty": "RSA",
                     "e": nopad_b64(binascii.unhexlify(pub_exp.encode("utf-8"))),
-                    "n": nopad_b64(binascii.unhexlify(re.sub(r"(\s|:)", "", pub_hex).encode("utf-8"))),
+                    "n": nopad_b64(_decode_octets(pub_hex)),
                 },
-                'hash': 'sha256',
+                "hash": "sha256",
             }
-        elif account_key_type == 'ec':
+        elif account_key_type == "ec":
             pub_data = re.search(
                 r"pub:\s*\n\s+04:([a-f0-9\:\s]+?)\nASN1 OID: (\S+)(?:\nNIST CURVE: (\S+))?",
-                to_text(out, errors='surrogate_or_strict'), re.MULTILINE | re.DOTALL)
+                out_text,
+                re.MULTILINE | re.DOTALL,
+            )
             if pub_data is None:
-                raise KeyParsingError('cannot parse elliptic curve key')
-            pub_hex = binascii.unhexlify(re.sub(r"(\s|:)", "", pub_data.group(1)).encode("utf-8"))
+                raise KeyParsingError("cannot parse elliptic curve key")
+            pub_hex = _decode_octets(pub_data.group(1))
             asn1_oid_curve = pub_data.group(2).lower()
             nist_curve = pub_data.group(3).lower() if pub_data.group(3) else None
-            if asn1_oid_curve == 'prime256v1' or nist_curve == 'p-256':
+            if asn1_oid_curve == "prime256v1" or nist_curve == "p-256":
                 bits = 256
-                alg = 'ES256'
-                hashalg = 'sha256'
+                alg = "ES256"
+                hashalg = "sha256"
                 point_size = 32
-                curve = 'P-256'
-            elif asn1_oid_curve == 'secp384r1' or nist_curve == 'p-384':
+                curve = "P-256"
+            elif asn1_oid_curve == "secp384r1" or nist_curve == "p-384":
                 bits = 384
-                alg = 'ES384'
-                hashalg = 'sha384'
+                alg = "ES384"
+                hashalg = "sha384"
                 point_size = 48
-                curve = 'P-384'
-            elif asn1_oid_curve == 'secp521r1' or nist_curve == 'p-521':
+                curve = "P-384"
+            elif asn1_oid_curve == "secp521r1" or nist_curve == "p-521":
                 # Not yet supported on Let's Encrypt side, see
                 # https://github.com/letsencrypt/boulder/issues/2217
                 bits = 521
-                alg = 'ES512'
-                hashalg = 'sha512'
+                alg = "ES512"
+                hashalg = "sha512"
                 point_size = 66
-                curve = 'P-521'
+                curve = "P-521"
             else:
-                raise KeyParsingError('unknown elliptic curve: %s / %s' % (asn1_oid_curve, nist_curve))
+                raise KeyParsingError(
+                    "unknown elliptic curve: %s / %s" % (asn1_oid_curve, nist_curve)
+                )
             num_bytes = (bits + 7) // 8
             if len(pub_hex) != 2 * num_bytes:
-                raise KeyParsingError('bad elliptic curve point (%s / %s)' % (asn1_oid_curve, nist_curve))
+                raise KeyParsingError(
+                    "bad elliptic curve point (%s / %s)" % (asn1_oid_curve, nist_curve)
+                )
             return {
-                'key_file': key_file,
-                'type': 'ec',
-                'alg': alg,
-                'jwk': {
+                "key_file": key_file,
+                "type": "ec",
+                "alg": alg,
+                "jwk": {
                     "kty": "EC",
                     "crv": curve,
                     "x": nopad_b64(pub_hex[:num_bytes]),
                     "y": nopad_b64(pub_hex[num_bytes:]),
                 },
-                'hash': hashalg,
-                'point_size': point_size,
+                "hash": hashalg,
+                "point_size": point_size,
             }
 
     def sign(self, payload64, protected64, key_data):
-        sign_payload = "{0}.{1}".format(protected64, payload64).encode('utf8')
-        if key_data['type'] == 'hmac':
-            hex_key = to_native(binascii.hexlify(base64.urlsafe_b64decode(key_data['jwk']['k'])))
-            cmd_postfix = ["-mac", "hmac", "-macopt", "hexkey:{0}".format(hex_key), "-binary"]
+        sign_payload = "{0}.{1}".format(protected64, payload64).encode("utf8")
+        if key_data["type"] == "hmac":
+            hex_key = to_native(
+                binascii.hexlify(base64.urlsafe_b64decode(key_data["jwk"]["k"]))
+            )
+            cmd_postfix = [
+                "-mac",
+                "hmac",
+                "-macopt",
+                "hexkey:{0}".format(hex_key),
+                "-binary",
+            ]
         else:
-            cmd_postfix = ["-sign", key_data['key_file']]
-        openssl_sign_cmd = [self.openssl_binary, "dgst", "-{0}".format(key_data['hash'])] + cmd_postfix
+            cmd_postfix = ["-sign", key_data["key_file"]]
+        openssl_sign_cmd = [
+            self.openssl_binary,
+            "dgst",
+            "-{0}".format(key_data["hash"]),
+        ] + cmd_postfix
 
-        dummy, out, dummy = self.module.run_command(
-            openssl_sign_cmd, data=sign_payload, check_rc=True, binary_data=True, environ_update=_OPENSSL_ENVIRONMENT_UPDATE)
+        rc, out, err = self.module.run_command(
+            openssl_sign_cmd,
+            data=sign_payload,
+            check_rc=False,
+            binary_data=True,
+            environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+        )
+        if rc != 0:
+            raise BackendException(
+                "Error while running {cmd}: {stderr}".format(
+                    cmd=" ".join(openssl_sign_cmd), stderr=to_text(err)
+                )
+            )
 
-        if key_data['type'] == 'ec':
+        if key_data["type"] == "ec":
             dummy, der_out, dummy = self.module.run_command(
                 [self.openssl_binary, "asn1parse", "-inform", "DER"],
-                data=out, binary_data=True, environ_update=_OPENSSL_ENVIRONMENT_UPDATE)
-            expected_len = 2 * key_data['point_size']
+                data=out,
+                binary_data=True,
+                environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+            )
+            expected_len = 2 * key_data["point_size"]
             sig = re.findall(
                 r"prim:\s+INTEGER\s+:([0-9A-F]{1,%s})\n" % expected_len,
-                to_text(der_out, errors='surrogate_or_strict'))
+                to_text(der_out, errors="surrogate_or_strict"),
+            )
             if len(sig) != 2:
                 raise BackendException(
                     "failed to generate Elliptic Curve signature; cannot parse DER output: {0}".format(
-                        to_text(der_out, errors='surrogate_or_strict')))
-            sig[0] = (expected_len - len(sig[0])) * '0' + sig[0]
-            sig[1] = (expected_len - len(sig[1])) * '0' + sig[1]
+                        to_text(der_out, errors="surrogate_or_strict")
+                    )
+                )
+            sig[0] = (expected_len - len(sig[0])) * "0" + sig[0]
+            sig[1] = (expected_len - len(sig[1])) * "0" + sig[1]
             out = binascii.unhexlify(sig[0]) + binascii.unhexlify(sig[1])
 
         return {
@@ -187,112 +305,257 @@ class OpenSSLCLIBackend(CryptoBackend):
         }
 
     def create_mac_key(self, alg, key):
-        '''Create a MAC key.'''
-        if alg == 'HS256':
-            hashalg = 'sha256'
+        """Create a MAC key."""
+        if alg == "HS256":
+            hashalg = "sha256"
             hashbytes = 32
-        elif alg == 'HS384':
-            hashalg = 'sha384'
+        elif alg == "HS384":
+            hashalg = "sha384"
             hashbytes = 48
-        elif alg == 'HS512':
-            hashalg = 'sha512'
+        elif alg == "HS512":
+            hashalg = "sha512"
             hashbytes = 64
         else:
-            raise BackendException('Unsupported MAC key algorithm for OpenSSL backend: {0}'.format(alg))
+            raise BackendException(
+                "Unsupported MAC key algorithm for OpenSSL backend: {0}".format(alg)
+            )
         key_bytes = base64.urlsafe_b64decode(key)
         if len(key_bytes) < hashbytes:
             raise BackendException(
-                '{0} key must be at least {1} bytes long (after Base64 decoding)'.format(alg, hashbytes))
+                "{0} key must be at least {1} bytes long (after Base64 decoding)".format(
+                    alg, hashbytes
+                )
+            )
         return {
-            'type': 'hmac',
-            'alg': alg,
-            'jwk': {
-                'kty': 'oct',
-                'k': key,
+            "type": "hmac",
+            "alg": alg,
+            "jwk": {
+                "kty": "oct",
+                "k": key,
             },
-            'hash': hashalg,
+            "hash": hashalg,
         }
 
     @staticmethod
     def _normalize_ip(ip):
         try:
-            return to_native(compat_ipaddress.ip_address(to_text(ip)).compressed)
+            return to_native(ipaddress.ip_address(to_text(ip)).compressed)
         except ValueError:
-            # We don't want to error out on something IPAddress() can't parse
+            # We do not want to error out on something IPAddress() cannot parse
             return ip
 
-    def get_csr_identifiers(self, csr_filename=None, csr_content=None):
-        '''
-        Return a set of requested identifiers (CN and SANs) for the CSR.
+    def get_ordered_csr_identifiers(self, csr_filename=None, csr_content=None):
+        """
+        Return a list of requested identifiers (CN and SANs) for the CSR.
         Each identifier is a pair (type, identifier), where type is either
         'dns' or 'ip'.
-        '''
+
+        The list is deduplicated, and if a CNAME is present, it will be returned
+        as the first element in the result.
+        """
         filename = csr_filename
         data = None
         if csr_content is not None:
-            filename = '/dev/stdin'
-            data = csr_content.encode('utf-8')
+            filename = "/dev/stdin"
+            data = csr_content.encode("utf-8")
 
-        openssl_csr_cmd = [self.openssl_binary, "req", "-in", filename, "-noout", "-text"]
-        dummy, out, dummy = self.module.run_command(
-            openssl_csr_cmd, data=data, check_rc=True, binary_data=True, environ_update=_OPENSSL_ENVIRONMENT_UPDATE)
+        openssl_csr_cmd = [
+            self.openssl_binary,
+            "req",
+            "-in",
+            filename,
+            "-noout",
+            "-text",
+        ]
+        rc, out, err = self.module.run_command(
+            openssl_csr_cmd,
+            data=data,
+            check_rc=False,
+            binary_data=True,
+            environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+        )
+        if rc != 0:
+            raise BackendException(
+                "Error while running {cmd}: {stderr}".format(
+                    cmd=" ".join(openssl_csr_cmd), stderr=to_text(err)
+                )
+            )
 
-        identifiers = set([])
-        common_name = re.search(r"Subject:.* CN\s?=\s?([^\s,;/]+)", to_text(out, errors='surrogate_or_strict'))
+        identifiers = set()
+        result = []
+
+        def add_identifier(identifier):
+            if identifier in identifiers:
+                return
+            identifiers.add(identifier)
+            result.append(identifier)
+
+        common_name = re.search(
+            r"Subject:.* CN\s?=\s?([^\s,;/]+)",
+            to_text(out, errors="surrogate_or_strict"),
+        )
         if common_name is not None:
-            identifiers.add(('dns', common_name.group(1)))
+            add_identifier(("dns", common_name.group(1)))
         subject_alt_names = re.search(
             r"X509v3 Subject Alternative Name: (?:critical)?\n +([^\n]+)\n",
-            to_text(out, errors='surrogate_or_strict'), re.MULTILINE | re.DOTALL)
+            to_text(out, errors="surrogate_or_strict"),
+            re.MULTILINE | re.DOTALL,
+        )
         if subject_alt_names is not None:
             for san in subject_alt_names.group(1).split(", "):
                 if san.lower().startswith("dns:"):
-                    identifiers.add(('dns', san[4:]))
+                    add_identifier(("dns", san[4:]))
                 elif san.lower().startswith("ip:"):
-                    identifiers.add(('ip', self._normalize_ip(san[3:])))
+                    add_identifier(("ip", self._normalize_ip(san[3:])))
                 elif san.lower().startswith("ip address:"):
-                    identifiers.add(('ip', self._normalize_ip(san[11:])))
+                    add_identifier(("ip", self._normalize_ip(san[11:])))
                 else:
-                    raise BackendException('Found unsupported SAN identifier "{0}"'.format(san))
-        return identifiers
+                    raise BackendException(
+                        'Found unsupported SAN identifier "{0}"'.format(san)
+                    )
+        return result
+
+    def get_csr_identifiers(self, csr_filename=None, csr_content=None):
+        """
+        Return a set of requested identifiers (CN and SANs) for the CSR.
+        Each identifier is a pair (type, identifier), where type is either
+        'dns' or 'ip'.
+        """
+        return set(
+            self.get_ordered_csr_identifiers(
+                csr_filename=csr_filename, csr_content=csr_content
+            )
+        )
 
     def get_cert_days(self, cert_filename=None, cert_content=None, now=None):
-        '''
+        """
         Return the days the certificate in cert_filename remains valid and -1
         if the file was not found. If cert_filename contains more than one
         certificate, only the first one will be considered.
 
         If now is not specified, datetime.datetime.now() is used.
-        '''
+        """
         filename = cert_filename
         data = None
         if cert_content is not None:
-            filename = '/dev/stdin'
-            data = cert_content.encode('utf-8')
-            cert_filename_suffix = ''
+            filename = "/dev/stdin"
+            data = cert_content.encode("utf-8")
+            cert_filename_suffix = ""
         elif cert_filename is not None:
             if not os.path.exists(cert_filename):
                 return -1
-            cert_filename_suffix = ' in {0}'.format(cert_filename)
+            cert_filename_suffix = " in {0}".format(cert_filename)
         else:
             return -1
 
-        openssl_cert_cmd = [self.openssl_binary, "x509", "-in", filename, "-noout", "-text"]
-        dummy, out, dummy = self.module.run_command(
-            openssl_cert_cmd, data=data, check_rc=True, binary_data=True, environ_update=_OPENSSL_ENVIRONMENT_UPDATE)
-        try:
-            not_after_str = re.search(r"\s+Not After\s*:\s+(.*)", to_text(out, errors='surrogate_or_strict')).group(1)
-            not_after = datetime.datetime.strptime(not_after_str, '%b %d %H:%M:%S %Y %Z')
-        except AttributeError:
-            raise BackendException("No 'Not after' date found{0}".format(cert_filename_suffix))
-        except ValueError:
-            raise BackendException("Failed to parse 'Not after' date{0}".format(cert_filename_suffix))
+        openssl_cert_cmd = [
+            self.openssl_binary,
+            "x509",
+            "-in",
+            filename,
+            "-noout",
+            "-text",
+        ]
+        rc, out, err = self.module.run_command(
+            openssl_cert_cmd,
+            data=data,
+            check_rc=False,
+            binary_data=True,
+            environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+        )
+        if rc != 0:
+            raise BackendException(
+                "Error while running {cmd}: {stderr}".format(
+                    cmd=" ".join(openssl_cert_cmd), stderr=to_text(err)
+                )
+            )
+
+        out_text = to_text(out, errors="surrogate_or_strict")
+        not_after = _extract_date(
+            out_text, "Not After", cert_filename_suffix=cert_filename_suffix
+        )
         if now is None:
-            now = datetime.datetime.now()
+            now = self.get_now()
+        else:
+            now = ensure_utc_timezone(now)
         return (not_after - now).days
 
     def create_chain_matcher(self, criterium):
-        '''
+        """
         Given a Criterium object, creates a ChainMatcher object.
-        '''
-        raise BackendException('Alternate chain matching can only be used with the "cryptography" backend.')
+        """
+        raise BackendException(
+            'Alternate chain matching can only be used with the "cryptography" backend.'
+        )
+
+    def get_cert_information(self, cert_filename=None, cert_content=None):
+        """
+        Return some information on a X.509 certificate as a CertificateInformation object.
+        """
+        filename = cert_filename
+        data = None
+        if cert_filename is not None:
+            cert_filename_suffix = " in {0}".format(cert_filename)
+        else:
+            filename = "/dev/stdin"
+            data = to_bytes(cert_content)
+            cert_filename_suffix = ""
+
+        openssl_cert_cmd = [
+            self.openssl_binary,
+            "x509",
+            "-in",
+            filename,
+            "-noout",
+            "-text",
+        ]
+        rc, out, err = self.module.run_command(
+            openssl_cert_cmd,
+            data=data,
+            check_rc=False,
+            binary_data=True,
+            environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+        )
+        if rc != 0:
+            raise BackendException(
+                "Error while running {cmd}: {stderr}".format(
+                    cmd=" ".join(openssl_cert_cmd), stderr=to_text(err)
+                )
+            )
+
+        out_text = to_text(out, errors="surrogate_or_strict")
+
+        not_after = _extract_date(
+            out_text, "Not After", cert_filename_suffix=cert_filename_suffix
+        )
+        not_before = _extract_date(
+            out_text, "Not Before", cert_filename_suffix=cert_filename_suffix
+        )
+
+        sn = re.search(
+            r" Serial Number: ([0-9]+)",
+            to_text(out, errors="surrogate_or_strict"),
+            re.MULTILINE | re.DOTALL,
+        )
+        if sn:
+            serial = int(sn.group(1))
+        else:
+            serial = convert_bytes_to_int(
+                _extract_octets(out_text, "Serial Number", required=True)
+            )
+
+        ski = _extract_octets(out_text, "X509v3 Subject Key Identifier", required=False)
+        aki = _extract_octets(
+            out_text,
+            "X509v3 Authority Key Identifier",
+            required=False,
+            potential_prefixes=["keyid:", ""],
+        )
+
+        return CertificateInformation(
+            not_valid_after=not_after,
+            not_valid_before=not_before,
+            serial_number=serial,
+            subject_key_identifier=ski,
+            authority_key_identifier=aki,
+        )

plugins/module_utils/acme/backends.py

@@ -1,29 +1,146 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import abc
+import datetime
+import re
+from collections import namedtuple
 
 from ansible.module_utils import six
+from ansible.module_utils.common.text.converters import to_native
+from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
+    BackendException,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils.time import (
+    UTC,
+    ensure_utc_timezone,
+    from_epoch_seconds,
+    get_epoch_seconds,
+    get_now_datetime,
+    get_relative_time_option,
+    remove_timezone,
+)
+
+
+CertificateInformation = namedtuple(
+    "CertificateInformation",
+    (
+        "not_valid_after",
+        "not_valid_before",
+        "serial_number",
+        "subject_key_identifier",
+        "authority_key_identifier",
+    ),
+)
+
+
+_FRACTIONAL_MATCHER = re.compile(
+    r"^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(|\.\d+)(Z|[+-]\d{2}:?\d{2}.*)$"
+)
+
+
+def _reduce_fractional_digits(timestamp_str):
+    """
+    Given a RFC 3339 timestamp that includes too many digits for the fractional seconds part, reduces these to at most 6.
+    """
+    # RFC 3339 (https://www.rfc-editor.org/info/rfc3339)
+    m = _FRACTIONAL_MATCHER.match(timestamp_str)
+    if not m:
+        raise BackendException(
+            "Cannot parse ISO 8601 timestamp {0!r}".format(timestamp_str)
+        )
+    timestamp, fractional, timezone = m.groups()
+    if len(fractional) > 7:
+        # Python does not support anything smaller than microseconds
+        # (Golang supports nanoseconds, Boulder often emits more fractional digits, which Python chokes on)
+        fractional = fractional[:7]
+    return "%s%s%s" % (timestamp, fractional, timezone)
+
+
+def _parse_acme_timestamp(timestamp_str, with_timezone):
+    """
+    Parses a RFC 3339 timestamp.
+    """
+    # RFC 3339 (https://www.rfc-editor.org/info/rfc3339)
+    timestamp_str = _reduce_fractional_digits(timestamp_str)
+    for format in (
+        "%Y-%m-%dT%H:%M:%SZ",
+        "%Y-%m-%dT%H:%M:%S.%fZ",
+        "%Y-%m-%dT%H:%M:%S%z",
+        "%Y-%m-%dT%H:%M:%S.%f%z",
+    ):
+        # Note that %z will not work with Python 2... https://stackoverflow.com/a/27829491
+        try:
+            result = datetime.datetime.strptime(timestamp_str, format)
+        except ValueError:
+            pass
+        else:
+            return (
+                ensure_utc_timezone(result)
+                if with_timezone
+                else remove_timezone(result)
+            )
+    raise BackendException(
+        "Cannot parse ISO 8601 timestamp {0!r}".format(timestamp_str)
+    )
 
 
 @six.add_metaclass(abc.ABCMeta)
 class CryptoBackend(object):
-    def __init__(self, module):
+    def __init__(self, module, with_timezone=False):
         self.module = module
+        self._with_timezone = with_timezone
+
+    def get_now(self):
+        return get_now_datetime(with_timezone=self._with_timezone)
+
+    def parse_acme_timestamp(self, timestamp_str):
+        # RFC 3339 (https://www.rfc-editor.org/info/rfc3339)
+        return _parse_acme_timestamp(timestamp_str, with_timezone=self._with_timezone)
+
+    def parse_module_parameter(self, value, name):
+        try:
+            return get_relative_time_option(
+                value, name, backend="cryptography", with_timezone=self._with_timezone
+            )
+        except OpenSSLObjectError as exc:
+            raise BackendException(to_native(exc))
+
+    def interpolate_timestamp(self, timestamp_start, timestamp_end, percentage):
+        start = get_epoch_seconds(timestamp_start)
+        end = get_epoch_seconds(timestamp_end)
+        return from_epoch_seconds(
+            start + percentage * (end - start), with_timezone=self._with_timezone
+        )
+
+    def get_utc_datetime(self, *args, **kwargs):
+        kwargs_ext = dict(kwargs)
+        if self._with_timezone and ("tzinfo" not in kwargs_ext and len(args) < 8):
+            kwargs_ext["tzinfo"] = UTC
+        result = datetime.datetime(*args, **kwargs_ext)
+        if self._with_timezone and ("tzinfo" in kwargs or len(args) >= 8):
+            result = ensure_utc_timezone(result)
+        return result
 
     @abc.abstractmethod
     def parse_key(self, key_file=None, key_content=None, passphrase=None):
-        '''
+        """
         Parses an RSA or Elliptic Curve key file in PEM format and returns key_data.
         Raises KeyParsingError in case of errors.
-        '''
+        """
 
     @abc.abstractmethod
     def sign(self, payload64, protected64, key_data):
@@ -31,28 +148,56 @@ class CryptoBackend(object):
 
     @abc.abstractmethod
     def create_mac_key(self, alg, key):
-        '''Create a MAC key.'''
+        """Create a MAC key."""
+
+    def get_ordered_csr_identifiers(self, csr_filename=None, csr_content=None):
+        """
+        Return a list of requested identifiers (CN and SANs) for the CSR.
+        Each identifier is a pair (type, identifier), where type is either
+        'dns' or 'ip'.
+
+        The list is deduplicated, and if a CNAME is present, it will be returned
+        as the first element in the result.
+        """
+        self.module.deprecate(
+            "Every backend must override the get_ordered_csr_identifiers() method."
+            " The default implementation will be removed in 3.0.0 and this method will be marked as `abstractmethod` by then.",
+            version="3.0.0",
+            collection_name="community.crypto",
+        )
+        return sorted(
+            self.get_csr_identifiers(csr_filename=csr_filename, csr_content=csr_content)
+        )
 
     @abc.abstractmethod
     def get_csr_identifiers(self, csr_filename=None, csr_content=None):
-        '''
+        """
         Return a set of requested identifiers (CN and SANs) for the CSR.
         Each identifier is a pair (type, identifier), where type is either
         'dns' or 'ip'.
-        '''
+        """
 
     @abc.abstractmethod
     def get_cert_days(self, cert_filename=None, cert_content=None, now=None):
-        '''
+        """
         Return the days the certificate in cert_filename remains valid and -1
         if the file was not found. If cert_filename contains more than one
         certificate, only the first one will be considered.
 
         If now is not specified, datetime.datetime.now() is used.
-        '''
+        """
 
     @abc.abstractmethod
     def create_chain_matcher(self, criterium):
-        '''
+        """
         Given a Criterium object, creates a ChainMatcher object.
-        '''
+        """
+
+    def get_cert_information(self, cert_filename=None, cert_content=None):
+        """
+        Return some information on a X.509 certificate as a CertificateInformation object.
+        """
+        # Not implementing this method in a backend is DEPRECATED and will be
+        # disallowed in community.crypto 3.0.0. This method will be marked as
+        # @abstractmethod by then.
+        raise BackendException("This backend does not support get_cert_information()")

plugins/module_utils/acme/certificate.py

@@ -0,0 +1,337 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+import os
+
+from ansible_collections.community.crypto.plugins.module_utils.acme.account import (
+    ACMEAccount,
+)
+from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
+    ACMEClient,
+)
+from ansible_collections.community.crypto.plugins.module_utils.acme.certificates import (
+    CertificateChain,
+    Criterium,
+)
+from ansible_collections.community.crypto.plugins.module_utils.acme.challenges import (
+    Authorization,
+    wait_for_validation,
+)
+from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
+    ModuleFailException,
+)
+from ansible_collections.community.crypto.plugins.module_utils.acme.io import write_file
+from ansible_collections.community.crypto.plugins.module_utils.acme.orders import Order
+from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
+    pem_to_der,
+)
+
+
+class ACMECertificateClient(object):
+    """
+    ACME v2 client class. Uses an ACME account object and a CSR to
+    start and validate ACME challenges and download the respective
+    certificates.
+    """
+
+    def __init__(self, module, backend, client=None, account=None):
+        self.module = module
+        self.version = module.params["acme_version"]
+        self.csr = module.params.get("csr")
+        self.csr_content = module.params.get("csr_content")
+        if client is None:
+            client = ACMEClient(module, backend)
+        self.client = client
+        if account is None:
+            account = ACMEAccount(self.client)
+        self.account = account
+        self.order_uri = module.params.get("order_uri")
+        self.order_creation_error_strategy = module.params.get(
+            "order_creation_error_strategy", "auto"
+        )
+        self.order_creation_max_retries = module.params.get(
+            "order_creation_max_retries", 3
+        )
+
+        # Make sure account exists
+        dummy, account_data = self.account.setup_account(allow_creation=False)
+        if account_data is None:
+            raise ModuleFailException(msg="Account does not exist or is deactivated.")
+
+        if self.csr is not None and not os.path.exists(self.csr):
+            raise ModuleFailException("CSR %s not found" % (self.csr))
+
+        # Extract list of identifiers from CSR
+        if self.csr is not None or self.csr_content is not None:
+            self.identifiers = self.client.backend.get_ordered_csr_identifiers(
+                csr_filename=self.csr, csr_content=self.csr_content
+            )
+        else:
+            self.identifiers = None
+
+    def parse_select_chain(self, select_chain):
+        select_chain_matcher = []
+        if select_chain:
+            for criterium_idx, criterium in enumerate(select_chain):
+                try:
+                    select_chain_matcher.append(
+                        self.client.backend.create_chain_matcher(
+                            Criterium(criterium, index=criterium_idx)
+                        )
+                    )
+                except ValueError as exc:
+                    self.module.warn(
+                        "Error while parsing criterium: {error}. Ignoring criterium.".format(
+                            error=exc
+                        )
+                    )
+        return select_chain_matcher
+
+    def load_order(self):
+        if not self.order_uri:
+            raise ModuleFailException("The order URI has not been provided")
+        order = Order.from_url(self.client, self.order_uri)
+        order.load_authorizations(self.client)
+        return order
+
+    def create_order(self, replaces_cert_id=None, profile=None):
+        """
+        Create a new order.
+        """
+        if self.identifiers is None:
+            raise ModuleFailException("No identifiers have been provided")
+        order = Order.create_with_error_handling(
+            self.client,
+            self.identifiers,
+            error_strategy=self.order_creation_error_strategy,
+            error_max_retries=self.order_creation_max_retries,
+            replaces_cert_id=replaces_cert_id,
+            profile=profile,
+            message_callback=self.module.warn,
+        )
+        self.order_uri = order.url
+        order.load_authorizations(self.client)
+        return order
+
+    def get_challenges_data(self, order):
+        """
+        Get challenge details.
+
+        Return a tuple of generic challenge details, and specialized DNS challenge details.
+        """
+        # Get general challenge data
+        data = []
+        for authz in order.authorizations.values():
+            # Skip valid authentications: their challenges are already valid
+            # and do not need to be returned
+            if authz.status == "valid":
+                continue
+            data.append(
+                dict(
+                    identifier=authz.identifier,
+                    identifier_type=authz.identifier_type,
+                    challenges=authz.get_challenge_data(self.client),
+                )
+            )
+        # Get DNS challenge data
+        data_dns = {}
+        dns_challenge_type = "dns-01"
+        for entry in data:
+            dns_challenge = entry["challenges"].get(dns_challenge_type)
+            if dns_challenge:
+                values = data_dns.get(dns_challenge["record"])
+                if values is None:
+                    values = []
+                    data_dns[dns_challenge["record"]] = values
+                values.append(dns_challenge["resource_value"])
+        return data, data_dns
+
+    def check_that_authorizations_can_be_used(self, order):
+        bad_authzs = []
+        for authz in order.authorizations.values():
+            if authz.status not in ("valid", "pending"):
+                bad_authzs.append(
+                    "{authz} (status={status!r})".format(
+                        authz=authz.combined_identifier,
+                        status=authz.status,
+                    )
+                )
+        if bad_authzs:
+            raise ModuleFailException(
+                "Some of the authorizations for the order are in a bad state, so the order"
+                " can no longer be satisfied: {bad_authzs}".format(
+                    bad_authzs=", ".join(sorted(bad_authzs)),
+                ),
+            )
+
+    def collect_invalid_authzs(self, order):
+        return [
+            authz
+            for authz in order.authorizations.values()
+            if authz.status == "invalid"
+        ]
+
+    def collect_pending_authzs(self, order):
+        return [
+            authz
+            for authz in order.authorizations.values()
+            if authz.status == "pending"
+        ]
+
+    def call_validate(self, pending_authzs, get_challenge, wait=True):
+        authzs_with_challenges_to_wait_for = []
+        for authz in pending_authzs:
+            challenge_type = get_challenge(authz)
+            authz.call_validate(self.client, challenge_type, wait=wait)
+            authzs_with_challenges_to_wait_for.append(
+                (authz, challenge_type, authz.find_challenge(challenge_type))
+            )
+        return authzs_with_challenges_to_wait_for
+
+    def wait_for_validation(self, authzs_to_wait_for):
+        wait_for_validation(authzs_to_wait_for, self.client)
+
+    def _download_alternate_chains(self, cert):
+        alternate_chains = []
+        for alternate in cert.alternates:
+            try:
+                alt_cert = CertificateChain.download(self.client, alternate)
+            except ModuleFailException as e:
+                self.module.warn(
+                    "Error while downloading alternative certificate {0}: {1}".format(
+                        alternate, e
+                    )
+                )
+                continue
+            if alt_cert.cert is not None:
+                alternate_chains.append(alt_cert)
+            else:
+                self.module.warn(
+                    "Error while downloading alternative certificate {0}: no certificate found".format(
+                        alternate
+                    )
+                )
+        return alternate_chains
+
+    def download_certificate(self, order, download_all_chains=True):
+        """
+        Download certificate from a valid oder.
+        """
+        if order.status != "valid":
+            raise ModuleFailException(
+                "The order must be valid, but has state {state!r}!".format(
+                    state=order.state
+                )
+            )
+
+        if not order.certificate_uri:
+            raise ModuleFailException(
+                "Order's crtificate URL {url!r} is empty!".format(
+                    url=order.certificate_uri
+                )
+            )
+
+        cert = CertificateChain.download(self.client, order.certificate_uri)
+        if cert.cert is None:
+            raise ModuleFailException(
+                "Certificate at {url} is empty!".format(url=order.certificate_uri)
+            )
+
+        alternate_chains = None
+        if download_all_chains:
+            alternate_chains = self._download_alternate_chains(cert)
+
+        return cert, alternate_chains
+
+    def get_certificate(self, order, download_all_chains=True):
+        """
+        Request a new certificate and downloads it, and optionally all certificate chains.
+        First verifies whether all authorizations are valid; if not, aborts with an error.
+        """
+        if self.csr is None and self.csr_content is None:
+            raise ModuleFailException("No CSR has been provided")
+        for identifier, authz in order.authorizations.items():
+            if authz.status != "valid":
+                authz.raise_error(
+                    'Status is {status!r} and not "valid"'.format(status=authz.status),
+                    module=self.module,
+                )
+
+        order.finalize(self.client, pem_to_der(self.csr, self.csr_content))
+
+        return self.download_certificate(order, download_all_chains=download_all_chains)
+
+    def find_matching_chain(self, chains, select_chain_matcher):
+        for criterium_idx, matcher in enumerate(select_chain_matcher):
+            for chain in chains:
+                if matcher.match(chain):
+                    self.module.debug(
+                        "Found matching chain for criterium {0}".format(criterium_idx)
+                    )
+                    return chain
+        return None
+
+    def write_cert_chain(
+        self, cert, cert_dest=None, fullchain_dest=None, chain_dest=None
+    ):
+        changed = False
+
+        if cert_dest and write_file(self.module, cert_dest, cert.cert.encode("utf8")):
+            changed = True
+
+        if fullchain_dest and write_file(
+            self.module,
+            fullchain_dest,
+            (cert.cert + "\n".join(cert.chain)).encode("utf8"),
+        ):
+            changed = True
+
+        if chain_dest and write_file(
+            self.module, chain_dest, ("\n".join(cert.chain)).encode("utf8")
+        ):
+            changed = True
+
+        return changed
+
+    def deactivate_authzs(self, order):
+        """
+        Deactivates all valid authz's. Does not raise exceptions.
+        https://community.letsencrypt.org/t/authorization-deactivation/19860/2
+        https://tools.ietf.org/html/rfc8555#section-7.5.2
+        """
+        if len(order.authorization_uris) > len(order.authorizations):
+            for authz_uri in order.authorization_uris:
+                authz = None
+                try:
+                    authz = Authorization.deactivate_url(self.client, authz_uri)
+                except Exception:
+                    # ignore errors
+                    pass
+                if authz is None or authz.status != "deactivated":
+                    self.module.warn(
+                        warning="Could not deactivate authz object {0}.".format(
+                            authz_uri
+                        )
+                    )
+        else:
+            for authz in order.authorizations.values():
+                try:
+                    authz.deactivate(self.client)
+                except Exception:
+                    # ignore errors
+                    pass
+                if authz.status != "deactivated":
+                    self.module.warn(
+                        warning="Could not deactivate authz object {0}.".format(
+                            authz.url
+                        )
+                    )

plugins/module_utils/acme/certificates.py

@@ -1,37 +1,37 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import abc
 
 from ansible.module_utils import six
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
     ModuleFailException,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
     der_to_pem,
     nopad_b64,
     process_links,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import (
     split_pem_list,
 )
 
 
 class CertificateChain(object):
-    '''
+    """
     Download and parse the certificate chain.
     https://tools.ietf.org/html/rfc8555#section-7.4.2
-    '''
+    """
 
     def __init__(self, url):
         self.url = url
@@ -41,86 +41,106 @@ class CertificateChain(object):
 
     @classmethod
     def download(cls, client, url):
-        content, info = client.get_request(url, parse_json_result=False, headers={'Accept': 'application/pem-certificate-chain'})
+        content, info = client.get_request(
+            url,
+            parse_json_result=False,
+            headers={"Accept": "application/pem-certificate-chain"},
+        )
 
-        if not content or not info['content-type'].startswith('application/pem-certificate-chain'):
+        if not content or not info["content-type"].startswith(
+            "application/pem-certificate-chain"
+        ):
             raise ModuleFailException(
                 "Cannot download certificate chain from {0}, as content type is not application/pem-certificate-chain: {1} (headers: {2})".format(
-                    url, content, info))
+                    url, content, info
+                )
+            )
 
         result = cls(url)
 
         # Parse data
-        certs = split_pem_list(content.decode('utf-8'), keep_inbetween=True)
+        certs = split_pem_list(content.decode("utf-8"), keep_inbetween=True)
         if certs:
             result.cert = certs[0]
             result.chain = certs[1:]
 
-        process_links(info, lambda link, relation: result._process_links(client, link, relation))
+        process_links(
+            info, lambda link, relation: result._process_links(client, link, relation)
+        )
 
         if result.cert is None:
-            raise ModuleFailException("Failed to parse certificate chain download from {0}: {1} (headers: {2})".format(url, content, info))
+            raise ModuleFailException(
+                "Failed to parse certificate chain download from {0}: {1} (headers: {2})".format(
+                    url, content, info
+                )
+            )
 
         return result
 
     def _process_links(self, client, link, relation):
-        if relation == 'up':
+        if relation == "up":
             # Process link-up headers if there was no chain in reply
             if not self.chain:
-                chain_result, chain_info = client.get_request(link, parse_json_result=False)
-                if chain_info['status'] in [200, 201]:
+                chain_result, chain_info = client.get_request(
+                    link, parse_json_result=False
+                )
+                if chain_info["status"] in [200, 201]:
                     self.chain.append(der_to_pem(chain_result))
-        elif relation == 'alternate':
+        elif relation == "alternate":
             self.alternates.append(link)
 
     def to_json(self):
-        cert = self.cert.encode('utf8')
-        chain = ('\n'.join(self.chain)).encode('utf8')
+        cert = self.cert.encode("utf8")
+        chain = ("\n".join(self.chain)).encode("utf8")
         return {
-            'cert': cert,
-            'chain': chain,
-            'full_chain': cert + chain,
+            "cert": cert,
+            "chain": chain,
+            "full_chain": cert + chain,
         }
 
 
 class Criterium(object):
     def __init__(self, criterium, index=None):
         self.index = index
-        self.test_certificates = criterium['test_certificates']
-        self.subject = criterium['subject']
-        self.issuer = criterium['issuer']
-        self.subject_key_identifier = criterium['subject_key_identifier']
-        self.authority_key_identifier = criterium['authority_key_identifier']
+        self.test_certificates = criterium["test_certificates"]
+        self.subject = criterium["subject"]
+        self.issuer = criterium["issuer"]
+        self.subject_key_identifier = criterium["subject_key_identifier"]
+        self.authority_key_identifier = criterium["authority_key_identifier"]
 
 
 @six.add_metaclass(abc.ABCMeta)
 class ChainMatcher(object):
     @abc.abstractmethod
     def match(self, certificate):
-        '''
+        """
         Check whether a certificate chain (CertificateChain instance) matches.
-        '''
+        """
 
 
 def retrieve_acme_v1_certificate(client, csr_der):
-    '''
+    """
     Create a new certificate based on the CSR (ACME v1 protocol).
     Return the certificate object as dict
     https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.5
-    '''
+    """
     new_cert = {
         "resource": "new-cert",
         "csr": nopad_b64(csr_der),
     }
     result, info = client.send_signed_request(
-        client.directory['new-cert'], new_cert, error_msg='Failed to receive certificate', expected_status_codes=[200, 201])
-    cert = CertificateChain(info['location'])
+        client.directory["new-cert"],
+        new_cert,
+        error_msg="Failed to receive certificate",
+        expected_status_codes=[200, 201],
+    )
+    cert = CertificateChain(info["location"])
     cert.cert = der_to_pem(result)
 
     def f(link, relation):
-        if relation == 'up':
+        if relation == "up":
             chain_result, chain_info = client.get_request(link, parse_json_result=False)
-            if chain_info['status'] in [200, 201]:
+            if chain_info["status"] in [200, 201]:
                 del cert.chain[:]
                 cert.chain.append(der_to_pem(chain_result))
 

plugins/module_utils/acme/challenges.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
@@ -15,39 +18,53 @@ import re
 import time
 
 from ansible.module_utils.common.text.converters import to_bytes
-
-from ansible_collections.community.crypto.plugins.module_utils.compat import ipaddress as compat_ipaddress
-
+from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
+    ACMEProtocolException,
+    ModuleFailException,
+    format_error_problem,
+)
 from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
     nopad_b64,
 )
 
-from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
-    format_error_problem,
-    ACMEProtocolException,
-    ModuleFailException,
-)
+
+try:
+    import ipaddress
+except ImportError:
+    pass
 
 
 def create_key_authorization(client, token):
-    '''
+    """
     Returns the key authorization for the given token
     https://tools.ietf.org/html/rfc8555#section-8.1
-    '''
-    accountkey_json = json.dumps(client.account_jwk, sort_keys=True, separators=(',', ':'))
-    thumbprint = nopad_b64(hashlib.sha256(accountkey_json.encode('utf8')).digest())
+    """
+    accountkey_json = json.dumps(
+        client.account_jwk, sort_keys=True, separators=(",", ":")
+    )
+    thumbprint = nopad_b64(hashlib.sha256(accountkey_json.encode("utf8")).digest())
     return "{0}.{1}".format(token, thumbprint)
 
 
 def combine_identifier(identifier_type, identifier):
-    return '{type}:{identifier}'.format(type=identifier_type, identifier=identifier)
+    return "{type}:{identifier}".format(type=identifier_type, identifier=identifier)
+
+
+def normalize_combined_identifier(identifier):
+    identifier_type, identifier = split_identifier(identifier)
+    # Normalize DNS names and IPs
+    identifier = identifier.lower()
+    return combine_identifier(identifier_type, identifier)
 
 
 def split_identifier(identifier):
-    parts = identifier.split(':', 1)
+    parts = identifier.split(":", 1)
     if len(parts) != 2:
         raise ModuleFailException(
-            'Identifier "{identifier}" is not of the form <type>:<identifier>'.format(identifier=identifier))
+            'Identifier "{identifier}" is not of the form <type>:<identifier>'.format(
+                identifier=identifier
+            )
+        )
     return parts
 
 
@@ -55,27 +72,27 @@ class Challenge(object):
     def __init__(self, data, url):
         self.data = data
 
-        self.type = data['type']
+        self.type = data["type"]
         self.url = url
-        self.status = data['status']
-        self.token = data.get('token')
+        self.status = data["status"]
+        self.token = data.get("token")
 
     @classmethod
     def from_json(cls, client, data, url=None):
-        return cls(data, url or (data['uri'] if client.version == 1 else data['url']))
+        return cls(data, url or (data["uri"] if client.version == 1 else data["url"]))
 
     def call_validate(self, client):
         challenge_response = {}
         if client.version == 1:
             token = re.sub(r"[^A-Za-z0-9_\-]", "_", self.token)
             key_authorization = create_key_authorization(client, token)
-            challenge_response['resource'] = 'challenge'
-            challenge_response['keyAuthorization'] = key_authorization
-            challenge_response['type'] = self.type
+            challenge_response["resource"] = "challenge"
+            challenge_response["keyAuthorization"] = key_authorization
+            challenge_response["type"] = self.type
         client.send_signed_request(
             self.url,
             challenge_response,
-            error_msg='Failed to validate challenge',
+            error_msg="Failed to validate challenge",
             expected_status_codes=[200, 202],
         )
 
@@ -86,40 +103,44 @@ class Challenge(object):
         token = re.sub(r"[^A-Za-z0-9_\-]", "_", self.token)
         key_authorization = create_key_authorization(client, token)
 
-        if self.type == 'http-01':
+        if self.type == "http-01":
             # https://tools.ietf.org/html/rfc8555#section-8.3
             return {
-                'resource': '.well-known/acme-challenge/{token}'.format(token=token),
-                'resource_value': key_authorization,
+                "resource": ".well-known/acme-challenge/{token}".format(token=token),
+                "resource_value": key_authorization,
             }
 
-        if self.type == 'dns-01':
-            if identifier_type != 'dns':
+        if self.type == "dns-01":
+            if identifier_type != "dns":
                 return None
             # https://tools.ietf.org/html/rfc8555#section-8.4
-            resource = '_acme-challenge'
+            resource = "_acme-challenge"
             value = nopad_b64(hashlib.sha256(to_bytes(key_authorization)).digest())
-            record = (resource + identifier[1:]) if identifier.startswith('*.') else '{0}.{1}'.format(resource, identifier)
+            record = "{0}.{1}".format(
+                resource, identifier[2:] if identifier.startswith("*.") else identifier
+            )
             return {
-                'resource': resource,
-                'resource_value': value,
-                'record': record,
+                "resource": resource,
+                "resource_value": value,
+                "record": record,
             }
 
-        if self.type == 'tls-alpn-01':
+        if self.type == "tls-alpn-01":
             # https://www.rfc-editor.org/rfc/rfc8737.html#section-3
-            if identifier_type == 'ip':
+            if identifier_type == "ip":
                 # IPv4/IPv6 address: use reverse mapping (RFC1034, RFC3596)
-                resource = compat_ipaddress.ip_address(identifier).reverse_pointer
-                if not resource.endswith('.'):
-                    resource += '.'
+                resource = ipaddress.ip_address(identifier).reverse_pointer
+                if not resource.endswith("."):
+                    resource += "."
             else:
                 resource = identifier
-            value = base64.b64encode(hashlib.sha256(to_bytes(key_authorization)).digest())
+            value = base64.b64encode(
+                hashlib.sha256(to_bytes(key_authorization)).digest()
+            )
             return {
-                'resource': resource,
-                'resource_original': combine_identifier(identifier_type, identifier),
-                'resource_value': value,
+                "resource": resource,
+                "resource_original": combine_identifier(identifier_type, identifier),
+                "resource_value": value,
             }
 
         # Unknown challenge type: ignore
@@ -128,20 +149,28 @@ class Challenge(object):
 
 class Authorization(object):
     def _setup(self, client, data):
-        data['uri'] = self.url
+        data["uri"] = self.url
         self.data = data
-        self.challenges = [Challenge.from_json(client, challenge) for challenge in data['challenges']]
-        if client.version == 1 and 'status' not in data:
+        # While 'challenges' is a required field, apparently not every CA cares
+        # (https://github.com/ansible-collections/community.crypto/issues/824)
+        if data.get("challenges"):
+            self.challenges = [
+                Challenge.from_json(client, challenge)
+                for challenge in data["challenges"]
+            ]
+        else:
+            self.challenges = []
+        if client.version == 1 and "status" not in data:
             # https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.1.2
             # "status (required, string): ...
             # If this field is missing, then the default value is "pending"."
-            self.status = 'pending'
+            self.status = "pending"
         else:
-            self.status = data['status']
-        self.identifier = data['identifier']['value']
-        self.identifier_type = data['identifier']['type']
-        if data.get('wildcard', False):
-            self.identifier = '*.{0}'.format(self.identifier)
+            self.status = data["status"]
+        self.identifier = data["identifier"]["value"]
+        self.identifier_type = data["identifier"]["type"]
+        if data.get("wildcard", False):
+            self.identifier = "*.{0}".format(self.identifier)
 
     def __init__(self, url):
         self.url = url
@@ -166,11 +195,11 @@ class Authorization(object):
 
     @classmethod
     def create(cls, client, identifier_type, identifier):
-        '''
+        """
         Create a new authorization for the given identifier.
         Return the authorization object of the new authorization
         https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.4
-        '''
+        """
         new_authz = {
             "identifier": {
                 "type": identifier_type,
@@ -178,16 +207,22 @@ class Authorization(object):
             },
         }
         if client.version == 1:
-            url = client.directory['new-authz']
+            url = client.directory["new-authz"]
             new_authz["resource"] = "new-authz"
         else:
-            if 'newAuthz' not in client.directory.directory:
-                raise ACMEProtocolException(client.module, 'ACME endpoint does not support pre-authorization')
-            url = client.directory['newAuthz']
+            if "newAuthz" not in client.directory.directory:
+                raise ACMEProtocolException(
+                    client.module, "ACME endpoint does not support pre-authorization"
+                )
+            url = client.directory["newAuthz"]
 
         result, info = client.send_signed_request(
-            url, new_authz, error_msg='Failed to request challenges', expected_status_codes=[200, 201])
-        return cls.from_json(client, result, info['location'])
+            url,
+            new_authz,
+            error_msg="Failed to request challenges",
+            expected_status_codes=[200, 201],
+        )
+        return cls.from_json(client, result, info["location"])
 
     @property
     def combined_identifier(self):
@@ -203,39 +238,44 @@ class Authorization(object):
         return changed
 
     def get_challenge_data(self, client):
-        '''
+        """
         Returns a dict with the data for all proposed (and supported) challenges
         of the given authorization.
-        '''
+        """
         data = {}
         for challenge in self.challenges:
-            validation_data = challenge.get_validation_data(client, self.identifier_type, self.identifier)
+            validation_data = challenge.get_validation_data(
+                client, self.identifier_type, self.identifier
+            )
             if validation_data is not None:
                 data[challenge.type] = validation_data
         return data
 
     def raise_error(self, error_msg, module=None):
-        '''
+        """
         Aborts with a specific error for a challenge.
-        '''
+        """
         error_details = []
         # multiple challenges could have failed at this point, gather error
         # details for all of them before failing
         for challenge in self.challenges:
-            if challenge.status == 'invalid':
-                msg = 'Challenge {type}'.format(type=challenge.type)
-                if 'error' in challenge.data:
-                    msg = '{msg}: {problem}'.format(
+            if challenge.status == "invalid":
+                msg = "Challenge {type}".format(type=challenge.type)
+                if "error" in challenge.data:
+                    msg = "{msg}: {problem}".format(
                         msg=msg,
-                        problem=format_error_problem(challenge.data['error'], subproblem_prefix='{0}.'.format(challenge.type)),
+                        problem=format_error_problem(
+                            challenge.data["error"],
+                            subproblem_prefix="{0}.".format(challenge.type),
+                        ),
                     )
                 error_details.append(msg)
         raise ACMEProtocolException(
             module,
-            'Failed to validate challenge for {identifier}: {error}. {details}'.format(
+            "Failed to validate challenge for {identifier}: {error}. {details}".format(
                 identifier=self.combined_identifier,
                 error=error_msg,
-                details='; '.join(error_details),
+                details="; ".join(error_details),
             ),
             extras=dict(
                 identifier=self.combined_identifier,
@@ -252,48 +292,93 @@ class Authorization(object):
     def wait_for_validation(self, client, callenge_type):
         while True:
             self.refresh(client)
-            if self.status in ['valid', 'invalid', 'revoked']:
+            if self.status in ["valid", "invalid", "revoked"]:
                 break
             time.sleep(2)
 
-        if self.status == 'invalid':
+        if self.status == "invalid":
             self.raise_error('Status is "invalid"', module=client.module)
 
-        return self.status == 'valid'
+        return self.status == "valid"
 
     def call_validate(self, client, challenge_type, wait=True):
-        '''
+        """
         Validate the authorization provided in the auth dict. Returns True
         when the validation was successful and False when it was not.
-        '''
+        """
         challenge = self.find_challenge(challenge_type)
         if challenge is None:
-            raise ModuleFailException('Found no challenge of type "{challenge}" for identifier {identifier}!'.format(
-                challenge=challenge_type,
-                identifier=self.combined_identifier,
-            ))
+            raise ModuleFailException(
+                'Found no challenge of type "{challenge}" for identifier {identifier}!'.format(
+                    challenge=challenge_type,
+                    identifier=self.combined_identifier,
+                )
+            )
 
         challenge.call_validate(client)
 
         if not wait:
-            return self.status == 'valid'
+            return self.status == "valid"
         return self.wait_for_validation(client, challenge_type)
 
-    def deactivate(self, client):
-        '''
+    def can_deactivate(self):
+        """
         Deactivates this authorization.
         https://community.letsencrypt.org/t/authorization-deactivation/19860/2
         https://tools.ietf.org/html/rfc8555#section-7.5.2
-        '''
-        if self.status != 'valid':
+        """
+        return self.status in ("valid", "pending")
+
+    def deactivate(self, client):
+        """
+        Deactivates this authorization.
+        https://community.letsencrypt.org/t/authorization-deactivation/19860/2
+        https://tools.ietf.org/html/rfc8555#section-7.5.2
+        """
+        if not self.can_deactivate():
             return
-        authz_deactivate = {
-            'status': 'deactivated'
-        }
+        authz_deactivate = {"status": "deactivated"}
         if client.version == 1:
-            authz_deactivate['resource'] = 'authz'
-        result, info = client.send_signed_request(self.url, authz_deactivate, fail_on_error=False)
-        if 200 <= info['status'] < 300 and result.get('status') == 'deactivated':
-            self.status = 'deactivated'
+            authz_deactivate["resource"] = "authz"
+        result, info = client.send_signed_request(
+            self.url, authz_deactivate, fail_on_error=False
+        )
+        if 200 <= info["status"] < 300 and result.get("status") == "deactivated":
+            self.status = "deactivated"
             return True
         return False
+
+    @classmethod
+    def deactivate_url(cls, client, url):
+        """
+        Deactivates this authorization.
+        https://community.letsencrypt.org/t/authorization-deactivation/19860/2
+        https://tools.ietf.org/html/rfc8555#section-7.5.2
+        """
+        authz = cls(url)
+        authz_deactivate = {"status": "deactivated"}
+        if client.version == 1:
+            authz_deactivate["resource"] = "authz"
+        result, info = client.send_signed_request(
+            url, authz_deactivate, fail_on_error=True
+        )
+        authz._setup(client, result)
+        return authz
+
+
+def wait_for_validation(authzs, client):
+    """
+    Wait until a list of authz is valid. Fail if at least one of them is invalid or revoked.
+    """
+    while authzs:
+        authzs_next = []
+        for authz in authzs:
+            authz.refresh(client)
+            if authz.status in ["valid", "invalid", "revoked"]:
+                if authz.status != "valid":
+                    authz.raise_error('Status is not "valid"', module=client.module)
+            else:
+                authzs_next.append(authz)
+        if authzs_next:
+            time.sleep(2)
+        authzs = authzs_next

plugins/module_utils/acme/errors.py

@@ -1,43 +1,60 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
-from ansible.module_utils.six import binary_type
 from ansible.module_utils.common.text.converters import to_text
+from ansible.module_utils.six import PY3, binary_type
+from ansible.module_utils.six.moves.http_client import responses as http_responses
 
 
-def format_error_problem(problem, subproblem_prefix=''):
-    if 'title' in problem:
+def format_http_status(status_code):
+    expl = http_responses.get(status_code)
+    if not expl:
+        return str(status_code)
+    return "%d %s" % (status_code, expl)
+
+
+def format_error_problem(problem, subproblem_prefix=""):
+    error_type = problem.get(
+        "type", "about:blank"
+    )  # https://www.rfc-editor.org/rfc/rfc7807#section-3.1
+    if "title" in problem:
         msg = 'Error "{title}" ({type})'.format(
-            type=problem['type'],
-            title=problem['title'],
+            type=error_type,
+            title=problem["title"],
         )
     else:
-        msg = 'Error {type}'.format(type=problem['type'])
-    if 'detail' in problem:
-        msg += ': "{detail}"'.format(detail=problem['detail'])
-    subproblems = problem.get('subproblems')
+        msg = "Error {type}".format(type=error_type)
+    if "detail" in problem:
+        msg += ': "{detail}"'.format(detail=problem["detail"])
+    subproblems = problem.get("subproblems")
     if subproblems is not None:
-        msg = '{msg} Subproblems:'.format(msg=msg)
+        msg = "{msg} Subproblems:".format(msg=msg)
         for index, problem in enumerate(subproblems):
-            index_str = '{prefix}{index}'.format(prefix=subproblem_prefix, index=index)
-            msg = '{msg}\n({index}) {problem}'.format(
+            index_str = "{prefix}{index}".format(prefix=subproblem_prefix, index=index)
+            msg = "{msg}\n({index}) {problem}".format(
                 msg=msg,
                 index=index_str,
-                problem=format_error_problem(problem, subproblem_prefix='{0}.'.format(index_str)),
+                problem=format_error_problem(
+                    problem, subproblem_prefix="{0}.".format(index_str)
+                ),
             )
     return msg
 
 
 class ModuleFailException(Exception):
-    '''
+    """
     If raised, module.fail_json() will be called with the given parameters after cleanup.
-    '''
+    """
+
     def __init__(self, msg, **args):
         super(ModuleFailException, self).__init__(self, msg)
         self.msg = msg
@@ -48,13 +65,26 @@ class ModuleFailException(Exception):
 
 
 class ACMEProtocolException(ModuleFailException):
-    def __init__(self, module, msg=None, info=None, response=None, content=None, content_json=None, extras=None):
+    def __init__(
+        self,
+        module,
+        msg=None,
+        info=None,
+        response=None,
+        content=None,
+        content_json=None,
+        extras=None,
+    ):
         # Try to get hold of content, if response is given and content is not provided
         if content is None and content_json is None and response is not None:
             try:
+                # In Python 2, reading from a closed response yields a TypeError.
+                # In Python 3, read() simply returns ''
+                if PY3 and response.closed:
+                    raise TypeError
                 content = response.read()
-            except AttributeError:
-                content = info.pop('body', None)
+            except (AttributeError, TypeError):
+                content = info.pop("body", None)
 
         # Make sure that content_json is None or a dictionary
         if content_json is not None and not isinstance(content_json, dict):
@@ -66,55 +96,84 @@ class ACMEProtocolException(ModuleFailException):
         if content_json is None and content is not None and module is not None:
             try:
                 content_json = module.from_json(to_text(content))
-            except Exception as e:
+            except Exception:
                 pass
 
         extras = extras or dict()
+        error_code = None
+        error_type = None
 
         if msg is None:
-            msg = 'ACME request failed'
-        add_msg = ''
+            msg = "ACME request failed"
+        add_msg = ""
 
         if info is not None:
-            url = info['url']
-            code = info['status']
-            extras['http_url'] = url
-            extras['http_status'] = code
-            if code is not None and code >= 400 and content_json is not None and 'type' in content_json:
-                if 'status' in content_json and content_json['status'] != code:
-                    code = 'status {problem_code} (HTTP status: {http_code})'.format(http_code=code, problem_code=content_json['status'])
+            url = info["url"]
+            code = info["status"]
+            extras["http_url"] = url
+            extras["http_status"] = code
+            error_code = code
+            if (
+                code is not None
+                and code >= 400
+                and content_json is not None
+                and "type" in content_json
+            ):
+                error_type = content_json["type"]
+                if "status" in content_json and content_json["status"] != code:
+                    code_msg = (
+                        "status {problem_code} (HTTP status: {http_code})".format(
+                            http_code=format_http_status(code),
+                            problem_code=content_json["status"],
+                        )
+                    )
                 else:
-                    code = 'status {problem_code}'.format(problem_code=code)
-                subproblems = content_json.pop('subproblems', None)
-                add_msg = ' {problem}.'.format(problem=format_error_problem(content_json))
-                extras['problem'] = content_json
-                extras['subproblems'] = subproblems or []
+                    code_msg = "status {problem_code}".format(
+                        problem_code=format_http_status(code)
+                    )
+                    if code == -1 and info.get("msg"):
+                        code_msg = "error: {msg}".format(msg=info["msg"])
+                subproblems = content_json.pop("subproblems", None)
+                add_msg = " {problem}.".format(
+                    problem=format_error_problem(content_json)
+                )
+                extras["problem"] = content_json
+                extras["subproblems"] = subproblems or []
                 if subproblems is not None:
-                    add_msg = '{add_msg} Subproblems:'.format(add_msg=add_msg)
+                    add_msg = "{add_msg} Subproblems:".format(add_msg=add_msg)
                     for index, problem in enumerate(subproblems):
-                        add_msg = '{add_msg}\n({index}) {problem}.'.format(
+                        add_msg = "{add_msg}\n({index}) {problem}.".format(
                             add_msg=add_msg,
                             index=index,
-                            problem=format_error_problem(problem, subproblem_prefix='{0}.'.format(index)),
+                            problem=format_error_problem(
+                                problem, subproblem_prefix="{0}.".format(index)
+                            ),
                         )
             else:
-                code = 'HTTP status {code}'.format(code=code)
+                code_msg = "HTTP status {code}".format(code=format_http_status(code))
+                if code == -1 and info.get("msg"):
+                    code_msg = "error: {msg}".format(msg=info["msg"])
                 if content_json is not None:
-                    add_msg = ' The JSON error result: {content}'.format(content=content_json)
+                    add_msg = " The JSON error result: {content}".format(
+                        content=content_json
+                    )
                 elif content is not None:
-                    add_msg = ' The raw error result: {content}'.format(content=to_text(content))
-            msg = '{msg} for {url} with {code}'.format(msg=msg, url=url, code=code)
+                    add_msg = " The raw error result: {content}".format(
+                        content=to_text(content)
+                    )
+            msg = "{msg} for {url} with {code}".format(msg=msg, url=url, code=code_msg)
         elif content_json is not None:
-            add_msg = ' The JSON result: {content}'.format(content=content_json)
+            add_msg = " The JSON result: {content}".format(content=content_json)
         elif content is not None:
-            add_msg = ' The raw result: {content}'.format(content=to_text(content))
+            add_msg = " The raw result: {content}".format(content=to_text(content))
 
         super(ACMEProtocolException, self).__init__(
-            '{msg}.{add_msg}'.format(msg=msg, add_msg=add_msg),
-            **extras
+            "{msg}.{add_msg}".format(msg=msg, add_msg=add_msg), **extras
         )
         self.problem = {}
         self.subproblems = []
+        self.error_code = error_code
+        self.error_type = error_type
         for k, v in extras.items():
             setattr(self, k, v)
 

plugins/module_utils/acme/io.py

@@ -1,11 +1,14 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2013, Romeo Theriault <romeot () hawaii.edu>
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2013, Romeo Theriault <romeot () hawaii.edu>
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
@@ -15,13 +18,14 @@ import tempfile
 import traceback
 
 from ansible.module_utils.common.text.converters import to_native
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.errors import ModuleFailException
+from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
+    ModuleFailException,
+)
 
 
-def read_file(fn, mode='b'):
+def read_file(fn, mode="b"):
     try:
-        with open(fn, 'r' + mode) as f:
+        with open(fn, "r" + mode) as f:
             return f.read()
     except Exception as e:
         raise ModuleFailException('Error while reading file "{0}": {1}'.format(fn, e))
@@ -29,23 +33,26 @@ def read_file(fn, mode='b'):
 
 # This function was adapted from an earlier version of https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/uri.py
 def write_file(module, dest, content):
-    '''
+    """
     Write content to destination file dest, only if the content
     has changed.
-    '''
+    """
     changed = False
     # create a tempfile
     fd, tmpsrc = tempfile.mkstemp(text=False)
-    f = os.fdopen(fd, 'wb')
+    f = os.fdopen(fd, "wb")
     try:
         f.write(content)
     except Exception as err:
         try:
             f.close()
-        except Exception as dummy:
+        except Exception:
             pass
         os.remove(tmpsrc)
-        raise ModuleFailException("failed to create temporary content file: %s" % to_native(err), exception=traceback.format_exc())
+        raise ModuleFailException(
+            "failed to create temporary content file: %s" % to_native(err),
+            exception=traceback.format_exc(),
+        )
     f.close()
     checksum_src = None
     checksum_dest = None
@@ -53,7 +60,7 @@ def write_file(module, dest, content):
     if not os.path.exists(tmpsrc):
         try:
             os.remove(tmpsrc)
-        except Exception as dummy:
+        except Exception:
             pass
         raise ModuleFailException("Source %s does not exist" % (tmpsrc))
     if not os.access(tmpsrc, os.R_OK):
@@ -71,7 +78,7 @@ def write_file(module, dest, content):
             raise ModuleFailException("Destination %s not readable" % (dest))
         checksum_dest = module.sha1(dest)
     else:
-        dirname = os.path.dirname(dest) or '.'
+        dirname = os.path.dirname(dest) or "."
         if not os.access(dirname, os.W_OK):
             os.remove(tmpsrc)
             raise ModuleFailException("Destination dir %s not writable" % (dirname))
@@ -81,6 +88,9 @@ def write_file(module, dest, content):
             changed = True
         except Exception as err:
             os.remove(tmpsrc)
-            raise ModuleFailException("failed to copy %s to %s: %s" % (tmpsrc, dest, to_native(err)), exception=traceback.format_exc())
+            raise ModuleFailException(
+                "failed to copy %s to %s: %s" % (tmpsrc, dest, to_native(err)),
+                exception=traceback.format_exc(),
+            )
     os.remove(tmpsrc)
     return changed

plugins/module_utils/acme/orders.py

@@ -1,25 +1,27 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import time
 
-from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
-    nopad_b64,
+from ansible_collections.community.crypto.plugins.module_utils.acme.challenges import (
+    Authorization,
+    normalize_combined_identifier,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
     ACMEProtocolException,
 )
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.challenges import (
-    Authorization,
+from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
+    nopad_b64,
 )
 
 
@@ -27,13 +29,14 @@ class Order(object):
     def _setup(self, client, data):
         self.data = data
 
-        self.status = data['status']
+        self.status = data["status"]
         self.identifiers = []
-        for identifier in data['identifiers']:
-            self.identifiers.append((identifier['type'], identifier['value']))
-        self.finalize_uri = data.get('finalize')
-        self.certificate_uri = data.get('certificate')
-        self.authorization_uris = data['authorizations']
+        for identifier in data["identifiers"]:
+            self.identifiers.append((identifier["type"], identifier["value"]))
+        self.replaces_cert_id = data.get("replaces")
+        self.finalize_uri = data.get("finalize")
+        self.certificate_uri = data.get("certificate")
+        self.authorization_uris = data["authorizations"]
         self.authorizations = {}
 
     def __init__(self, url):
@@ -43,6 +46,7 @@ class Order(object):
 
         self.status = None
         self.identifiers = []
+        self.replaces_cert_id = None
         self.finalize_uri = None
         self.certificate_uri = None
         self.authorization_uris = []
@@ -61,23 +65,90 @@ class Order(object):
         return result
 
     @classmethod
-    def create(cls, client, identifiers):
-        '''
+    def create(cls, client, identifiers, replaces_cert_id=None, profile=None):
+        """
         Start a new certificate order (ACME v2 protocol).
         https://tools.ietf.org/html/rfc8555#section-7.4
-        '''
+        """
         acme_identifiers = []
         for identifier_type, identifier in identifiers:
-            acme_identifiers.append({
-                'type': identifier_type,
-                'value': identifier,
-            })
-        new_order = {
-            "identifiers": acme_identifiers
-        }
+            acme_identifiers.append(
+                {
+                    "type": identifier_type,
+                    "value": identifier,
+                }
+            )
+        new_order = {"identifiers": acme_identifiers}
+        if replaces_cert_id is not None:
+            new_order["replaces"] = replaces_cert_id
+        if profile is not None:
+            new_order["profile"] = profile
         result, info = client.send_signed_request(
-            client.directory['newOrder'], new_order, error_msg='Failed to start new order', expected_status_codes=[201])
-        return cls.from_json(client, result, info['location'])
+            client.directory["newOrder"],
+            new_order,
+            error_msg="Failed to start new order",
+            expected_status_codes=[201],
+        )
+        return cls.from_json(client, result, info["location"])
+
+    @classmethod
+    def create_with_error_handling(
+        cls,
+        client,
+        identifiers,
+        error_strategy="auto",
+        error_max_retries=3,
+        replaces_cert_id=None,
+        profile=None,
+        message_callback=None,
+    ):
+        """
+        error_strategy can be one of the following strings:
+
+        * ``fail``: simply fail. (Same behavior as ``Order.create()``.)
+        * ``retry_without_replaces_cert_id``: if ``replaces_cert_id`` is not ``None``, set it to ``None`` and retry.
+          The only exception is an error of type ``urn:ietf:params:acme:error:alreadyReplaced``, that indicates that
+          the certificate was already replaced.
+        * ``auto``: try to be clever. Right now this is identical to ``retry_without_replaces_cert_id``, but that can
+          change at any time in the future.
+        * ``always``: always retry until ``error_max_retries`` has been reached.
+        """
+        tries = 0
+        while True:
+            tries += 1
+            try:
+                return cls.create(
+                    client,
+                    identifiers,
+                    replaces_cert_id=replaces_cert_id,
+                    profile=profile,
+                )
+            except ACMEProtocolException as exc:
+                if tries <= error_max_retries + 1 and error_strategy != "fail":
+                    if error_strategy == "always":
+                        continue
+
+                    if (
+                        error_strategy in ("auto", "retry_without_replaces_cert_id")
+                        and replaces_cert_id is not None
+                        and not (
+                            exc.error_code == 409
+                            and exc.error_type
+                            == "urn:ietf:params:acme:error:alreadyReplaced"
+                        )
+                    ):
+                        if message_callback:
+                            message_callback(
+                                "Stop passing `replaces={replaces}` due to error {code} {type} when creating ACME order".format(
+                                    code=exc.error_code,
+                                    type=exc.error_type,
+                                    replaces=replaces_cert_id,
+                                )
+                            )
+                        replaces_cert_id = None
+                        continue
+
+                raise
 
     def refresh(self, client):
         result, dummy = client.get_request(self.url)
@@ -88,32 +159,41 @@ class Order(object):
     def load_authorizations(self, client):
         for auth_uri in self.authorization_uris:
             authz = Authorization.from_url(client, auth_uri)
-            self.authorizations[authz.combined_identifier] = authz
+            self.authorizations[
+                normalize_combined_identifier(authz.combined_identifier)
+            ] = authz
 
     def wait_for_finalization(self, client):
         while True:
             self.refresh(client)
-            if self.status in ['valid', 'invalid', 'pending', 'ready']:
+            if self.status in ["valid", "invalid", "pending", "ready"]:
                 break
             time.sleep(2)
 
-        if self.status != 'valid':
+        if self.status != "valid":
             raise ACMEProtocolException(
                 client.module,
-                'Failed to wait for order to complete; got status "{status}"'.format(status=self.status),
-                content_json=self.data)
+                'Failed to wait for order to complete; got status "{status}"'.format(
+                    status=self.status
+                ),
+                content_json=self.data,
+            )
 
     def finalize(self, client, csr_der, wait=True):
-        '''
+        """
         Create a new certificate based on the csr.
         Return the certificate object as dict
         https://tools.ietf.org/html/rfc8555#section-7.4
-        '''
+        """
         new_cert = {
             "csr": nopad_b64(csr_der),
         }
         result, info = client.send_signed_request(
-            self.finalize_uri, new_cert, error_msg='Failed to finalizing order', expected_status_codes=[200])
+            self.finalize_uri,
+            new_cert,
+            error_msg="Failed to finalizing order",
+            expected_status_codes=[200],
+        )
         # It is not clear from the RFC whether the finalize call returns the order object or not.
         # Instead of using the result, we call self.refresh(client) below.
 
@@ -121,9 +201,12 @@ class Order(object):
             self.wait_for_finalization(client)
         else:
             self.refresh(client)
-            if self.status not in ['procesing', 'valid', 'invalid']:
+            if self.status not in ["procesing", "valid", "invalid"]:
                 raise ACMEProtocolException(
                     client.module,
-                    'Failed to finalize order; got status "{status}"'.format(status=self.status),
+                    'Failed to finalize order; got status "{status}"'.format(
+                        status=self.status
+                    ),
                     info=info,
-                    content_json=result)
+                    content_json=result,
+                )

plugins/module_utils/acme/utils.py

@@ -1,42 +1,54 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
-# Copyright: (c) 2021 Felix Fontein <felix@fontein.de>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
+# Copyright (c) 2021 Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import base64
+import datetime
 import re
 import textwrap
 import traceback
 
 from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.six.moves.urllib.parse import unquote
-
-from ansible_collections.community.crypto.plugins.module_utils.acme.errors import ModuleFailException
+from ansible_collections.community.crypto.plugins.module_utils.acme.errors import (
+    ModuleFailException,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.math import (
+    convert_int_to_bytes,
+)
+from ansible_collections.community.crypto.plugins.module_utils.time import (
+    get_now_datetime,
+)
 
 
 def nopad_b64(data):
-    return base64.urlsafe_b64encode(data).decode('utf8').replace("=", "")
+    return base64.urlsafe_b64encode(data).decode("utf8").replace("=", "")
 
 
 def der_to_pem(der_cert):
-    '''
+    """
     Convert the DER format certificate in der_cert to a PEM format certificate and return it.
-    '''
+    """
     return """-----BEGIN CERTIFICATE-----\n{0}\n-----END CERTIFICATE-----\n""".format(
-        "\n".join(textwrap.wrap(base64.b64encode(der_cert).decode('utf8'), 64)))
+        "\n".join(textwrap.wrap(base64.b64encode(der_cert).decode("utf8"), 64))
+    )
 
 
 def pem_to_der(pem_filename=None, pem_content=None):
-    '''
+    """
     Load PEM file, or use PEM file's content, and convert to DER.
 
     If PEM contains multiple entities, the first entity will be used.
-    '''
+    """
     certificate_lines = []
     if pem_content is not None:
         lines = pem_content.splitlines()
@@ -45,12 +57,17 @@ def pem_to_der(pem_filename=None, pem_content=None):
             with open(pem_filename, "rt") as f:
                 lines = list(f)
         except Exception as err:
-            raise ModuleFailException("cannot load PEM file {0}: {1}".format(pem_filename, to_native(err)), exception=traceback.format_exc())
+            raise ModuleFailException(
+                "cannot load PEM file {0}: {1}".format(pem_filename, to_native(err)),
+                exception=traceback.format_exc(),
+            )
     else:
-        raise ModuleFailException('One of pem_filename and pem_content must be provided')
+        raise ModuleFailException(
+            "One of pem_filename and pem_content must be provided"
+        )
     header_line_count = 0
     for line in lines:
-        if line.startswith('-----'):
+        if line.startswith("-----"):
             header_line_count += 1
             if header_line_count == 2:
                 # If certificate file contains other certs appended
@@ -58,14 +75,73 @@ def pem_to_der(pem_filename=None, pem_content=None):
                 break
             continue
         certificate_lines.append(line.strip())
-    return base64.b64decode(''.join(certificate_lines))
+    return base64.b64decode("".join(certificate_lines))
 
 
 def process_links(info, callback):
-    '''
+    """
     Process link header, calls callback for every link header with the URL and relation as options.
-    '''
-    if 'link' in info:
-        link = info['link']
+
+    https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link
+    """
+    if "link" in info:
+        link = info["link"]
         for url, relation in re.findall(r'<([^>]+)>;\s*rel="(\w+)"', link):
             callback(unquote(url), relation)
+
+
+def parse_retry_after(value, relative_with_timezone=True, now=None):
+    """
+    Parse the value of a Retry-After header and return a timestamp.
+
+    https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
+    """
+    # First try a number of seconds
+    try:
+        delta = datetime.timedelta(seconds=int(value))
+        if now is None:
+            now = get_now_datetime(relative_with_timezone)
+        return now + delta
+    except ValueError:
+        pass
+
+    try:
+        return datetime.datetime.strptime(value, "%a, %d %b %Y %H:%M:%S GMT")
+    except ValueError:
+        pass
+
+    raise ValueError("Cannot parse Retry-After header value %s" % repr(value))
+
+
+def compute_cert_id(
+    backend,
+    cert_info=None,
+    cert_filename=None,
+    cert_content=None,
+    none_if_required_information_is_missing=False,
+):
+    # Obtain certificate info if not provided
+    if cert_info is None:
+        cert_info = backend.get_cert_information(
+            cert_filename=cert_filename, cert_content=cert_content
+        )
+
+    # Convert Authority Key Identifier to string
+    if cert_info.authority_key_identifier is None:
+        if none_if_required_information_is_missing:
+            return None
+        raise ModuleFailException(
+            "Certificate has no Authority Key Identifier extension"
+        )
+    aki = to_native(
+        base64.urlsafe_b64encode(cert_info.authority_key_identifier)
+    ).replace("=", "")
+
+    # Convert serial number to string
+    serial_bytes = convert_int_to_bytes(cert_info.serial_number)
+    if ord(serial_bytes[:1]) >= 128:
+        serial_bytes = b"\x00" + serial_bytes
+    serial = to_native(base64.urlsafe_b64encode(serial_bytes)).replace("=", "")
+
+    # Compose cert ID
+    return "{aki}.{serial}".format(aki=aki, serial=serial)

plugins/module_utils/argspec.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) 2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+
+
+__metaclass__ = type
+
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def _ensure_list(value):
+    if value is None:
+        return []
+    return list(value)
+
+
+class ArgumentSpec:
+    def __init__(
+        self,
+        argument_spec=None,
+        mutually_exclusive=None,
+        required_together=None,
+        required_one_of=None,
+        required_if=None,
+        required_by=None,
+    ):
+        self.argument_spec = argument_spec or {}
+        self.mutually_exclusive = _ensure_list(mutually_exclusive)
+        self.required_together = _ensure_list(required_together)
+        self.required_one_of = _ensure_list(required_one_of)
+        self.required_if = _ensure_list(required_if)
+        self.required_by = required_by or {}
+
+    def update_argspec(self, **kwargs):
+        self.argument_spec.update(kwargs)
+        return self
+
+    def update(
+        self,
+        mutually_exclusive=None,
+        required_together=None,
+        required_one_of=None,
+        required_if=None,
+        required_by=None,
+    ):
+        if mutually_exclusive:
+            self.mutually_exclusive.extend(mutually_exclusive)
+        if required_together:
+            self.required_together.extend(required_together)
+        if required_one_of:
+            self.required_one_of.extend(required_one_of)
+        if required_if:
+            self.required_if.extend(required_if)
+        if required_by:
+            for k, v in required_by.items():
+                if k in self.required_by:
+                    v = list(self.required_by[k]) + list(v)
+                self.required_by[k] = v
+        return self
+
+    def merge(self, other):
+        self.update_argspec(**other.argument_spec)
+        self.update(
+            mutually_exclusive=other.mutually_exclusive,
+            required_together=other.required_together,
+            required_one_of=other.required_one_of,
+            required_if=other.required_if,
+            required_by=other.required_by,
+        )
+        return self
+
+    def create_ansible_module_helper(self, clazz, args, **kwargs):
+        return clazz(
+            *args,
+            argument_spec=self.argument_spec,
+            mutually_exclusive=self.mutually_exclusive,
+            required_together=self.required_together,
+            required_one_of=self.required_one_of,
+            required_if=self.required_if,
+            required_by=self.required_by,
+            **kwargs
+        )
+
+    def create_ansible_module(self, **kwargs):
+        return self.create_ansible_module_helper(AnsibleModule, (), **kwargs)
+
+
+__all__ = ("ArgumentSpec",)

plugins/module_utils/crypto/__init__.py

@@ -1,99 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# (c) 2016, Yanis Guenane <yanis+ansible@guenane.org>
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
-
-
-# THIS FILE IS FOR COMPATIBILITY ONLY! YOU SHALL NOT IMPORT IT!
-#
-# This fill will be removed eventually, so if you're using it,
-# please stop doing so.
-
-from .basic import (
-    HAS_PYOPENSSL,
-    CRYPTOGRAPHY_HAS_X25519,
-    CRYPTOGRAPHY_HAS_X25519_FULL,
-    CRYPTOGRAPHY_HAS_X448,
-    CRYPTOGRAPHY_HAS_ED25519,
-    CRYPTOGRAPHY_HAS_ED448,
-    HAS_CRYPTOGRAPHY,
-    OpenSSLObjectError,
-    OpenSSLBadPassphraseError,
-)
-
-from .cryptography_crl import (
-    REVOCATION_REASON_MAP,
-    REVOCATION_REASON_MAP_INVERSE,
-    cryptography_decode_revoked_certificate,
-)
-
-from .cryptography_support import (
-    cryptography_get_extensions_from_cert,
-    cryptography_get_extensions_from_csr,
-    cryptography_name_to_oid,
-    cryptography_oid_to_name,
-    cryptography_get_name,
-    cryptography_decode_name,
-    cryptography_parse_key_usage_params,
-    cryptography_get_basic_constraints,
-    cryptography_key_needs_digest_for_signing,
-    cryptography_compare_public_keys,
-)
-
-from .pem import (
-    identify_private_key_format,
-)
-
-from .math import (
-    binary_exp_mod,
-    simple_gcd,
-    quick_is_not_prime,
-    count_bits,
-)
-
-from ._obj2txt import obj2txt as _obj2txt
-
-from ._objects_data import OID_MAP as _OID_MAP
-
-from ._objects import OID_LOOKUP as _OID_LOOKUP
-from ._objects import NORMALIZE_NAMES as _NORMALIZE_NAMES
-from ._objects import NORMALIZE_NAMES_SHORT as _NORMALIZE_NAMES_SHORT
-
-from .pyopenssl_support import (
-    pyopenssl_normalize_name,
-    pyopenssl_get_extensions_from_cert,
-    pyopenssl_get_extensions_from_csr,
-)
-
-from .support import (
-    get_fingerprint_of_bytes,
-    get_fingerprint,
-    load_privatekey,
-    load_certificate,
-    load_certificate_request,
-    parse_name_field,
-    convert_relative_to_datetime,
-    get_relative_time_option,
-    select_message_digest,
-    OpenSSLObject,
-)
-
-from ..io import (
-    load_file_if_exists,
-    write_file,
-)

plugins/module_utils/crypto/_asn1.py

@@ -1,9 +1,12 @@
 # -*- coding: utf-8 -*-
 
-# (c) 2020, Jordan Borean <jborean93@gmail.com>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2020, Jordan Borean <jborean93@gmail.com>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 import re
@@ -28,8 +31,10 @@ type:
 value:
     The value to encode, the format of this value depends on the <type> specified.
 """
-ASN1_STRING_REGEX = re.compile(r'^((?P<tag_type>IMPLICIT|EXPLICIT):(?P<tag_number>\d+)(?P<tag_class>U|A|P|C)?,)?'
-                               r'(?P<value_type>[\w\d]+):(?P<value>.*)')
+ASN1_STRING_REGEX = re.compile(
+    r"^((?P<tag_type>IMPLICIT|EXPLICIT):(?P<tag_number>\d+)(?P<tag_class>U|A|P|C)?,)?"
+    r"(?P<value_type>[\w\d]+):(?P<value>.*)"
+)
 
 
 class TagClass:
@@ -45,7 +50,7 @@ class TagNumber:
 
 
 def _pack_octet_integer(value):
-    """ Packs an integer value into 1 or multiple octets. """
+    """Packs an integer value into 1 or multiple octets."""
     # NOTE: This is *NOT* the same as packing an ASN.1 INTEGER like value.
     octets = bytearray()
 
@@ -67,37 +72,41 @@ def _pack_octet_integer(value):
 
 
 def serialize_asn1_string_as_der(value):
-    """ Deserializes an ASN.1 string to a DER encoded byte string. """
+    """Deserializes an ASN.1 string to a DER encoded byte string."""
     asn1_match = ASN1_STRING_REGEX.match(value)
     if not asn1_match:
-        raise ValueError("The ASN.1 serialized string must be in the format [modifier,]type[:value]")
+        raise ValueError(
+            "The ASN.1 serialized string must be in the format [modifier,]type[:value]"
+        )
 
-    tag_type = asn1_match.group('tag_type')
-    tag_number = asn1_match.group('tag_number')
-    tag_class = asn1_match.group('tag_class') or 'C'
-    value_type = asn1_match.group('value_type')
-    asn1_value = asn1_match.group('value')
+    tag_type = asn1_match.group("tag_type")
+    tag_number = asn1_match.group("tag_number")
+    tag_class = asn1_match.group("tag_class") or "C"
+    value_type = asn1_match.group("value_type")
+    asn1_value = asn1_match.group("value")
 
-    if value_type != 'UTF8':
-        raise ValueError('The ASN.1 serialized string is not a known type "{0}", only UTF8 types are '
-                         'supported'.format(value_type))
+    if value_type != "UTF8":
+        raise ValueError(
+            'The ASN.1 serialized string is not a known type "{0}", only UTF8 types are '
+            "supported".format(value_type)
+        )
 
-    b_value = to_bytes(asn1_value, encoding='utf-8', errors='surrogate_or_strict')
+    b_value = to_bytes(asn1_value, encoding="utf-8", errors="surrogate_or_strict")
 
     # We should only do a universal type tag if not IMPLICITLY tagged or the tag class is not universal.
-    if not tag_type or (tag_type == 'EXPLICIT' and tag_class != 'U'):
+    if not tag_type or (tag_type == "EXPLICIT" and tag_class != "U"):
         b_value = pack_asn1(TagClass.universal, False, TagNumber.utf8_string, b_value)
 
     if tag_type:
         tag_class = {
-            'U': TagClass.universal,
-            'A': TagClass.application,
-            'P': TagClass.private,
-            'C': TagClass.context_specific,
+            "U": TagClass.universal,
+            "A": TagClass.application,
+            "P": TagClass.private,
+            "C": TagClass.context_specific,
         }[tag_class]
 
         # When adding support for more types this should be looked into further. For now it works with UTF8Strings.
-        constructed = tag_type == 'EXPLICIT' and tag_class != TagClass.universal
+        constructed = tag_type == "EXPLICIT" and tag_class != TagClass.universal
         b_value = pack_asn1(tag_class, constructed, int(tag_number), b_value)
 
     return b_value
@@ -118,7 +127,7 @@ def pack_asn1(tag_class, constructed, tag_number, b_data):
     # Bit 8 and 7 denotes the class.
     identifier_octets = tag_class << 6
     # Bit 6 denotes whether the value is primitive or constructed.
-    identifier_octets |= ((1 if constructed else 0) << 5)
+    identifier_octets |= (1 if constructed else 0) << 5
 
     # Bits 5-1 contain the tag number, if it cannot be encoded in these 5 bits
     # then they are set and another octet(s) is used to denote the tag number.

plugins/module_utils/crypto/_obj2txt.py

@@ -1,7 +1,17 @@
+# This code is part of Ansible, but is an independent component.
+# This particular file snippet, and this file snippet only, is licensed under the
+# Apache 2.0 License. Modules you write using this snippet, which is embedded
+# dynamically by Ansible, still belong to the author of the module, and may assign
+# their own license to the complete work.
+
 # This excerpt is dual licensed under the terms of the Apache License, Version
 # 2.0, and the BSD License. See the LICENSE file at
 # https://github.com/pyca/cryptography/blob/master/LICENSE for complete details.
 #
+# The Apache 2.0 license has been included as LICENSES/Apache-2.0.txt in this collection.
+# The BSD License license has been included as LICENSES/BSD-3-Clause.txt in this collection.
+# SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
+#
 # Adapted from cryptography's hazmat/backends/openssl/decode_asn1.py
 #
 # Copyright (c) 2015, 2016 Paul Kehrer (@reaperhulk)
@@ -17,9 +27,16 @@
 #    pyca/cryptography@d607dd7e5bc5c08854ec0c9baff70ba4a35be36f
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
+# WARNING: this function no longer works with cryptography 35.0.0 and newer!
+#          It must **ONLY** be used in compatibility code for older
+#          cryptography versions!
+
+
 def obj2txt(openssl_lib, openssl_ffi, obj):
     # Set to 80 on the recommendation of
     # https://www.openssl.org/docs/crypto/OBJ_nid2ln.html#return_values

plugins/module_utils/crypto/_objects.py

@@ -1,26 +1,18 @@
 # -*- coding: utf-8 -*-
 #
-# (c) 2019, Felix Fontein <felix@fontein.de>
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2019, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 from ._objects_data import OID_MAP
 
+
 OID_LOOKUP = dict()
 NORMALIZE_NAMES = dict()
 NORMALIZE_NAMES_SHORT = dict()
@@ -29,17 +21,19 @@ for dotted, names in OID_MAP.items():
     for name in names:
         if name in NORMALIZE_NAMES and OID_LOOKUP[name] != dotted:
             raise AssertionError(
-                'Name collision during setup: "{0}" for OIDs {1} and {2}'
-                .format(name, dotted, OID_LOOKUP[name])
+                'Name collision during setup: "{0}" for OIDs {1} and {2}'.format(
+                    name, dotted, OID_LOOKUP[name]
+                )
             )
         NORMALIZE_NAMES[name] = names[0]
         NORMALIZE_NAMES_SHORT[name] = names[-1]
         OID_LOOKUP[name] = dotted
-for alias, original in [('userID', 'userId')]:
+for alias, original in [("userID", "userId")]:
     if alias in NORMALIZE_NAMES:
         raise AssertionError(
-            'Name collision during adding aliases: "{0}" (alias for "{1}") is already mapped to OID {2}'
-            .format(alias, original, OID_LOOKUP[alias])
+            'Name collision during adding aliases: "{0}" (alias for "{1}") is already mapped to OID {2}'.format(
+                alias, original, OID_LOOKUP[alias]
+            )
         )
     NORMALIZE_NAMES[alias] = original
     NORMALIZE_NAMES_SHORT[alias] = NORMALIZE_NAMES_SHORT[original]

plugins/module_utils/crypto/basic.py

@@ -1,34 +1,20 @@
 # -*- coding: utf-8 -*-
 #
-# (c) 2016, Yanis Guenane <yanis+ansible@guenane.org>
-# (c) 2020, Felix Fontein <felix@fontein.de>
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2016, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2020, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
-from distutils.version import LooseVersion
+from ansible_collections.community.crypto.plugins.module_utils.version import (
+    LooseVersion,
+)
 
-try:
-    import OpenSSL  # noqa
-    from OpenSSL import crypto  # noqa
-    HAS_PYOPENSSL = True
-except ImportError:
-    # Error handled in the calling module.
-    HAS_PYOPENSSL = False
 
 try:
     import cryptography
@@ -41,7 +27,7 @@ try:
     # actually doing that in x509_certificate, and potentially in other code,
     # we need to monkey-patch __hash__ for these classes to make sure our code
     # works fine.
-    if LooseVersion(cryptography.__version__) < LooseVersion('2.1'):
+    if LooseVersion(cryptography.__version__) < LooseVersion("2.1"):
         # A very simply hash function which relies on the representation
         # of an object to be implemented. This is the case since at least
         # cryptography 1.0, see
@@ -58,7 +44,7 @@ try:
         x509.OtherName.__hash__ = simple_hash
         x509.RegisteredID.__hash__ = simple_hash
 
-        if LooseVersion(cryptography.__version__) < LooseVersion('1.2'):
+        if LooseVersion(cryptography.__version__) < LooseVersion("1.2"):
             # The hash functions for the following types were added for cryptography 1.2:
             # https://github.com/pyca/cryptography/commit/b642deed88a8696e5f01ce6855ccf89985fc35d0
             # https://github.com/pyca/cryptography/commit/d1b5681f6db2bde7a14625538bd7907b08dfb486
@@ -69,6 +55,7 @@ try:
     try:
         # added in 0.5 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/dsa/
         import cryptography.hazmat.primitives.asymmetric.dsa
+
         CRYPTOGRAPHY_HAS_DSA = True
         try:
             # added later in 1.5
@@ -82,6 +69,7 @@ try:
     try:
         # added in 2.6 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ed25519/
         import cryptography.hazmat.primitives.asymmetric.ed25519
+
         CRYPTOGRAPHY_HAS_ED25519 = True
         try:
             # added with the primitive in 2.6
@@ -95,6 +83,7 @@ try:
     try:
         # added in 2.6 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ed448/
         import cryptography.hazmat.primitives.asymmetric.ed448
+
         CRYPTOGRAPHY_HAS_ED448 = True
         try:
             # added with the primitive in 2.6
@@ -108,6 +97,7 @@ try:
     try:
         # added in 0.5 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ec/
         import cryptography.hazmat.primitives.asymmetric.ec
+
         CRYPTOGRAPHY_HAS_EC = True
         try:
             # added later in 1.5
@@ -121,6 +111,7 @@ try:
     try:
         # added in 0.5 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/rsa/
         import cryptography.hazmat.primitives.asymmetric.rsa
+
         CRYPTOGRAPHY_HAS_RSA = True
         try:
             # added later in 1.4
@@ -134,6 +125,7 @@ try:
     try:
         # added in 2.0 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/x25519/
         import cryptography.hazmat.primitives.asymmetric.x25519
+
         CRYPTOGRAPHY_HAS_X25519 = True
         try:
             # added later in 2.5
@@ -147,6 +139,7 @@ try:
     try:
         # added in 2.5 - https://cryptography.io/en/latest/hazmat/primitives/asymmetric/x448/
         import cryptography.hazmat.primitives.asymmetric.x448
+
         CRYPTOGRAPHY_HAS_X448 = True
     except ImportError:
         CRYPTOGRAPHY_HAS_X448 = False

plugins/module_utils/crypto/cryptography_crl.py

@@ -1,58 +1,56 @@
 # -*- coding: utf-8 -*-
 #
-# (c) 2019, Felix Fontein <felix@fontein.de>
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2019, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
+from ansible_collections.community.crypto.plugins.module_utils.version import (
+    LooseVersion as _LooseVersion,
+)
+
+
 try:
+    import cryptography
     from cryptography import x509
 except ImportError:
     # Error handled in the calling module.
     pass
 
-from .basic import (
-    HAS_CRYPTOGRAPHY,
-)
+from ._obj2txt import obj2txt
+from .basic import HAS_CRYPTOGRAPHY
+from .cryptography_support import CRYPTOGRAPHY_TIMEZONE, cryptography_decode_name
 
-from .cryptography_support import (
-    cryptography_decode_name,
-)
-
-from ._obj2txt import (
-    obj2txt,
-)
 
+# TODO: once cryptography has a _utc variant of InvalidityDate.invalidity_date, set this
+#       to True and adjust get_invalidity_date() accordingly.
+#       (https://github.com/pyca/cryptography/issues/10818)
+CRYPTOGRAPHY_TIMEZONE_INVALIDITY_DATE = False
+if HAS_CRYPTOGRAPHY:
+    CRYPTOGRAPHY_TIMEZONE_INVALIDITY_DATE = _LooseVersion(
+        cryptography.__version__
+    ) >= _LooseVersion("43.0.0")
 
 TIMESTAMP_FORMAT = "%Y%m%d%H%M%SZ"
 
 
 if HAS_CRYPTOGRAPHY:
     REVOCATION_REASON_MAP = {
-        'unspecified': x509.ReasonFlags.unspecified,
-        'key_compromise': x509.ReasonFlags.key_compromise,
-        'ca_compromise': x509.ReasonFlags.ca_compromise,
-        'affiliation_changed': x509.ReasonFlags.affiliation_changed,
-        'superseded': x509.ReasonFlags.superseded,
-        'cessation_of_operation': x509.ReasonFlags.cessation_of_operation,
-        'certificate_hold': x509.ReasonFlags.certificate_hold,
-        'privilege_withdrawn': x509.ReasonFlags.privilege_withdrawn,
-        'aa_compromise': x509.ReasonFlags.aa_compromise,
-        'remove_from_crl': x509.ReasonFlags.remove_from_crl,
+        "unspecified": x509.ReasonFlags.unspecified,
+        "key_compromise": x509.ReasonFlags.key_compromise,
+        "ca_compromise": x509.ReasonFlags.ca_compromise,
+        "affiliation_changed": x509.ReasonFlags.affiliation_changed,
+        "superseded": x509.ReasonFlags.superseded,
+        "cessation_of_operation": x509.ReasonFlags.cessation_of_operation,
+        "certificate_hold": x509.ReasonFlags.certificate_hold,
+        "privilege_withdrawn": x509.ReasonFlags.privilege_withdrawn,
+        "aa_compromise": x509.ReasonFlags.aa_compromise,
+        "remove_from_crl": x509.ReasonFlags.remove_from_crl,
     }
     REVOCATION_REASON_MAP_INVERSE = dict()
     for k, v in REVOCATION_REASON_MAP.items():
@@ -65,50 +63,61 @@ else:
 
 def cryptography_decode_revoked_certificate(cert):
     result = {
-        'serial_number': cert.serial_number,
-        'revocation_date': cert.revocation_date,
-        'issuer': None,
-        'issuer_critical': False,
-        'reason': None,
-        'reason_critical': False,
-        'invalidity_date': None,
-        'invalidity_date_critical': False,
+        "serial_number": cert.serial_number,
+        "revocation_date": get_revocation_date(cert),
+        "issuer": None,
+        "issuer_critical": False,
+        "reason": None,
+        "reason_critical": False,
+        "invalidity_date": None,
+        "invalidity_date_critical": False,
     }
     try:
         ext = cert.extensions.get_extension_for_class(x509.CertificateIssuer)
-        result['issuer'] = list(ext.value)
-        result['issuer_critical'] = ext.critical
+        result["issuer"] = list(ext.value)
+        result["issuer_critical"] = ext.critical
     except x509.ExtensionNotFound:
         pass
     try:
         ext = cert.extensions.get_extension_for_class(x509.CRLReason)
-        result['reason'] = ext.value.reason
-        result['reason_critical'] = ext.critical
+        result["reason"] = ext.value.reason
+        result["reason_critical"] = ext.critical
     except x509.ExtensionNotFound:
         pass
     try:
         ext = cert.extensions.get_extension_for_class(x509.InvalidityDate)
-        result['invalidity_date'] = ext.value.invalidity_date
-        result['invalidity_date_critical'] = ext.critical
+        result["invalidity_date"] = get_invalidity_date(ext.value)
+        result["invalidity_date_critical"] = ext.critical
     except x509.ExtensionNotFound:
         pass
     return result
 
 
-def cryptography_dump_revoked(entry):
+def cryptography_dump_revoked(entry, idn_rewrite="ignore"):
     return {
-        'serial_number': entry['serial_number'],
-        'revocation_date': entry['revocation_date'].strftime(TIMESTAMP_FORMAT),
-        'issuer':
-            [cryptography_decode_name(issuer) for issuer in entry['issuer']]
-            if entry['issuer'] is not None else None,
-        'issuer_critical': entry['issuer_critical'],
-        'reason': REVOCATION_REASON_MAP_INVERSE.get(entry['reason']) if entry['reason'] is not None else None,
-        'reason_critical': entry['reason_critical'],
-        'invalidity_date':
-            entry['invalidity_date'].strftime(TIMESTAMP_FORMAT)
-            if entry['invalidity_date'] is not None else None,
-        'invalidity_date_critical': entry['invalidity_date_critical'],
+        "serial_number": entry["serial_number"],
+        "revocation_date": entry["revocation_date"].strftime(TIMESTAMP_FORMAT),
+        "issuer": (
+            [
+                cryptography_decode_name(issuer, idn_rewrite=idn_rewrite)
+                for issuer in entry["issuer"]
+            ]
+            if entry["issuer"] is not None
+            else None
+        ),
+        "issuer_critical": entry["issuer_critical"],
+        "reason": (
+            REVOCATION_REASON_MAP_INVERSE.get(entry["reason"])
+            if entry["reason"] is not None
+            else None
+        ),
+        "reason_critical": entry["reason_critical"],
+        "invalidity_date": (
+            entry["invalidity_date"].strftime(TIMESTAMP_FORMAT)
+            if entry["invalidity_date"] is not None
+            else None
+        ),
+        "invalidity_date_critical": entry["invalidity_date_critical"],
     }
 
 
@@ -116,10 +125,44 @@ def cryptography_get_signature_algorithm_oid_from_crl(crl):
     try:
         return crl.signature_algorithm_oid
     except AttributeError:
-        # Older cryptography versions don't have signature_algorithm_oid yet
+        # Older cryptography versions do not have signature_algorithm_oid yet
         dotted = obj2txt(
-            crl._backend._lib,
-            crl._backend._ffi,
-            crl._x509_crl.sig_alg.algorithm
+            crl._backend._lib, crl._backend._ffi, crl._x509_crl.sig_alg.algorithm
         )
         return x509.oid.ObjectIdentifier(dotted)
+
+
+def get_next_update(obj):
+    if CRYPTOGRAPHY_TIMEZONE:
+        return obj.next_update_utc
+    return obj.next_update
+
+
+def get_last_update(obj):
+    if CRYPTOGRAPHY_TIMEZONE:
+        return obj.last_update_utc
+    return obj.last_update
+
+
+def get_revocation_date(obj):
+    if CRYPTOGRAPHY_TIMEZONE:
+        return obj.revocation_date_utc
+    return obj.revocation_date
+
+
+def get_invalidity_date(obj):
+    if CRYPTOGRAPHY_TIMEZONE_INVALIDITY_DATE:
+        return obj.invalidity_date_utc
+    return obj.invalidity_date
+
+
+def set_next_update(builder, value):
+    return builder.next_update(value)
+
+
+def set_last_update(builder, value):
+    return builder.last_update(value)
+
+
+def set_revocation_date(builder, value):
+    return builder.revocation_date(value)

plugins/module_utils/crypto/math.py

@@ -1,21 +1,12 @@
 # -*- coding: utf-8 -*-
 #
-# (c) 2019, Felix Fontein <felix@fontein.de>
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright (c) 2019, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
@@ -23,7 +14,7 @@ import sys
 
 
 def binary_exp_mod(f, e, m):
-    '''Computes f^e mod m in O(log e) multiplications modulo m.'''
+    """Computes f^e mod m in O(log e) multiplications modulo m."""
     # Compute len_e = floor(log_2(e))
     len_e = -1
     x = e
@@ -40,22 +31,74 @@ def binary_exp_mod(f, e, m):
 
 
 def simple_gcd(a, b):
-    '''Compute GCD of its two inputs.'''
+    """Compute GCD of its two inputs."""
     while b != 0:
         a, b = b, a % b
     return a
 
 
 def quick_is_not_prime(n):
-    '''Does some quick checks to see if we can poke a hole into the primality of n.
+    """Does some quick checks to see if we can poke a hole into the primality of n.
 
     A result of `False` does **not** mean that the number is prime; it just means
-    that we couldn't detect quickly whether it is not prime.
-    '''
+    that we could not detect quickly whether it is not prime.
+    """
     if n <= 2:
-        return True
+        return n < 2
     # The constant in the next line is the product of all primes < 200
-    if simple_gcd(n, 7799922041683461553249199106329813876687996789903550945093032474868511536164700810) > 1:
+    prime_product = 7799922041683461553249199106329813876687996789903550945093032474868511536164700810
+    gcd = simple_gcd(n, prime_product)
+    if gcd > 1:
+        if n < 200 and gcd == n:
+            # Explicitly check for all primes < 200
+            return n not in (
+                2,
+                3,
+                5,
+                7,
+                11,
+                13,
+                17,
+                19,
+                23,
+                29,
+                31,
+                37,
+                41,
+                43,
+                47,
+                53,
+                59,
+                61,
+                67,
+                71,
+                73,
+                79,
+                83,
+                89,
+                97,
+                101,
+                103,
+                107,
+                109,
+                113,
+                127,
+                131,
+                137,
+                139,
+                149,
+                151,
+                157,
+                163,
+                167,
+                173,
+                179,
+                181,
+                191,
+                193,
+                197,
+                199,
+            )
         return True
     # TODO: maybe do some iterations of Miller-Rabin to increase confidence
     # (https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test)
@@ -65,17 +108,114 @@ def quick_is_not_prime(n):
 python_version = (sys.version_info[0], sys.version_info[1])
 if python_version >= (2, 7) or python_version >= (3, 1):
     # Ansible still supports Python 2.6 on remote nodes
+
+    def count_bytes(no):
+        """
+        Given an integer, compute the number of bytes necessary to store its absolute value.
+        """
+        no = abs(no)
+        if no == 0:
+            return 0
+        return (no.bit_length() + 7) // 8
+
     def count_bits(no):
+        """
+        Given an integer, compute the number of bits necessary to store its absolute value.
+        """
         no = abs(no)
         if no == 0:
             return 0
         return no.bit_length()
+
 else:
     # Slow, but works
+    def count_bytes(no):
+        """
+        Given an integer, compute the number of bytes necessary to store its absolute value.
+        """
+        no = abs(no)
+        count = 0
+        while no > 0:
+            no >>= 8
+            count += 1
+        return count
+
     def count_bits(no):
+        """
+        Given an integer, compute the number of bits necessary to store its absolute value.
+        """
         no = abs(no)
         count = 0
         while no > 0:
             no >>= 1
             count += 1
         return count
+
+
+if sys.version_info[0] >= 3:
+    # Python 3 (and newer)
+    def _convert_int_to_bytes(count, no):
+        return no.to_bytes(count, byteorder="big")
+
+    def _convert_bytes_to_int(data):
+        return int.from_bytes(data, byteorder="big", signed=False)
+
+    def _to_hex(no):
+        return hex(no)[2:]
+
+else:
+    # Python 2
+    def _convert_int_to_bytes(count, n):
+        if n == 0 and count == 0:
+            return ""
+        h = "%x" % n
+        if len(h) > 2 * count:
+            raise Exception("Number {1} needs more than {0} bytes!".format(count, n))
+        return ("0" * (2 * count - len(h)) + h).decode("hex")
+
+    def _convert_bytes_to_int(data):
+        v = 0
+        for x in data:
+            v = (v << 8) | ord(x)
+        return v
+
+    def _to_hex(no):
+        return "%x" % no
+
+
+def convert_int_to_bytes(no, count=None):
+    """
+    Convert the absolute value of an integer to a byte string in network byte order.
+
+    If ``count`` is provided, it must be sufficiently large so that the integer's
+    absolute value can be represented with these number of bytes. The resulting byte
+    string will have length exactly ``count``.
+
+    The value zero will be converted to an empty byte string if ``count`` is provided.
+    """
+    no = abs(no)
+    if count is None:
+        count = count_bytes(no)
+    return _convert_int_to_bytes(count, no)
+
+
+def convert_int_to_hex(no, digits=None):
+    """
+    Convert the absolute value of an integer to a string of hexadecimal digits.
+
+    If ``digits`` is provided, the string will be padded on the left with ``0``s so
+    that the returned value has length ``digits``. If ``digits`` is not sufficient,
+    the string will be longer.
+    """
+    no = abs(no)
+    value = _to_hex(no)
+    if digits is not None and len(value) < digits:
+        value = "0" * (digits - len(value)) + value
+    return value
+
+
+def convert_bytes_to_int(data):
+    """
+    Convert a byte string to an unsigned integer in network byte order.
+    """
+    return _convert_bytes_to_int(data)

plugins/module_utils/crypto/module_backends/certificate.py

@@ -1,61 +1,54 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
-# Copyright: (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import abc
 import traceback
 
-from distutils.version import LooseVersion
-
 from ansible.module_utils import six
 from ansible.module_utils.basic import missing_required_lib
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.common import ArgumentSpec
-
+from ansible_collections.community.crypto.plugins.module_utils.argspec import (
+    ArgumentSpec,
+)
 from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import (
-    OpenSSLObjectError,
     OpenSSLBadPassphraseError,
+    OpenSSLObjectError,
 )
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.support import (
-    load_privatekey,
-    load_certificate,
-    load_certificate_request,
-)
-
 from ansible_collections.community.crypto.plugins.module_utils.crypto.cryptography_support import (
     cryptography_compare_public_keys,
+    get_not_valid_after,
+    get_not_valid_before,
 )
-
 from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate_info import (
     get_certificate_info,
 )
+from ansible_collections.community.crypto.plugins.module_utils.crypto.support import (
+    load_certificate,
+    load_certificate_request,
+    load_privatekey,
+)
+from ansible_collections.community.crypto.plugins.module_utils.version import (
+    LooseVersion,
+)
 
-MINIMAL_CRYPTOGRAPHY_VERSION = '1.6'
-MINIMAL_PYOPENSSL_VERSION = '0.15'
 
-PYOPENSSL_IMP_ERR = None
-try:
-    import OpenSSL
-    from OpenSSL import crypto
-    PYOPENSSL_VERSION = LooseVersion(OpenSSL.__version__)
-except ImportError:
-    PYOPENSSL_IMP_ERR = traceback.format_exc()
-    PYOPENSSL_FOUND = False
-else:
-    PYOPENSSL_FOUND = True
+MINIMAL_CRYPTOGRAPHY_VERSION = "1.6"
 
 CRYPTOGRAPHY_IMP_ERR = None
 CRYPTOGRAPHY_VERSION = None
 try:
     import cryptography
     from cryptography import x509
+
     CRYPTOGRAPHY_VERSION = LooseVersion(cryptography.__version__)
 except ImportError:
     CRYPTOGRAPHY_IMP_ERR = traceback.format_exc()
@@ -74,20 +67,21 @@ class CertificateBackend(object):
         self.module = module
         self.backend = backend
 
-        self.force = module.params['force']
-        self.privatekey_path = module.params['privatekey_path']
-        self.privatekey_content = module.params['privatekey_content']
+        self.force = module.params["force"]
+        self.ignore_timestamps = module.params["ignore_timestamps"]
+        self.privatekey_path = module.params["privatekey_path"]
+        self.privatekey_content = module.params["privatekey_content"]
         if self.privatekey_content is not None:
-            self.privatekey_content = self.privatekey_content.encode('utf-8')
-        self.privatekey_passphrase = module.params['privatekey_passphrase']
-        self.csr_path = module.params['csr_path']
-        self.csr_content = module.params['csr_content']
+            self.privatekey_content = self.privatekey_content.encode("utf-8")
+        self.privatekey_passphrase = module.params["privatekey_passphrase"]
+        self.csr_path = module.params["csr_path"]
+        self.csr_content = module.params["csr_content"]
         if self.csr_content is not None:
-            self.csr_content = self.csr_content.encode('utf-8')
+            self.csr_content = self.csr_content.encode("utf-8")
 
         # The following are default values which make sure check() works as
         # before if providers do not explicitly change these properties.
-        self.create_subject_key_identifier = 'never_create'
+        self.create_subject_key_identifier = "never_create"
         self.create_authority_key_identifier = False
 
         self.privatekey = None
@@ -106,10 +100,12 @@ class CertificateBackend(object):
         if data is None:
             return dict()
         try:
-            result = get_certificate_info(self.module, self.backend, data, prefer_one_fingerprint=True)
-            result['can_parse_certificate'] = True
+            result = get_certificate_info(
+                self.module, self.backend, data, prefer_one_fingerprint=True
+            )
+            result["can_parse_certificate"] = True
             return result
-        except Exception as exc:
+        except Exception:
             return dict(can_parse_certificate=False)
 
     @abc.abstractmethod
@@ -125,7 +121,9 @@ class CertificateBackend(object):
     def set_existing(self, certificate_bytes):
         """Set existing certificate bytes. None indicates that the key does not exist."""
         self.existing_certificate_bytes = certificate_bytes
-        self.diff_after = self.diff_before = self._get_info(self.existing_certificate_bytes)
+        self.diff_after = self.diff_before = self._get_info(
+            self.existing_certificate_bytes
+        )
 
     def has_existing(self):
         """Query whether an existing certificate is/has been there."""
@@ -173,64 +171,60 @@ class CertificateBackend(object):
 
     def _check_privatekey(self):
         """Check whether provided parameters match, assuming self.existing_certificate and self.privatekey have been populated."""
-        if self.backend == 'pyopenssl':
-            ctx = OpenSSL.SSL.Context(OpenSSL.SSL.TLSv1_2_METHOD)
-            ctx.use_privatekey(self.privatekey)
-            ctx.use_certificate(self.existing_certificate)
-            try:
-                ctx.check_privatekey()
-                return True
-            except OpenSSL.SSL.Error:
-                return False
-        elif self.backend == 'cryptography':
-            return cryptography_compare_public_keys(self.existing_certificate.public_key(), self.privatekey.public_key())
+        if self.backend == "cryptography":
+            return cryptography_compare_public_keys(
+                self.existing_certificate.public_key(), self.privatekey.public_key()
+            )
 
     def _check_csr(self):
         """Check whether provided parameters match, assuming self.existing_certificate and self.csr have been populated."""
-        if self.backend == 'pyopenssl':
-            # Verify that CSR is signed by certificate's private key
-            try:
-                self.csr.verify(self.existing_certificate.get_pubkey())
-            except OpenSSL.crypto.Error:
-                return False
-            # Check subject
-            if self.check_csr_subject and self.csr.get_subject() != self.existing_certificate.get_subject():
-                return False
-            # Check extensions
-            if not self.check_csr_extensions:
-                return True
-            csr_extensions = self.csr.get_extensions()
-            cert_extension_count = self.existing_certificate.get_extension_count()
-            if len(csr_extensions) != cert_extension_count:
-                return False
-            for extension_number in range(0, cert_extension_count):
-                cert_extension = self.existing_certificate.get_extension(extension_number)
-                csr_extension = filter(lambda extension: extension.get_short_name() == cert_extension.get_short_name(), csr_extensions)
-                if cert_extension.get_data() != list(csr_extension)[0].get_data():
-                    return False
-            return True
-        elif self.backend == 'cryptography':
+        if self.backend == "cryptography":
             # Verify that CSR is signed by certificate's private key
             if not self.csr.is_signature_valid:
                 return False
-            if not cryptography_compare_public_keys(self.csr.public_key(), self.existing_certificate.public_key()):
+            if not cryptography_compare_public_keys(
+                self.csr.public_key(), self.existing_certificate.public_key()
+            ):
                 return False
             # Check subject
-            if self.check_csr_subject and self.csr.subject != self.existing_certificate.subject:
+            if (
+                self.check_csr_subject
+                and self.csr.subject != self.existing_certificate.subject
+            ):
                 return False
             # Check extensions
             if not self.check_csr_extensions:
                 return True
             cert_exts = list(self.existing_certificate.extensions)
             csr_exts = list(self.csr.extensions)
-            if self.create_subject_key_identifier != 'never_create':
+            if self.create_subject_key_identifier != "never_create":
                 # Filter out SubjectKeyIdentifier extension before comparison
-                cert_exts = list(filter(lambda x: not isinstance(x.value, x509.SubjectKeyIdentifier), cert_exts))
-                csr_exts = list(filter(lambda x: not isinstance(x.value, x509.SubjectKeyIdentifier), csr_exts))
+                cert_exts = list(
+                    filter(
+                        lambda x: not isinstance(x.value, x509.SubjectKeyIdentifier),
+                        cert_exts,
+                    )
+                )
+                csr_exts = list(
+                    filter(
+                        lambda x: not isinstance(x.value, x509.SubjectKeyIdentifier),
+                        csr_exts,
+                    )
+                )
             if self.create_authority_key_identifier:
                 # Filter out AuthorityKeyIdentifier extension before comparison
-                cert_exts = list(filter(lambda x: not isinstance(x.value, x509.AuthorityKeyIdentifier), cert_exts))
-                csr_exts = list(filter(lambda x: not isinstance(x.value, x509.AuthorityKeyIdentifier), csr_exts))
+                cert_exts = list(
+                    filter(
+                        lambda x: not isinstance(x.value, x509.AuthorityKeyIdentifier),
+                        cert_exts,
+                    )
+                )
+                csr_exts = list(
+                    filter(
+                        lambda x: not isinstance(x.value, x509.AuthorityKeyIdentifier),
+                        csr_exts,
+                    )
+                )
             if len(cert_exts) != len(csr_exts):
                 return False
             for cert_ext in cert_exts:
@@ -238,46 +232,51 @@ class CertificateBackend(object):
                     csr_ext = self.csr.extensions.get_extension_for_oid(cert_ext.oid)
                     if cert_ext != csr_ext:
                         return False
-                except cryptography.x509.ExtensionNotFound as dummy:
+                except cryptography.x509.ExtensionNotFound:
                     return False
             return True
 
     def _check_subject_key_identifier(self):
         """Check whether Subject Key Identifier matches, assuming self.existing_certificate has been populated."""
-        if self.backend != 'cryptography':
-            # We do not support SKI with pyOpenSSL backend
-            return True
-
         # Get hold of certificate's SKI
         try:
-            ext = self.existing_certificate.extensions.get_extension_for_class(x509.SubjectKeyIdentifier)
-        except cryptography.x509.ExtensionNotFound as dummy:
+            ext = self.existing_certificate.extensions.get_extension_for_class(
+                x509.SubjectKeyIdentifier
+            )
+        except cryptography.x509.ExtensionNotFound:
             return False
         # Get hold of CSR's SKI for 'create_if_not_provided'
         csr_ext = None
-        if self.create_subject_key_identifier == 'create_if_not_provided':
+        if self.create_subject_key_identifier == "create_if_not_provided":
             try:
-                csr_ext = self.csr.extensions.get_extension_for_class(x509.SubjectKeyIdentifier)
-            except cryptography.x509.ExtensionNotFound as dummy:
+                csr_ext = self.csr.extensions.get_extension_for_class(
+                    x509.SubjectKeyIdentifier
+                )
+            except cryptography.x509.ExtensionNotFound:
                 pass
         if csr_ext is None:
             # If CSR had no SKI, or we chose to ignore it ('always_create'), compare with created SKI
-            if ext.value.digest != x509.SubjectKeyIdentifier.from_public_key(self.existing_certificate.public_key()).digest:
+            if (
+                ext.value.digest
+                != x509.SubjectKeyIdentifier.from_public_key(
+                    self.existing_certificate.public_key()
+                ).digest
+            ):
                 return False
         else:
-            # If CSR had SKI and we didn't ignore it ('create_if_not_provided'), compare SKIs
+            # If CSR had SKI and we did not ignore it ('create_if_not_provided'), compare SKIs
             if ext.value.digest != csr_ext.value.digest:
                 return False
         return True
 
-    def needs_regeneration(self):
+    def needs_regeneration(self, not_before=None, not_after=None):
         """Check whether a regeneration is necessary."""
         if self.force or self.existing_certificate_bytes is None:
             return True
 
         try:
             self._ensure_existing_certificate_loaded()
-        except Exception as dummy:
+        except Exception:
             return True
 
         # Check whether private key matches
@@ -291,17 +290,26 @@ class CertificateBackend(object):
             return True
 
         # Check SubjectKeyIdentifier
-        if self.create_subject_key_identifier != 'never_create' and not self._check_subject_key_identifier():
+        if (
+            self.create_subject_key_identifier != "never_create"
+            and not self._check_subject_key_identifier()
+        ):
             return True
 
+        # Check not before
+        if not_before is not None and not self.ignore_timestamps:
+            if get_not_valid_before(self.existing_certificate) != not_before:
+                return True
+
+        # Check not after
+        if not_after is not None and not self.ignore_timestamps:
+            if get_not_valid_after(self.existing_certificate) != not_after:
+                return True
         return False
 
     def dump(self, include_certificate):
         """Serialize the object into a dictionary."""
-        result = {
-            'privatekey': self.privatekey_path,
-            'csr': self.csr_path
-        }
+        result = {"privatekey": self.privatekey_path, "csr": self.csr_path}
         # Get hold of certificate bytes
         certificate_bytes = self.existing_certificate_bytes
         if self.cert is not None:
@@ -309,9 +317,11 @@ class CertificateBackend(object):
         self.diff_after = self._get_info(certificate_bytes)
         if include_certificate:
             # Store result
-            result['certificate'] = certificate_bytes.decode('utf-8') if certificate_bytes else None
+            result["certificate"] = (
+                certificate_bytes.decode("utf-8") if certificate_bytes else None
+            )
 
-        result['diff'] = dict(
+        result["diff"] = dict(
             before=self.diff_before,
             after=self.diff_after,
         )
@@ -328,10 +338,6 @@ class CertificateProvider(object):
     def needs_version_two_certs(self, module):
         """Whether the provider needs to create a version 2 certificate."""
 
-    def needs_pyopenssl_get_extensions(self, module):
-        """Whether the provider needs to use get_extensions() with pyOpenSSL."""
-        return True
-
     @abc.abstractmethod
     def create_backend(self, module, backend):
         """Create an implementation for a backend.
@@ -348,49 +354,38 @@ def select_backend(module, backend, provider):
     """
     provider.validate_module_args(module)
 
-    backend = module.params['select_crypto_backend']
-    if backend == 'auto':
+    backend = module.params["select_crypto_backend"]
+    if backend == "auto":
         # Detect what backend we can use
-        can_use_cryptography = CRYPTOGRAPHY_FOUND and CRYPTOGRAPHY_VERSION >= LooseVersion(MINIMAL_CRYPTOGRAPHY_VERSION)
-        can_use_pyopenssl = PYOPENSSL_FOUND and PYOPENSSL_VERSION >= LooseVersion(MINIMAL_PYOPENSSL_VERSION)
+        can_use_cryptography = (
+            CRYPTOGRAPHY_FOUND
+            and CRYPTOGRAPHY_VERSION >= LooseVersion(MINIMAL_CRYPTOGRAPHY_VERSION)
+        )
 
         # If cryptography is available we'll use it
         if can_use_cryptography:
-            backend = 'cryptography'
-        elif can_use_pyopenssl:
-            backend = 'pyopenssl'
-
-        if provider.needs_version_two_certs(module):
-            module.warn('crypto backend forced to pyopenssl. The cryptography library does not support v2 certificates')
-            backend = 'pyopenssl'
+            backend = "cryptography"
 
         # Fail if no backend has been found
-        if backend == 'auto':
-            module.fail_json(msg=("Can't detect any of the required Python libraries "
-                                  "cryptography (>= {0}) or PyOpenSSL (>= {1})").format(
-                                      MINIMAL_CRYPTOGRAPHY_VERSION,
-                                      MINIMAL_PYOPENSSL_VERSION))
+        if backend == "auto":
+            module.fail_json(
+                msg=(
+                    "Cannot detect the required Python library " "cryptography (>= {0})"
+                ).format(MINIMAL_CRYPTOGRAPHY_VERSION)
+            )
 
-    if backend == 'pyopenssl':
-        module.deprecate('The module is using the PyOpenSSL backend. This backend has been deprecated',
-                         version='2.0.0', collection_name='community.crypto')
-
-        if not PYOPENSSL_FOUND:
-            module.fail_json(msg=missing_required_lib('pyOpenSSL >= {0}'.format(MINIMAL_PYOPENSSL_VERSION)),
-                             exception=PYOPENSSL_IMP_ERR)
-        if provider.needs_pyopenssl_get_extensions(module):
-            try:
-                getattr(crypto.X509Req, 'get_extensions')
-            except AttributeError:
-                module.fail_json(msg='You need to have PyOpenSSL>=0.15')
-
-    elif backend == 'cryptography':
+    if backend == "cryptography":
         if not CRYPTOGRAPHY_FOUND:
-            module.fail_json(msg=missing_required_lib('cryptography >= {0}'.format(MINIMAL_CRYPTOGRAPHY_VERSION)),
-                             exception=CRYPTOGRAPHY_IMP_ERR)
+            module.fail_json(
+                msg=missing_required_lib(
+                    "cryptography >= {0}".format(MINIMAL_CRYPTOGRAPHY_VERSION)
+                ),
+                exception=CRYPTOGRAPHY_IMP_ERR,
+            )
         if provider.needs_version_two_certs(module):
-            module.fail_json(msg='The cryptography backend does not support v2 certificates, '
-                                 'use select_crypto_backend=pyopenssl for v2 certificates')
+            module.fail_json(
+                msg="The cryptography backend does not support v2 certificates"
+            )
 
     return provider.create_backend(module, backend)
 
@@ -398,19 +393,26 @@ def select_backend(module, backend, provider):
 def get_certificate_argument_spec():
     return ArgumentSpec(
         argument_spec=dict(
-            provider=dict(type='str', choices=[]),  # choices will be filled by add_XXX_provider_to_argument_spec() in certificate_xxx.py
-            force=dict(type='bool', default=False,),
-            csr_path=dict(type='path'),
-            csr_content=dict(type='str'),
-            select_crypto_backend=dict(type='str', default='auto', choices=['auto', 'cryptography', 'pyopenssl']),
-
+            provider=dict(
+                type="str", choices=[]
+            ),  # choices will be filled by add_XXX_provider_to_argument_spec() in certificate_xxx.py
+            force=dict(
+                type="bool",
+                default=False,
+            ),
+            csr_path=dict(type="path"),
+            csr_content=dict(type="str"),
+            ignore_timestamps=dict(type="bool", default=True),
+            select_crypto_backend=dict(
+                type="str", default="auto", choices=["auto", "cryptography"]
+            ),
             # General properties of a certificate
-            privatekey_path=dict(type='path'),
-            privatekey_content=dict(type='str', no_log=True),
-            privatekey_passphrase=dict(type='str', no_log=True),
+            privatekey_path=dict(type="path"),
+            privatekey_content=dict(type="str", no_log=True),
+            privatekey_passphrase=dict(type="str", no_log=True),
         ),
         mutually_exclusive=[
-            ['csr_path', 'csr_content'],
-            ['privatekey_path', 'privatekey_content'],
+            ["csr_path", "csr_content"],
+            ["privatekey_path", "privatekey_content"],
         ],
     )

plugins/module_utils/crypto/module_backends/certificate_acme.py

@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
-# Copyright: (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
@@ -12,11 +15,10 @@ import os
 import tempfile
 import traceback
 
-from ansible.module_utils.common.text.converters import to_native, to_bytes
-
+from ansible.module_utils.common.text.converters import to_bytes, to_native
 from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate import (
-    CertificateError,
     CertificateBackend,
+    CertificateError,
     CertificateProvider,
 )
 
@@ -24,61 +26,61 @@ from ansible_collections.community.crypto.plugins.module_utils.crypto.module_bac
 class AcmeCertificateBackend(CertificateBackend):
     def __init__(self, module, backend):
         super(AcmeCertificateBackend, self).__init__(module, backend)
-        self.accountkey_path = module.params['acme_accountkey_path']
-        self.challenge_path = module.params['acme_challenge_path']
-        self.use_chain = module.params['acme_chain']
-        self.acme_directory = module.params['acme_directory']
+        self.accountkey_path = module.params["acme_accountkey_path"]
+        self.challenge_path = module.params["acme_challenge_path"]
+        self.use_chain = module.params["acme_chain"]
+        self.acme_directory = module.params["acme_directory"]
 
         if self.csr_content is None and self.csr_path is None:
             raise CertificateError(
-                'csr_path or csr_content is required for ownca provider'
+                "csr_path or csr_content is required for ownca provider"
             )
         if self.csr_content is None and not os.path.exists(self.csr_path):
             raise CertificateError(
-                'The certificate signing request file %s does not exist' % self.csr_path
+                "The certificate signing request file %s does not exist" % self.csr_path
             )
 
         if not os.path.exists(self.accountkey_path):
             raise CertificateError(
-                'The account key %s does not exist' % self.accountkey_path
+                "The account key %s does not exist" % self.accountkey_path
             )
 
         if not os.path.exists(self.challenge_path):
             raise CertificateError(
-                'The challenge path %s does not exist' % self.challenge_path
+                "The challenge path %s does not exist" % self.challenge_path
             )
 
-        self.acme_tiny_path = self.module.get_bin_path('acme-tiny', required=True)
+        self.acme_tiny_path = self.module.get_bin_path("acme-tiny", required=True)
 
     def generate_certificate(self):
         """(Re-)Generate certificate."""
 
         command = [self.acme_tiny_path]
         if self.use_chain:
-            command.append('--chain')
-        command.extend(['--account-key', self.accountkey_path])
+            command.append("--chain")
+        command.extend(["--account-key", self.accountkey_path])
         if self.csr_content is not None:
             # We need to temporarily write the CSR to disk
             fd, tmpsrc = tempfile.mkstemp()
             self.module.add_cleanup_file(tmpsrc)  # Ansible will delete the file on exit
-            f = os.fdopen(fd, 'wb')
+            f = os.fdopen(fd, "wb")
             try:
                 f.write(self.csr_content)
             except Exception as err:
                 try:
                     f.close()
-                except Exception as dummy:
+                except Exception:
                     pass
                 self.module.fail_json(
                     msg="failed to create temporary CSR file: %s" % to_native(err),
-                    exception=traceback.format_exc()
+                    exception=traceback.format_exc(),
                 )
             f.close()
-            command.extend(['--csr', tmpsrc])
+            command.extend(["--csr", tmpsrc])
         else:
-            command.extend(['--csr', self.csr_path])
-        command.extend(['--acme-dir', self.challenge_path])
-        command.extend(['--directory-url', self.acme_directory])
+            command.extend(["--csr", self.csr_path])
+        command.extend(["--acme-dir", self.challenge_path])
+        command.extend(["--directory-url", self.acme_directory])
 
         try:
             self.cert = to_bytes(self.module.run_command(command, check_rc=True)[1])
@@ -91,16 +93,20 @@ class AcmeCertificateBackend(CertificateBackend):
 
     def dump(self, include_certificate):
         result = super(AcmeCertificateBackend, self).dump(include_certificate)
-        result['accountkey'] = self.accountkey_path
+        result["accountkey"] = self.accountkey_path
         return result
 
 
 class AcmeCertificateProvider(CertificateProvider):
     def validate_module_args(self, module):
-        if module.params['acme_accountkey_path'] is None:
-            module.fail_json(msg='The acme_accountkey_path option must be specified for the acme provider.')
-        if module.params['acme_challenge_path'] is None:
-            module.fail_json(msg='The acme_challenge_path option must be specified for the acme provider.')
+        if module.params["acme_accountkey_path"] is None:
+            module.fail_json(
+                msg="The acme_accountkey_path option must be specified for the acme provider."
+            )
+        if module.params["acme_challenge_path"] is None:
+            module.fail_json(
+                msg="The acme_challenge_path option must be specified for the acme provider."
+            )
 
     def needs_version_two_certs(self, module):
         return False
@@ -110,10 +116,14 @@ class AcmeCertificateProvider(CertificateProvider):
 
 
 def add_acme_provider_to_argument_spec(argument_spec):
-    argument_spec.argument_spec['provider']['choices'].append('acme')
-    argument_spec.argument_spec.update(dict(
-        acme_accountkey_path=dict(type='path'),
-        acme_challenge_path=dict(type='path'),
-        acme_chain=dict(type='bool', default=False),
-        acme_directory=dict(type='str', default="https://acme-v02.api.letsencrypt.org/directory"),
-    ))
+    argument_spec.argument_spec["provider"]["choices"].append("acme")
+    argument_spec.argument_spec.update(
+        dict(
+            acme_accountkey_path=dict(type="path"),
+            acme_challenge_path=dict(type="path"),
+            acme_chain=dict(type="bool", default=False),
+            acme_directory=dict(
+                type="str", default="https://acme-v02.api.letsencrypt.org/directory"
+            ),
+        )
+    )

plugins/module_utils/crypto/module_backends/certificate_assertonly.py

@@ -1,664 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# Copyright: (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
-# Copyright: (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-
-from __future__ import absolute_import, division, print_function
-__metaclass__ = type
-
-
-import abc
-import datetime
-
-from ansible.module_utils.common.text.converters import to_native, to_bytes, to_text
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.support import (
-    parse_name_field,
-    get_relative_time_option,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.cryptography_support import (
-    cryptography_compare_public_keys,
-    cryptography_get_name,
-    cryptography_name_to_oid,
-    cryptography_parse_key_usage_params,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.pyopenssl_support import (
-    pyopenssl_normalize_name_attribute,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate import (
-    CertificateBackend,
-    CertificateProvider,
-)
-
-try:
-    import OpenSSL
-    from OpenSSL import crypto
-except ImportError:
-    pass
-
-try:
-    import cryptography
-    from cryptography import x509
-    from cryptography.x509 import NameAttribute, Name
-except ImportError:
-    pass
-
-
-def compare_sets(subset, superset, equality=False):
-    if equality:
-        return set(subset) == set(superset)
-    else:
-        return all(x in superset for x in subset)
-
-
-def compare_dicts(subset, superset, equality=False):
-    if equality:
-        return subset == superset
-    else:
-        return all(superset.get(x) == v for x, v in subset.items())
-
-
-NO_EXTENSION = 'no extension'
-
-
-class AssertOnlyCertificateBackend(CertificateBackend):
-    def __init__(self, module, backend):
-        super(AssertOnlyCertificateBackend, self).__init__(module, backend)
-
-        self.signature_algorithms = module.params['signature_algorithms']
-        if module.params['subject']:
-            self.subject = parse_name_field(module.params['subject'])
-        else:
-            self.subject = []
-        self.subject_strict = module.params['subject_strict']
-        if module.params['issuer']:
-            self.issuer = parse_name_field(module.params['issuer'])
-        else:
-            self.issuer = []
-        self.issuer_strict = module.params['issuer_strict']
-        self.has_expired = module.params['has_expired']
-        self.version = module.params['version']
-        self.key_usage = module.params['key_usage']
-        self.key_usage_strict = module.params['key_usage_strict']
-        self.extended_key_usage = module.params['extended_key_usage']
-        self.extended_key_usage_strict = module.params['extended_key_usage_strict']
-        self.subject_alt_name = module.params['subject_alt_name']
-        self.subject_alt_name_strict = module.params['subject_alt_name_strict']
-        self.not_before = module.params['not_before']
-        self.not_after = module.params['not_after']
-        self.valid_at = module.params['valid_at']
-        self.invalid_at = module.params['invalid_at']
-        self.valid_in = module.params['valid_in']
-        if self.valid_in and not self.valid_in.startswith("+") and not self.valid_in.startswith("-"):
-            try:
-                int(self.valid_in)
-            except ValueError:
-                module.fail_json(msg='The supplied value for "valid_in" (%s) is not an integer or a valid timespec' % self.valid_in)
-            self.valid_in = "+" + self.valid_in + "s"
-
-        # Load objects
-        self._ensure_private_key_loaded()
-        self._ensure_csr_loaded()
-
-    @abc.abstractmethod
-    def _validate_privatekey(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_csr_signature(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_csr_subject(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_csr_extensions(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_signature_algorithms(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_subject(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_issuer(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_has_expired(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_version(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_key_usage(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_extended_key_usage(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_subject_alt_name(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_not_before(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_not_after(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_valid_at(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_invalid_at(self):
-        pass
-
-    @abc.abstractmethod
-    def _validate_valid_in(self):
-        pass
-
-    def assertonly(self):
-        messages = []
-        if self.privatekey_path is not None or self.privatekey_content is not None:
-            if not self._validate_privatekey():
-                messages.append(
-                    'Certificate and private key %s do not match' %
-                    (self.privatekey_path or '(provided in module options)')
-                )
-
-        if self.csr_path is not None or self.csr_content is not None:
-            if not self._validate_csr_signature():
-                messages.append(
-                    'Certificate and CSR %s do not match: private key mismatch' %
-                    (self.csr_path or '(provided in module options)')
-                )
-            if not self._validate_csr_subject():
-                messages.append(
-                    'Certificate and CSR %s do not match: subject mismatch' %
-                    (self.csr_path or '(provided in module options)')
-                )
-            if not self._validate_csr_extensions():
-                messages.append(
-                    'Certificate and CSR %s do not match: extensions mismatch' %
-                    (self.csr_path or '(provided in module options)')
-                )
-
-        if self.signature_algorithms is not None:
-            wrong_alg = self._validate_signature_algorithms()
-            if wrong_alg:
-                messages.append(
-                    'Invalid signature algorithm (got %s, expected one of %s)' %
-                    (wrong_alg, self.signature_algorithms)
-                )
-
-        if self.subject is not None:
-            failure = self._validate_subject()
-            if failure:
-                dummy, cert_subject = failure
-                messages.append(
-                    'Invalid subject component (got %s, expected all of %s to be present)' %
-                    (cert_subject, self.subject)
-                )
-
-        if self.issuer is not None:
-            failure = self._validate_issuer()
-            if failure:
-                dummy, cert_issuer = failure
-                messages.append(
-                    'Invalid issuer component (got %s, expected all of %s to be present)' % (cert_issuer, self.issuer)
-                )
-
-        if self.has_expired is not None:
-            cert_expired = self._validate_has_expired()
-            if cert_expired != self.has_expired:
-                messages.append(
-                    'Certificate expiration check failed (certificate expiration is %s, expected %s)' %
-                    (cert_expired, self.has_expired)
-                )
-
-        if self.version is not None:
-            cert_version = self._validate_version()
-            if cert_version != self.version:
-                messages.append(
-                    'Invalid certificate version number (got %s, expected %s)' %
-                    (cert_version, self.version)
-                )
-
-        if self.key_usage is not None:
-            failure = self._validate_key_usage()
-            if failure == NO_EXTENSION:
-                messages.append('Found no keyUsage extension')
-            elif failure:
-                dummy, cert_key_usage = failure
-                messages.append(
-                    'Invalid keyUsage components (got %s, expected all of %s to be present)' %
-                    (cert_key_usage, self.key_usage)
-                )
-
-        if self.extended_key_usage is not None:
-            failure = self._validate_extended_key_usage()
-            if failure == NO_EXTENSION:
-                messages.append('Found no extendedKeyUsage extension')
-            elif failure:
-                dummy, ext_cert_key_usage = failure
-                messages.append(
-                    'Invalid extendedKeyUsage component (got %s, expected all of %s to be present)' % (ext_cert_key_usage, self.extended_key_usage)
-                )
-
-        if self.subject_alt_name is not None:
-            failure = self._validate_subject_alt_name()
-            if failure == NO_EXTENSION:
-                messages.append('Found no subjectAltName extension')
-            elif failure:
-                dummy, cert_san = failure
-                messages.append(
-                    'Invalid subjectAltName component (got %s, expected all of %s to be present)' %
-                    (cert_san, self.subject_alt_name)
-                )
-
-        if self.not_before is not None:
-            cert_not_valid_before = self._validate_not_before()
-            if cert_not_valid_before != get_relative_time_option(self.not_before, 'not_before', backend=self.backend):
-                messages.append(
-                    'Invalid not_before component (got %s, expected %s to be present)' %
-                    (cert_not_valid_before, self.not_before)
-                )
-
-        if self.not_after is not None:
-            cert_not_valid_after = self._validate_not_after()
-            if cert_not_valid_after != get_relative_time_option(self.not_after, 'not_after', backend=self.backend):
-                messages.append(
-                    'Invalid not_after component (got %s, expected %s to be present)' %
-                    (cert_not_valid_after, self.not_after)
-                )
-
-        if self.valid_at is not None:
-            not_before, valid_at, not_after = self._validate_valid_at()
-            if not (not_before <= valid_at <= not_after):
-                messages.append(
-                    'Certificate is not valid for the specified date (%s) - not_before: %s - not_after: %s' %
-                    (self.valid_at, not_before, not_after)
-                )
-
-        if self.invalid_at is not None:
-            not_before, invalid_at, not_after = self._validate_invalid_at()
-            if not_before <= invalid_at <= not_after:
-                messages.append(
-                    'Certificate is not invalid for the specified date (%s) - not_before: %s - not_after: %s' %
-                    (self.invalid_at, not_before, not_after)
-                )
-
-        if self.valid_in is not None:
-            not_before, valid_in, not_after = self._validate_valid_in()
-            if not not_before <= valid_in <= not_after:
-                messages.append(
-                    'Certificate is not valid in %s from now (that would be %s) - not_before: %s - not_after: %s' %
-                    (self.valid_in, valid_in, not_before, not_after)
-                )
-        return messages
-
-    def needs_regeneration(self):
-        self._ensure_existing_certificate_loaded()
-        if self.existing_certificate is None:
-            self.messages = ['Certificate not provided']
-        else:
-            self.messages = self.assertonly()
-
-        return len(self.messages) != 0
-
-    def generate_certificate(self):
-        self.module.fail_json(msg=' | '.join(self.messages))
-
-    def get_certificate_data(self):
-        return self.existing_certificate_bytes
-
-
-class AssertOnlyCertificateBackendCryptography(AssertOnlyCertificateBackend):
-    """Validate the supplied cert, using the cryptography backend"""
-    def __init__(self, module):
-        super(AssertOnlyCertificateBackendCryptography, self).__init__(module, 'cryptography')
-
-    def _validate_privatekey(self):
-        return cryptography_compare_public_keys(self.existing_certificate.public_key(), self.privatekey.public_key())
-
-    def _validate_csr_signature(self):
-        if not self.csr.is_signature_valid:
-            return False
-        return cryptography_compare_public_keys(self.csr.public_key(), self.existing_certificate.public_key())
-
-    def _validate_csr_subject(self):
-        return self.csr.subject == self.existing_certificate.subject
-
-    def _validate_csr_extensions(self):
-        cert_exts = self.existing_certificate.extensions
-        csr_exts = self.csr.extensions
-        if len(cert_exts) != len(csr_exts):
-            return False
-        for cert_ext in cert_exts:
-            try:
-                csr_ext = csr_exts.get_extension_for_oid(cert_ext.oid)
-                if cert_ext != csr_ext:
-                    return False
-            except cryptography.x509.ExtensionNotFound as dummy:
-                return False
-        return True
-
-    def _validate_signature_algorithms(self):
-        if self.existing_certificate.signature_algorithm_oid._name not in self.signature_algorithms:
-            return self.existing_certificate.signature_algorithm_oid._name
-
-    def _validate_subject(self):
-        expected_subject = Name([NameAttribute(oid=cryptography_name_to_oid(sub[0]), value=to_text(sub[1]))
-                                 for sub in self.subject])
-        cert_subject = self.existing_certificate.subject
-        if not compare_sets(expected_subject, cert_subject, self.subject_strict):
-            return expected_subject, cert_subject
-
-    def _validate_issuer(self):
-        expected_issuer = Name([NameAttribute(oid=cryptography_name_to_oid(iss[0]), value=to_text(iss[1]))
-                                for iss in self.issuer])
-        cert_issuer = self.existing_certificate.issuer
-        if not compare_sets(expected_issuer, cert_issuer, self.issuer_strict):
-            return self.issuer, cert_issuer
-
-    def _validate_has_expired(self):
-        cert_not_after = self.existing_certificate.not_valid_after
-        cert_expired = cert_not_after < datetime.datetime.utcnow()
-        return cert_expired
-
-    def _validate_version(self):
-        if self.existing_certificate.version == x509.Version.v1:
-            return 1
-        if self.existing_certificate.version == x509.Version.v3:
-            return 3
-        return "unknown"
-
-    def _validate_key_usage(self):
-        try:
-            current_key_usage = self.existing_certificate.extensions.get_extension_for_class(x509.KeyUsage).value
-            test_key_usage = dict(
-                digital_signature=current_key_usage.digital_signature,
-                content_commitment=current_key_usage.content_commitment,
-                key_encipherment=current_key_usage.key_encipherment,
-                data_encipherment=current_key_usage.data_encipherment,
-                key_agreement=current_key_usage.key_agreement,
-                key_cert_sign=current_key_usage.key_cert_sign,
-                crl_sign=current_key_usage.crl_sign,
-                encipher_only=False,
-                decipher_only=False
-            )
-            if test_key_usage['key_agreement']:
-                test_key_usage.update(dict(
-                    encipher_only=current_key_usage.encipher_only,
-                    decipher_only=current_key_usage.decipher_only
-                ))
-
-            key_usages = cryptography_parse_key_usage_params(self.key_usage)
-            if not compare_dicts(key_usages, test_key_usage, self.key_usage_strict):
-                return self.key_usage, [k for k, v in test_key_usage.items() if v is True]
-
-        except cryptography.x509.ExtensionNotFound:
-            # This is only bad if the user specified a non-empty list
-            if self.key_usage:
-                return NO_EXTENSION
-
-    def _validate_extended_key_usage(self):
-        try:
-            current_ext_keyusage = self.existing_certificate.extensions.get_extension_for_class(x509.ExtendedKeyUsage).value
-            usages = [cryptography_name_to_oid(usage) for usage in self.extended_key_usage]
-            expected_ext_keyusage = x509.ExtendedKeyUsage(usages)
-            if not compare_sets(expected_ext_keyusage, current_ext_keyusage, self.extended_key_usage_strict):
-                return [eku.value for eku in expected_ext_keyusage], [eku.value for eku in current_ext_keyusage]
-
-        except cryptography.x509.ExtensionNotFound:
-            # This is only bad if the user specified a non-empty list
-            if self.extended_key_usage:
-                return NO_EXTENSION
-
-    def _validate_subject_alt_name(self):
-        try:
-            current_san = self.existing_certificate.extensions.get_extension_for_class(x509.SubjectAlternativeName).value
-            expected_san = [cryptography_get_name(san) for san in self.subject_alt_name]
-            if not compare_sets(expected_san, current_san, self.subject_alt_name_strict):
-                return self.subject_alt_name, current_san
-        except cryptography.x509.ExtensionNotFound:
-            # This is only bad if the user specified a non-empty list
-            if self.subject_alt_name:
-                return NO_EXTENSION
-
-    def _validate_not_before(self):
-        return self.existing_certificate.not_valid_before
-
-    def _validate_not_after(self):
-        return self.existing_certificate.not_valid_after
-
-    def _validate_valid_at(self):
-        rt = get_relative_time_option(self.valid_at, 'valid_at', backend=self.backend)
-        return self.existing_certificate.not_valid_before, rt, self.existing_certificate.not_valid_after
-
-    def _validate_invalid_at(self):
-        rt = get_relative_time_option(self.invalid_at, 'invalid_at', backend=self.backend)
-        return self.existing_certificate.not_valid_before, rt, self.existing_certificate.not_valid_after
-
-    def _validate_valid_in(self):
-        valid_in_date = get_relative_time_option(self.valid_in, "valid_in", backend=self.backend)
-        return self.existing_certificate.not_valid_before, valid_in_date, self.existing_certificate.not_valid_after
-
-
-class AssertOnlyCertificateBackendPyOpenSSL(AssertOnlyCertificateBackend):
-    """validate the supplied certificate."""
-
-    def __init__(self, module):
-        super(AssertOnlyCertificateBackendPyOpenSSL, self).__init__(module, 'pyopenssl')
-
-        # Ensure inputs are properly sanitized before comparison.
-        for param in ['signature_algorithms', 'key_usage', 'extended_key_usage',
-                      'subject_alt_name', 'subject', 'issuer', 'not_before',
-                      'not_after', 'valid_at', 'invalid_at']:
-            attr = getattr(self, param)
-            if isinstance(attr, list) and attr:
-                if isinstance(attr[0], str):
-                    setattr(self, param, [to_bytes(item) for item in attr])
-                elif isinstance(attr[0], tuple):
-                    setattr(self, param, [(to_bytes(item[0]), to_bytes(item[1])) for item in attr])
-            elif isinstance(attr, tuple):
-                setattr(self, param, dict((to_bytes(k), to_bytes(v)) for (k, v) in attr.items()))
-            elif isinstance(attr, dict):
-                setattr(self, param, dict((to_bytes(k), to_bytes(v)) for (k, v) in attr.items()))
-            elif isinstance(attr, str):
-                setattr(self, param, to_bytes(attr))
-
-    def _validate_privatekey(self):
-        ctx = OpenSSL.SSL.Context(OpenSSL.SSL.TLSv1_2_METHOD)
-        ctx.use_privatekey(self.privatekey)
-        ctx.use_certificate(self.existing_certificate)
-        try:
-            ctx.check_privatekey()
-            return True
-        except OpenSSL.SSL.Error:
-            return False
-
-    def _validate_csr_signature(self):
-        try:
-            self.csr.verify(self.existing_certificate.get_pubkey())
-        except OpenSSL.crypto.Error:
-            return False
-
-    def _validate_csr_subject(self):
-        if self.csr.get_subject() != self.existing_certificate.get_subject():
-            return False
-
-    def _validate_csr_extensions(self):
-        csr_extensions = self.csr.get_extensions()
-        cert_extension_count = self.existing_certificate.get_extension_count()
-        if len(csr_extensions) != cert_extension_count:
-            return False
-        for extension_number in range(0, cert_extension_count):
-            cert_extension = self.existing_certificate.get_extension(extension_number)
-            csr_extension = filter(lambda extension: extension.get_short_name() == cert_extension.get_short_name(), csr_extensions)
-            if cert_extension.get_data() != list(csr_extension)[0].get_data():
-                return False
-        return True
-
-    def _validate_signature_algorithms(self):
-        if self.existing_certificate.get_signature_algorithm() not in self.signature_algorithms:
-            return self.existing_certificate.get_signature_algorithm()
-
-    def _validate_subject(self):
-        expected_subject = [(OpenSSL._util.lib.OBJ_txt2nid(sub[0]), sub[1]) for sub in self.subject]
-        cert_subject = self.existing_certificate.get_subject().get_components()
-        current_subject = [(OpenSSL._util.lib.OBJ_txt2nid(sub[0]), sub[1]) for sub in cert_subject]
-        if not compare_sets(expected_subject, current_subject, self.subject_strict):
-            return expected_subject, current_subject
-
-    def _validate_issuer(self):
-        expected_issuer = [(OpenSSL._util.lib.OBJ_txt2nid(iss[0]), iss[1]) for iss in self.issuer]
-        cert_issuer = self.existing_certificate.get_issuer().get_components()
-        current_issuer = [(OpenSSL._util.lib.OBJ_txt2nid(iss[0]), iss[1]) for iss in cert_issuer]
-        if not compare_sets(expected_issuer, current_issuer, self.issuer_strict):
-            return self.issuer, cert_issuer
-
-    def _validate_has_expired(self):
-        # The following 3 lines are the same as the current PyOpenSSL code for cert.has_expired().
-        # Older version of PyOpenSSL have a buggy implementation,
-        # to avoid issues with those we added the code from a more recent release here.
-
-        time_string = to_native(self.existing_certificate.get_notAfter())
-        not_after = datetime.datetime.strptime(time_string, "%Y%m%d%H%M%SZ")
-        cert_expired = not_after < datetime.datetime.utcnow()
-        return cert_expired
-
-    def _validate_version(self):
-        # Version numbers in certs are off by one:
-        # v1: 0, v2: 1, v3: 2 ...
-        return self.existing_certificate.get_version() + 1
-
-    def _validate_key_usage(self):
-        found = False
-        for extension_idx in range(0, self.existing_certificate.get_extension_count()):
-            extension = self.existing_certificate.get_extension(extension_idx)
-            if extension.get_short_name() == b'keyUsage':
-                found = True
-                expected_extension = crypto.X509Extension(b"keyUsage", False, b', '.join(self.key_usage))
-                key_usage = [usage.strip() for usage in to_text(expected_extension, errors='surrogate_or_strict').split(',')]
-                current_ku = [usage.strip() for usage in to_text(extension, errors='surrogate_or_strict').split(',')]
-                if not compare_sets(key_usage, current_ku, self.key_usage_strict):
-                    return self.key_usage, str(extension).split(', ')
-        if not found:
-            # This is only bad if the user specified a non-empty list
-            if self.key_usage:
-                return NO_EXTENSION
-
-    def _validate_extended_key_usage(self):
-        found = False
-        for extension_idx in range(0, self.existing_certificate.get_extension_count()):
-            extension = self.existing_certificate.get_extension(extension_idx)
-            if extension.get_short_name() == b'extendedKeyUsage':
-                found = True
-                extKeyUsage = [OpenSSL._util.lib.OBJ_txt2nid(keyUsage) for keyUsage in self.extended_key_usage]
-                current_xku = [OpenSSL._util.lib.OBJ_txt2nid(usage.strip()) for usage in
-                               to_bytes(extension, errors='surrogate_or_strict').split(b',')]
-                if not compare_sets(extKeyUsage, current_xku, self.extended_key_usage_strict):
-                    return self.extended_key_usage, str(extension).split(', ')
-        if not found:
-            # This is only bad if the user specified a non-empty list
-            if self.extended_key_usage:
-                return NO_EXTENSION
-
-    def _validate_subject_alt_name(self):
-        found = False
-        for extension_idx in range(0, self.existing_certificate.get_extension_count()):
-            extension = self.existing_certificate.get_extension(extension_idx)
-            if extension.get_short_name() == b'subjectAltName':
-                found = True
-                l_altnames = [pyopenssl_normalize_name_attribute(altname.strip()) for altname in
-                              to_text(extension, errors='surrogate_or_strict').split(', ')]
-                sans = [pyopenssl_normalize_name_attribute(to_text(san, errors='surrogate_or_strict')) for san in self.subject_alt_name]
-                if not compare_sets(sans, l_altnames, self.subject_alt_name_strict):
-                    return self.subject_alt_name, l_altnames
-        if not found:
-            # This is only bad if the user specified a non-empty list
-            if self.subject_alt_name:
-                return NO_EXTENSION
-
-    def _validate_not_before(self):
-        return self.existing_certificate.get_notBefore()
-
-    def _validate_not_after(self):
-        return self.existing_certificate.get_notAfter()
-
-    def _validate_valid_at(self):
-        rt = get_relative_time_option(self.valid_at, "valid_at", backend=self.backend)
-        rt = to_bytes(rt, errors='surrogate_or_strict')
-        return self.existing_certificate.get_notBefore(), rt, self.existing_certificate.get_notAfter()
-
-    def _validate_invalid_at(self):
-        rt = get_relative_time_option(self.invalid_at, "invalid_at", backend=self.backend)
-        rt = to_bytes(rt, errors='surrogate_or_strict')
-        return self.existing_certificate.get_notBefore(), rt, self.existing_certificate.get_notAfter()
-
-    def _validate_valid_in(self):
-        valid_in_asn1 = get_relative_time_option(self.valid_in, "valid_in", backend=self.backend)
-        valid_in_date = to_bytes(valid_in_asn1, errors='surrogate_or_strict')
-        return self.existing_certificate.get_notBefore(), valid_in_date, self.existing_certificate.get_notAfter()
-
-
-class AssertOnlyCertificateProvider(CertificateProvider):
-    def validate_module_args(self, module):
-        module.deprecate("The 'assertonly' provider is deprecated; please see the examples of "
-                         "the 'x509_certificate' module on how to replace it with other modules",
-                         version='2.0.0', collection_name='community.crypto')
-
-    def needs_version_two_certs(self, module):
-        return False
-
-    def create_backend(self, module, backend):
-        if backend == 'cryptography':
-            return AssertOnlyCertificateBackendCryptography(module)
-        if backend == 'pyopenssl':
-            return AssertOnlyCertificateBackendPyOpenSSL(module)
-
-
-def add_assertonly_provider_to_argument_spec(argument_spec):
-    argument_spec.argument_spec['provider']['choices'].append('assertonly')
-    argument_spec.argument_spec.update(dict(
-        signature_algorithms=dict(type='list', elements='str', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        subject=dict(type='dict', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        subject_strict=dict(type='bool', default=False, removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        issuer=dict(type='dict', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        issuer_strict=dict(type='bool', default=False, removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        has_expired=dict(type='bool', default=False, removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        version=dict(type='int', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        key_usage=dict(type='list', elements='str', aliases=['keyUsage'],
-                       removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        key_usage_strict=dict(type='bool', default=False, aliases=['keyUsage_strict'],
-                              removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        extended_key_usage=dict(type='list', elements='str', aliases=['extendedKeyUsage'],
-                                removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        extended_key_usage_strict=dict(type='bool', default=False, aliases=['extendedKeyUsage_strict'],
-                                       removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        subject_alt_name=dict(type='list', elements='str', aliases=['subjectAltName'],
-                              removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        subject_alt_name_strict=dict(type='bool', default=False, aliases=['subjectAltName_strict'],
-                                     removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        not_before=dict(type='str', aliases=['notBefore'], removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        not_after=dict(type='str', aliases=['notAfter'], removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        valid_at=dict(type='str', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        invalid_at=dict(type='str', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-        valid_in=dict(type='str', removed_in_version='2.0.0', removed_from_collection='community.crypto'),
-    ))

plugins/module_utils/crypto/module_backends/certificate_entrust.py

@@ -1,35 +1,43 @@
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
-# Copyright: (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
 
 from __future__ import absolute_import, division, print_function
+
+
 __metaclass__ = type
 
 
 import datetime
-import time
 import os
 
-from ansible.module_utils.common.text.converters import to_native, to_bytes
-
-from ansible_collections.community.crypto.plugins.module_utils.ecs.api import ECSClient, RestOperationException, SessionConfigurationException
-
+from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible_collections.community.crypto.plugins.module_utils.crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_serial_number_of_cert,
+    get_not_valid_after,
+)
+from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate import (
+    CertificateBackend,
+    CertificateError,
+    CertificateProvider,
+)
 from ansible_collections.community.crypto.plugins.module_utils.crypto.support import (
     load_certificate,
+)
+from ansible_collections.community.crypto.plugins.module_utils.ecs.api import (
+    ECSClient,
+    RestOperationException,
+    SessionConfigurationException,
+)
+from ansible_collections.community.crypto.plugins.module_utils.time import (
+    get_now_datetime,
     get_relative_time_option,
 )
 
-from ansible_collections.community.crypto.plugins.module_utils.crypto.cryptography_support import (
-    cryptography_serial_number_of_cert,
-)
-
-from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate import (
-    CertificateError,
-    CertificateBackend,
-    CertificateProvider,
-)
 
 try:
     from cryptography.x509.oid import NameOID
@@ -41,15 +49,22 @@ class EntrustCertificateBackend(CertificateBackend):
     def __init__(self, module, backend):
         super(EntrustCertificateBackend, self).__init__(module, backend)
         self.trackingId = None
-        self.notAfter = get_relative_time_option(module.params['entrust_not_after'], 'entrust_not_after', backend=self.backend)
+        self.notAfter = get_relative_time_option(
+            module.params["entrust_not_after"],
+            "entrust_not_after",
+            backend=self.backend,
+            with_timezone=CRYPTOGRAPHY_TIMEZONE,
+        )
 
         if self.csr_content is None and self.csr_path is None:
             raise CertificateError(
-                'csr_path or csr_content is required for entrust provider'
+                "csr_path or csr_content is required for entrust provider"
             )
         if self.csr_content is None and not os.path.exists(self.csr_path):
             raise CertificateError(
-                'The certificate signing request file {0} does not exist'.format(self.csr_path)
+                "The certificate signing request file {0} does not exist".format(
+                    self.csr_path
+                )
             )
 
         self._ensure_csr_loaded()
@@ -58,39 +73,42 @@ class EntrustCertificateBackend(CertificateBackend):
         # We want to always force behavior of trying to use the organization provided in the CSR.
         # To that end we need to parse out the organization from the CSR.
         self.csr_org = None
-        if self.backend == 'pyopenssl':
-            csr_subject = self.csr.get_subject()
-            csr_subject_components = csr_subject.get_components()
-            for k, v in csr_subject_components:
-                if k.upper() == 'O':
-                    # Entrust does not support multiple validated organizations in a single certificate
-                    if self.csr_org is not None:
-                        self.module.fail_json(msg=("Entrust provider does not currently support multiple validated organizations. Multiple organizations "
-                                                   "found in Subject DN: '{0}'. ".format(csr_subject)))
-                    else:
-                        self.csr_org = v
-        elif self.backend == 'cryptography':
-            csr_subject_orgs = self.csr.subject.get_attributes_for_oid(NameOID.ORGANIZATION_NAME)
+        if self.backend == "cryptography":
+            csr_subject_orgs = self.csr.subject.get_attributes_for_oid(
+                NameOID.ORGANIZATION_NAME
+            )
             if len(csr_subject_orgs) == 1:
                 self.csr_org = csr_subject_orgs[0].value
             elif len(csr_subject_orgs) > 1:
-                self.module.fail_json(msg=("Entrust provider does not currently support multiple validated organizations. Multiple organizations found in "
-                                           "Subject DN: '{0}'. ".format(self.csr.subject)))
+                self.module.fail_json(
+                    msg=(
+                        "Entrust provider does not currently support multiple validated organizations. Multiple organizations found in "
+                        "Subject DN: '{0}'. ".format(self.csr.subject)
+                    )
+                )
         # If no organization in the CSR, explicitly tell ECS that it should be blank in issued cert, not defaulted to
         # organization tied to the account.
         if self.csr_org is None:
-            self.csr_org = ''
+            self.csr_org = ""
 
         try:
             self.ecs_client = ECSClient(
-                entrust_api_user=self.module.params['entrust_api_user'],
-                entrust_api_key=self.module.params['entrust_api_key'],
-                entrust_api_cert=self.module.params['entrust_api_client_cert_path'],
-                entrust_api_cert_key=self.module.params['entrust_api_client_cert_key_path'],
-                entrust_api_specification_path=self.module.params['entrust_api_specification_path']
+                entrust_api_user=self.module.params["entrust_api_user"],
+                entrust_api_key=self.module.params["entrust_api_key"],
+                entrust_api_cert=self.module.params["entrust_api_client_cert_path"],
+                entrust_api_cert_key=self.module.params[
+                    "entrust_api_client_cert_key_path"
+                ],
+                entrust_api_specification_path=self.module.params[
+                    "entrust_api_specification_path"
+                ],
             )
         except SessionConfigurationException as e:
-            module.fail_json(msg='Failed to initialize Entrust Provider: {0}'.format(to_native(e.message)))
+            module.fail_json(
+                msg="Failed to initialize Entrust Provider: {0}".format(
+                    to_native(e.message)
+                )
+            )
 
     def generate_certificate(self):
         """(Re-)Generate certificate."""
@@ -99,36 +117,42 @@ class EntrustCertificateBackend(CertificateBackend):
         # Read the CSR that was generated for us
         if self.csr_content is not None:
             # csr_content contains bytes
-            body['csr'] = to_native(self.csr_content)
+            body["csr"] = to_native(self.csr_content)
         else:
-            with open(self.csr_path, 'r') as csr_file:
-                body['csr'] = csr_file.read()
+            with open(self.csr_path, "r") as csr_file:
+                body["csr"] = csr_file.read()
 
-        body['certType'] = self.module.params['entrust_cert_type']
+        body["certType"] = self.module.params["entrust_cert_type"]
 
         # Handle expiration (30 days if not specified)
         expiry = self.notAfter
         if not expiry:
-            gmt_now = datetime.datetime.fromtimestamp(time.mktime(time.gmtime()))
+            gmt_now = get_now_datetime(with_timezone=CRYPTOGRAPHY_TIMEZONE)
             expiry = gmt_now + datetime.timedelta(days=365)
 
         expiry_iso3339 = expiry.strftime("%Y-%m-%dT%H:%M:%S.00Z")
-        body['certExpiryDate'] = expiry_iso3339
-        body['org'] = self.csr_org
-        body['tracking'] = {
-            'requesterName': self.module.params['entrust_requester_name'],
-            'requesterEmail': self.module.params['entrust_requester_email'],
-            'requesterPhone': self.module.params['entrust_requester_phone'],
+        body["certExpiryDate"] = expiry_iso3339
+        body["org"] = self.csr_org
+        body["tracking"] = {
+            "requesterName": self.module.params["entrust_requester_name"],
+            "requesterEmail": self.module.params["entrust_requester_email"],
+            "requesterPhone": self.module.params["entrust_requester_phone"],
         }
 
         try:
             result = self.ecs_client.NewCertRequest(Body=body)
-            self.trackingId = result.get('trackingId')
+            self.trackingId = result.get("trackingId")
         except RestOperationException as e:
-            self.module.fail_json(msg='Failed to request new certificate from Entrust Certificate Services (ECS): {0}'.format(to_native(e.message)))
+            self.module.fail_json(
+                msg="Failed to request new certificate from Entrust Certificate Services (ECS): {0}".format(
+                    to_native(e.message)
+                )
+            )
 
-        self.cert_bytes = to_bytes(result.get('endEntityCert'))
-        self.cert = load_certificate(path=None, content=self.cert_bytes, backend=self.backend)
+        self.cert_bytes = to_bytes(result.get("endEntityCert"))
+        self.cert = load_certificate(
+            path=None, content=self.cert_bytes, backend=self.backend
+        )
 
     def get_certificate_data(self):
         """Return bytes for self.cert."""
@@ -140,15 +164,23 @@ class EntrustCertificateBackend(CertificateBackend):
         try:
             cert_details = self._get_cert_details()
         except RestOperationException as e:
-            self.module.fail_json(msg='Failed to get status of existing certificate from Entrust Certificate Services (ECS): {0}.'.format(to_native(e.message)))
+            self.module.fail_json(
+                msg="Failed to get status of existing certificate from Entrust Certificate Services (ECS): {0}.".format(
+                    to_native(e.message)
+                )
+            )
 
         # Always issue a new certificate if the certificate is expired, suspended or revoked
-        status = cert_details.get('status', False)
-        if status == 'EXPIRED' or status == 'SUSPENDED' or status == 'REVOKED':
+        status = cert_details.get("status", False)
+        if status == "EXPIRED" or status == "SUSPENDED" or status == "REVOKED":
             return True
 
         # If the requested cert type was specified and it is for a different certificate type than the initial certificate, a new one is needed
-        if self.module.params['entrust_cert_type'] and cert_details.get('certType') and self.module.params['entrust_cert_type'] != cert_details.get('certType'):
+        if (
+            self.module.params["entrust_cert_type"]
+            and cert_details.get("certType")
+            and self.module.params["entrust_cert_type"] != cert_details.get("certType")
+        ):
             return True
 
         return parent_check
@@ -157,36 +189,38 @@ class EntrustCertificateBackend(CertificateBackend):
         cert_details = {}
         try:
             self._ensure_existing_certificate_loaded()
-        except Exception as dummy:
+        except Exception:
             return
         if self.existing_certificate:
             serial_number = None
             expiry = None
-            if self.backend == 'pyopenssl':
-                serial_number = "{0:X}".format(self.existing_certificate.get_serial_number())
-                time_string = to_native(self.existing_certificate.get_notAfter())
-                expiry = datetime.datetime.strptime(time_string, "%Y%m%d%H%M%SZ")
-            elif self.backend == 'cryptography':
-                serial_number = "{0:X}".format(cryptography_serial_number_of_cert(self.existing_certificate))
-                expiry = self.existing_certificate.not_valid_after
+            if self.backend == "cryptography":
+                serial_number = "{0:X}".format(
+                    cryptography_serial_number_of_cert(self.existing_certificate)
+                )
+                expiry = get_not_valid_after(self.existing_certificate)
 
             # get some information about the expiry of this certificate
             expiry_iso3339 = expiry.strftime("%Y-%m-%dT%H:%M:%S.00Z")
-            cert_details['expiresAfter'] = expiry_iso3339
+            cert_details["expiresAfter"] = expiry_iso3339
 
             # If a trackingId is not already defined (from the result of a generate)
             # use the serial number to identify the tracking Id
             if self.trackingId is None and serial_number is not None:
-                cert_results = self.ecs_client.GetCertificates(serialNumber=serial_number).get('certificates', {})
+                cert_results = self.ecs_client.GetCertificates(
+                    serialNumber=serial_number
+                ).get("certificates", {})
 
                 # Finding 0 or more than 1 result is a very unlikely use case, it simply means we cannot perform additional checks
                 # on the 'state' as returned by Entrust Certificate Services (ECS). The general certificate validity is
                 # still checked as it is in the rest of the module.
                 if len(cert_results) == 1:
-                    self.trackingId = cert_results[0].get('trackingId')
+                    self.trackingId = cert_results[0].get("trackingId")
 
         if self.trackingId is not None:
-            cert_details.update(self.ecs_client.GetCertificate(trackingId=self.trackingId))
+            cert_details.update(
+                self.ecs_client.GetCertificate(trackingId=self.trackingId)
+            )
 
         return cert_details
 
@@ -203,23 +237,51 @@ class EntrustCertificateProvider(CertificateProvider):
 
 
 def add_entrust_provider_to_argument_spec(argument_spec):
-    argument_spec.argument_spec['provider']['choices'].append('entrust')
-    argument_spec.argument_spec.update(dict(
-        entrust_cert_type=dict(type='str', default='STANDARD_SSL',
-                               choices=['STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL',
-                                        'PRIVATE_SSL', 'PD_SSL', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT']),
-        entrust_requester_email=dict(type='str'),
-        entrust_requester_name=dict(type='str'),
-        entrust_requester_phone=dict(type='str'),
-        entrust_api_user=dict(type='str'),
-        entrust_api_key=dict(type='str', no_log=True),
-        entrust_api_client_cert_path=dict(type='path'),
-        entrust_api_client_cert_key_path=dict(type='path', no_log=True),
-        entrust_api_specification_path=dict(type='path', default='https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml'),
-        entrust_not_after=dict(type='str', default='+365d'),
-    ))
-    argument_spec.required_if.append(
-        ['provider', 'entrust', ['entrust_requester_email', 'entrust_requester_name', 'entrust_requester_phone',
-                                 'entrust_api_user', 'entrust_api_key', 'entrust_api_client_cert_path',
-                                 'entrust_api_client_cert_key_path']]
+    argument_spec.argument_spec["provider"]["choices"].append("entrust")
+    argument_spec.argument_spec.update(
+        dict(
+            entrust_cert_type=dict(
+                type="str",
+                default="STANDARD_SSL",
+                choices=[
+                    "STANDARD_SSL",
+                    "ADVANTAGE_SSL",
+                    "UC_SSL",
+                    "EV_SSL",
+                    "WILDCARD_SSL",
+                    "PRIVATE_SSL",
+                    "PD_SSL",
+                    "CDS_ENT_LITE",
+                    "CDS_ENT_PRO",
+                    "SMIME_ENT",
+                ],
+            ),
+            entrust_requester_email=dict(type="str"),
+            entrust_requester_name=dict(type="str"),
+            entrust_requester_phone=dict(type="str"),
+            entrust_api_user=dict(type="str"),
+            entrust_api_key=dict(type="str", no_log=True),
+            entrust_api_client_cert_path=dict(type="path"),
+            entrust_api_client_cert_key_path=dict(type="path", no_log=True),
+            entrust_api_specification_path=dict(
+                type="path",
+                default="https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml",
+            ),
+            entrust_not_after=dict(type="str", default="+365d"),
+        )
+    )
+    argument_spec.required_if.append(
+        [
+            "provider",
+            "entrust",
+            [
+                "entrust_requester_email",
+                "entrust_requester_name",
+                "entrust_requester_phone",
+                "entrust_api_user",
+                "entrust_api_key",
+                "entrust_api_client_cert_path",
+                "entrust_api_client_cert_key_path",
+            ],
+        ]
     )