Release 3.0.0-a2.

* Remove Entrust modules and certificate providers.

* Add more information on Entrust removal.

* Remove Entrust content from ignore.txt files.

* Work around bug in ansible-test.

.ansible-lint

@@ -0,0 +1,31 @@
+---
+# 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
+
+skip_list:
+  # Ignore rules that make no sense:
+  - galaxy[tags]
+  - galaxy[version-incorrect]
+  - meta-runtime[unsupported-version]
+  - no-changed-when
+  - sanity[cannot-ignore]  # some of the rules you cannot ignore actually MUST be ignored, like yamllint:unparsable-with-libyaml
+  - yaml  # we're using yamllint ourselves
+
+  # To be checked and maybe fixed:
+  - fqcn[action]
+  - fqcn[action-core]
+  - ignore-errors
+  - jinja[spacing]
+  - key-order[task]
+  - name[casing]
+  - name[missing]
+  - name[play]
+  - name[template]
+  - no-free-form
+  - no-handler
+  - risky-file-permissions
+  - risky-shell-pipe
+  - var-naming[no-reserved]
+  - var-naming[pattern]
+  - var-naming[read-only]

.azure-pipelines/azure-pipelines.yml

@@ -36,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
@@ -46,7 +44,7 @@ variables:
 resources:
   containers:
     - container: default
-      image: quay.io/ansible/azure-pipelines-test-container:4.0.1
+      image: quay.io/ansible/azure-pipelines-test-container:6.0.0
 
 pool: Standard
 
@@ -61,43 +59,30 @@ 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_16
+  - stage: Ansible_2_18
-    displayName: Sanity & Units 2.16
+    displayName: Sanity & Units 2.18
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           targets:
             - name: Sanity
-              test: '2.16/sanity/1'
+              test: '2.18/sanity/1'
             - name: Units
-              test: '2.16/units/1'
+              test: '2.18/units/1'
-  - stage: Ansible_2_15
+  - stage: Ansible_2_17
-    displayName: Sanity & Units 2.15
+    displayName: Sanity & Units 2.17
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           targets:
             - name: Sanity
-              test: '2.15/sanity/1'
+              test: '2.17/sanity/1'
             - name: Units
-              test: '2.15/units/1'
+              test: '2.17/units/1'
-  - stage: Ansible_2_14
-    displayName: Sanity & Units 2.14
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          targets:
-            - name: Sanity
-              test: '2.14/sanity/1'
-            - name: Units
-              test: '2.14/units/1'
 ### Docker
   - stage: Docker_devel
     displayName: Docker devel
@@ -106,56 +91,47 @@ stages:
       - template: templates/matrix.yml
         parameters:
           testFormat: devel/linux/{0}
+          targets:
+            - 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
+            - name: Alpine 3.19
-              test: alpine3
+              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
-          groups:
-            - 1
-            - 2
-  - stage: Docker_2_15
-    displayName: Docker 2.15
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.15/linux/{0}
-          targets:
-            - name: Fedora 37
-              test: fedora37
-            - name: CentOS 7
-              test: centos7
-          groups:
-            - 1
-            - 2
-  - stage: Docker_2_14
-    displayName: Docker 2.14
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.14/linux/{0}
-          targets:
-            - name: Ubuntu 20.04
-              test: ubuntu2004
           groups:
             - 1
             - 2
@@ -169,12 +145,12 @@ stages:
         parameters:
           testFormat: devel/linux-community/{0}
           targets:
-            - name: Debian Bullseye
-              test: debian-bullseye/3.9
             - name: Debian Bookworm
               test: debian-bookworm/3.11
+            - name: Debian Bullseye
+              test: debian-bullseye/3.9
             - name: ArchLinux
-              test: archlinux/3.11
+              test: archlinux/3.13
           groups:
             - 1
             - 2
@@ -188,12 +164,14 @@ stages:
         parameters:
           testFormat: devel/{0}
           targets:
-            - name: Alpine 3.18
+            - name: Alpine 3.21
-              test: alpine/3.18
+              test: alpine/3.21
-            - name: Fedora 39
+            - name: Fedora 41
-              test: fedora/39
+              test: fedora/41
             - name: Ubuntu 22.04
               test: ubuntu/22.04
+            - name: Ubuntu 24.04
+              test: ubuntu/24.04
           groups:
             - vm
   - stage: Remote_devel
@@ -204,65 +182,48 @@ stages:
         parameters:
           testFormat: devel/{0}
           targets:
-            - name: macOS 13.2
+            - name: macOS 15.3
-              test: macos/13.2
+              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.2
+            - name: FreeBSD 13.3
-              test: freebsd/13.2
+              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: RHEL 9.2
-              test: rhel/9.2
-            - name: RHEL 8.8
-              test: rhel/8.8
-          groups:
-            - 1
-            - 2
-  - stage: Remote_2_15
-    displayName: Remote 2.15
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.15/{0}
-          targets:
-            - name: RHEL 9.1
-              test: rhel/9.1
-            - name: RHEL 8.7
-              test: rhel/8.7
-            - name: RHEL 7.9
-              test: rhel/7.9
-            # - name: FreeBSD 13.1
-            #   test: freebsd/13.1
-            - name: FreeBSD 12.4
-              test: freebsd/12.4
-          groups:
-            - 1
-            - 2
-  - stage: Remote_2_14
-    displayName: Remote 2.14
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          testFormat: 2.14/{0}
-          targets:
-            #- name: macOS 12.0
-            #  test: macos/12.0
-            - name: RHEL 9.0
-              test: rhel/9.0
-            #- name: FreeBSD 12.4
-            #  test: freebsd/12.4
           groups:
             - 1
             - 2
@@ -276,54 +237,39 @@ stages:
           nameFormat: Python {0}
           testFormat: devel/generic/{0}
           targets:
-            - test: 3.7
+            - test: "3.8"
-            # - test: 3.8
+            - test: "3.9"
-            # - test: 3.9
-            # - test: "3.10"
-            - test: "3.11"
-            - 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.16/generic/{0}
-          targets:
-            - test: "2.7"
-            - test: "3.6"
-            - test: "3.11"
-          groups:
-            - 1
-            - 2
-  - stage: Generic_2_15
-    displayName: Generic 2.15
-    dependsOn: []
-    jobs:
-      - template: templates/matrix.yml
-        parameters:
-          nameFormat: Python {0}
-          testFormat: 2.15/generic/{0}
-          targets:
-            - test: 3.5
             - test: "3.10"
+            - test: "3.11"
+            - test: "3.13"
           groups:
             - 1
             - 2
-  - stage: Generic_2_14
+  - stage: Generic_2_18
-    displayName: Generic 2.14
+    displayName: Generic 2.18
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
           nameFormat: Python {0}
-          testFormat: 2.14/generic/{0}
+          testFormat: 2.18/generic/{0}
           targets:
-            - test: 3.9
+            - 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.17/generic/{0}
+          targets:
+            - test: "3.7"
+            - test: "3.12"
           groups:
             - 1
             - 2
@@ -334,22 +280,18 @@ stages:
     condition: succeededOrFailed()
     dependsOn:
       - Ansible_devel
-      - Ansible_2_16
+      - Ansible_2_18
-      - Ansible_2_15
+      - Ansible_2_17
-      - Ansible_2_14
       - Remote_devel_extra_vms
       - Remote_devel
-      - Remote_2_16
+      - Remote_2_18
-      - Remote_2_15
+      - Remote_2_17
-      - Remote_2_14
       - Docker_devel
-      - Docker_2_16
+      - Docker_2_18
-      - Docker_2_15
+      - Docker_2_17
-      - Docker_2_14
       - Docker_community_devel
       - Generic_devel
-      - Generic_2_16
+      - Generic_2_18
-      - Generic_2_15
+      - Generic_2_17
-      - Generic_2_14
     jobs:
       - template: templates/coverage.yml

.azure-pipelines/templates/coverage.yml

@@ -28,16 +28,6 @@ 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.py "$(outputPath)"
         displayName: Publish to codecov.io
         condition: gt(variables.coverageFileCount, 0)

.flake8

@@ -0,0 +1,13 @@
+# 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>
+
+[flake8]
+extend-ignore = E203, E402, F401
+count = true
+# TODO: decrease this to ~10
+max-complexity = 60
+# black's max-line-length is 89, but it doesn't touch long string literals.
+# Since ansible-test's limit is 160, let's use that here.
+max-line-length = 160
+statistics = true

.git-blame-ignore-revs

@@ -0,0 +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
+
+# 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
+# Reformat with black another time, this time without Python 2 compatibility
+797bd8a6e2a6f4a37a89ecb15ca34ec88b33258d

.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      ci:
+        patterns:
+          - "*"

.github/workflows/ansible-test.yml

@@ -1,278 +0,0 @@
----
-# 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'
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
-    runs-on: >-
-      ${{ contains(fromJson(
-          '["2.9", "2.10", "2.11"]'
-      ), matrix.ansible) && 'ubuntu-20.04' || 'ubuntu-latest' }}
-    steps:
-      - name: Perform sanity testing
-        uses: felixfontein/ansible-test-gh-action@main
-        with:
-          ansible-core-github-repository-slug: ${{ contains(fromJson('["2.10", "2.11"]'), matrix.ansible) && 'felixfontein/ansible' || 'ansible/ansible' }}
-          ansible-core-version: stable-${{ matrix.ansible }}
-          coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }}
-          pull-request-change-detection: 'true'
-          testing-type: sanity
-
-  units:
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
-    runs-on: >-
-      ${{ contains(fromJson(
-          '["2.9", "2.10", "2.11"]'
-      ), matrix.ansible) && 'ubuntu-20.04' || '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'
-
-    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.10", "2.11"]'), matrix.ansible) && 'felixfontein/ansible' || 'ansible/ansible' }}
-          ansible-core-version: stable-${{ matrix.ansible }}
-          coverage: ${{ github.event_name == 'schedule' && 'always' || 'never' }}
-          pull-request-change-detection: 'true'
-          testing-type: units
-
-  integration:
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
-    runs-on: >-
-      ${{ contains(fromJson(
-          '["2.9", "2.10", "2.11"]'
-      ), matrix.ansible) && 'ubuntu-20.04' || '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: fedora31
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.9'
-            docker: fedora31
-            python: ''
-            target: azp/posix/2/
-          - 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: fedora32
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.11'
-            docker: fedora32
-            python: ''
-            target: azp/posix/2/
-          - 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/
-
-    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.10", "2.11"]'), matrix.ansible) && 'felixfontein/ansible' || 'ansible/ansible' }}
-          ansible-core-version: stable-${{ matrix.ansible }}
-          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 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

@@ -7,7 +7,7 @@ name: Collection Docs
 concurrency:
   group: docs-pr-${{ github.head_ref }}
   cancel-in-progress: true
-on:
+'on':
   pull_request_target:
     types: [opened, synchronize, reopened, closed]
 
@@ -38,12 +38,15 @@ jobs:
     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 }}
 

.github/workflows/docs-push.yml

@@ -7,7 +7,7 @@ name: Collection Docs
 concurrency:
   group: docs-push-${{ github.sha }}
   cancel-in-progress: true
-on:
+'on':
   push:
     branches:
       - main
@@ -43,10 +43,13 @@ jobs:
     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

@@ -4,17 +4,17 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 name: execution environment
-on:
+'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 04:45 UTC)
+  # 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: '45 4 * * *'
+    - cron: '0 9 * * *'
 
 env:
   NAMESPACE: community
@@ -48,55 +48,38 @@ jobs:
             ansible_runner: ansible-runner
             other_deps: |2
                 python_interpreter:
-                  package_system: python3.11 python3.11-pip python3.11-wheel python3.11-cryptography
+                  package_system: python3.12 python3.12-pip python3.12-wheel python3.12-cryptography
-                  python_path: "/usr/bin/python3.11"
+                  python_path: "/usr/bin/python3.12"
             base_image: docker.io/redhat/ubi9:latest
             pre_base: '"#"'
-            # For some reason ansible-builder will not install EPEL dependencies on RHEL
+          - name: ansible-core 2.17 @ Rocky Linux 9
-            extra_vars: -e has_no_pyopenssl=true
+            ansible_core: https://github.com/ansible/ansible/archive/stable-2.17.tar.gz
-          - 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
+            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: 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
+          - name: ansible-core 2.18 @ CentOS Stream 9
-            extra_vars: -e has_no_pyopenssl=true
+            ansible_core: https://github.com/ansible/ansible/archive/stable-2.18.tar.gz
-          - 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
+            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: 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
-          - name: ansible-core 2.12 @ CentOS Stream 8
-            ansible_core: https://github.com/ansible/ansible/archive/stable-2.12.tar.gz
-            ansible_runner: ansible-runner
-            other_deps: |2
-                python_interpreter:
-                  package_system: python39 python39-pip python39-wheel python39-cryptography
-            base_image: quay.io/centos/centos:stream8
-            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@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.11'
 
@@ -127,7 +110,7 @@ jobs:
 
       - name: Create files for building execution environment
         run: |
-          COLLECTION_FILENAME="$(ls "${{ env.NAMESPACE }}-${{ env.COLLECTION_NAME }}"-*.tar.gz)"
+          COLLECTION_FILENAME="$(ls "${NAMESPACE}-${COLLECTION_NAME}"-*.tar.gz)"
 
           # EE config
           cat > execution-environment.yml <<EOF

.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

.github/workflows/reuse.yml

@@ -1,34 +0,0 @@
----
-# 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: Verify REUSE
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-  # Run CI once per day (at 04:45 UTC)
-  schedule:
-    - cron: '45 4 * * *'
-
-jobs:
-  check:
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install dependencies
-        run: |
-          pip install reuse
-
-      - name: Check REUSE compliance (except some PEM files)
-        run: |
-          rm -f tests/integration/targets/*/files/*.pem
-          rm -f tests/integration/targets/*/files/roots/*.pem
-          reuse lint

.gitignore

@@ -4,6 +4,7 @@
 
 # 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

.isort.cfg

@@ -1,6 +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
 
-# defaults file for test_ecs_certificate
+[isort]
+profile=black
+lines_after_imports = 2

.mypy.ini

@@ -0,0 +1,19 @@
+# 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
+
+[mypy]
+# check_untyped_defs = True
+# disallow_untyped_defs = True -- not yet feasible
+
+# strict = True -- only try to enable once everything is typed
+strict_equality = True
+
+[mypy-ansible.*]
+# ansible-core has no typing information
+# ignore_missing_imports = True
+follow_untyped_imports = True
+
+[mypy-ansible_collections.community.internal_test_tools.*]
+# community.internal_test_tools has no typing information
+ignore_missing_imports = True

.pylintrc

@@ -0,0 +1,592 @@
+# 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>
+
+[MAIN]
+
+# Clear in-memory caches upon conclusion of linting. Useful if running pylint
+# in a server-like mode.
+clear-cache-post-run=no
+
+# Load and enable all available extensions. Use --list-extensions to see a list
+# all available extensions.
+#enable-all-extensions=
+
+# Specify a score threshold under which the program will exit with error.
+fail-under=10
+
+# Use multiple processes to speed up Pylint. Specifying 0 will auto-detect the
+# number of processors available to use, and will cap the count on Windows to
+# avoid hangs.
+jobs=0
+
+# Minimum Python version to use for version dependent checks. Will default to
+# the version used to run pylint.
+py-version=3.7
+
+# Allow loading of arbitrary C extensions. Extensions are imported into the
+# active Python interpreter and may run arbitrary code.
+unsafe-load-any-extension=no
+
+# In verbose mode, extra non-checker-related info will be displayed.
+#verbose=
+
+
+[BASIC]
+
+# Naming style matching correct argument names.
+argument-naming-style=snake_case
+
+# Regular expression matching correct argument names. Overrides argument-
+# naming-style. If left empty, argument names will be checked with the set
+# naming style.
+#argument-rgx=
+
+# Naming style matching correct attribute names.
+attr-naming-style=snake_case
+
+# Regular expression matching correct attribute names. Overrides attr-naming-
+# style. If left empty, attribute names will be checked with the set naming
+# style.
+#attr-rgx=
+
+# Bad variable names which should always be refused, separated by a comma.
+bad-names=foo,
+          bar,
+          baz,
+          toto,
+          tutu,
+          tata
+
+# Bad variable names regexes, separated by a comma. If names match any regex,
+# they will always be refused
+bad-names-rgxs=
+
+# Naming style matching correct class attribute names.
+class-attribute-naming-style=any
+
+# Regular expression matching correct class attribute names. Overrides class-
+# attribute-naming-style. If left empty, class attribute names will be checked
+# with the set naming style.
+#class-attribute-rgx=
+
+# Naming style matching correct class constant names.
+class-const-naming-style=UPPER_CASE
+
+# Regular expression matching correct class constant names. Overrides class-
+# const-naming-style. If left empty, class constant names will be checked with
+# the set naming style.
+#class-const-rgx=
+
+# Naming style matching correct class names.
+class-naming-style=PascalCase
+
+# Regular expression matching correct class names. Overrides class-naming-
+# style. If left empty, class names will be checked with the set naming style.
+#class-rgx=
+
+# Naming style matching correct constant names.
+const-naming-style=UPPER_CASE
+
+# Regular expression matching correct constant names. Overrides const-naming-
+# style. If left empty, constant names will be checked with the set naming
+# style.
+#const-rgx=
+
+# Minimum line length for functions/classes that require docstrings, shorter
+# ones are exempt.
+docstring-min-length=-1
+
+# Naming style matching correct function names.
+function-naming-style=snake_case
+
+# Regular expression matching correct function names. Overrides function-
+# naming-style. If left empty, function names will be checked with the set
+# naming style.
+#function-rgx=
+
+# Good variable names which should always be accepted, separated by a comma.
+good-names=i,
+           j,
+           k,
+           ex,
+           Run,
+           _
+
+# Good variable names regexes, separated by a comma. If names match any regex,
+# they will always be accepted
+good-names-rgxs=
+
+# Include a hint for the correct naming format with invalid-name.
+include-naming-hint=no
+
+# Naming style matching correct inline iteration names.
+inlinevar-naming-style=any
+
+# Regular expression matching correct inline iteration names. Overrides
+# inlinevar-naming-style. If left empty, inline iteration names will be checked
+# with the set naming style.
+#inlinevar-rgx=
+
+# Naming style matching correct method names.
+method-naming-style=snake_case
+
+# Regular expression matching correct method names. Overrides method-naming-
+# style. If left empty, method names will be checked with the set naming style.
+#method-rgx=
+
+# Naming style matching correct module names.
+module-naming-style=snake_case
+
+# Regular expression matching correct module names. Overrides module-naming-
+# style. If left empty, module names will be checked with the set naming style.
+#module-rgx=
+
+# Colon-delimited sets of names that determine each other's naming style when
+# the name regexes allow several styles.
+name-group=
+
+# Regular expression which should only match function or class names that do
+# not require a docstring.
+no-docstring-rgx=^_
+
+# List of decorators that produce properties, such as abc.abstractproperty. Add
+# to this list to register other decorators that produce valid properties.
+# These decorators are taken in consideration only for invalid-name.
+property-classes=abc.abstractproperty
+
+# Regular expression matching correct type alias names. If left empty, type
+# alias names will be checked with the set naming style.
+#typealias-rgx=
+
+# Regular expression matching correct type variable names. If left empty, type
+# variable names will be checked with the set naming style.
+#typevar-rgx=
+
+# Naming style matching correct variable names.
+variable-naming-style=snake_case
+
+# Regular expression matching correct variable names. Overrides variable-
+# naming-style. If left empty, variable names will be checked with the set
+# naming style.
+#variable-rgx=
+
+
+[CLASSES]
+
+# Warn about protected attribute access inside special methods
+check-protected-access-in-special-methods=no
+
+# List of method names used to declare (i.e. assign) instance attributes.
+defining-attr-methods=__init__,
+                      __new__,
+                      setUp,
+                      asyncSetUp,
+                      __post_init__
+
+# List of member names, which should be excluded from the protected access
+# warning.
+exclude-protected=_asdict,_fields,_replace,_source,_make,os._exit
+
+# List of valid names for the first argument in a class method.
+valid-classmethod-first-arg=cls
+
+# List of valid names for the first argument in a metaclass class method.
+valid-metaclass-classmethod-first-arg=mcs
+
+
+[DESIGN]
+
+# List of regular expressions of class ancestor names to ignore when counting
+# public methods (see R0903)
+exclude-too-few-public-methods=
+
+# List of qualified class names to ignore when counting class parents (see
+# R0901)
+ignored-parents=
+
+# Maximum number of arguments for function / method.
+max-args=5
+
+# Maximum number of attributes for a class (see R0902).
+max-attributes=7
+
+# Maximum number of boolean expressions in an if statement (see R0916).
+max-bool-expr=5
+
+# Maximum number of branch for function / method body.
+max-branches=12
+
+# Maximum number of locals for function / method body.
+max-locals=15
+
+# Maximum number of parents for a class (see R0901).
+max-parents=7
+
+# Maximum number of positional arguments for function / method.
+max-positional-arguments=5
+
+# Maximum number of public methods for a class (see R0904).
+max-public-methods=20
+
+# Maximum number of return / yield for function / method body.
+max-returns=6
+
+# Maximum number of statements in function / method body.
+max-statements=50
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods=2
+
+
+[EXCEPTIONS]
+
+# Exceptions that will emit a warning when caught.
+overgeneral-exceptions=builtins.BaseException,builtins.Exception
+
+
+[FORMAT]
+
+# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
+expected-line-ending-format=
+
+# Regexp for a line that is allowed to be longer than the limit.
+ignore-long-lines=^\s*(# )?<?https?://\S+>?$
+
+# Number of spaces of indent required inside a hanging or continued line.
+indent-after-paren=4
+
+# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
+# tab).
+indent-string='    '
+
+# Maximum number of characters on a single line.
+max-line-length=160
+
+# Maximum number of lines in a module.
+max-module-lines=1000
+
+# Allow the body of a class to be on the same line as the declaration if body
+# contains single statement.
+single-line-class-stmt=no
+
+# Allow the body of an if to be on the same line as the test if there is no
+# else.
+single-line-if-stmt=no
+
+
+[IMPORTS]
+
+# List of modules that can be imported at any level, not just the top level
+# one.
+allow-any-import-level=
+
+# Allow explicit reexports by alias from a package __init__.
+allow-reexport-from-package=no
+
+# Allow wildcard imports from modules that define __all__.
+allow-wildcard-with-all=no
+
+# Deprecated modules which should not be used, separated by a comma.
+deprecated-modules=
+
+# Output a graph (.gv or any supported image format) of external dependencies
+# to the given file (report RP0402 must not be disabled).
+ext-import-graph=
+
+# Output a graph (.gv or any supported image format) of all (i.e. internal and
+# external) dependencies to the given file (report RP0402 must not be
+# disabled).
+import-graph=
+
+# Output a graph (.gv or any supported image format) of internal dependencies
+# to the given file (report RP0402 must not be disabled).
+int-import-graph=
+
+# Force import order to recognize a module as part of the standard
+# compatibility libraries.
+known-standard-library=
+
+# Force import order to recognize a module as part of a third party library.
+known-third-party=enchant
+
+# Couples of modules and preferred modules, separated by a comma.
+preferred-modules=
+
+
+[LOGGING]
+
+# The type of string formatting that logging methods do. `old` means using %
+# formatting, `new` is for `{}` formatting.
+logging-format-style=old
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format.
+logging-modules=logging
+
+
+[MESSAGES CONTROL]
+
+# Only show warnings with the listed confidence levels. Leave empty to show
+# all. Valid levels: HIGH, CONTROL_FLOW, INFERENCE, INFERENCE_FAILURE,
+# UNDEFINED.
+confidence=HIGH,
+           CONTROL_FLOW,
+           INFERENCE,
+           INFERENCE_FAILURE,
+           UNDEFINED
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once). You can also use "--disable=all" to
+# disable everything first and then re-enable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use "--disable=all --enable=classes
+# --disable=W".
+disable=raw-checker-failed,
+        bad-inline-option,
+        deprecated-pragma,
+        duplicate-code,
+        file-ignored,
+        import-outside-toplevel,
+        missing-class-docstring,
+        missing-function-docstring,
+        missing-module-docstring,
+        locally-disabled,
+        suppressed-message,
+        use-implicit-booleaness-not-comparison,
+        use-implicit-booleaness-not-comparison-to-string,
+        use-implicit-booleaness-not-comparison-to-zero,
+        superfluous-parens,
+        too-few-public-methods,
+        too-many-arguments,
+        too-many-boolean-expressions,
+        too-many-branches,
+        too-many-function-args,
+        too-many-instance-attributes,
+        too-many-lines,
+        too-many-locals,
+        too-many-nested-blocks,
+        too-many-positional-arguments,
+        too-many-return-statements,
+        too-many-statements,
+        ungrouped-imports,
+        useless-parent-delegation,
+        wrong-import-order,
+        wrong-import-position,
+        # To clean up:
+        broad-exception-caught,
+        broad-exception-raised,
+        fixme,
+        invalid-name,
+        unused-argument,
+        # Cannot remove yet due to inadequacy of rules
+        inconsistent-return-statements,  # doesn't notice that fail_json() does not return
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once). See also the "--disable" option for examples.
+enable=
+
+
+[METHOD_ARGS]
+
+# List of qualified names (i.e., library.method) which require a timeout
+# parameter e.g. 'requests.api.get,requests.api.post'
+timeout-methods=requests.api.delete,requests.api.get,requests.api.head,requests.api.options,requests.api.patch,requests.api.post,requests.api.put,requests.api.request
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+notes=FIXME,
+      XXX,
+      TODO
+
+# Regular expression of note tags to take in consideration.
+notes-rgx=
+
+
+[REFACTORING]
+
+# Maximum number of nested blocks for function / method body
+max-nested-blocks=5
+
+# Complete name of functions that never returns. When checking for
+# inconsistent-return-statements if a never returning function is called then
+# it will be considered as an explicit return statement and no message will be
+# printed.
+never-returning-functions=sys.exit,argparse.parse_error
+
+# Let 'consider-using-join' be raised when the separator to join on would be
+# non-empty (resulting in expected fixes of the type: ``"- " + " -
+# ".join(items)``)
+suggest-join-with-non-empty-separator=yes
+
+
+[REPORTS]
+
+# Python expression which should return a score less than or equal to 10. You
+# have access to the variables 'fatal', 'error', 'warning', 'refactor',
+# 'convention', and 'info' which contain the number of messages in each
+# category, as well as 'statement' which is the total number of statements
+# analyzed. This score is used by the global evaluation report (RP0004).
+evaluation=max(0, 0 if fatal else 10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10))
+
+# Template used to display messages. This is a python new-style format string
+# used to format the message information. See doc for all details.
+msg-template=
+
+# Set the output format. Available formats are: text, parseable, colorized,
+# json2 (improved json format), json (old json format) and msvs (visual
+# studio). You can also give a reporter class, e.g.
+# mypackage.mymodule.MyReporterClass.
+#output-format=
+
+# Tells whether to display a full report or only the messages.
+reports=no
+
+# Activate the evaluation score.
+score=yes
+
+
+[SIMILARITIES]
+
+# Comments are removed from the similarity computation
+ignore-comments=yes
+
+# Docstrings are removed from the similarity computation
+ignore-docstrings=yes
+
+# Imports are removed from the similarity computation
+ignore-imports=yes
+
+# Signatures are removed from the similarity computation
+ignore-signatures=yes
+
+# Minimum lines number of a similarity.
+min-similarity-lines=4
+
+
+[SPELLING]
+
+# Limits count of emitted suggestions for spelling mistakes.
+max-spelling-suggestions=4
+
+# Spelling dictionary name. No available dictionaries : You need to install
+# both the python package and the system dependency for enchant to work.
+spelling-dict=
+
+# List of comma separated words that should be considered directives if they
+# appear at the beginning of a comment and should not be checked.
+spelling-ignore-comment-directives=fmt: on,fmt: off,noqa:,noqa,nosec,isort:skip,mypy:
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains the private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to the private dictionary (see the
+# --spelling-private-dict-file option) instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[STRING]
+
+# This flag controls whether inconsistent-quotes generates a warning when the
+# character used as a quote delimiter is used inconsistently within a module.
+check-quote-consistency=no
+
+# This flag controls whether the implicit-str-concat should generate a warning
+# on implicit string concatenation in sequences defined over several lines.
+check-str-concat-over-line-jumps=no
+
+
+[TYPECHECK]
+
+# List of decorators that produce context managers, such as
+# contextlib.contextmanager. Add to this list to register other decorators that
+# produce valid context managers.
+contextmanager-decorators=contextlib.contextmanager
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E1101 when accessed. Python regular
+# expressions are accepted.
+generated-members=
+
+# Tells whether to warn about missing members when the owner of the attribute
+# is inferred to be None.
+ignore-none=yes
+
+# This flag controls whether pylint should warn about no-member and similar
+# checks whenever an opaque object is returned when inferring. The inference
+# can return multiple potential results while evaluating a Python object, but
+# some branches might not be evaluated, which results in partial inference. In
+# that case, it might be useful to still emit no-member and other checks for
+# the rest of the inferred objects.
+ignore-on-opaque-inference=yes
+
+# List of symbolic message names to ignore for Mixin members.
+ignored-checks-for-mixins=no-member,
+                          not-async-context-manager,
+                          not-context-manager,
+                          attribute-defined-outside-init
+
+# List of class names for which member attributes should not be checked (useful
+# for classes with dynamically set attributes). This supports the use of
+# qualified names.
+ignored-classes=optparse.Values,thread._local,_thread._local,argparse.Namespace
+
+# Show a hint with possible names when a member name was not found. The aspect
+# of finding the hint is based on edit distance.
+missing-member-hint=yes
+
+# The minimum edit distance a name should have in order to be considered a
+# similar match for a missing member name.
+missing-member-hint-distance=1
+
+# The total number of similar names that should be taken in consideration when
+# showing a hint for a missing member.
+missing-member-max-choices=1
+
+# Regex pattern to define which classes are considered mixins.
+mixin-class-rgx=.*[Mm]ixin
+
+# List of decorators that change the signature of a decorated function.
+signature-mutators=
+
+
+[VARIABLES]
+
+# List of additional names supposed to be defined in builtins. Remember that
+# you should avoid defining new builtins when possible.
+additional-builtins=
+
+# Tells whether unused global variables should be treated as a violation.
+allow-global-unused-variables=yes
+
+# List of names allowed to shadow builtins
+allowed-redefined-builtins=
+
+# List of strings which can identify a callback function by name. A callback
+# name must start or end with one of those strings.
+callbacks=cb_,
+          _cb
+
+# A regular expression matching the name of dummy variables (i.e. expected to
+# not be used).
+dummy-variables-rgx=_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_
+
+# Argument names that match this expression will be ignored.
+ignored-argument-names=_.*|^ignored_|^unused_
+
+# Tells whether we should check for unused import in __init__ files.
+init-import=no
+
+# List of qualified module names which can have objects that can redefine
+# builtins.
+redefining-builtins-modules=six.moves,past.builtins,future.builtins,builtins,io

.reuse/dep5

@@ -1,5 +0,0 @@
-Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
-
-Files: changelogs/fragments/*
-Copyright: Ansible Project
-License: GPL-3.0-or-later

.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.rst

@@ -4,6 +4,406 @@ Community Crypto Release Notes
 
 .. contents:: Topics
 
+v3.0.0-a2
+=========
+
+Release Summary
+---------------
+
+Second pre-release for community.crypto 3.0.0.
+
+This release removes all Entrust content.
+
+Removed Features (previously deprecated)
+----------------------------------------
+
+- All Entrust content is being removed since the Entrust service in currently being sunsetted after the sale of Entrust's Public Certificates Business to Sectigo; see `the announcement with key dates <https://www.entrust.com/tls-certificate-information-center>`__ and `the migration brief for customers <https://www.sectigo.com/uploads/resources/EOL_Migration-Brief-End-Customer.pdf>`__ for details. Since this process will be completed in 2025, we decided to remove all Entrust content from community.general 3.0.0 (https://github.com/ansible-collections/community.crypto/issues/895, https://github.com/ansible-collections/community.crypto/pull/901).
+- ecs_certificate - the module has been removed. Please use community.crypto 2.x.y if you need this module (https://github.com/ansible-collections/community.crypto/pull/900).
+- ecs_domain - the module has been removed. Please use community.crypto 2.x.y if you need this module (https://github.com/ansible-collections/community.crypto/pull/900).
+- x509_certificate - the ``entrust`` provider has been removed. Please use community.crypto 2.x.y if you need this provider (https://github.com/ansible-collections/community.crypto/pull/900).
+- x509_certificate_pipe - the ``entrust`` provider has been removed. Please use community.crypto 2.x.y if you need this provider (https://github.com/ansible-collections/community.crypto/pull/900).
+
+v3.0.0-a1
+=========
+
+Release Summary
+---------------
+
+First pre-release for community.crypto 3.0.0.
+This release drops compatibility for ansible-core before 2.17, for Python before 3.7, and for cryptography before 3.3.
+
+Minor Changes
+-------------
+
+- No longer provide cryptography's ``backend`` parameter. This will break with cryptography < 3.1 (https://github.com/ansible-collections/community.crypto/pull/878).
+- On cryptography 36.0.0+, always use ``public_bytes()`` for X.509 extension objects instead of using cryptography internals to obtain DER value of extension (https://github.com/ansible-collections/community.crypto/pull/878).
+- Python code modernization: add type hints and type checking (https://github.com/ansible-collections/community.crypto/pull/885).
+- Python code modernization: avoid unnecessary string conversion (https://github.com/ansible-collections/community.crypto/pull/880).
+- Python code modernization: avoid using ``six`` (https://github.com/ansible-collections/community.crypto/pull/884).
+- Python code modernization: remove Python 3 specific code (https://github.com/ansible-collections/community.crypto/pull/877).
+- Python code modernization: update ``__future__`` imports, remove Python 2 specific boilerplates (https://github.com/ansible-collections/community.crypto/pull/876).
+- Python code modernization: use ``unittest.mock`` instead of ``ansible_collections.community.internal_test_tools.tests.unit.compat.mock`` (https://github.com/ansible-collections/community.crypto/pull/881).
+- Python code modernization: use f-strings instead of ``%`` and ``str.format()`` (https://github.com/ansible-collections/community.crypto/pull/875).
+- Remove ``backend`` parameter from internal code whenever possible (https://github.com/ansible-collections/community.crypto/pull/883).
+- Remove various compatibility code for cryptography < 3.3 (https://github.com/ansible-collections/community.crypto/pull/878).
+- Remove vendored copy of ``distutils.version`` in favor of vendored copy included with ansible-core 2.12+ (https://github.com/ansible-collections/community.crypto/pull/371).
+- acme_* modules - improve parsing of ``Retry-After`` reply headers in regular ACME requests (https://github.com/ansible-collections/community.crypto/pull/890).
+- action_module plugin utils - remove compatibility with older ansible-core/ansible-base/Ansible versions (https://github.com/ansible-collections/community.crypto/pull/872).
+- x509_certificate, x509_certificate_pipe - the ``ownca_version`` and ``selfsigned_version`` parameters explicitly only allow the value ``3``. The module already failed for other values in the past, now this is validated as part of the module argument spec (https://github.com/ansible-collections/community.crypto/pull/890).
+
+Breaking Changes / Porting Guide
+--------------------------------
+
+- All doc_fragments are now private to the collection and must not be used from other collections or unrelated plugins/modules. Breaking changes in these can happen at any time, even in bugfix releases (https://github.com/ansible-collections/community.crypto/pull/898).
+- All module_utils and plugin_utils are now private to the collection and must not be used from other collections or unrelated plugins/modules. Breaking changes in these can happen at any time, even in bugfix releases (https://github.com/ansible-collections/community.crypto/pull/887).
+- Ignore value of ``select_crypto_backend`` for all modules except acme_* and ..., and always assume the value ``auto``. This ensures that the ``cryptography`` version is always checked (https://github.com/ansible-collections/community.crypto/pull/883).
+- The validation for relative timestamps is now more strict. A string starting with ``+`` or ``-`` must be valid, otherwise validation will fail. In the past such strings were often silently ignored, and in many cases the code which triggered the validation was not able to handle no result (https://github.com/ansible-collections/community.crypto/pull/885).
+- acme.certificates module utils - the ``retrieve_acme_v1_certificate()`` helper function has been removed (https://github.com/ansible-collections/community.crypto/pull/873).
+- get_certificate - the default for ``asn1_base64`` changed from ``false`` to ``true`` (https://github.com/ansible-collections/community.crypto/pull/873).
+- x509_crl - the ``mode`` parameter no longer denotes the update mode, but the CRL file mode. Use ``crl_mode`` instead for the update mode (https://github.com/ansible-collections/community.crypto/pull/873).
+
+Deprecated Features
+-------------------
+
+- acme_certificate - deprecate the ``agreement`` option which has no more effect. It will be removed from community.crypto 4.0.0 (https://github.com/ansible-collections/community.crypto/pull/891).
+- openssl_pkcs12 - deprecate the ``maciter_size`` option which has no more effect. It will be removed from community.crypto 4.0.0 (https://github.com/ansible-collections/community.crypto/pull/891).
+
+Removed Features (previously deprecated)
+----------------------------------------
+
+- The collection no longer supports cryptography < 3.3 (https://github.com/ansible-collections/community.crypto/pull/878, https://github.com/ansible-collections/community.crypto/pull/882).
+- acme.acme module utils - the ``get_default_argspec()`` function has been removed. Use ``create_default_argspec()`` instead (https://github.com/ansible-collections/community.crypto/pull/873).
+- acme.backends module utils - the methods ``get_ordered_csr_identifiers()`` and ``get_cert_information()`` of ``CryptoBackend`` now must be implemented (https://github.com/ansible-collections/community.crypto/pull/873).
+- acme.documentation docs fragment - the ``documentation`` docs fragment has been removed. Use both the ``basic`` and ``account`` docs fragments in ``acme`` instead (https://github.com/ansible-collections/community.crypto/pull/873).
+- acme_* modules - support for ACME v1 has been removed (https://github.com/ansible-collections/community.crypto/pull/873).
+- community.crypto no longer supports Ansible 2.9, ansible-base 2.10, and ansible-core versions 2.11, 2.12, 2.13, 2.14, 2.15, and 2.16. While content from this collection might still work with some older versions of ansible-core, it will not work with any Python version before 3.7 (https://github.com/ansible-collections/community.crypto/pull/870).
+- crypto.basic module utils - remove ``CRYPTOGRAPHY_HAS_*`` flags. All tested features are supported since cryptography 3.0 (https://github.com/ansible-collections/community.crypto/pull/878).
+- crypto.cryptography_support module utils - remove ``cryptography_serial_number_of_cert()`` helper function (https://github.com/ansible-collections/community.crypto/pull/878).
+- crypto.module_backends.common module utils - this module utils has been removed. Use the ``argspec`` module utils instead (https://github.com/ansible-collections/community.crypto/pull/873).
+- crypto.support module utils - remove ``pyopenssl`` backend (https://github.com/ansible-collections/community.crypto/pull/874).
+- execution environment dependencies - remove PyOpenSSL dependency (https://github.com/ansible-collections/community.crypto/pull/874).
+- openssl_csr_pipe - the module now ignores check mode and will always behave as if check mode is not active (https://github.com/ansible-collections/community.crypto/pull/873).
+- openssl_pkcs12 - support for the ``pyopenssl`` backend has been removed (https://github.com/ansible-collections/community.crypto/pull/873).
+- openssl_privatekey_pipe - the module now ignores check mode and will always behave as if check mode is not active (https://github.com/ansible-collections/community.crypto/pull/873).
+- time module utils - remove ``pyopenssl`` backend (https://github.com/ansible-collections/community.crypto/pull/874).
+- x509_certificate_pipe - the module now ignores check mode and will always behave as if check mode is not active (https://github.com/ansible-collections/community.crypto/pull/873).
+
+v2.26.1
+=======
+
+Release Summary
+---------------
+
+Bugfix and maintenance release with improved CI.
+
+Bugfixes
+--------
+
+- luks_device - mark parameter ``passphrase_encoding`` as ``no_log=False`` to avoid confusing warning (https://github.com/ansible-collections/community.crypto/pull/867).
+- luks_device - removing a specific keyslot with ``remove_keyslot`` caused the module to hang while cryptsetup was waiting for a passphrase from stdin, while the module did not supply one. Since a keyslot is not necessary, do not provide one (https://github.com/ansible-collections/community.crypto/issues/864, https://github.com/ansible-collections/community.crypto/pull/868).
+
+v2.26.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- openssl_pkcs12 - the module now supports ``certificate_content``/``other_certificates_content`` for cases where the data already exists in memory and not yet in a file (https://github.com/ansible-collections/community.crypto/issues/847, https://github.com/ansible-collections/community.crypto/pull/848).
+
+v2.25.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- luks_device - allow passphrases to contain newlines (https://github.com/ansible-collections/community.crypto/pull/844).
+
+v2.24.0
+=======
+
+Release Summary
+---------------
+
+New feature and bugfix release with multiple new modules. It also deprecates support for older ansible-core and Python versions.
+
+Minor Changes
+-------------
+
+- acme_certificate - add options ``order_creation_error_strategy`` and ``order_creation_max_retries`` which allow to configure the error handling behavior if creating a new ACME order fails. This is particularly important when using the ``include_renewal_cert_id`` option, and the default value ``auto`` for ``order_creation_error_strategy`` tries to gracefully handle related errors (https://github.com/ansible-collections/community.crypto/pull/842).
+- acme_certificate - allow to chose a profile for certificate generation, in case the CA supports this using Internet-Draft `draft-aaron-acme-profiles <https://datatracker.ietf.org/doc/draft-aaron-acme-profiles/>`__ (https://github.com/ansible-collections/community.crypto/pull/835).
+- acme_certificate_renewal_info - add ``exists`` and ``parsable`` return values and ``treat_parsing_error_as_non_existing`` option (https://github.com/ansible-collections/community.crypto/pull/838).
+
+Deprecated Features
+-------------------
+
+- Support for ansible-core 2.11, 2.12, 2.13, 2.14, 2.15, and 2.16 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with some of these versions afterwards, but we will no longer keep compatibility code that was needed to support them. Note that this means that support for all Python versions before 3.7 will be dropped, also on the target side (https://github.com/ansible-collections/community.crypto/issues/559, https://github.com/ansible-collections/community.crypto/pull/839).
+- Support for cryptography < 3.4 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with older versions of cryptography, but we will no longer keep compatibility code that was needed to support them (https://github.com/ansible-collections/community.crypto/issues/559, https://github.com/ansible-collections/community.crypto/pull/839).
+
+Bugfixes
+--------
+
+- crypto_info - when running the module on Fedora 41 with ``cryptography`` installed from the package repository, the module crashed apparently due to some elliptic curves being removed from libssl against which cryptography is running, which cryptography did not expect (https://github.com/ansible-collections/community.crypto/pull/834).
+
+New Modules
+-----------
+
+- community.crypto.acme_certificate_order_create - Create an ACME v2 order.
+- community.crypto.acme_certificate_order_finalize - Finalize an ACME v2 order.
+- community.crypto.acme_certificate_order_info - Obtain information for an ACME v2 order.
+- community.crypto.acme_certificate_order_validate - Validate authorizations of an ACME v2 order.
+
+v2.23.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- acme_certificate - add compatibility for ACME CAs that are not fully RFC8555 compliant and do not provide ``challenges`` in authz objects (https://github.com/ansible-collections/community.crypto/issues/824, https://github.com/ansible-collections/community.crypto/pull/832).
+- luks_device - allow to provide passphrases base64-encoded (https://github.com/ansible-collections/community.crypto/issues/827, https://github.com/ansible-collections/community.crypto/pull/829).
+- x509_certificate_convert - add new option ``verify_cert_parsable`` which allows to check whether the certificate can actually be parsed (https://github.com/ansible-collections/community.crypto/issues/809, https://github.com/ansible-collections/community.crypto/pull/830).
+
+Deprecated Features
+-------------------
+
+- openssl_pkcs12 - the PyOpenSSL based backend is deprecated and will be removed from community.crypto 3.0.0. From that point on you need cryptography 3.0 or newer to use this module (https://github.com/ansible-collections/community.crypto/issues/667, https://github.com/ansible-collections/community.crypto/pull/831).
+
+v2.22.3
+=======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Bugfixes
+--------
+
+- acme_* modules - when using the OpenSSL backend, explicitly use the UTC timezone in Python code (https://github.com/ansible-collections/community.crypto/pull/811).
+- time module utils - fix conversion of naive ``datetime`` objects to UNIX timestamps for Python 3 (https://github.com/ansible-collections/community.crypto/issues/808, https://github.com/ansible-collections/community.crypto/pull/810).
+
+v2.22.2
+=======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Bugfixes
+--------
+
+- acme_certificate - fix authorization failure when CSR contains SANs with mixed case (https://github.com/ansible-collections/community.crypto/pull/803).
+
+v2.22.1
+=======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Bugfixes
+--------
+
+- acme_* modules - when querying renewal information, make sure to insert a slash between the base URL and the certificate identifier (https://github.com/ansible-collections/community.crypto/issues/801, https://github.com/ansible-collections/community.crypto/pull/802).
+- various modules - pass absolute paths to ``module.atomic_move()`` (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.crypto/pull/799).
+
+v2.22.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- openssl_privatekey, openssl_privatekey_pipe - add default value ``auto`` for ``cipher`` option, which happens to be the only supported value for this option anyway. Therefore it is no longer necessary to specify ``cipher=auto`` when providing ``passphrase`` (https://github.com/ansible-collections/community.crypto/issues/793, https://github.com/ansible-collections/community.crypto/pull/794).
+
+v2.21.1
+=======
+
+Release Summary
+---------------
+
+Maintenance release.
+
+Bugfixes
+--------
+
+- When using cryptography >= 43.0.0, use offset-aware ``datetime.datetime`` objects (with timezone UTC) instead of offset-naive UTC timestamps for the ``InvalidityDate`` X.509 CRL extension (https://github.com/ansible-collections/community.crypto/issues/726, https://github.com/ansible-collections/community.crypto/pull/730).
+
+v2.21.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- certificate_complete_chain - add ability to identify Ed25519 and Ed448 complete chains (https://github.com/ansible-collections/community.crypto/pull/777).
+- get_certificate - adds ``tls_ctx_options`` option for specifying SSL CTX options (https://github.com/ansible-collections/community.crypto/pull/779).
+- get_certificate - allow to obtain the certificate chain sent by the server, and the one used for validation, with the new ``get_certificate_chain`` option. Note that this option only works if the module is run with Python 3.10 or newer (https://github.com/ansible-collections/community.crypto/issues/568, https://github.com/ansible-collections/community.crypto/pull/784).
+
+v2.20.0
+=======
+
+Release Summary
+---------------
+
+Feature and bugfix release.
+
+The deprecations in this release are only relevant for collections that use shared
+code or docs fragments from this collection.
+
+Minor Changes
+-------------
+
+- acme_certificate - add ``include_renewal_cert_id`` option to allow requesting renewal of a specific certificate according to the current ACME Renewal Information specification draft (https://github.com/ansible-collections/community.crypto/pull/739).
+
+Deprecated Features
+-------------------
+
+- acme documentation fragment - the default ``community.crypto.acme[.documentation]`` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new ``community.crypto.acme.basic`` and ``community.crypto.acme.account`` fragments (https://github.com/ansible-collections/community.crypto/pull/735).
+- acme.backends module utils - the ``get_cert_information()`` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736).
+- crypto.module_backends.common module utils - the ``crypto.module_backends.common`` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved ``argspec`` module util instead (https://github.com/ansible-collections/community.crypto/pull/749).
+
+Bugfixes
+--------
+
+- x509_crl, x509_certificate, x509_certificate_info - when parsing absolute timestamps which omitted the second count, the first digit of the minutes was used as a one-digit minutes count, and the second digit of the minutes as a one-digit second count (https://github.com/ansible-collections/community.crypto/pull/745).
+
+New Modules
+-----------
+
+- community.crypto.acme_ari_info - Retrieves ACME Renewal Information (ARI) for a certificate.
+- community.crypto.acme_certificate_deactivate_authz - Deactivate all authz for an ACME v2 order.
+- community.crypto.acme_certificate_renewal_info - Determine whether a certificate should be renewed or not.
+
+v2.19.1
+=======
+
+Release Summary
+---------------
+
+Bugfix release.
+
+Bugfixes
+--------
+
+- crypto.math module utils - change return values for ``quick_is_not_prime()`` and ``convert_int_to_bytes(0, 0)`` for special cases that do not appear when using the collection (https://github.com/ansible-collections/community.crypto/pull/733).
+- ecs_certificate - fixed ``csr`` option to be empty and allow renewal of a specific certificate according to the Renewal Information specification (https://github.com/ansible-collections/community.crypto/pull/740).
+- x509_certificate - since community.crypto 2.19.0 the module was no longer idempotent with respect to ``not_before`` and ``not_after`` times. This is now fixed (https://github.com/ansible-collections/community.crypto/issues/753, https://github.com/ansible-collections/community.crypto/pull/754).
+
+v2.19.0
+=======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- When using cryptography >= 42.0.0, use offset-aware ``datetime.datetime`` objects (with timezone UTC) instead of offset-naive UTC timestamps (https://github.com/ansible-collections/community.crypto/issues/726, https://github.com/ansible-collections/community.crypto/pull/727).
+- openssh_cert - avoid UTC functions deprecated in Python 3.12 when using Python 3 (https://github.com/ansible-collections/community.crypto/pull/727).
+
+Deprecated Features
+-------------------
+
+- acme.backends module utils - from community.crypto on, all implementations of ``CryptoBackend`` must override ``get_ordered_csr_identifiers()``. The current default implementation, which simply sorts the result of ``get_csr_identifiers()``, will then be removed (https://github.com/ansible-collections/community.crypto/pull/725).
+
+Bugfixes
+--------
+
+- acme_certificate - respect the order of the CNAME and SAN identifiers that are passed on when creating an ACME order (https://github.com/ansible-collections/community.crypto/issues/723, https://github.com/ansible-collections/community.crypto/pull/725).
+
+New Modules
+-----------
+
+- community.crypto.x509_certificate_convert - Convert X.509 certificates
+
+v2.18.0
+=======
+
+Release Summary
+---------------
+
+Bugfix and feature release.
+
+Minor Changes
+-------------
+
+- x509_crl - the new option ``serial_numbers`` allow to configure in which format serial numbers can be provided to ``revoked_certificates[].serial_number``. The default is as integers (``serial_numbers=integer``) for backwards compatibility; setting ``serial_numbers=hex-octets`` allows to specify colon-separated hex octet strings like ``00:11:22:FF`` (https://github.com/ansible-collections/community.crypto/issues/687, https://github.com/ansible-collections/community.crypto/pull/715).
+
+Deprecated Features
+-------------------
+
+- openssl_csr_pipe, openssl_privatekey_pipe, x509_certificate_pipe - the current behavior of check mode is deprecated and will change in community.crypto 3.0.0. The current behavior is similar to the modules without ``_pipe``: if the object needs to be (re-)generated, only the ``changed`` status is set, but the object is not updated. From community.crypto 3.0.0 on, the modules will ignore check mode and always act as if check mode is not active. This behavior can already achieved now by adding ``check_mode: false`` to the task. If you think this breaks your use-case of this module, please `create an issue in the community.crypto repository <https://github.com/ansible-collections/community.crypto/issues/new/choose>`__ (https://github.com/ansible-collections/community.crypto/issues/712, https://github.com/ansible-collections/community.crypto/pull/714).
+
+Bugfixes
+--------
+
+- luks_device - fixed module a bug that prevented using ``remove_keyslot`` with the value ``0`` (https://github.com/ansible-collections/community.crypto/pull/710).
+- luks_device - fixed module falsely outputting ``changed=false`` when trying to add a new slot with a key that is already present in another slot. The module now rejects adding keys that are already present in another slot (https://github.com/ansible-collections/community.crypto/pull/710).
+- luks_device - fixed testing of LUKS passphrases in when specifying a keyslot for cryptsetup version 2.0.3. The output of this cryptsetup version slightly differs from later versions (https://github.com/ansible-collections/community.crypto/pull/710).
+
+New Plugins
+-----------
+
+Filter
+~~~~~~
+
+- community.crypto.parse_serial - Convert a serial number as a colon-separated list of hex numbers to an integer
+- community.crypto.to_serial - Convert an integer to a colon-separated list of hex numbers
+
+v2.17.1
+=======
+
+Release Summary
+---------------
+
+Bugfix release for compatibility with cryptography 42.0.0.
+
+Bugfixes
+--------
+
+- openssl_dhparam - was using an internal function instead of the public API to load DH param files when using the ``cryptography`` backend. The internal function was removed in cryptography 42.0.0. The module now uses the public API, which has been available since support for DH params was added to cryptography (https://github.com/ansible-collections/community.crypto/pull/698).
+- openssl_privatekey_info - ``check_consistency=true`` no longer works for RSA keys with cryptography 42.0.0+ (https://github.com/ansible-collections/community.crypto/pull/701).
+- openssl_privatekey_info - ``check_consistency=true`` now reports a warning if it cannot determine consistency (https://github.com/ansible-collections/community.crypto/pull/705).
+
+v2.17.0
+=======
+
+Release Summary
+---------------
+
+Feature release.
+
+Minor Changes
+-------------
+
+- luks_device - add allow discards option (https://github.com/ansible-collections/community.crypto/pull/693).
 
 v2.16.2
 =======
@@ -95,12 +495,12 @@ New Plugins
 Filter
 ~~~~~~
 
-- gpg_fingerprint - Retrieve a GPG fingerprint from a GPG public or private key
+- community.crypto.gpg_fingerprint - Retrieve a GPG fingerprint from a GPG public or private key
 
 Lookup
 ~~~~~~
 
-- gpg_fingerprint - Retrieve a GPG fingerprint from a GPG public or private key file
+- community.crypto.gpg_fingerprint - Retrieve a GPG fingerprint from a GPG public or private key file
 
 v2.14.1
 =======
@@ -119,7 +519,6 @@ ansible-core 2.15 or later to see it as it is intended. Alternatively you can
 look at `the devel docsite <https://docs.ansible.com/ansible/devel/collections/community/crypto/>`__
 for the rendered HTML version of the documentation of the latest release.
 
-
 Bugfixes
 --------
 
@@ -244,12 +643,12 @@ New Plugins
 Filter
 ~~~~~~
 
-- openssl_csr_info - Retrieve information from OpenSSL Certificate Signing Requests (CSR)
+- community.crypto.openssl_csr_info - Retrieve information from OpenSSL Certificate Signing Requests (CSR)
-- openssl_privatekey_info - Retrieve information from OpenSSL private keys
+- community.crypto.openssl_privatekey_info - Retrieve information from OpenSSL private keys
-- openssl_publickey_info - Retrieve information from OpenSSL public keys in PEM format
+- community.crypto.openssl_publickey_info - Retrieve information from OpenSSL public keys in PEM format
-- split_pem - Split PEM file contents into multiple objects
+- community.crypto.split_pem - Split PEM file contents into multiple objects
-- x509_certificate_info - Retrieve information from X.509 certificates in PEM format
+- community.crypto.x509_certificate_info - Retrieve information from X.509 certificates in PEM format
-- x509_crl_info - Retrieve information from X.509 CRLs in PEM format
+- community.crypto.x509_crl_info - Retrieve information from X.509 CRLs in PEM format
 
 v2.9.0
 ======
@@ -379,7 +778,6 @@ This release is identical to what should have been 2.3.3, except that the
 version number has been bumped to 2.3.4 and this changelog entry for 2.3.4
 has been added.
 
-
 v2.3.3
 ======
 
@@ -486,7 +884,6 @@ Regular bugfix release.
 
 In this release, we extended the test matrix to include Alpine 3, ArchLinux, Debian Bullseye, and CentOS Stream 8. CentOS 8 was removed from the test matrix.
 
-
 Bugfixes
 --------
 
@@ -550,8 +947,8 @@ Bugfixes
 New Modules
 -----------
 
-- crypto_info - Retrieve cryptographic capabilities
+- community.crypto.crypto_info - Retrieve cryptographic capabilities
-- openssl_privatekey_convert - Convert OpenSSL private keys
+- community.crypto.openssl_privatekey_convert - Convert OpenSSL private keys
 
 v2.0.2
 ======
@@ -590,7 +987,6 @@ Release Summary
 
 A new major release of the ``community.crypto`` collection. The main changes are removal of the PyOpenSSL backends for almost all modules (``openssl_pkcs12`` being the only exception), and removal of the ``assertonly`` provider in the ``x509_certificate`` provider. There are also some other breaking changes which should improve the user interface/experience of this collection long-term.
 
-
 Minor Changes
 -------------
 
@@ -798,7 +1194,7 @@ Bugfixes
 New Modules
 -----------
 
-- openssl_publickey_info - Provide information for OpenSSL public keys
+- community.crypto.openssl_publickey_info - Provide information for OpenSSL public keys
 
 v1.6.2
 ======
@@ -909,7 +1305,6 @@ Release Summary
 
 Contains new modules ``openssl_privatekey_pipe``, ``openssl_csr_pipe`` and ``x509_certificate_pipe`` which allow to create or update private keys, CSRs and X.509 certificates without having to write them to disk.
 
-
 Minor Changes
 -------------
 
@@ -930,9 +1325,9 @@ Bugfixes
 New Modules
 -----------
 
-- openssl_csr_pipe - Generate OpenSSL Certificate Signing Request (CSR)
+- community.crypto.openssl_csr_pipe - Generate OpenSSL Certificate Signing Request (CSR)
-- openssl_privatekey_pipe - Generate OpenSSL private keys without disk access
+- community.crypto.openssl_privatekey_pipe - Generate OpenSSL private keys without disk access
-- x509_certificate_pipe - Generate and/or check OpenSSL certificates
+- community.crypto.x509_certificate_pipe - Generate and/or check OpenSSL certificates
 
 v1.2.0
 ======
@@ -985,7 +1380,6 @@ Release Summary
 
 Release for Ansible 2.10.0.
 
-
 Minor Changes
 -------------
 
@@ -1009,8 +1403,8 @@ Bugfixes
 New Modules
 -----------
 
-- openssl_signature - Sign data with openssl
+- community.crypto.openssl_signature - Sign data with openssl
-- openssl_signature_info - Verify signatures with openssl
+- community.crypto.openssl_signature_info - Verify signatures with openssl
 
 v1.0.0
 ======
@@ -1020,7 +1414,6 @@ Release Summary
 
 This is the first proper release of the ``community.crypto`` collection. This changelog contains all changes to the modules in this collection that were added after the release of Ansible 2.9.0.
 
-
 Minor Changes
 -------------
 
@@ -1086,6 +1479,6 @@ Bugfixes
 New Modules
 -----------
 
-- ecs_domain - Request validation of a domain with the Entrust Certificate Services (ECS) API
+- community.crypto.ecs_domain - Request validation of a domain with the Entrust Certificate Services (ECS) API
-- x509_crl - Generate Certificate Revocation Lists (CRLs)
+- community.crypto.x509_crl - Generate Certificate Revocation Lists (CRLs)
-- x509_crl_info - Retrieve information on Certificate Revocation Lists (CRLs)
+- community.crypto.x509_crl_info - Retrieve information on Certificate Revocation Lists (CRLs)

LICENSES/BSD-2-Clause.txt

@@ -1,8 +0,0 @@
-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/PSF-2.0.txt

@@ -1,48 +0,0 @@
-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

@@ -6,9 +6,11 @@ SPDX-License-Identifier: GPL-3.0-or-later
 
 # Ansible Community Crypto Collection
 
+[![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=main)](https://dev.azure.com/ansible/community.crypto/_build?definitionId=21)
-[![EOL CI](https://github.com/ansible-collections/community.crypto/workflows/EOL%20CI/badge.svg?event=push)](https://github.com/ansible-collections/community.crypto/actions)
+[![Nox CI](https://github.com/ansible-collections/community.crypto/actions/workflows/nox.yml/badge.svg?branch=main)](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.
 
@@ -16,15 +18,34 @@ 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, ansible-core 2.12, ansible-core 2.13, ansible-core 2.14, ansible-core 2.15, and ansible-core-2.16 releases and the current development version of ansible-core. Ansible versions before 2.9.10 are not supported.
+Tested with the current ansible-core-2.17, ansible-core 2.18, and ansible-core 2.19 releases and the current development version of ansible-core. Ansible-core versions before 2.17 are not supported; please use community.crypto 2.x.y with these.
 
 ## External requirements
 
 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.
+Most modules require a recent enough version of [the Python cryptography library](https://pypi.org/project/cryptography/); the minimum supported version by this collection is 3.3. See the module documentations for the minimal version supported for each module.
 
 ## Collection Documentation
 
@@ -36,51 +57,6 @@ We also separately publish [**latest commit** collection documentation](https://
 
 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 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_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_certificate 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
-
-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/main/).
-
 ## Using this collection
 
 Before using the crypto community collection, you need to install the collection with the `ansible-galaxy` CLI:
@@ -111,20 +87,12 @@ 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/main/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.
-
 ## More information
 
 - [Ansible Collection overview](https://github.com/ansible-collections/overview)
@@ -138,6 +106,6 @@ This collection is primarily licensed and distributed as a whole under the GNU G
 
 See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/community.crypto/blob/main/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/main/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/main/LICENSES/BSD-2-Clause.txt) (`plugins/module_utils/ecs/api.py`), the [BSD 3-Clause license](https://github.com/ansible-collections/community.crypto/blob/main/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/main/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.
+Parts of the collection are licensed under the [Apache 2.0 license](https://github.com/ansible-collections/community.crypto/blob/main/LICENSES/Apache-2.0.txt) (`plugins/module_utils/_crypto/_obj2txt.py` and `plugins/module_utils/_crypto/_objects_data.py`) and the [BSD 3-Clause license](https://github.com/ansible-collections/community.crypto/blob/main/LICENSES/BSD-3-Clause.txt) (`plugins/module_utils/_crypto/_obj2txt.py`). This only applies to vendored files in ``plugins/module_utils/``.
 
-Almost 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/dep5`. Right now a few vendored PEM files do not have licensing information as well. This conforms to the [REUSE specification](https://reuse.software/spec/) up to the aforementioned PEM files.
+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,57 @@
+# 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 = ".isort.cfg"
+run_black = true
+run_flake8 = true
+flake8_config = ".flake8"
+run_pylint = true
+pylint_rcfile = ".pylintrc"
+pylint_ansible_core_package = "ansible-core>=2.19.0b4"
+run_yamllint = true
+yamllint_config = ".yamllint"
+yamllint_config_plugins = ".yamllint-docs"
+yamllint_config_plugins_examples = ".yamllint-examples"
+run_mypy = true
+mypy_ansible_core_package = "ansible-core>=2.19.0b4"
+mypy_config = ".mypy.ini"
+mypy_extra_deps = [
+    "cryptography",
+    "types-mock",
+    "types-PyYAML",
+]
+
+[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/config.yaml

@@ -11,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
     - Major Changes
-- - minor_changes
+  - - minor_changes
     - Minor Changes
-- - breaking_changes
+  - - breaking_changes
     - Breaking Changes / Porting Guide
-- - deprecated_features
+  - - deprecated_features
     - Deprecated Features
-- - removed_features
+  - - removed_features
     - Removed Features (previously deprecated)
-- - security_fixes
+  - - security_fixes
     - Security Fixes
-- - bugfixes
+  - - bugfixes
     - Bugfixes
-- - known_issues
+  - - 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

@@ -3,4 +3,5 @@
 # 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
 
-has_pyopenssl: false
+changelog:
+  write_changelog: true

docs/docsite/links.yml

@@ -9,6 +9,10 @@ edit_on_github:
   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
@@ -22,6 +26,13 @@ communication:
     - topic: General usage and support questions
       network: Libera
       channel: '#ansible'
-  mailing_lists:
+  forums:
-    - topic: Ansible Project List
+    - topic: "Ansible Forum: General usage and support questions"
-      url: https://groups.google.com/g/ansible-project
+      # 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

galaxy.yml

@@ -5,18 +5,18 @@
 
 namespace: community
 name: crypto
-version: 2.16.2
+version: 3.0.0-a2
 readme: README.md
 authors:
   - Ansible (github.com/ansible)
-description: null
+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
+# license_file: COPYING
 tags:
   - acme
   - certificate

meta/ee-bindep.txt

@@ -11,11 +11,3 @@ 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/runtime.yml

@@ -3,18 +3,31 @@
 # 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'
+requires_ansible: '>=2.17.0'
 
 action_groups:
   acme:
     - acme_inspect
-    - acme_certificate_revoke
     - 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:
+    ecs_certificate:
+      tombstone:
+        removal_version: 3.0.0
+        warning_text: The 'community.crypto.ecs_certificate' module has been removed due to the upcoming sunsetting of the ECS service. Please use community.crypto 2.x.y to continue using this module
+    ecs_domain:
+      tombstone:
+        removal_version: 3.0.0
+        warning_text: The 'community.crypto.ecs_domain' module has been removed due to the upcoming sunsetting of the ECS service. Please use community.crypto 2.x.y to continue using this module.
     acme_account_facts:
       tombstone:
         removal_version: 2.0.0

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,91 +1,100 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
-
 
 import base64
+import typing as t
 
-from ansible.module_utils.common.text.converters import to_native, to_bytes
+from ansible.module_utils.common.text.converters import to_bytes
-
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
-from ansible_collections.community.crypto.plugins.plugin_utils.action_module import ActionModuleBase
-
-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 (
-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,
 )
 
 
-class PrivateKeyModule(object):
+if t.TYPE_CHECKING:
-    def __init__(self, module, module_backend):
+    from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+        ArgumentSpec,
+    )
+    from ansible_collections.community.crypto.plugins.module_utils._crypto.module_backends.privatekey import (
+        PrivateKeyBackend,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+
+
+class PrivateKeyModule:
+    def __init__(
+        self, module: AnsibleActionModule, module_backend: PrivateKeyBackend
+    ) -> None:
         self.module = module
         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: bool = module.params["return_current_key"]
 
-        if module.params['content'] is not None:
+        content: str | None = module.params["content"]
-            if module.params['content_base64']:
+        content_base64: bool = module.params["content_base64"]
+        if content is not None:
+            if content_base64:
                 try:
-                    data = base64.b64decode(module.params['content'])
+                    data = base64.b64decode(content)
                 except Exception as e:
-                    module.fail_json(msg='Cannot decode Base64 encoded data: {0}'.format(e))
+                    module.fail_json(msg=f"Cannot decode Base64 encoded data: {e}")
             else:
-                data = to_bytes(module.params['content'])
+                data = to_bytes(content)
-            module_backend.set_existing(data)
+            module_backend.set_existing(privatekey_bytes=data)
 
-    def generate(self, module):
+    def generate(self, module: AnsibleActionModule) -> None:
         """Generate a keypair."""
 
         if self.module_backend.needs_regeneration():
             # Regenerate
-            if not self.check_mode:
             self.module_backend.generate_private_key()
-                privatekey_data = self.module_backend.get_private_key_data()
+            # Call get_private_key_data() to make sure that exceptions are raised now:
-                self.privatekey_bytes = privatekey_data
+            self.module_backend.get_private_key_data()
             self.changed = True
         elif self.module_backend.needs_conversion():
             # Convert
-            if not self.check_mode:
             self.module_backend.convert_private_key()
-                privatekey_data = self.module_backend.get_private_key_data()
+            # Call get_private_key_data() to make sure that exceptions are raised now:
-                self.privatekey_bytes = privatekey_data
+            self.module_backend.get_private_key_data()
             self.changed = True
 
-    def dump(self):
+    def dump(self) -> dict[str, t.Any]:
         """Serialize the object into a dictionary."""
-        result = self.module_backend.dump(include_key=self.changed or self.return_current_key)
+        result = self.module_backend.dump(
-        result['changed'] = self.changed
+            include_key=self.changed or self.return_current_key
+        )
+        result["changed"] = self.changed
         return result
 
 
 class ActionModule(ActionModuleBase):
-    @staticmethod
+    def setup_module(self) -> tuple[ArgumentSpec, dict[str, t.Any]]:
-    def setup_module():
         argument_spec = get_privatekey_argument_spec()
-        argument_spec.argument_spec.update(dict(
+        argument_spec.argument_spec.update(
-            content=dict(type='str', no_log=True),
+            {
-            content_base64=dict(type='bool', default=False),
+                "content": {"type": "str", "no_log": True},
-            return_current_key=dict(type='bool', default=False),
+                "content_base64": {"type": "bool", "default": False},
-        ))
+                "return_current_key": {"type": "bool", "default": False},
-        return argument_spec, dict(
+            }
-            supports_check_mode=True,
         )
+        return argument_spec, {
+            "supports_check_mode": True,
+        }
 
-    @staticmethod
+    def run_module(self, module: AnsibleActionModule) -> None:
-    def run_module(module):
+        module_backend = select_backend(module=module)
-        backend, module_backend = select_backend(
-            module=module,
-            backend=module.params['select_crypto_backend'],
-        )
 
         try:
             private_key = PrivateKeyModule(module, module_backend)
@@ -99,10 +108,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))
+            module.fail_json(msg=str(exc))

plugins/doc_fragments/_acme.py

@@ -0,0 +1,152 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+
+    # 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. 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 C(openssl)
+  - or L(cryptography,https://cryptography.io/) >= 3.3
+options:
+  acme_version:
+    description:
+      - The ACME version of the endpoint.
+      - Must be V(2) for standardized ACME v2 endpoints.
+      - The value V(1) is no longer supported since community.crypto 3.0.0.
+    type: int
+    default: 2
+    choices:
+      - 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).
+      - 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.
+      - '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.
+      - 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,99 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+
+    # 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/_cryptography_dep.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2025 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+    """
+    Doc fragments for cryptography requirements.
+
+    Must be kept in sync with plugins/module_utils/_cryptography_dep.py.
+    """
+
+    # Corresponds to the plugins.module_utils._cryptography_dep.COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION constant
+    MINIMUM = r"""
+requirements:
+  - cryptography >= 3.3
+options: {}
+"""

plugins/doc_fragments/_module_certificate.py

@@ -0,0 +1,332 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+
+    # Standard files documentation fragment
+    DOCUMENTATION = r"""
+description:
+  - 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:
+  - cryptography >= 3.3 (if using V(selfsigned) or V(ownca) provider)
+options:
+  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 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 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 O(privatekey_path) resp. O(privatekey_content).
+      - This is required if the private key is password protected.
+    type: str
+
+  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.
+      - Note that with community.crypto 3.0.0, all values behave the same.
+        This option will be deprecated in a later version.
+        We recommend to not set it explicitly.
+    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 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
+"""
+
+    BACKEND_ACME_DOCUMENTATION = r"""
+description:
+  - This module allows one to (re)generate OpenSSL certificates.
+requirements:
+  - acme-tiny >= 4.0.0 (if using the V(acme) provider)
+options:
+  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 V(acme) provider.
+    type: path
+
+  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
+"""
+
+    BACKEND_OWNCA_DOCUMENTATION = r"""
+description:
+  - The V(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 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
+
+  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
+
+  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
+
+  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
+
+  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
+    choices:
+      - 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]) (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
+
+  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
+
+  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.
+    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 V(ownca) provider.
+    type: bool
+    default: true
+"""
+
+    BACKEND_SELFSIGNED_DOCUMENTATION = r"""
+notes:
+  - 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).
+
+  # 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 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 V(selfsigned) certificate.
+      - Nowadays it should almost always be V(3).
+      - This is only used by the V(selfsigned) provider.
+    type: int
+    default: 3
+    choices:
+      - 3
+
+  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]) (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]) (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 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.
+    type: str
+    choices: [create_if_not_provided, always_create, never_create]
+    default: create_if_not_provided
+"""

plugins/doc_fragments/_module_csr.py

@@ -0,0 +1,344 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+
+    # Standard files documentation fragment
+    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.
+attributes:
+  diff_mode:
+    support: full
+  idempotent:
+    support: full
+requirements:
+  - cryptography >= 3.3
+options:
+  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.
+      - Note that with community.crypto 3.0.0, all values behave the same.
+        This option will be deprecated in a later version.
+        We recommend to not set it explicitly.
+    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.
+    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).
+    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.
+      - 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.
+      - 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.
+      - 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.
+    type: list
+    elements: dict
+    suboptions:
+      full_name:
+        description:
+          - 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
+      relative_name:
+        description:
+          - 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).'
+        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
+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.
+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
+  - plugin: community.crypto.parse_serial
+    plugin_type: filter
+"""

plugins/doc_fragments/_module_privatekey.py

@@ -0,0 +1,146 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+
+    # Standard files documentation fragment
+    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.
+attributes:
+  diff_mode:
+    support: full
+  idempotent:
+    support: partial
+    details:
+      - The option O(regenerate=always) generally disables idempotency.
+requirements:
+  - cryptography >= 3.3
+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.
+    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.
+      - Note that with community.crypto 3.0.0, all values behave the same.
+        This option will be deprecated in a later version.
+        We recommend to not set it explicitly.
+    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.
+    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
+"""

plugins/doc_fragments/_module_privatekey_convert.py

@@ -0,0 +1,52 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+
+    # Standard files documentation fragment
+    DOCUMENTATION = r"""
+requirements:
+  - cryptography >= 3.3
+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,32 @@
+# 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
+
+# Note that this doc fragment is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+class ModuleDocFragment:
+    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/doc_fragments/acme.py

@@ -1,139 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# 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'''
-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))."
-  - "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:
-  - 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 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."
-      - "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
-  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)."
-      - 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
-'''

plugins/doc_fragments/attributes.py

@@ -1,85 +0,0 @@
-# -*- 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.
-'''
-
-    # 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,44 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# Copyright (c), Entrust Datacard Corporation, 2019
-# 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):
-
-    # Plugin options for Entrust Certificate Services (ECS) credentials
-    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
-requirements:
-    - "PyYAML >= 3.11"
-'''

plugins/doc_fragments/module_certificate.py

@@ -1,404 +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 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'''
-description:
-    - This module allows one to (re)generate OpenSSL certificates.
-    - It uses the cryptography python library to interact with OpenSSL.
-requirements:
-    - 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: false
-
-    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 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 O(privatekey_path) resp. O(privatekey_content).
-            - This is required if the private key is password protected.
-        type: str
-
-    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 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
-'''
-
-    BACKEND_ACME_DOCUMENTATION = r'''
-description:
-    - This module allows one to (re)generate OpenSSL certificates.
-requirements:
-    - acme-tiny >= 4.0.0 (if using the V(acme) provider)
-options:
-    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 V(acme) provider.
-        type: path
-
-    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
-'''
-
-    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 V(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 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
-
-    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
-
-    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
-
-    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
-
-    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
-
-    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
-
-    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
-
-    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
-
-    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
-'''
-
-    BACKEND_SELFSIGNED_DOCUMENTATION = r'''
-notes:
-    - 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).
-
-    # 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 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 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 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]) (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]) (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 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,325 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# 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'''
-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.
-requirements:
-    - cryptography >= 1.3
-options:
-    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.
-        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 O(crl_distribution_points[].relative_name).
-                    - "Example: V(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 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
-            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
-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.
-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
-'''

plugins/doc_fragments/module_privatekey.py

@@ -1,146 +0,0 @@
-# -*- coding: utf-8 -*-
-
-# 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'''
-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.
-requirements:
-    - 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 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. Must be V(auto).
-        type: str
-    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
-'''

plugins/doc_fragments/module_privatekey_convert.py

@@ -1,48 +0,0 @@
-# -*- 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)
-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

@@ -1,31 +0,0 @@
-# -*- 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

@@ -1,18 +1,17 @@
-# -*- 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)
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = """
+
+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."
+  - Takes the content of a private or public GPG key as input and returns its fingerprint.
 options:
   _input:
     description:
@@ -26,43 +25,51 @@ seealso:
     plugin_type: lookup
 """
 
-EXAMPLES = """
+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 = """
+RETURN = r"""
-  _value:
+_value:
   description:
     - The fingerprint of the provided public or private GPG key.
   type: string
 """
 
+import typing as t
+
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible.module_utils.common.text.converters import to_bytes
-from ansible.module_utils.six import string_types
+from ansible_collections.community.crypto.plugins.module_utils._gnupg.cli import (
-
+    GPGError,
-from ansible_collections.community.crypto.plugins.module_utils.gnupg.cli import GPGError, get_fingerprint_from_bytes
+    get_fingerprint_from_bytes,
-from ansible_collections.community.crypto.plugins.plugin_utils.gnupg import PluginGPGRunner
+)
+from ansible_collections.community.crypto.plugins.plugin_utils._gnupg import (
+    PluginGPGRunner,
+)
 
 
-def gpg_fingerprint(input):
+def gpg_fingerprint(gpg_key_content: str | bytes) -> str:
-    if not isinstance(input, string_types):
+    if not isinstance(gpg_key_content, (str, bytes)):
         raise AnsibleFilterError(
-            'The input for the community.crypto.gpg_fingerprint filter must be a string; got {type} instead'.format(type=type(input))
+            f"The input for the community.crypto.gpg_fingerprint filter must be a string; got {type(gpg_key_content)} instead"
         )
     try:
         gpg = PluginGPGRunner()
-        return get_fingerprint_from_bytes(gpg, to_bytes(input))
+        return get_fingerprint_from_bytes(
+            gpg_runner=gpg, content=to_bytes(gpg_key_content)
+        )
     except GPGError as exc:
-        raise AnsibleFilterError(to_native(exc))
+        raise AnsibleFilterError(str(exc)) from exc
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'gpg_fingerprint': gpg_fingerprint,
+            "gpg_fingerprint": gpg_fingerprint,
         }

plugins/filter/openssl_csr_info.py

@@ -1,13 +1,11 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = '''
+
+DOCUMENTATION = r"""
 name: openssl_csr_info
 short_description: Retrieve information from OpenSSL Certificate Signing Requests (CSR)
 version_added: 2.10.0
@@ -23,12 +21,15 @@ options:
     type: string
     required: true
 extends_documentation_fragment:
-    - community.crypto.name_encoding
+  - community.crypto._name_encoding
 seealso:
   - module: community.crypto.openssl_csr_info
-'''
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 - name: Show the Subject Alt Names of the CSR
   ansible.builtin.debug:
     msg: >-
@@ -38,9 +39,9 @@ EXAMPLES = '''
           | community.crypto.openssl_csr_info
         ).subject_alt_name | join(', ')
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _value:
   description:
     - Information on the certificate.
@@ -73,7 +74,7 @@ _value:
       returned: success
       type: bool
     extensions_by_oid:
-            description: Returns a dictionary for every extension OID
+      description: Returns a dictionary for every extension OID.
       returned: success
       type: dict
       contains:
@@ -84,15 +85,13 @@ _value:
         value:
           description:
             - The Base64 encoded value (in DER format) of the extension.
-                      - B(Note) that depending on the C(cryptography) version used, it is
+            - B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content
-                        not possible to extract the ASN.1 content of the extension, but only
+              of the extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
-                        to provide the re-encoded content of the extension in case it was
+              This should usually result in exactly the same value, except if the original extension value was malformed.
-                        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="}}
+      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
@@ -157,7 +156,7 @@ _value:
       elements: list
       sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
     public_key:
-            description: CSR's public key in PEM format
+      description: CSR's public key in PEM format.
       returned: success
       type: str
       sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
@@ -199,8 +198,8 @@ _value:
         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
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
-                          multiplicative group of the prime field used.
+              group of the prime field used.
           type: int
           returned: When RV(_value.public_key_type=DSA)
         g:
@@ -227,8 +226,8 @@ _value:
         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
+            - For RV(_value.public_key_type=DSA), this is the publicly known group element whose discrete logarithm with respect
-                          respect to C(g) is the private key.
+              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:
@@ -268,47 +267,59 @@ _value:
       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
-'''
+"""
+
+import typing as t
 
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.six import string_types
+from ansible.module_utils.common.text.converters import to_bytes, to_text
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
-
-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 (
-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 (
-from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import FilterModuleMock
+    FilterModuleMock,
+)
 
 
-def openssl_csr_info_filter(data, name_encoding='ignore'):
+def openssl_csr_info_filter(
-    '''Extract information from X.509 PEM certificate.'''
+    data: str | bytes, name_encoding: t.Literal["ignore", "idna", "unicode"] = "ignore"
-    if not isinstance(data, string_types):
+) -> dict[str, t.Any]:
-        raise AnsibleFilterError('The community.crypto.openssl_csr_info input must be a text type, not %s' % type(data))
+    """Extract information from X.509 PEM certificate."""
-    if not isinstance(name_encoding, string_types):
+    if not isinstance(data, (str, bytes)):
-        raise AnsibleFilterError('The name_encoding option must be of a text type, not %s' % type(name_encoding))
+        raise AnsibleFilterError(
-    name_encoding = to_native(name_encoding)
+            f"The community.crypto.openssl_csr_info input must be a text type, not {type(data)}"
-    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)
+    if not isinstance(name_encoding, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The name_encoding option must be of a text type, not {type(name_encoding)}"
+        )
+    name_encoding = to_text(name_encoding)
+    if name_encoding not in ("ignore", "idna", "unicode"):
+        raise AnsibleFilterError(
+            f'The name_encoding option must be one of the values "ignore", "idna", or "unicode", not "{name_encoding}"'
+        )
 
-    module = FilterModuleMock({'name_encoding': name_encoding})
+    module = FilterModuleMock({"name_encoding": name_encoding})
     try:
-        return get_csr_info(module, 'cryptography', content=to_bytes(data), validate_signature=True)
+        return get_csr_info(
+            module=module, content=to_bytes(data), validate_signature=True
+        )
     except OpenSSLObjectError as exc:
-        raise AnsibleFilterError(to_native(exc))
+        raise AnsibleFilterError(str(exc)) from exc
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'openssl_csr_info': openssl_csr_info_filter,
+            "openssl_csr_info": openssl_csr_info_filter,
         }

plugins/filter/openssl_privatekey_info.py

@@ -1,13 +1,11 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = '''
+
+DOCUMENTATION = r"""
 name: openssl_privatekey_info
 short_description: Retrieve information from OpenSSL private keys
 version_added: 2.10.0
@@ -29,18 +27,18 @@ options:
   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
+      - Only set this to V(true) when you want private information about this key to be extracted.
-              be extracted.
+      - B(WARNING:) you have to make sure that private key data is not accidentally logged!
-            - "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
+  - community.crypto._name_encoding
 seealso:
   - module: community.crypto.openssl_privatekey_info
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 - name: Show the Subject Alt Names of the CSR
   ansible.builtin.debug:
     msg: >-
@@ -50,9 +48,9 @@ EXAMPLES = '''
           | community.crypto.openssl_privatekey_info
         ).subject_alt_name | join(', ')
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _value:
   description:
     - Information on the certificate.
@@ -109,8 +107,8 @@ _value:
         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
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
-                          multiplicative group of the prime field used.
+              group of the prime field used.
           type: int
           returned: When RV(_value.type=DSA)
         g:
@@ -137,8 +135,8 @@ _value:
         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
+            - For RV(_value.type=DSA), this is the publicly known group element whose discrete logarithm with respect to C(g)
-                          respect to C(g) is the private key.
+              is the private key.
           type: int
           returned: When RV(_value.type=DSA) or RV(_value.type=ECC)
     private_data:
@@ -146,49 +144,64 @@ _value:
         - Private key data. Depends on key type.
       returned: success and when O(return_private_key_data) is set to V(true)
       type: dict
-'''
+"""
+
+import typing as t
 
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.six import string_types
+from ansible.module_utils.common.text.converters import to_bytes, to_text
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
-
-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 (
-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 (
-from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import FilterModuleMock
+    FilterModuleMock,
+)
 
 
-def openssl_privatekey_info_filter(data, passphrase=None, return_private_key_data=False):
+def openssl_privatekey_info_filter(
-    '''Extract information from X.509 PEM certificate.'''
+    data: str | bytes,
-    if not isinstance(data, string_types):
+    passphrase: str | bytes | None = None,
-        raise AnsibleFilterError('The community.crypto.openssl_privatekey_info input must be a text type, not %s' % type(data))
+    return_private_key_data: bool = False,
-    if passphrase is not None and not isinstance(passphrase, string_types):
+) -> dict[str, t.Any]:
-        raise AnsibleFilterError('The passphrase option must be a text type, not %s' % type(passphrase))
+    """Extract information from X.509 PEM certificate."""
+    if not isinstance(data, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The community.crypto.openssl_privatekey_info input must be a text type, not {type(data)}"
+        )
+    if passphrase is not None and not isinstance(passphrase, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The passphrase option must be a text type, not {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))
+        raise AnsibleFilterError(
+            f"The return_private_key_data option must be a boolean, not {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 = get_privatekey_info(
-        result.pop('can_parse_key', None)
+            module=module,
-        result.pop('key_is_consistent', None)
+            content=to_bytes(data),
+            passphrase=to_text(passphrase) if passphrase is not None else None,
+            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)
+        raise AnsibleFilterError(exc.error_message) from exc
     except OpenSSLObjectError as exc:
-        raise AnsibleFilterError(to_native(exc))
+        raise AnsibleFilterError(str(exc)) from exc
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'openssl_privatekey_info': openssl_privatekey_info_filter,
+            "openssl_privatekey_info": openssl_privatekey_info_filter,
         }

plugins/filter/openssl_publickey_info.py

@@ -1,13 +1,11 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = '''
+
+DOCUMENTATION = r"""
 name: openssl_publickey_info
 short_description: Retrieve information from OpenSSL public keys in PEM format
 version_added: 2.10.0
@@ -24,9 +22,10 @@ options:
     required: true
 seealso:
   - module: community.crypto.openssl_publickey_info
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 - name: Show the type of a public key
   ansible.builtin.debug:
     msg: >-
@@ -36,9 +35,9 @@ EXAMPLES = '''
           | community.crypto.openssl_publickey_info
         ).type
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _value:
   description:
     - Information on the public key.
@@ -90,8 +89,8 @@ _value:
         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
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
-                          multiplicative group of the prime field used.
+              group of the prime field used.
           type: int
           returned: When RV(_value.type=DSA)
         g:
@@ -118,46 +117,48 @@ _value:
         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
+            - For RV(_value.type=DSA), this is the publicly known group element whose discrete logarithm with respect to C(g)
-                          respect to C(g) is the private key.
+              is the private key.
           type: int
           returned: When RV(_value.type=DSA) or RV(_value.type=ECC)
-'''
+"""
+
+import typing as t
 
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.six import string_types
+from ansible.module_utils.common.text.converters import to_bytes
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
-
-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 (
-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 (
-from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import FilterModuleMock
+    FilterModuleMock,
+)
 
 
-def openssl_publickey_info_filter(data):
+def openssl_publickey_info_filter(data: str | bytes) -> dict[str, t.Any]:
-    '''Extract information from OpenSSL PEM public key.'''
+    """Extract information from OpenSSL PEM public key."""
-    if not isinstance(data, string_types):
+    if not isinstance(data, (str, bytes)):
-        raise AnsibleFilterError('The community.crypto.openssl_publickey_info input must be a text type, not %s' % type(data))
+        raise AnsibleFilterError(
+            f"The community.crypto.openssl_publickey_info input must be a text type, not {type(data)}"
+        )
 
     module = FilterModuleMock({})
     try:
-        return get_publickey_info(module, 'cryptography', content=to_bytes(data))
+        return get_publickey_info(module=module, content=to_bytes(data))
     except PublicKeyParseError as exc:
-        raise AnsibleFilterError(exc.error_message)
+        raise AnsibleFilterError(exc.error_message) from exc
     except OpenSSLObjectError as exc:
-        raise AnsibleFilterError(to_native(exc))
+        raise AnsibleFilterError(str(exc)) from exc
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'openssl_publickey_info': openssl_publickey_info_filter,
+            "openssl_publickey_info": openssl_publickey_info_filter,
         }

plugins/filter/parse_serial.py

@@ -0,0 +1,68 @@
+# 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 annotations
+
+
+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
+"""
+
+import typing as t
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common.text.converters import to_text
+from ansible_collections.community.crypto.plugins.module_utils._serial import (
+    parse_serial,
+)
+
+
+def parse_serial_filter(serial_str: str | bytes) -> int:
+    if not isinstance(serial_str, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The input for the community.crypto.parse_serial filter must be a string; got {type(serial_str)} instead"
+        )
+    try:
+        return parse_serial(to_text(serial_str))
+    except ValueError as exc:
+        raise AnsibleFilterError(str(exc)) from exc
+
+
+class FilterModule:
+    """Ansible jinja2 filters"""
+
+    def filters(self) -> dict[str, t.Callable]:
+        return {
+            "parse_serial": parse_serial_filter,
+        }

plugins/filter/split_pem.py

@@ -1,13 +1,11 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = '''
+
+DOCUMENTATION = r"""
 name: split_pem
 short_description: Split PEM file contents into multiple objects
 version_added: 2.10.0
@@ -21,44 +19,48 @@ options:
       - The PEM contents to split.
     type: string
     required: true
-'''
+"""
 
-EXAMPLES = '''
+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 = '''
+RETURN = r"""
 _value:
   description:
     - A list of PEM file contents.
   type: list
   elements: string
-'''
+"""
+
+import typing as t
 
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.six import string_types
 from ansible.module_utils.common.text.converters import to_text
-
+from ansible_collections.community.crypto.plugins.module_utils._crypto.pem import (
-from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import split_pem_list
+    split_pem_list,
+)
 
 
-def split_pem_filter(data):
+def split_pem_filter(data: str | bytes) -> list[str]:
-    '''Split PEM file.'''
+    """Split PEM file."""
-    if not isinstance(data, string_types):
+    if not isinstance(data, (str, bytes)):
-        raise AnsibleFilterError('The community.crypto.split_pem input must be a text type, not %s' % type(data))
+        raise AnsibleFilterError(
+            f"The community.crypto.split_pem input must be a text type, not {type(data)}"
+        )
 
-    data = to_text(data)
+    return split_pem_list(to_text(data))
-    return split_pem_list(data)
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'split_pem': split_pem_filter,
+            "split_pem": split_pem_filter,
         }

plugins/filter/to_serial.py

@@ -0,0 +1,69 @@
+# 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 annotations
+
+
+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
+"""
+
+import typing as t
+
+from ansible.errors import AnsibleFilterError
+from ansible_collections.community.crypto.plugins.module_utils._serial import to_serial
+
+
+def to_serial_filter(serial_int: int) -> str:
+    if not isinstance(serial_int, int):
+        raise AnsibleFilterError(
+            f"The input for the community.crypto.to_serial filter must be an integer; got {type(serial_int)} instead"
+        )
+    if serial_int < 0:
+        raise AnsibleFilterError(
+            "The input for the community.crypto.to_serial filter must not be negative"
+        )
+    try:
+        return to_serial(serial_int)
+    except ValueError as exc:
+        raise AnsibleFilterError(str(exc)) from exc
+
+
+class FilterModule:
+    """Ansible jinja2 filters"""
+
+    def filters(self) -> dict[str, t.Callable]:
+        return {
+            "to_serial": to_serial_filter,
+        }

plugins/filter/x509_certificate_info.py

@@ -1,13 +1,11 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = '''
+
+DOCUMENTATION = r"""
 name: x509_certificate_info
 short_description: Retrieve information from X.509 certificates in PEM format
 version_added: 2.10.0
@@ -23,12 +21,15 @@ options:
     type: string
     required: true
 extends_documentation_fragment:
-    - community.crypto.name_encoding
+  - community.crypto._name_encoding
 seealso:
   - module: community.crypto.x509_certificate_info
-'''
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 - name: Show the Subject Alt Names of the certificate
   ansible.builtin.debug:
     msg: >-
@@ -38,9 +39,9 @@ EXAMPLES = '''
           | community.crypto.x509_certificate_info
         ).subject_alt_name | join(', ')
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _value:
   description:
     - Information on the certificate.
@@ -82,15 +83,13 @@ _value:
         value:
           description:
             - The Base64 encoded value (in DER format) of the extension.
-                      - B(Note) that depending on the C(cryptography) version used, it is
+            - B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content
-                        not possible to extract the ASN.1 content of the extension, but only
+              of the extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
-                        to provide the re-encoded content of the extension in case it was
+              This should usually result in exactly the same value, except if the original extension value was malformed.
-                        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="}}
+      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
@@ -199,8 +198,8 @@ _value:
         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
+            - This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the multiplicative
-                          multiplicative group of the prime field used.
+              group of the prime field used.
           type: int
           returned: When RV(_value.public_key_type=DSA)
         g:
@@ -227,8 +226,8 @@ _value:
         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
+            - For RV(_value.public_key_type=DSA), this is the publicly known group element whose discrete logarithm with respect
-                          respect to C(g) is the private key.
+              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:
@@ -253,7 +252,10 @@ _value:
       type: str
       sample: sha256WithRSAEncryption
     serial_number:
-            description: The certificate's 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
@@ -291,57 +293,65 @@ _value:
       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
+      description: The OCSP responder URI, if included in the certificate. Will be V(none) if no OCSP responder URI is included.
-                         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
+      description: The Issuer URI, if included in the certificate. Will be V(none) if no issuer URI is included.
-                         V(none) if no issuer URI is included.
       returned: success
       type: str
-'''
+"""
+
+import typing as t
 
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.six import string_types
+from ansible.module_utils.common.text.converters import to_bytes, to_text
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
-
-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 (
-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 (
-from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import FilterModuleMock
+    FilterModuleMock,
+)
 
 
-def x509_certificate_info_filter(data, name_encoding='ignore'):
+def x509_certificate_info_filter(
-    '''Extract information from X.509 PEM certificate.'''
+    data: str | bytes, name_encoding: t.Literal["ignore", "idna", "unicode"] = "ignore"
-    if not isinstance(data, string_types):
+) -> dict[str, t.Any]:
-        raise AnsibleFilterError('The community.crypto.x509_certificate_info input must be a text type, not %s' % type(data))
+    """Extract information from X.509 PEM certificate."""
-    if not isinstance(name_encoding, string_types):
+    if not isinstance(data, (str, bytes)):
-        raise AnsibleFilterError('The name_encoding option must be of a text type, not %s' % type(name_encoding))
+        raise AnsibleFilterError(
-    name_encoding = to_native(name_encoding)
+            f"The community.crypto.x509_certificate_info input must be a text type, not {type(data)}"
-    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)
+    if not isinstance(name_encoding, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The name_encoding option must be of a text type, not {type(name_encoding)}"
+        )
+    name_encoding = to_text(name_encoding)
+    if name_encoding not in ("ignore", "idna", "unicode"):
+        raise AnsibleFilterError(
+            f'The name_encoding option must be one of the values "ignore", "idna", or "unicode", not "{name_encoding}"'
+        )
 
-    module = FilterModuleMock({'name_encoding': name_encoding})
+    module = FilterModuleMock({"name_encoding": name_encoding})
     try:
-        return get_certificate_info(module, 'cryptography', content=to_bytes(data))
+        return get_certificate_info(module=module, content=to_bytes(data))
     except OpenSSLObjectError as exc:
-        raise AnsibleFilterError(to_native(exc))
+        raise AnsibleFilterError(str(exc)) from exc
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'x509_certificate_info': x509_certificate_info_filter,
+            "x509_certificate_info": x509_certificate_info_filter,
         }

plugins/filter/x509_crl_info.py

@@ -1,13 +1,11 @@
-# -*- 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
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = '''
+
+DOCUMENTATION = r"""
 name: x509_crl_info
 short_description: Retrieve information from X.509 CRLs in PEM format
 version_added: 2.10.0
@@ -25,19 +23,21 @@ options:
   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
+      - This is useful when retrieving information on large CRL files. Enumerating all revoked certificates can take some
-              certificates can take some time, including serializing the result as JSON, sending it to
+        time, including serializing the result as JSON, sending it to the Ansible controller, and decoding it again.
-              the Ansible controller, and decoding it again.
     type: bool
     default: true
     version_added: 1.7.0
 extends_documentation_fragment:
-    - community.crypto.name_encoding
+  - community.crypto._name_encoding
 seealso:
   - module: community.crypto.x509_crl_info
-'''
+  - plugin: community.crypto.to_serial
+    plugin_type: filter
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
+---
 - name: Show the Organization Name of the CRL's subject
   ansible.builtin.debug:
     msg: >-
@@ -47,9 +47,9 @@ EXAMPLES = '''
           | community.crypto.x509_crl_info
         ).issuer.organizationName
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
 _value:
   description:
     - Information on the CRL.
@@ -100,7 +100,10 @@ _value:
       elements: dict
       contains:
         serial_number:
-                    description: Serial number of the certificate.
+          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:
@@ -139,7 +142,7 @@ _value:
           type: bool
           sample: false
         invalidity_date:
-                    description: |
+          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
@@ -148,60 +151,74 @@ _value:
           description: Whether the invalidity date extension is critical.
           type: bool
           sample: false
-'''
+"""
 
 import base64
 import binascii
+import typing as t
 
 from ansible.errors import AnsibleFilterError
-from ansible.module_utils.six import string_types
+from ansible.module_utils.common.text.converters import to_bytes, to_text
-from ansible.module_utils.common.text.converters import to_bytes, to_native
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
-
-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 (
-from ansible_collections.community.crypto.plugins.module_utils.crypto.pem import (
-    identify_pem_format,
-)
-
-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 (
-from ansible_collections.community.crypto.plugins.plugin_utils.filter_module import FilterModuleMock
+    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):
+def x509_crl_info_filter(
-    '''Extract information from X.509 PEM certificate.'''
+    data: str | bytes,
-    if not isinstance(data, string_types):
+    name_encoding: t.Literal["ignore", "idna", "unicode"] = "ignore",
-        raise AnsibleFilterError('The community.crypto.x509_crl_info input must be a text type, not %s' % type(data))
+    list_revoked_certificates: bool = True,
-    if not isinstance(name_encoding, string_types):
+) -> dict[str, t.Any]:
-        raise AnsibleFilterError('The name_encoding option must be of a text type, not %s' % type(name_encoding))
+    """Extract information from X.509 PEM certificate."""
+    if not isinstance(data, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The community.crypto.x509_crl_info input must be a text type, not {type(data)}"
+        )
+    if not isinstance(name_encoding, (str, bytes)):
+        raise AnsibleFilterError(
+            f"The name_encoding option must be of a text type, not {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))
+        raise AnsibleFilterError(
-    name_encoding = to_native(name_encoding)
+            f"The list_revoked_certificates option must be a boolean, not {type(list_revoked_certificates)}"
-    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)
+    name_encoding = to_text(name_encoding)
+    if name_encoding not in ("ignore", "idna", "unicode"):
+        raise AnsibleFilterError(
+            f'The name_encoding option must be one of the values "ignore", "idna", or "unicode", not "{name_encoding}"'
+        )
 
-    data = to_bytes(data)
+    data_bytes = to_bytes(data)
-    if not identify_pem_format(data):
+    if not identify_pem_format(data_bytes):
         try:
-            data = base64.b64decode(to_native(data))
+            data_bytes = base64.b64decode(to_text(data_bytes))
-        except (binascii.Error, TypeError, ValueError, UnicodeEncodeError) as e:
+        except (binascii.Error, TypeError, ValueError, UnicodeEncodeError):
             pass
 
-    module = FilterModuleMock({'name_encoding': name_encoding})
+    module = FilterModuleMock({"name_encoding": name_encoding})
     try:
-        return get_crl_info(module, content=data, list_revoked_certificates=list_revoked_certificates)
+        return get_crl_info(
+            module=module,
+            content=data_bytes,
+            list_revoked_certificates=list_revoked_certificates,
+        )
     except OpenSSLObjectError as exc:
-        raise AnsibleFilterError(to_native(exc))
+        raise AnsibleFilterError(str(exc)) from exc
 
 
-class FilterModule(object):
+class FilterModule:
-    '''Ansible jinja2 filters'''
+    """Ansible jinja2 filters"""
 
-    def filters(self):
+    def filters(self) -> dict[str, t.Callable]:
         return {
-            'x509_crl_info': x509_crl_info_filter,
+            "x509_crl_info": x509_crl_info_filter,
         }

plugins/lookup/gpg_fingerprint.py

@@ -1,18 +1,17 @@
-# -*- 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)
+from __future__ import annotations
-__metaclass__ = type
 
-DOCUMENTATION = """
+
+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."
+  - Takes a list of filenames pointing to GPG public or private key files. Returns the fingerprints for each of these keys.
 options:
   _terms:
     description:
@@ -27,14 +26,15 @@ seealso:
     plugin_type: filter
 """
 
-EXAMPLES = """
+EXAMPLES = r"""
+---
 - name: Show fingerprint of GPG public key
   ansible.builtin.debug:
     msg: "{{ lookup('community.crypto.gpg_fingerprint', '/path/to/public_key.gpg') }}"
 """
 
-RETURN = """
+RETURN = r"""
-  _value:
+_value:
   description:
     - The fingerprints of the provided public or private GPG keys.
     - The list has one entry for every path provided.
@@ -42,23 +42,38 @@ RETURN = """
   elements: string
 """
 
-from ansible.plugins.lookup import LookupBase
+import os
-from ansible.errors import AnsibleLookupError
+import typing as t
-from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.crypto.plugins.module_utils.gnupg.cli import GPGError, get_fingerprint_from_file
+from ansible.errors import AnsibleLookupError
-from ansible_collections.community.crypto.plugins.plugin_utils.gnupg import PluginGPGRunner
+from ansible.module_utils.common.text.converters import to_text
+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):
+    def run(self, terms: list[t.Any], variables=None, **kwargs) -> list[str]:
         self.set_options(direct=kwargs)
+        if self._loader is None:
+            raise AssertionError("Contract violation: self._loader is None")
 
         try:
             gpg = PluginGPGRunner(cwd=self._loader.get_basedir())
             result = []
-            for path in terms:
+            for i, path in enumerate(terms):
-                result.append(get_fingerprint_from_file(gpg, path))
+                if not isinstance(path, (str, bytes, os.PathLike)):
+                    raise AnsibleLookupError(
+                        f"Lookup parameter #{i} should be string or a path object, but got {type(path)}"
+                    )
+                result.append(
+                    get_fingerprint_from_file(gpg_runner=gpg, path=to_text(path))
+                )
             return result
         except GPGError as exc:
-            raise AnsibleLookupError(to_native(exc))
+            raise AnsibleLookupError(str(exc)) from exc

plugins/module_utils/_acme/account.py

@@ -0,0 +1,346 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils.common._collections_compat import Mapping
+from ansible_collections.community.crypto.plugins.module_utils._acme.errors import (
+    ACMEProtocolException,
+    ModuleFailException,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible_collections.community.crypto.plugins.module_utils._acme.acme import (
+        ACMEClient,
+    )
+
+
+class ACMEAccount:
+    """
+    ACME account object. Allows to create new accounts, check for existence of accounts,
+    retrieve account data.
+    """
+
+    def __init__(self, *, client: ACMEClient) -> None:
+        # Set to true to enable logging of all signed requests
+        self._debug: bool = False
+
+        self.client = client
+
+    def _new_reg(
+        self,
+        *,
+        contact: list[str] | None = None,
+        terms_agreed: bool = False,
+        allow_creation: bool = True,
+        external_account_binding: dict[str, t.Any] | None = None,
+    ) -> tuple[bool, dict[str, t.Any] | 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),
+        or does not exist. In case the account was created or exists,
+        ``data`` contains the account data; otherwise, it is ``None``.
+
+        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
+        """
+        contact = contact or []
+
+        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 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.
+
+        new_reg: dict[str, t.Any] = {"contact": contact}
+        if not allow_creation:
+            # https://tools.ietf.org/html/rfc8555#section-7.3.1
+            new_reg["onlyReturnExisting"] = True
+        if terms_agreed:
+            new_reg["termsOfServiceAgreed"] = True
+        url = self.client.directory["newAccount"]
+        if external_account_binding is not None:
+            new_reg["externalAccountBinding"] = self.client.sign_request(
+                protected={
+                    "alg": external_account_binding["alg"],
+                    "kid": external_account_binding["kid"],
+                    "url": url,
+                },
+                payload=self.client.account_jwk,
+                key_data=self.client.backend.create_mac_key(
+                    alg=external_account_binding["alg"],
+                    key=external_account_binding["key"],
+                ),
+            )
+        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."
+            )
+
+        result, info = self.client.send_signed_request(
+            url, new_reg, fail_on_error=False
+        )
+        if not isinstance(result, Mapping):
+            raise ACMEProtocolException(
+                module=self.client.module,
+                msg="Invalid account creation reply from ACME server",
+                info=info,
+                content_json=result,
+            )
+
+        if info["status"] == 201:
+            # Account did not exist
+            if "location" in info:
+                self.client.set_account_uri(info["location"])
+            return True, result
+        if info["status"] == 200:
+            # Account did exist
+            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
+                # https://tools.ietf.org/html/rfc8555#section-7.3.6:
+                #     "Once an account is deactivated, the server MUST NOT accept further
+                #      requests authorized by that account's key."
+                if not allow_creation:
+                    return False, None
+                raise ModuleFailException("Account is deactivated")
+            if "location" in info:
+                self.client.set_account_uri(info["location"])
+            return False, result
+        if (
+            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
+        if (
+            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:
+                return False, None
+            raise ModuleFailException("Account is deactivated")
+        raise ACMEProtocolException(
+            module=self.client.module,
+            msg="Registering ACME account failed",
+            info=info,
+            content_json=result,
+        )
+
+    def get_account_data(self) -> dict[str, t.Any] | None:
+        """
+        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")
+        # try POST-as-GET first (draft-15 or newer)
+        data: dict[str, t.Any] | None = None
+        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"
+        ):
+            # 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 not isinstance(result, Mapping):
+            raise ACMEProtocolException(
+                module=self.client.module,
+                msg="Invalid account data retrieved from ACME server",
+                info=info,
+                content_json=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"
+        ):
+            # Returned when account does not exist
+            return None
+        if info["status"] < 200 or info["status"] >= 300:
+            raise ACMEProtocolException(
+                module=self.client.module,
+                msg="Error retrieving account data",
+                info=info,
+                content_json=result,
+            )
+        return result
+
+    @t.overload
+    def setup_account(
+        self,
+        *,
+        contact: list[str] | None = None,
+        terms_agreed: bool = False,
+        allow_creation: t.Literal[True] = True,
+        remove_account_uri_if_not_exists: bool = False,
+        external_account_binding: dict[str, t.Any] | None = None,
+    ) -> tuple[bool, dict[str, t.Any]]: ...
+
+    @t.overload
+    def setup_account(
+        self,
+        *,
+        contact: list[str] | None = None,
+        terms_agreed: bool = False,
+        allow_creation: bool = True,
+        remove_account_uri_if_not_exists: bool = False,
+        external_account_binding: dict[str, t.Any] | None = None,
+    ) -> tuple[bool, dict[str, t.Any] | None]: ...
+
+    def setup_account(
+        self,
+        *,
+        contact: list[str] | None = None,
+        terms_agreed: bool = False,
+        allow_creation: bool = True,
+        remove_account_uri_if_not_exists: bool = False,
+        external_account_binding: dict[str, t.Any] | None = None,
+    ) -> tuple[bool, dict[str, t.Any] | 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 ``client.account_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
+        """
+
+        if self.client.account_uri is not None:
+            created = False
+            # Verify that the account key belongs to the URI.
+            # (If update_contact is True, this will be done below.)
+            account_data = self.get_account_data()
+            if account_data is None:
+                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!"
+                    )
+        else:
+            created, account_data = self._new_reg(
+                contact=contact,
+                terms_agreed=terms_agreed,
+                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
+            ):
+                created = True
+                account_data = {"contact": contact or []}
+        return created, account_data
+
+    def update_account(
+        self, *, account_data: dict[str, t.Any], contact: list[str] | None = None
+    ) -> tuple[bool, dict[str, t.Any]]:
+        """
+        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
+        """
+        if self.client.account_uri is None:
+            raise ModuleFailException("Cannot update account without account URI")
+
+        # Create request
+        update_request: dict[str, t.Any] = {}
+        if contact is not None and account_data.get("contact", []) != contact:
+            update_request["contact"] = list(contact)
+
+        # No change?
+        if not update_request:
+            return False, dict(account_data)
+
+        # Apply change
+        if self.client.module.check_mode:
+            account_data = dict(account_data)
+            account_data.update(update_request)
+        else:
+            account_data, info = self.client.send_signed_request(
+                self.client.account_uri, update_request
+            )
+            if not isinstance(account_data, Mapping):
+                raise ACMEProtocolException(
+                    module=self.client.module,
+                    msg="Invalid account updating reply from ACME server",
+                    info=info,
+                    content_json=account_data,
+                )
+
+        return True, account_data
+
+
+__all__ = ("ACMEAccount",)

plugins/module_utils/_acme/acme.py

@@ -0,0 +1,738 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import copy
+import datetime
+import json
+import locale
+import time
+import typing as t
+
+from ansible.module_utils.basic import missing_required_lib
+from ansible.module_utils.common.text.converters import to_bytes
+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.errors import (
+    ACMEProtocolException,
+    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,
+)
+from ansible_collections.community.crypto.plugins.module_utils._time import (
+    get_now_datetime,
+)
+
+
+if t.TYPE_CHECKING:
+    import os
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._acme.account import (
+        ACMEAccount,
+    )
+    from ansible_collections.community.crypto.plugins.module_utils._acme.backends import (
+        CertificateInformation,
+        CryptoBackend,
+    )
+
+
+# -1 usually means connection problems
+RETRY_STATUS_CODES = (-1, 408, 429, 503)
+
+RETRY_COUNT = 10
+
+
+def _decode_retry(
+    *, module: AnsibleModule, response: t.Any, info: dict[str, t.Any], retry_count: int
+) -> bool:
+    if info["status"] not in RETRY_STATUS_CODES:
+        return False
+
+    if retry_count >= RETRY_COUNT:
+        raise ACMEProtocolException(
+            module=module,
+            msg=f"Giving up after {RETRY_COUNT} retries",
+            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)
+    now = get_now_datetime(with_timezone=True)
+    try:
+        then = parse_retry_after(
+            info.get("retry-after", "10"), relative_with_timezone=True, now=now
+        )
+        retry_after = (then - now).total_seconds()
+        retry_after = min(max(1, retry_after), 60)
+    except (TypeError, ValueError):
+        retry_after = 10
+    module.log(
+        f"Retrieved a {format_http_status(info['status'])} HTTP status on {info['url']}, retrying in {retry_after} seconds"
+    )
+
+    time.sleep(retry_after)
+    return True
+
+
+def _assert_fetch_url_success(
+    *,
+    module: AnsibleModule,
+    response: t.Any,
+    info: dict[str, t.Any],
+    allow_redirect: bool = False,
+    allow_client_error: bool = True,
+    allow_server_error: bool = True,
+) -> None:
+    if info["status"] < 0:
+        raise NetworkException(msg=f"Failure downloading {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=module, info=info, response=response)
+
+
+def _is_failed(
+    *, info: dict[str, t.Any], expected_status_codes: t.Iterable[int] | None = None
+) -> bool:
+    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
+    ):
+        return True
+    return False
+
+
+class ACMEDirectory:
+    """
+    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: AnsibleModule, client: ACMEClient) -> None:
+        self.module = module
+        self.directory_root = module.params["acme_directory"]
+        self.version = module.params["acme_version"]
+
+        self.directory, dummy = client.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 == 2:
+            for key in ("newNonce", "newAccount", "newOrder"):
+                if key not in self.directory:
+                    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"] = {}
+
+    def __getitem__(self, key: str) -> t.Any:
+        return self.directory[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.directory
+
+    def get(self, key: str, default_value: t.Any = None) -> t.Any:
+        return self.directory.get(key, default_value)
+
+    def get_nonce(self, resource: str | None = None) -> str:
+        url = self.directory["newNonce"]
+        if resource is not None:
+            url = resource
+        retry_count = 0
+        while True:
+            response, info = fetch_url(
+                self.module, url, method="HEAD", timeout=self.request_timeout
+            )
+            if _decode_retry(
+                module=self.module,
+                response=response,
+                info=info,
+                retry_count=retry_count,
+            ):
+                retry_count += 1
+                continue
+            if info["status"] not in (200, 204):
+                raise NetworkException(
+                    f"Failed to get replay-nonce, got status {format_http_status(info['status'])}"
+                )
+            if "replay-nonce" in info:
+                return info["replay-nonce"]
+            self.module.log(
+                f"HEAD to {url} did return status {format_http_status(info['status'])}, but no replay-nonce header!"
+            )
+            if retry_count >= 5:
+                raise ACMEProtocolException(
+                    module=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) -> bool:
+        return "renewalInfo" in self.directory
+
+
+class ACMEClient:
+    """
+    ACME client object. Handles the authorized communication with the
+    ACME server.
+    """
+
+    def __init__(self, *, module: AnsibleModule, backend: CryptoBackend) -> None:
+        # Set to true to enable logging of all signed requests
+        self._debug = False
+
+        self.module = module
+        self.backend = backend
+        self.version = module.params["acme_version"]
+        # account_key path and content are mutually exclusive
+        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.request_timeout = module.params["request_timeout"]
+
+        self.account_key_data = None
+        self.account_jwk = None
+        self.account_jws_header = None
+        if self.account_key_file is not None or self.account_key_content is not None:
+            try:
+                self.account_key_data = self.parse_key(
+                    key_file=self.account_key_file,
+                    key_content=self.account_key_content,
+                    passphrase=self.account_key_passphrase,
+                )
+            except KeyParsingError as e:
+                raise ModuleFailException(
+                    f"Error while parsing account key: {e.msg}"
+                ) from e
+            self.account_jwk = self.account_key_data["jwk"]
+            self.account_jws_header = {
+                "alg": self.account_key_data["alg"],
+                "jwk": self.account_jwk,
+            }
+            if self.account_uri:
+                # Make sure self.account_jws_header is updated
+                self.set_account_uri(self.account_uri)
+
+        self.directory = ACMEDirectory(module=module, client=self)
+
+    def set_account_uri(self, uri: str) -> None:
+        """
+        Set account URI. For ACME v2, it needs to be used to sending signed
+        requests.
+        """
+        self.account_uri = uri
+        if self.account_jws_header:
+            self.account_jws_header.pop("jwk", None)
+            self.account_jws_header["kid"] = self.account_uri
+
+    def parse_key(
+        self,
+        *,
+        key_file: str | os.PathLike | None = None,
+        key_content: str | None = None,
+        passphrase: str | None = None,
+    ) -> dict[str, t.Any]:
+        """
+        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!")
+        return self.backend.parse_key(
+            key_file=key_file, key_content=key_content, passphrase=passphrase
+        )
+
+    def sign_request(
+        self,
+        *,
+        protected: dict[str, t.Any],
+        payload: str | dict[str, t.Any] | None,
+        key_data: dict[str, t.Any],
+        encode_payload: bool = True,
+    ) -> dict[str, t.Any]:
+        """
+        Signs an ACME request.
+        """
+        try:
+            if payload is None:
+                # POST-as-GET
+                payload64 = ""
+            else:
+                # POST
+                if encode_payload:
+                    payload = self.module.jsonify(payload).encode("utf8")
+                payload64 = nopad_b64(to_bytes(payload))
+            protected64 = nopad_b64(self.module.jsonify(protected).encode("utf8"))
+        except Exception as e:
+            raise ModuleFailException(
+                f"Failed to encode payload / headers as JSON: {e}"
+            ) from e
+
+        return self.backend.sign(
+            payload64=payload64, protected64=protected64, key_data=key_data
+        )
+
+    def _log(self, msg: str, *, data: t.Any = None) -> None:
+        """
+        Write arguments to acme.log when logging is enabled.
+        """
+        if self._debug:
+            with open("acme.log", "ab") as f:
+                timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S.%s")
+                f.write(f"[{timestamp}] {msg}\n".encode("utf-8"))
+                if data is not None:
+                    f.write(
+                        f"{json.dumps(data, indent=2, sort_keys=True)}\n\n".encode(
+                            "utf-8"
+                        )
+                    )
+
+    @t.overload
+    def send_signed_request(
+        self,
+        url: str,
+        payload: str | dict[str, t.Any] | None,
+        *,
+        key_data: dict[str, t.Any] | None = None,
+        jws_header: dict[str, t.Any] | None = None,
+        parse_json_result: t.Literal[True] = True,
+        encode_payload: bool = True,
+        fail_on_error: bool = True,
+        error_msg: str | None = None,
+        expected_status_codes: t.Iterable[int] | None = None,
+    ) -> tuple[dict[str, t.Any], dict[str, t.Any]]: ...
+
+    @t.overload
+    def send_signed_request(
+        self,
+        url: str,
+        payload: str | dict[str, t.Any] | None,
+        *,
+        key_data: dict[str, t.Any] | None = None,
+        jws_header: dict[str, t.Any] | None = None,
+        parse_json_result: t.Literal[False],
+        encode_payload: bool = True,
+        fail_on_error: bool = True,
+        error_msg: str | None = None,
+        expected_status_codes: t.Iterable[int] | None = None,
+    ) -> tuple[bytes, dict[str, t.Any]]: ...
+
+    def send_signed_request(
+        self,
+        url: str,
+        payload: str | dict[str, t.Any] | None,
+        *,
+        key_data: dict[str, t.Any] | None = None,
+        jws_header: dict[str, t.Any] | None = None,
+        parse_json_result: bool = True,
+        encode_payload: bool = True,
+        fail_on_error: bool = True,
+        error_msg: str | None = None,
+        expected_status_codes: t.Iterable[int] | None = None,
+    ) -> tuple[dict[str, t.Any] | bytes, dict[str, t.Any]]:
+        """
+        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).
+        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)
+        """
+        key_data = key_data or self.account_key_data
+        if key_data is None:
+            raise ModuleFailException("Missing key data")
+        jws_header = jws_header or self.account_jws_header
+        if jws_header is None:
+            raise ModuleFailException("Missing JWS header")
+        failed_tries = 0
+        while True:
+            protected = copy.deepcopy(jws_header)
+            protected["nonce"] = self.directory.get_nonce()
+            protected["url"] = url
+
+            self._log("URL", data=url)
+            self._log("protected", data=protected)
+            self._log("payload", data=payload)
+            data = self.sign_request(
+                protected=protected,
+                payload=payload,
+                key_data=key_data,
+                encode_payload=encode_payload,
+            )
+            self._log("signed request", data=data)
+            data = self.module.jsonify(data)
+
+            headers = {
+                "Content-Type": "application/jose+json",
+            }
+            resp, info = fetch_url(
+                self.module,
+                url,
+                data=data,
+                headers=headers,
+                method="POST",
+                timeout=self.request_timeout,
+            )
+            if _decode_retry(
+                module=self.module, response=resp, info=info, retry_count=failed_tries
+            ):
+                failed_tries += 1
+                continue
+            _assert_fetch_url_success(module=self.module, response=resp, info=info)
+            result = {}
+
+            try:
+                # In Python 2, reading from a closed response yields a TypeError.
+                # In Python 3, read() simply returns ''
+                if resp.closed:
+                    raise TypeError
+                content = resp.read()
+            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:
+                    try:
+                        decoded_result = self.module.from_json(content.decode("utf8"))
+                        self._log("parsed result", data=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,
+                            )
+                        ):
+                            failed_tries += 1
+                            continue
+                        if parse_json_result:
+                            result = decoded_result
+                        else:
+                            result = content
+                    except ValueError as exc:
+                        raise NetworkException(
+                            f"Failed to parse the ACME response: {url} {content}"
+                        ) from exc
+                else:
+                    result = content
+
+            if fail_on_error and _is_failed(
+                info=info, expected_status_codes=expected_status_codes
+            ):
+                raise ACMEProtocolException(
+                    module=self.module,
+                    msg=error_msg,
+                    info=info,
+                    content=content,
+                    content_json=result if parse_json_result else None,
+                )
+            return result, info
+
+    @t.overload
+    def get_request(
+        self,
+        uri: str,
+        *,
+        parse_json_result: t.Literal[True] = True,
+        headers: dict[str, str] | None = None,
+        get_only: bool = False,
+        fail_on_error: bool = True,
+        error_msg: str | None = None,
+        expected_status_codes: t.Iterable[int] | None = None,
+    ) -> tuple[dict[str, t.Any], dict[str, t.Any]]: ...
+
+    @t.overload
+    def get_request(
+        self,
+        uri: str,
+        *,
+        parse_json_result: t.Literal[False],
+        headers: dict[str, str] | None = None,
+        get_only: bool = False,
+        fail_on_error: bool = True,
+        error_msg: str | None = None,
+        expected_status_codes: t.Iterable[int] | None = None,
+    ) -> tuple[bytes, dict[str, t.Any]]: ...
+
+    def get_request(
+        self,
+        uri: str,
+        *,
+        parse_json_result: bool = True,
+        headers: dict[str, str] | None = None,
+        get_only: bool = False,
+        fail_on_error: bool = True,
+        error_msg: str | None = None,
+        expected_status_codes: t.Iterable[int] | None = None,
+    ) -> tuple[dict[str, t.Any] | bytes, dict[str, t.Any]]:
+        """
+        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:
+            # Try POST-as-GET
+            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:
+            # Do unauthenticated GET
+            get_only = True
+
+        if get_only:
+            # Perform unauthenticated GET
+            retry_count = 0
+            while True:
+                resp, info = fetch_url(
+                    self.module,
+                    uri,
+                    method="GET",
+                    headers=headers,
+                    timeout=self.request_timeout,
+                )
+                if not _decode_retry(
+                    module=self.module,
+                    response=resp,
+                    info=info,
+                    retry_count=retry_count,
+                ):
+                    break
+                retry_count += 1
+
+            _assert_fetch_url_success(module=self.module, response=resp, info=info)
+
+            try:
+                # In Python 2, reading from a closed response yields a TypeError.
+                # In Python 3, read() simply returns ''
+                if resp.closed:
+                    raise TypeError
+                content = resp.read()
+            except (AttributeError, TypeError):
+                content = info.pop("body", None)
+
+        # Process result
+        parsed_json_result = False
+        result: dict[str, t.Any] | bytes
+        if parse_json_result:
+            result = {}
+            if content:
+                if info["content-type"].startswith("application/json"):
+                    try:
+                        result = self.module.from_json(content.decode("utf8"))
+                        parsed_json_result = True
+                    except ValueError as exc:
+                        raise NetworkException(
+                            f"Failed to parse the ACME response: {uri} {content!r}"
+                        ) from exc
+                else:
+                    result = content
+        else:
+            result = content
+
+        if fail_on_error and _is_failed(
+            info=info, expected_status_codes=expected_status_codes
+        ):
+            raise ACMEProtocolException(
+                module=self.module,
+                msg=error_msg,
+                info=info,
+                content=content,
+                content_json=(
+                    t.cast(dict[str, t.Any], result) if parsed_json_result else None
+                ),
+            )
+        return result, info
+
+    def get_renewal_info(
+        self,
+        *,
+        cert_id: str | None = None,
+        cert_info: CertificateInformation | None = None,
+        cert_filename: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+        include_retry_after: bool = False,
+        retry_after_relative_with_timezone: bool = True,
+    ) -> dict[str, t.Any]:
+        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(
+                backend=self.backend,
+                cert_info=cert_info,
+                cert_filename=cert_filename,
+                cert_content=cert_content,
+            )
+        url = f"{self.directory.directory['renewalInfo'].rstrip('/')}/{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 create_default_argspec(
+    *,
+    with_account: bool = True,
+    require_account_key: bool = True,
+    with_certificate: bool = False,
+) -> ArgumentSpec:
+    """
+    Provides default argument spec for the options documented in the acme doc fragment.
+    """
+    result = ArgumentSpec(
+        argument_spec={
+            "acme_directory": {"type": "str", "required": True},
+            "acme_version": {"type": "int", "choices": [2], "default": 2},
+            "validate_certs": {"type": "bool", "default": True},
+            "select_crypto_backend": {
+                "type": "str",
+                "default": "auto",
+                "choices": ["auto", "openssl", "cryptography"],
+            },
+            "request_timeout": {"type": "int", "default": 10},
+        },
+    )
+    if with_account:
+        result.update_argspec(
+            account_key_src={"type": "path", "aliases": ["account_key"]},
+            account_key_content={"type": "str", "no_log": True},
+            account_key_passphrase={"type": "str", "no_log": True},
+            account_uri={"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={"type": "path"},
+            csr_content={"type": "str"},
+        )
+        result.update(
+            required_one_of=[["csr", "csr_content"]],
+            mutually_exclusive=[["csr", "csr_content"]],
+        )
+    return result
+
+
+def create_backend(
+    module: AnsibleModule, *, needs_acme_v2: bool = True
+) -> CryptoBackend:
+    backend = module.params["select_crypto_backend"]
+
+    # Backend autodetect
+    if backend == "auto":
+        backend = "cryptography" if HAS_CURRENT_CRYPTOGRAPHY else "openssl"
+
+    # Create backend object
+    module_backend: CryptoBackend
+    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 = f"Unexpected error while preparing cryptography: {CRYPTOGRAPHY_ERROR.splitlines()[-1]}"
+            module.fail_json(msg=msg, exception=CRYPTOGRAPHY_ERROR)
+        if not HAS_CURRENT_CRYPTOGRAPHY:
+            # We succeeded importing cryptography, but its version is too old.
+            mrl = missing_required_lib(
+                f"cryptography >= {CRYPTOGRAPHY_MINIMAL_VERSION}"
+            )
+            module.fail_json(
+                msg=f"Found cryptography, but only version {CRYPTOGRAPHY_VERSION}. {mrl}"
+            )
+        module.debug(
+            f"Using cryptography backend (library version {CRYPTOGRAPHY_VERSION})"
+        )
+        module_backend = CryptographyBackend(module=module)
+    elif backend == "openssl":
+        module.debug("Using OpenSSL binary backend")
+        module_backend = OpenSSLCLIBackend(module=module)
+    else:
+        module.fail_json(msg=f'Unknown crypto backend "{backend}"!')
+
+    # Check common module parameters
+    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."
+        )
+
+    # 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")
+
+    return module_backend
+
+
+__all__ = (
+    "ACMEDirectory",
+    "ACMEClient",
+    "create_default_argspec",
+    "create_backend",
+)

plugins/module_utils/_acme/backend_cryptography.py

@@ -0,0 +1,550 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+import traceback
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes, 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._crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_name_to_oid,
+    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._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.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
+except ImportError:
+    HAS_CURRENT_CRYPTOGRAPHY = False
+    CRYPTOGRAPHY_VERSION = None
+    CRYPTOGRAPHY_ERROR = traceback.format_exc()
+else:
+    CRYPTOGRAPHY_VERSION = cryptography.__version__
+    HAS_CURRENT_CRYPTOGRAPHY = LooseVersion(CRYPTOGRAPHY_VERSION) >= LooseVersion(
+        CRYPTOGRAPHY_MINIMAL_VERSION
+    )
+
+if t.TYPE_CHECKING:
+    import datetime
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._acme.certificates import (
+        CertificateChain,
+        Criterium,
+    )
+
+
+class CryptographyChainMatcher(ChainMatcher):
+    @staticmethod
+    def _parse_key_identifier(
+        *,
+        key_identifier: str | None,
+        name: str,
+        criterium_idx: int,
+        module: AnsibleModule,
+    ) -> bytes | None:
+        if key_identifier:
+            try:
+                return binascii.unhexlify(key_identifier.replace(":", ""))
+            except Exception:
+                if criterium_idx is None:
+                    module.warn(
+                        f"Criterium has invalid {name} value. Ignoring criterium."
+                    )
+                else:
+                    module.warn(
+                        f"Criterium {criterium_idx} in select_chain has invalid {name} value. "
+                        "Ignoring criterium."
+                    )
+        return None
+
+    def __init__(self, *, criterium: Criterium, module: AnsibleModule) -> None:
+        self.criterium = criterium
+        self.test_certificates = criterium.test_certificates
+        self.subject: list[tuple[cryptography.x509.oid.ObjectIdentifier, str]] = []
+        self.issuer: list[tuple[cryptography.x509.oid.ObjectIdentifier, str]] = []
+        if criterium.subject:
+            self.subject = [
+                (cryptography_name_to_oid(k), to_text(v))
+                for k, v in parse_name_field(
+                    criterium.subject, name_field_name="subject"
+                )
+            ]
+        if criterium.issuer:
+            self.issuer = [
+                (cryptography_name_to_oid(k), to_text(v))
+                for k, v in parse_name_field(criterium.issuer, name_field_name="issuer")
+            ]
+        self.subject_key_identifier = CryptographyChainMatcher._parse_key_identifier(
+            key_identifier=criterium.subject_key_identifier,
+            name="subject_key_identifier",
+            criterium_idx=criterium.index,
+            module=module,
+        )
+        self.authority_key_identifier = CryptographyChainMatcher._parse_key_identifier(
+            key_identifier=criterium.authority_key_identifier,
+            name="authority_key_identifier",
+            criterium_idx=criterium.index,
+            module=module,
+        )
+        self.module = module
+
+    def _match_subject(
+        self,
+        *,
+        x509_subject: cryptography.x509.Name,
+        match_subject: list[tuple[cryptography.x509.oid.ObjectIdentifier, str]],
+    ) -> bool:
+        for oid, value in match_subject:
+            found = False
+            for attribute in x509_subject:
+                if attribute.oid == oid and value == to_text(attribute.value):
+                    found = True
+                    break
+            if not found:
+                return False
+        return True
+
+    def match(self, *, certificate: CertificateChain) -> bool:
+        """
+        Check whether an alternate chain matches the specified criterium.
+        """
+        chain = certificate.chain
+        if self.test_certificates == "last":
+            chain = chain[-1:]
+        elif self.test_certificates == "first":
+            chain = chain[:1]
+        for cert in chain:
+            try:
+                x509 = cryptography.x509.load_pem_x509_certificate(to_bytes(cert))
+                matches = True
+                if not self._match_subject(
+                    x509_subject=x509.subject, match_subject=self.subject
+                ):
+                    matches = False
+                if not self._match_subject(
+                    x509_subject=x509.issuer, match_subject=self.issuer
+                ):
+                    matches = False
+                if self.subject_key_identifier:
+                    try:
+                        ext_ski = x509.extensions.get_extension_for_class(
+                            cryptography.x509.SubjectKeyIdentifier
+                        )
+                        if self.subject_key_identifier != ext_ski.value.digest:
+                            matches = False
+                    except cryptography.x509.ExtensionNotFound:
+                        matches = False
+                if self.authority_key_identifier:
+                    try:
+                        ext_aki = x509.extensions.get_extension_for_class(
+                            cryptography.x509.AuthorityKeyIdentifier
+                        )
+                        if (
+                            self.authority_key_identifier
+                            != ext_aki.value.key_identifier
+                        ):
+                            matches = False
+                    except cryptography.x509.ExtensionNotFound:
+                        matches = False
+                if matches:
+                    return True
+            except Exception as e:
+                self.module.warn(f"Error while loading certificate {cert}: {e}")
+        return False
+
+
+class CryptographyBackend(CryptoBackend):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        super().__init__(module=module, with_timezone=CRYPTOGRAPHY_TIMEZONE)
+
+    def parse_key(
+        self,
+        *,
+        key_file: str | os.PathLike | None = None,
+        key_content: str | None = None,
+        passphrase: str | None = None,
+    ) -> dict[str, t.Any]:
+        """
+        Parses an RSA or Elliptic Curve key file in PEM format and returns key_data.
+        Raises KeyParsingError in case of errors.
+        """
+        # If key_content is not given, read key_file
+        if key_content is None:
+            if key_file is None:
+                raise KeyParsingError(
+                    "one of key_file and key_content must be specified"
+                )
+            b_key_content = read_file(key_file)
+        else:
+            b_key_content = to_bytes(key_content)
+        # Parse key
+        try:
+            key = cryptography.hazmat.primitives.serialization.load_pem_private_key(
+                b_key_content,
+                password=to_bytes(passphrase) if passphrase is not None else None,
+            )
+        except Exception as e:
+            raise KeyParsingError(f"error while loading key: {e}") from e
+        if isinstance(key, cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey):
+            rsa_pk = key.public_key().public_numbers()
+            return {
+                "key_obj": key,
+                "type": "rsa",
+                "alg": "RS256",
+                "jwk": {
+                    "kty": "RSA",
+                    "e": nopad_b64(convert_int_to_bytes(rsa_pk.e)),
+                    "n": nopad_b64(convert_int_to_bytes(rsa_pk.n)),
+                },
+                "hash": "sha256",
+            }
+        if isinstance(
+            key, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
+        ):
+            ec_pk = key.public_key().public_numbers()
+            if ec_pk.curve.name == "secp256r1":
+                bits = 256
+                alg = "ES256"
+                hashalg = "sha256"
+                point_size = 32
+                curve = "P-256"
+            elif ec_pk.curve.name == "secp384r1":
+                bits = 384
+                alg = "ES384"
+                hashalg = "sha384"
+                point_size = 48
+                curve = "P-384"
+            elif ec_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"
+                point_size = 66
+                curve = "P-521"
+            else:
+                raise KeyParsingError(f"unknown elliptic curve: {ec_pk.curve.name}")
+            num_bytes = (bits + 7) // 8
+            return {
+                "key_obj": key,
+                "type": "ec",
+                "alg": alg,
+                "jwk": {
+                    "kty": "EC",
+                    "crv": curve,
+                    "x": nopad_b64(convert_int_to_bytes(ec_pk.x, count=num_bytes)),
+                    "y": nopad_b64(convert_int_to_bytes(ec_pk.y, count=num_bytes)),
+                },
+                "hash": hashalg,
+                "point_size": point_size,
+            }
+        raise KeyParsingError(f'unknown key type "{type(key)}"')
+
+    def sign(
+        self, *, payload64: str, protected64: str, key_data: dict[str, t.Any]
+    ) -> dict[str, t.Any]:
+        sign_payload = f"{protected64}.{payload64}".encode("utf8")
+        hashalg: type[cryptography.hazmat.primitives.hashes.HashAlgorithm]
+        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,
+        ):
+            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":
+                hashalg = cryptography.hazmat.primitives.hashes.SHA256
+            elif key_data["hash"] == "sha384":
+                hashalg = cryptography.hazmat.primitives.hashes.SHA384
+            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 = convert_int_to_hex(r, digits=2 * key_data["point_size"])
+            ss = convert_int_to_hex(s, digits=2 * key_data["point_size"])
+            signature = binascii.unhexlify(rr) + binascii.unhexlify(ss)
+        else:
+            raise AssertionError("Can never be reached")  # pragma: no cover
+
+        return {
+            "protected": protected64,
+            "payload": payload64,
+            "signature": nopad_b64(signature),
+        }
+
+    def create_mac_key(self, *, alg: str, key: str) -> dict[str, t.Any]:
+        """Create a MAC key."""
+        hashalg: type[cryptography.hazmat.primitives.hashes.HashAlgorithm]
+        if alg == "HS256":
+            hashalg = cryptography.hazmat.primitives.hashes.SHA256
+            hashbytes = 32
+        elif alg == "HS384":
+            hashalg = cryptography.hazmat.primitives.hashes.SHA384
+            hashbytes = 48
+        elif alg == "HS512":
+            hashalg = cryptography.hazmat.primitives.hashes.SHA512
+            hashbytes = 64
+        else:
+            raise BackendException(
+                f"Unsupported MAC key algorithm for cryptography backend: {alg}"
+            )
+        key_bytes = base64.urlsafe_b64decode(key)
+        if len(key_bytes) < hashbytes:
+            raise BackendException(
+                f"{alg} key must be at least {hashbytes} bytes long (after Base64 decoding)"
+            )
+        return {
+            "mac_obj": lambda: cryptography.hazmat.primitives.hmac.HMAC(
+                key_bytes, hashalg()
+            ),
+            "type": "hmac",
+            "alg": alg,
+            "jwk": {
+                "kty": "oct",
+                "k": key,
+            },
+        }
+
+    def get_ordered_csr_identifiers(
+        self,
+        *,
+        csr_filename: str | os.PathLike | None = None,
+        csr_content: str | bytes | None = None,
+    ) -> list[tuple[str, str]]:
+        """
+        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.
+        """
+        if csr_content is None:
+            if csr_filename is None:
+                raise BackendException(
+                    "One of csr_content and csr_filename has to be provided"
+                )
+            b_csr_content = read_file(csr_filename)
+        else:
+            b_csr_content = to_bytes(csr_content)
+        csr = cryptography.x509.load_pem_x509_csr(b_csr_content)
+
+        identifiers = set()
+        result = []
+
+        def add_identifier(identifier: tuple[str, str]) -> None:
+            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:
+                add_identifier(("dns", t.cast(str, sub.value)))
+        for extension in csr.extensions:
+            if (
+                extension.oid
+                == cryptography.x509.oid.ExtensionOID.SUBJECT_ALTERNATIVE_NAME
+            ):
+                for name in extension.value:
+                    if isinstance(name, cryptography.x509.DNSName):
+                        add_identifier(("dns", name.value))
+                    elif isinstance(name, cryptography.x509.IPAddress):
+                        add_identifier(("ip", name.value.compressed))
+                    else:
+                        raise BackendException(
+                            f"Found unsupported SAN identifier {name}"
+                        )
+        return result
+
+    def get_csr_identifiers(
+        self,
+        *,
+        csr_filename: str | os.PathLike | None = None,
+        csr_content: str | bytes | bytes | None = None,
+    ) -> set[tuple[str, str]]:
+        """
+        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: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+        now: datetime.datetime | None = None,
+    ) -> int:
+        """
+        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):
+                cert_content = read_file(cert_filename)
+        else:
+            cert_content = to_bytes(cert_content)
+
+        if cert_content is None:
+            return -1
+
+        # Make sure we have at most one PEM. Otherwise cryptography 36.0.0 will barf.
+        b_cert_content = to_bytes(extract_first_pem(to_text(cert_content)) or "")
+
+        try:
+            cert = cryptography.x509.load_pem_x509_certificate(b_cert_content)
+        except Exception as e:
+            if cert_filename is None:
+                raise BackendException(f"Cannot parse certificate: {e}") from e
+            raise BackendException(
+                f"Cannot parse certificate {cert_filename}: {e}"
+            ) from e
+
+        if now is None:
+            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: Criterium) -> ChainMatcher:
+        """
+        Given a Criterium object, creates a ChainMatcher object.
+        """
+        return CryptographyChainMatcher(criterium=criterium, module=self.module)
+
+    def get_cert_information(
+        self,
+        *,
+        cert_filename: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+    ) -> CertificateInformation:
+        """
+        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.
+        b_cert_content = to_bytes(extract_first_pem(to_text(cert_content)) or "")
+
+        try:
+            cert = cryptography.x509.load_pem_x509_certificate(b_cert_content)
+        except Exception as e:
+            if cert_filename is None:
+                raise BackendException(f"Cannot parse certificate: {e}") from e
+            raise BackendException(
+                f"Cannot parse certificate {cert_filename}: {e}"
+            ) from e
+
+        ski = None
+        try:
+            ext_ski = cert.extensions.get_extension_for_class(
+                cryptography.x509.SubjectKeyIdentifier
+            )
+            ski = ext_ski.value.digest
+        except cryptography.x509.ExtensionNotFound:
+            pass
+
+        aki = None
+        try:
+            ext_aki = cert.extensions.get_extension_for_class(
+                cryptography.x509.AuthorityKeyIdentifier
+            )
+            aki = ext_aki.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=cert.serial_number,
+            subject_key_identifier=ski,
+            authority_key_identifier=aki,
+        )
+
+
+__all__ = (
+    "CRYPTOGRAPHY_MINIMAL_VERSION",
+    "CRYPTOGRAPHY_ERROR",
+    "CRYPTOGRAPHY_VERSION",
+    "CRYPTOGRAPHY_ERROR",
+    "CryptographyBackend",
+)

plugins/module_utils/_acme/backend_openssl_cli.py

@@ -0,0 +1,625 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import base64
+import binascii
+import datetime
+import ipaddress
+import os
+import re
+import tempfile
+import traceback
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes, 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._crypto.math import (
+    convert_bytes_to_int,
+)
+from ansible_collections.community.crypto.plugins.module_utils._time import (
+    ensure_utc_timezone,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._acme.certificates import (
+        Criterium,
+    )
+
+
+_OPENSSL_ENVIRONMENT_UPDATE = {
+    "LANG": "C",
+    "LC_ALL": "C",
+    "LC_MESSAGES": "C",
+    "LC_CTYPE": "C",
+}
+
+
+def _extract_date(
+    out_text: str, *, name: str, cert_filename_suffix: str = ""
+) -> datetime.datetime:
+    matcher = re.search(rf"\s+{name}\s*:\s+(.*)", out_text)
+    if matcher is None:
+        raise BackendException(f"No '{name}' date found{cert_filename_suffix}")
+    date_str = matcher.group(1)
+    try:
+        # 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 ValueError as exc:
+        raise BackendException(
+            f"Failed to parse '{name}' date{cert_filename_suffix}: {exc}"
+        ) from exc
+
+
+def _decode_octets(octets_text: str) -> bytes:
+    return binascii.unhexlify(re.sub(r"(\s|:)", "", octets_text).encode("utf-8"))
+
+
+@t.overload
+def _extract_octets(
+    out_text: str,
+    *,
+    name: str,
+    required: t.Literal[False],
+    potential_prefixes: t.Iterable[str] | None = None,
+) -> bytes | None: ...
+
+
+@t.overload
+def _extract_octets(
+    out_text: str,
+    *,
+    name: str,
+    required: t.Literal[True],
+    potential_prefixes: t.Iterable[str] | None = None,
+) -> bytes: ...
+
+
+def _extract_octets(
+    out_text: str,
+    *,
+    name: str,
+    required: bool = True,
+    potential_prefixes: t.Iterable[str] | None = None,
+) -> bytes | None:
+    part = (
+        f"(?:{'|'.join(re.escape(pp) for pp in potential_prefixes)})"
+        if potential_prefixes
+        else ""
+    )
+    regexp = rf"\s+{name}:\s*\n\s+{part}([A-Fa-f0-9]{{2}}(?::[A-Fa-f0-9]{{2}})*)\s*\n"
+    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(f"No '{name}' octet string found")
+
+
+class OpenSSLCLIBackend(CryptoBackend):
+    def __init__(
+        self, *, module: AnsibleModule, openssl_binary: str | None = None
+    ) -> None:
+        super().__init__(module=module, with_timezone=True)
+        if openssl_binary is None:
+            openssl_binary = module.get_bin_path("openssl", True)
+        self.openssl_binary = openssl_binary
+
+    def parse_key(
+        self,
+        *,
+        key_file: str | os.PathLike | None = None,
+        key_content: str | None = None,
+        passphrase: str | None = None,
+    ) -> dict[str, t.Any]:
+        """
+        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 is not given, but key_content, write that to a temporary file
+        if key_file is None:
+            if key_content is None:
+                raise KeyParsingError(
+                    "one of key_file and key_content must be specified"
+                )
+            fd, tmpsrc = tempfile.mkstemp()
+            self.module.add_cleanup_file(tmpsrc)  # Ansible will delete the file on exit
+            f = os.fdopen(fd, "wb")
+            try:
+                f.write(key_content.encode("utf-8"))
+                key_file = tmpsrc
+            except Exception as err:
+                try:
+                    f.close()
+                except Exception:
+                    pass
+                raise KeyParsingError(
+                    f"failed to create temporary content file: {err}",
+                    exception=traceback.format_exc(),
+                ) from err
+            f.close()
+        # Parse key
+        account_key_type = None
+        with open(key_file, "r", encoding="utf-8") as fi:
+            for line in fi:
+                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
+        if account_key_type is None:
+            # This happens for example if openssl_privatekey created this key
+            # (as opposed to the OpenSSL binary). For now, we assume this is
+            # an RSA key.
+            # FIXME: add some kind of auto-detection
+            account_key_type = "rsa"
+        if account_key_type not in ("rsa", "ec"):
+            raise KeyParsingError(f'unknown key type "{account_key_type}"')
+
+        openssl_keydump_cmd = [
+            self.openssl_binary,
+            account_key_type,
+            "-in",
+            str(key_file),
+            "-noout",
+            "-text",
+        ]
+        rc, out, stderr = self.module.run_command(
+            openssl_keydump_cmd,
+            check_rc=False,
+            environ_update=_OPENSSL_ENVIRONMENT_UPDATE,
+        )
+        if rc != 0:
+            raise BackendException(
+                f"Error while running {' '.join(openssl_keydump_cmd)}: {stderr}"
+            )
+
+        out_text = to_text(out, errors="surrogate_or_strict")
+
+        if account_key_type == "rsa":
+            matcher = re.search(
+                r"modulus:\n\s+00:([a-f0-9\:\s]+?)\npublicExponent",
+                out_text,
+                re.MULTILINE | re.DOTALL,
+            )
+            if matcher is None:
+                raise KeyParsingError("cannot parse RSA key: modulus not found")
+            pub_hex = matcher.group(1)
+
+            matcher = re.search(
+                r"\npublicExponent: ([0-9]+)", out_text, re.MULTILINE | re.DOTALL
+            )
+            if matcher is None:
+                raise KeyParsingError("cannot parse RSA key: public exponent not found")
+            pub_exp = matcher.group(1)
+            pub_exp = f"{int(pub_exp):x}"
+            if len(pub_exp) % 2:
+                pub_exp = f"0{pub_exp}"
+
+            return {
+                "key_file": str(key_file),
+                "type": "rsa",
+                "alg": "RS256",
+                "jwk": {
+                    "kty": "RSA",
+                    "e": nopad_b64(binascii.unhexlify(pub_exp.encode("utf-8"))),
+                    "n": nopad_b64(_decode_octets(pub_hex)),
+                },
+                "hash": "sha256",
+            }
+        if account_key_type == "ec":
+            pub_data = re.search(
+                r"pub:\s*\n\s+04:([a-f0-9\:\s]+?)\nASN1 OID: (\S+)(?:\nNIST CURVE: (\S+))?",
+                out_text,
+                re.MULTILINE | re.DOTALL,
+            )
+            if pub_data is None:
+                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":
+                bits = 256
+                alg = "ES256"
+                hashalg = "sha256"
+                point_size = 32
+                curve = "P-256"
+            elif asn1_oid_curve == "secp384r1" or nist_curve == "p-384":
+                bits = 384
+                alg = "ES384"
+                hashalg = "sha384"
+                point_size = 48
+                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"
+                point_size = 66
+                curve = "P-521"
+            else:
+                raise KeyParsingError(
+                    f"unknown elliptic curve: {asn1_oid_curve} / {nist_curve}"
+                )
+            num_bytes = (bits + 7) // 8
+            if len(pub_hex) != 2 * num_bytes:
+                raise KeyParsingError(
+                    f"bad elliptic curve point ({asn1_oid_curve} / {nist_curve})"
+                )
+            return {
+                "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,
+            }
+        raise KeyParsingError(
+            f"Internal error: unexpected account_key_type = {account_key_type!r}"
+        )
+
+    def sign(
+        self, *, payload64: str, protected64: str, key_data: dict[str, t.Any]
+    ) -> dict[str, t.Any]:
+        sign_payload = f"{protected64}.{payload64}".encode("utf8")
+        if key_data["type"] == "hmac":
+            hex_key = (
+                binascii.hexlify(base64.urlsafe_b64decode(key_data["jwk"]["k"]))
+            ).decode("ascii")
+            cmd_postfix = [
+                "-mac",
+                "hmac",
+                "-macopt",
+                f"hexkey:{hex_key}",
+                "-binary",
+            ]
+        else:
+            cmd_postfix = ["-sign", key_data["key_file"]]
+        openssl_sign_cmd = [
+            self.openssl_binary,
+            "dgst",
+            f"-{key_data['hash']}",
+        ] + cmd_postfix
+
+        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(
+                f"Error while running {' '.join(openssl_sign_cmd)}: {err}"
+            )
+
+        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"]
+            sig = re.findall(
+                rf"prim:\s+INTEGER\s+:([0-9A-F]{{1,{expected_len}}})\n",
+                to_text(der_out, errors="surrogate_or_strict"),
+            )
+            if len(sig) != 2:
+                der_output = to_text(der_out, errors="surrogate_or_strict")
+                raise BackendException(
+                    f"failed to generate Elliptic Curve signature; cannot parse DER output: {der_output}"
+                )
+            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 {
+            "protected": protected64,
+            "payload": payload64,
+            "signature": nopad_b64(to_bytes(out)),
+        }
+
+    def create_mac_key(self, *, alg: str, key: str) -> dict[str, t.Any]:
+        """Create a MAC key."""
+        if alg == "HS256":
+            hashalg = "sha256"
+            hashbytes = 32
+        elif alg == "HS384":
+            hashalg = "sha384"
+            hashbytes = 48
+        elif alg == "HS512":
+            hashalg = "sha512"
+            hashbytes = 64
+        else:
+            raise BackendException(
+                f"Unsupported MAC key algorithm for OpenSSL backend: {alg}"
+            )
+        key_bytes = base64.urlsafe_b64decode(key)
+        if len(key_bytes) < hashbytes:
+            raise BackendException(
+                f"{alg} key must be at least {hashbytes} bytes long (after Base64 decoding)"
+            )
+        return {
+            "type": "hmac",
+            "alg": alg,
+            "jwk": {
+                "kty": "oct",
+                "k": key,
+            },
+            "hash": hashalg,
+        }
+
+    @staticmethod
+    def _normalize_ip(ip: str) -> str:
+        try:
+            return ipaddress.ip_address(ip).compressed
+        except ValueError:
+            # We do not want to error out on something IPAddress() cannot parse
+            return ip
+
+    def get_ordered_csr_identifiers(
+        self,
+        *,
+        csr_filename: str | os.PathLike | None = None,
+        csr_content: str | bytes | None = None,
+    ) -> list[tuple[str, str]]:
+        """
+        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 = to_bytes(csr_content)
+
+        openssl_csr_cmd = [
+            self.openssl_binary,
+            "req",
+            "-in",
+            str(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(
+                f"Error while running {' '.join(openssl_csr_cmd)}: {err}"
+            )
+
+        identifiers = set()
+        result = []
+
+        def add_identifier(identifier: tuple[str, str]) -> None:
+            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:
+            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,
+        )
+        if subject_alt_names is not None:
+            for san in subject_alt_names.group(1).split(", "):
+                if san.lower().startswith("dns:"):
+                    add_identifier(("dns", san[4:]))
+                elif san.lower().startswith("ip:"):
+                    add_identifier(("ip", self._normalize_ip(san[3:])))
+                elif san.lower().startswith("ip address:"):
+                    add_identifier(("ip", self._normalize_ip(san[11:])))
+                else:
+                    raise BackendException(f'Found unsupported SAN identifier "{san}"')
+        return result
+
+    def get_csr_identifiers(
+        self,
+        *,
+        csr_filename: str | os.PathLike | None = None,
+        csr_content: str | bytes | None = None,
+    ) -> set[tuple[str, str]]:
+        """
+        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: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+        now: datetime.datetime | None = None,
+    ) -> int:
+        """
+        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 = to_bytes(cert_content)
+            cert_filename_suffix = ""
+        elif cert_filename is not None:
+            if not os.path.exists(cert_filename):
+                return -1
+            cert_filename_suffix = f" in {cert_filename}"
+        else:
+            return -1
+
+        openssl_cert_cmd = [
+            self.openssl_binary,
+            "x509",
+            "-in",
+            str(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(
+                f"Error while running {' '.join(openssl_cert_cmd)}: {err}"
+            )
+
+        out_text = to_text(out, errors="surrogate_or_strict")
+        not_after = _extract_date(
+            out_text, name="Not After", cert_filename_suffix=cert_filename_suffix
+        )
+        if now is None:
+            now = self.get_now()
+        else:
+            now = ensure_utc_timezone(now)
+        return (not_after - now).days
+
+    def create_chain_matcher(self, *, criterium: Criterium) -> t.NoReturn:
+        """
+        Given a Criterium object, creates a ChainMatcher object.
+        """
+        raise BackendException(
+            'Alternate chain matching can only be used with the "cryptography" backend.'
+        )
+
+    def get_cert_information(
+        self,
+        *,
+        cert_filename: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+    ) -> CertificateInformation:
+        """
+        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 = f" in {cert_filename}"
+        else:
+            filename = "/dev/stdin"
+            data = to_bytes(cert_content)
+            cert_filename_suffix = ""
+
+        openssl_cert_cmd = [
+            self.openssl_binary,
+            "x509",
+            "-in",
+            str(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(
+                f"Error while running {' '.join(openssl_cert_cmd)}: {err}"
+            )
+
+        out_text = to_text(out, errors="surrogate_or_strict")
+
+        not_after = _extract_date(
+            out_text, name="Not After", cert_filename_suffix=cert_filename_suffix
+        )
+        not_before = _extract_date(
+            out_text, name="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, name="Serial Number", required=True)
+            )
+
+        ski = _extract_octets(
+            out_text, name="X509v3 Subject Key Identifier", required=False
+        )
+        aki = _extract_octets(
+            out_text,
+            name="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,
+        )
+
+
+__all__ = ("OpenSSLCLIBackend",)

plugins/module_utils/_acme/backends.py

@@ -0,0 +1,230 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import datetime
+import re
+import typing as t
+
+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,
+)
+
+
+if t.TYPE_CHECKING:
+    import os
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._acme.certificates import (
+        ChainMatcher,
+        Criterium,
+    )
+
+
+class CertificateInformation(t.NamedTuple):
+    not_valid_after: datetime.datetime
+    not_valid_before: datetime.datetime
+    serial_number: int
+    subject_key_identifier: bytes | None
+    authority_key_identifier: bytes | None
+
+
+_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: str) -> 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(f"Cannot parse ISO 8601 timestamp {timestamp_str!r}")
+    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 f"{timestamp}{fractional}{timezone}"
+
+
+def _parse_acme_timestamp(
+    timestamp_str: str, *, with_timezone: bool
+) -> datetime.datetime:
+    """
+    Parses a RFC 3339 timestamp.
+    """
+    # RFC 3339 (https://www.rfc-editor.org/info/rfc3339)
+    timestamp_str = _reduce_fractional_digits(timestamp_str)
+    for time_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",
+    ):
+        try:
+            result = datetime.datetime.strptime(timestamp_str, time_format)
+        except ValueError:
+            pass
+        else:
+            return (
+                ensure_utc_timezone(result)
+                if with_timezone
+                else remove_timezone(result)
+            )
+    raise BackendException(f"Cannot parse ISO 8601 timestamp {timestamp_str!r}")
+
+
+class CryptoBackend(metaclass=abc.ABCMeta):
+    def __init__(self, *, module: AnsibleModule, with_timezone: bool = False) -> None:
+        self.module = module
+        self._with_timezone = with_timezone
+
+    def get_now(self) -> datetime.datetime:
+        return get_now_datetime(with_timezone=self._with_timezone)
+
+    def parse_acme_timestamp(self, timestamp_str: str) -> datetime.datetime:
+        # 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: str, name: str) -> datetime.datetime:
+        try:
+            result = get_relative_time_option(
+                value, input_name=name, with_timezone=self._with_timezone
+            )
+            if result is None:
+                raise BackendException(f"Invalid value for {name}: {value!r}")
+            return result
+        except OpenSSLObjectError as exc:
+            raise BackendException(str(exc)) from exc
+
+    def interpolate_timestamp(
+        self,
+        timestamp_start: datetime.datetime,
+        timestamp_end: datetime.datetime,
+        *,
+        percentage: float,
+    ) -> datetime.datetime:
+        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) -> datetime.datetime:
+        kwargs_ext: dict[str, t.Any] = 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: str | os.PathLike | None = None,
+        key_content: str | None = None,
+        passphrase: str | None = None,
+    ) -> dict[str, t.Any]:
+        """
+        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: str, protected64: str, key_data: dict[str, t.Any]
+    ) -> dict[str, t.Any]:
+        pass
+
+    @abc.abstractmethod
+    def create_mac_key(self, *, alg: str, key: str) -> dict[str, t.Any]:
+        """Create a MAC key."""
+
+    @abc.abstractmethod
+    def get_ordered_csr_identifiers(
+        self,
+        *,
+        csr_filename: str | os.PathLike | None = None,
+        csr_content: str | bytes | None = None,
+    ) -> list[tuple[str, str]]:
+        """
+        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.
+        """
+
+    @abc.abstractmethod
+    def get_csr_identifiers(
+        self,
+        *,
+        csr_filename: str | os.PathLike | None = None,
+        csr_content: str | bytes | None = None,
+    ) -> set[tuple[str, str]]:
+        """
+        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: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+        now: datetime.datetime | None = None,
+    ) -> int:
+        """
+        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: Criterium) -> ChainMatcher:
+        """
+        Given a Criterium object, creates a ChainMatcher object.
+        """
+
+    @abc.abstractmethod
+    def get_cert_information(
+        self,
+        *,
+        cert_filename: str | os.PathLike | None = None,
+        cert_content: str | bytes | None = None,
+    ) -> CertificateInformation:
+        """
+        Return some information on a X.509 certificate as a CertificateInformation object.
+        """
+
+
+__all__ = ("CertificateInformation", "CryptoBackend")

plugins/module_utils/_acme/certificate.py

@@ -0,0 +1,419 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import os
+import typing as t
+
+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,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._acme.backends import (
+        CryptoBackend,
+    )
+    from ansible_collections.community.crypto.plugins.module_utils._acme.certificates import (
+        ChainMatcher,
+    )
+    from ansible_collections.community.crypto.plugins.module_utils._acme.challenges import (
+        Challenge,
+    )
+
+
+class ACMECertificateClient:
+    """
+    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: AnsibleModule,
+        backend: CryptoBackend,
+        client: ACMEClient | None = None,
+        account: ACMEAccount | None = None,
+    ) -> 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=module, backend=backend)
+        self.client = client
+        if account is None:
+            account = ACMEAccount(client=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(f"CSR {self.csr} not found")
+
+        # Extract list of identifiers from CSR
+        if self.csr is not None or self.csr_content is not None:
+            self.identifiers: list[tuple[str, str]] | None = (
+                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: list[dict[str, t.Any]] | None
+    ) -> list[ChainMatcher]:
+        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(
+                                criterium=criterium, index=criterium_idx
+                            )
+                        )
+                    )
+                except ValueError as exc:
+                    self.module.warn(
+                        f"Error while parsing criterium: {exc}. Ignoring criterium."
+                    )
+        return select_chain_matcher
+
+    def load_order(self) -> Order:
+        if not self.order_uri:
+            raise ModuleFailException("The order URI has not been provided")
+        order = Order.from_url(client=self.client, url=self.order_uri)
+        order.load_authorizations(client=self.client)
+        return order
+
+    def create_order(
+        self, *, replaces_cert_id: str | None = None, profile: str | None = None
+    ) -> Order:
+        """
+        Create a new order.
+        """
+        if self.identifiers is None:
+            raise ModuleFailException("No identifiers have been provided")
+        order = Order.create_with_error_handling(
+            client=self.client,
+            identifiers=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(client=self.client)
+        return order
+
+    def get_challenges_data(
+        self, order: Order
+    ) -> tuple[list[dict[str, t.Any]], dict[str, list[str]]]:
+        """
+        Get challenge details.
+
+        Return a tuple of generic challenge details, and specialized DNS challenge details.
+        """
+        data: list[dict[str, t.Any]] = []
+        data_dns: dict[str, list[str]] = {}
+        dns_challenge_type = "dns-01"
+        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
+            challenge_data = authz.get_challenge_data(client=self.client)
+            data.append(
+                {
+                    "identifier": authz.identifier,
+                    "identifier_type": authz.identifier_type,
+                    "challenges": challenge_data,
+                }
+            )
+            dns_challenge = challenge_data.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: Order) -> None:
+        bad_authzs = []
+        for authz in order.authorizations.values():
+            if authz.status not in ("valid", "pending"):
+                bad_authzs.append(
+                    f"{authz.combined_identifier} (status={authz.status!r})"
+                )
+        if bad_authzs:
+            bad_authzs_str = ", ".join(sorted(bad_authzs))
+            raise ModuleFailException(
+                "Some of the authorizations for the order are in a bad state, so the order"
+                f" can no longer be satisfied: {bad_authzs_str}",
+            )
+
+    def collect_invalid_authzs(self, order: Order) -> list[Authorization]:
+        return [
+            authz
+            for authz in order.authorizations.values()
+            if authz.status == "invalid"
+        ]
+
+    def collect_pending_authzs(self, order: Order) -> list[Authorization]:
+        return [
+            authz
+            for authz in order.authorizations.values()
+            if authz.status == "pending"
+        ]
+
+    def call_validate(
+        self,
+        pending_authzs: list[Authorization],
+        *,
+        get_challenge: t.Callable[[Authorization], str],
+        wait: bool = True,
+    ) -> list[tuple[Authorization, str, Challenge | None]]:
+        authzs_with_challenges_to_wait_for = []
+        for authz in pending_authzs:
+            challenge_type = get_challenge(authz)
+            authz.call_validate(
+                client=self.client, challenge_type=challenge_type, wait=wait
+            )
+            authzs_with_challenges_to_wait_for.append(
+                (
+                    authz,
+                    challenge_type,
+                    authz.find_challenge(challenge_type=challenge_type),
+                )
+            )
+        return authzs_with_challenges_to_wait_for
+
+    def wait_for_validation(self, authzs_to_wait_for: list[Authorization]) -> None:
+        wait_for_validation(authzs=authzs_to_wait_for, client=self.client)
+
+    def _download_alternate_chains(
+        self, cert: CertificateChain
+    ) -> list[CertificateChain]:
+        alternate_chains = []
+        for alternate in cert.alternates:
+            try:
+                alt_cert = CertificateChain.download(client=self.client, url=alternate)
+            except ModuleFailException as e:
+                self.module.warn(
+                    f"Error while downloading alternative certificate {alternate}: {e}"
+                )
+                continue
+            if alt_cert.cert is not None:
+                alternate_chains.append(alt_cert)
+            else:
+                self.module.warn(
+                    f"Error while downloading alternative certificate {alternate}: no certificate found"
+                )
+        return alternate_chains
+
+    @t.overload
+    def download_certificate(
+        self, order: Order, *, download_all_chains: t.Literal[True] = True
+    ) -> tuple[CertificateChain, list[CertificateChain]]: ...
+
+    @t.overload
+    def download_certificate(
+        self, order: Order, *, download_all_chains: t.Literal[False]
+    ) -> tuple[CertificateChain, None]: ...
+
+    @t.overload
+    def download_certificate(
+        self, order: Order, *, download_all_chains: bool = True
+    ) -> tuple[CertificateChain, list[CertificateChain] | None]: ...
+
+    def download_certificate(
+        self, order: Order, *, download_all_chains: bool = True
+    ) -> tuple[CertificateChain, list[CertificateChain] | None]:
+        """
+        Download certificate from a valid oder.
+        """
+        if order.status != "valid":
+            raise ModuleFailException(
+                f"The order must be valid, but has state {order.status!r}!"
+            )
+
+        if not order.certificate_uri:
+            raise ModuleFailException(
+                f"Order's crtificate URL {order.certificate_uri!r} is empty!"
+            )
+
+        cert = CertificateChain.download(client=self.client, url=order.certificate_uri)
+        if cert.cert is None:
+            raise ModuleFailException(
+                f"Certificate at {order.certificate_uri} is empty!"
+            )
+
+        alternate_chains = None
+        if download_all_chains:
+            alternate_chains = self._download_alternate_chains(cert)
+
+        return cert, alternate_chains
+
+    @t.overload
+    def get_certificate(
+        self, order: Order, *, download_all_chains: t.Literal[True] = True
+    ) -> tuple[CertificateChain, list[CertificateChain] | None]: ...
+
+    @t.overload
+    def get_certificate(
+        self, order: Order, *, download_all_chains: t.Literal[False]
+    ) -> tuple[CertificateChain, list[CertificateChain] | None]: ...
+
+    @t.overload
+    def get_certificate(
+        self, order: Order, *, download_all_chains: bool = True
+    ) -> tuple[CertificateChain, list[CertificateChain] | None]: ...
+
+    def get_certificate(
+        self, order: Order, *, download_all_chains: bool = True
+    ) -> tuple[CertificateChain, list[CertificateChain] | None]:
+        """
+        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 authz in order.authorizations.values():
+            if authz.status != "valid":
+                authz.raise_error(
+                    error_msg=f'Status is {authz.status!r} and not "valid"',
+                    module=self.module,
+                )
+
+        order.finalize(
+            client=self.client,
+            csr_der=pem_to_der(pem_filename=self.csr, pem_content=self.csr_content),
+        )
+
+        return self.download_certificate(order, download_all_chains=download_all_chains)
+
+    def find_matching_chain(
+        self,
+        *,
+        chains: list[CertificateChain],
+        select_chain_matcher: t.Iterable[ChainMatcher],
+    ) -> CertificateChain | None:
+        for criterium_idx, matcher in enumerate(select_chain_matcher):
+            for chain in chains:
+                if matcher.match(certificate=chain):
+                    self.module.debug(
+                        f"Found matching chain for criterium {criterium_idx}"
+                    )
+                    return chain
+        return None
+
+    def write_cert_chain(
+        self,
+        *,
+        cert: CertificateChain,
+        cert_dest: str | os.PathLike | None = None,
+        fullchain_dest: str | os.PathLike | None = None,
+        chain_dest: str | os.PathLike | None = None,
+    ) -> bool:
+        changed = False
+        if cert.cert is None:
+            raise ValueError("Certificate is not present")
+
+        if cert_dest and write_file(
+            module=self.module, dest=cert_dest, content=cert.cert.encode("utf8")
+        ):
+            changed = True
+
+        if fullchain_dest and write_file(
+            module=self.module,
+            dest=fullchain_dest,
+            content=(cert.cert + "\n".join(cert.chain)).encode("utf8"),
+        ):
+            changed = True
+
+        if chain_dest and write_file(
+            module=self.module,
+            dest=chain_dest,
+            content=("\n".join(cert.chain)).encode("utf8"),
+        ):
+            changed = True
+
+        return changed
+
+    def deactivate_authzs(self, order: Order) -> None:
+        """
+        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(
+                        client=self.client, url=authz_uri
+                    )
+                except Exception:
+                    # ignore errors
+                    pass
+                if authz is None or authz.status != "deactivated":
+                    self.module.warn(
+                        warning=f"Could not deactivate authz object {authz_uri}."
+                    )
+        else:
+            for authz in order.authorizations.values():
+                try:
+                    authz.deactivate(client=self.client)
+                except Exception:
+                    # ignore errors
+                    pass
+                if authz.status != "deactivated":
+                    self.module.warn(
+                        warning=f"Could not deactivate authz object {authz.url}."
+                    )
+
+
+__all__ = ("ACMECertificateClient",)

plugins/module_utils/_acme/certificates.py

@@ -0,0 +1,132 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import typing as t
+
+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,
+    process_links,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.pem import (
+    split_pem_list,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible_collections.community.crypto.plugins.module_utils._acme.acme import (
+        ACMEClient,
+    )
+
+
+_CertificateChain = t.TypeVar("_CertificateChain", bound="CertificateChain")
+
+
+class CertificateChain:
+    """
+    Download and parse the certificate chain.
+    https://tools.ietf.org/html/rfc8555#section-7.4.2
+    """
+
+    def __init__(self, url: str):
+        self.url = url
+        self.cert: str | None = None
+        self.chain: list[str] = []
+        self.alternates: list[str] = []
+
+    @classmethod
+    def download(
+        cls: t.Type[_CertificateChain], *, client: ACMEClient, url: str
+    ) -> _CertificateChain:
+        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"
+        ):
+            raise ModuleFailException(
+                f"Cannot download certificate chain from {url}, as content type is not application/pem-certificate-chain: {content!r} (headers: {info})"
+            )
+
+        result = cls(url)
+
+        # Parse data
+        certs = split_pem_list(content.decode("utf-8"), keep_inbetween=True)
+        if certs:
+            result.cert = certs[0]
+            result.chain = certs[1:]
+
+        process_links(
+            info=info,
+            callback=lambda link, relation: result._process_links(  # pylint: disable=protected-access
+                client=client, link=link, relation=relation
+            ),
+        )
+
+        if result.cert is None:
+            raise ModuleFailException(
+                f"Failed to parse certificate chain download from {url}: {content!r} (headers: {info})"
+            )
+
+        return result
+
+    def _process_links(self, *, client: ACMEClient, link: str, relation: str) -> None:
+        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]:
+                    self.chain.append(der_to_pem(chain_result))
+        elif relation == "alternate":
+            self.alternates.append(link)
+
+    def to_json(self) -> dict[str, bytes]:
+        if self.cert is None:
+            raise ValueError("Has no certificate")
+        cert = self.cert.encode("utf8")
+        chain = ("\n".join(self.chain)).encode("utf8")
+        return {
+            "cert": cert,
+            "chain": chain,
+            "full_chain": cert + chain,
+        }
+
+
+class Criterium:
+    def __init__(self, *, criterium: dict[str, t.Any], index: int):
+        self.index = index
+        self.test_certificates: t.Literal["first", "last", "all"] = criterium[
+            "test_certificates"
+        ]
+        self.subject: dict[str, t.Any] | None = criterium["subject"]
+        self.issuer: dict[str, t.Any] | None = criterium["issuer"]
+        self.subject_key_identifier: str | None = criterium["subject_key_identifier"]
+        self.authority_key_identifier: str | None = criterium[
+            "authority_key_identifier"
+        ]
+
+
+class ChainMatcher(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def match(self, *, certificate: CertificateChain) -> bool:
+        """
+        Check whether a certificate chain (CertificateChain instance) matches.
+        """
+
+
+__all__ = ("CertificateChain", "Criterium", "ChainMatcher")

plugins/module_utils/_acme/challenges.py

@@ -0,0 +1,414 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import ipaddress
+import json
+import re
+import time
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes
+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,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._acme.acme import (
+        ACMEClient,
+    )
+
+
+def create_key_authorization(*, client: ACMEClient, token: str) -> str:
+    """
+    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())
+    return f"{token}.{thumbprint}"
+
+
+def combine_identifier(*, identifier_type: str, identifier: str) -> str:
+    return f"{identifier_type}:{identifier}"
+
+
+def normalize_combined_identifier(identifier: str) -> str:
+    identifier_type, identifier = split_identifier(identifier)
+    # Normalize DNS names and IPs
+    identifier = identifier.lower()
+    return combine_identifier(identifier_type=identifier_type, identifier=identifier)
+
+
+def split_identifier(identifier: str) -> tuple[str, str]:
+    parts = identifier.split(":", 1)
+    if len(parts) != 2:
+        raise ModuleFailException(
+            f'Identifier "{identifier}" is not of the form <type>:<identifier>'
+        )
+    return parts[0], parts[1]
+
+
+_Challenge = t.TypeVar("_Challenge", bound="Challenge")
+
+
+class Challenge:
+    def __init__(self, *, data: dict[str, t.Any], url: str) -> None:
+        self.data = data
+
+        self.type: str = data["type"]
+        self.url = url
+        self.status: str = data["status"]
+        self.token: str | None = data.get("token")
+
+    @classmethod
+    def from_json(
+        cls: t.Type[_Challenge],
+        *,
+        client: ACMEClient,
+        data: dict[str, t.Any],
+        url: str | None = None,
+    ) -> _Challenge:
+        return cls(data=data, url=url or data["url"])
+
+    def call_validate(self, client: ACMEClient) -> None:
+        challenge_response: dict[str, t.Any] = {}
+        client.send_signed_request(
+            self.url,
+            challenge_response,
+            error_msg="Failed to validate challenge",
+            expected_status_codes=[200, 202],
+        )
+
+    def to_json(self) -> dict[str, t.Any]:
+        return self.data.copy()
+
+    def get_validation_data(
+        self, *, client: ACMEClient, identifier_type: str, identifier: str
+    ) -> dict[str, t.Any] | None:
+        if self.token is None:
+            return None
+
+        token = re.sub(r"[^A-Za-z0-9_\-]", "_", self.token)
+        key_authorization = create_key_authorization(client=client, token=token)
+
+        if self.type == "http-01":
+            # https://tools.ietf.org/html/rfc8555#section-8.3
+            return {
+                "resource": f".well-known/acme-challenge/{token}",
+                "resource_value": key_authorization,
+            }
+
+        if self.type == "dns-01":
+            if identifier_type != "dns":
+                return None
+            # https://tools.ietf.org/html/rfc8555#section-8.4
+            resource = "_acme-challenge"
+            value = nopad_b64(hashlib.sha256(to_bytes(key_authorization)).digest())
+            record = f"{resource}.{identifier[2:] if identifier.startswith('*.') else identifier}"
+            return {
+                "resource": resource,
+                "resource_value": value,
+                "record": record,
+            }
+
+        if self.type == "tls-alpn-01":
+            # https://www.rfc-editor.org/rfc/rfc8737.html#section-3
+            if identifier_type == "ip":
+                # IPv4/IPv6 address: use reverse mapping (RFC1034, RFC3596)
+                resource = ipaddress.ip_address(identifier).reverse_pointer
+                if not resource.endswith("."):
+                    resource += "."
+            else:
+                resource = identifier
+            b_value = base64.b64encode(
+                hashlib.sha256(to_bytes(key_authorization)).digest()
+            )
+            return {
+                "resource": resource,
+                "resource_original": combine_identifier(
+                    identifier_type=identifier_type, identifier=identifier
+                ),
+                "resource_value": b_value,
+            }
+
+        # Unknown challenge type: ignore
+        return None
+
+
+_Authorization = t.TypeVar("_Authorization", bound="Authorization")
+
+
+class Authorization:
+    def __init__(self, *, url: str) -> None:
+        self.url = url
+
+        self.data: dict[str, t.Any] | None = None
+        self.challenges: list[Challenge] = []
+        self.status: str | None = None
+        self.identifier_type: str | None = None
+        self.identifier: str | None = None
+
+    def _setup(self, *, client: ACMEClient, data: dict[str, t.Any]) -> None:
+        data["uri"] = self.url
+        self.data = 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=client, data=challenge)
+                for challenge in data["challenges"]
+            ]
+        else:
+            self.challenges = []
+        self.status = data["status"]
+        self.identifier = data["identifier"]["value"]
+        self.identifier_type = data["identifier"]["type"]
+        if data.get("wildcard", False):
+            self.identifier = f"*.{self.identifier}"
+
+    @classmethod
+    def from_json(
+        cls: t.Type[_Authorization],
+        *,
+        client: ACMEClient,
+        data: dict[str, t.Any],
+        url: str,
+    ) -> _Authorization:
+        result = cls(url=url)
+        result._setup(client=client, data=data)
+        return result
+
+    @classmethod
+    def from_url(
+        cls: t.Type[_Authorization], *, client: ACMEClient, url: str
+    ) -> _Authorization:
+        result = cls(url=url)
+        result.refresh(client=client)
+        return result
+
+    @classmethod
+    def create(
+        cls: t.Type[_Authorization],
+        *,
+        client: ACMEClient,
+        identifier_type: str,
+        identifier: str,
+    ) -> _Authorization:
+        """
+        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,
+                "value": identifier,
+            },
+        }
+        if "newAuthz" not in client.directory.directory:
+            raise ACMEProtocolException(
+                module=client.module,
+                msg="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=client, data=result, url=info["location"])
+
+    @property
+    def combined_identifier(self) -> str:
+        if self.identifier_type is None or self.identifier is None:
+            raise ValueError("Data not present")
+        return combine_identifier(
+            identifier_type=self.identifier_type, identifier=self.identifier
+        )
+
+    def to_json(self) -> dict[str, t.Any]:
+        if self.data is None:
+            raise ValueError("Data not present")
+        return self.data.copy()
+
+    def refresh(self, *, client: ACMEClient) -> bool:
+        result, dummy = client.get_request(self.url)
+        changed = self.data != result
+        self._setup(client=client, data=result)
+        return changed
+
+    def get_challenge_data(self, *, client: ACMEClient) -> dict[str, t.Any]:
+        """
+        Returns a dict with the data for all proposed (and supported) challenges
+        of the given authorization.
+        """
+        if self.identifier_type is None or self.identifier is None:
+            raise ValueError("Data not present")
+        data = {}
+        for challenge in self.challenges:
+            validation_data = challenge.get_validation_data(
+                client=client,
+                identifier_type=self.identifier_type,
+                identifier=self.identifier,
+            )
+            if validation_data is not None:
+                data[challenge.type] = validation_data
+        return data
+
+    def raise_error(self, *, error_msg: str, module: AnsibleModule) -> t.NoReturn:
+        """
+        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 = f"Challenge {challenge.type}"
+                if "error" in challenge.data:
+                    problem = format_error_problem(
+                        challenge.data["error"],
+                        subproblem_prefix=f"{challenge.type}.",
+                    )
+                    msg = f"{msg}: {problem}"
+                error_details.append(msg)
+        raise ACMEProtocolException(
+            module=module,
+            msg=f"Failed to validate challenge for {self.combined_identifier}: {error_msg}. {'; '.join(error_details)}",
+            extras={
+                "identifier": self.combined_identifier,
+                "authorization": self.data,
+            },
+        )
+
+    def find_challenge(self, *, challenge_type: str) -> Challenge | None:
+        for challenge in self.challenges:
+            if challenge_type == challenge.type:
+                return challenge
+        return None
+
+    def wait_for_validation(self, *, client: ACMEClient) -> bool:
+        while True:
+            self.refresh(client=client)
+            if self.status in ["valid", "invalid", "revoked"]:
+                break
+            time.sleep(2)
+
+        if self.status == "invalid":
+            self.raise_error(error_msg='Status is "invalid"', module=client.module)
+
+        return self.status == "valid"
+
+    def call_validate(
+        self, *, client: ACMEClient, challenge_type: str, wait: bool = True
+    ) -> bool:
+        """
+        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=challenge_type)
+        if challenge is None:
+            raise ModuleFailException(
+                f'Found no challenge of type "{challenge_type}" for identifier {self.combined_identifier}!'
+            )
+
+        challenge.call_validate(client)
+
+        if not wait:
+            return self.status == "valid"
+        return self.wait_for_validation(client=client)
+
+    def can_deactivate(self) -> bool:
+        """
+        Deactivates this authorization.
+        https://community.letsencrypt.org/t/authorization-deactivation/19860/2
+        https://tools.ietf.org/html/rfc8555#section-7.5.2
+        """
+        return self.status in ("valid", "pending")
+
+    def deactivate(self, *, client: ACMEClient) -> bool | None:
+        """
+        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 None
+        authz_deactivate = {"status": "deactivated"}
+        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: t.Type[_Authorization], *, client: ACMEClient, url: str
+    ) -> _Authorization:
+        """
+        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=url)
+        authz_deactivate = {"status": "deactivated"}
+        result, _info = client.send_signed_request(
+            url, authz_deactivate, fail_on_error=True
+        )
+        authz._setup(client=client, data=result)
+        return authz
+
+
+def wait_for_validation(
+    *, authzs: t.Iterable[Authorization], client: ACMEClient
+) -> None:
+    """
+    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=client)
+            if authz.status in ["valid", "invalid", "revoked"]:
+                if authz.status != "valid":
+                    authz.raise_error(
+                        error_msg='Status is not "valid"', module=client.module
+                    )
+            else:
+                authzs_next.append(authz)
+        if authzs_next:
+            time.sleep(2)
+        authzs = authzs_next
+
+
+__all__ = (
+    "create_key_authorization",
+    "combine_identifier",
+    "normalize_combined_identifier",
+    "split_identifier",
+    "Challenge",
+    "Authorization",
+    "wait_for_validation",
+)

plugins/module_utils/_acme/errors.py

@@ -0,0 +1,184 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+from http.client import responses as http_responses
+
+from ansible.module_utils.common.text.converters import to_text
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+
+
+def format_http_status(status_code: int) -> str:
+    expl = http_responses.get(status_code)
+    if not expl:
+        return str(status_code)
+    return f"{status_code} {expl}"
+
+
+def format_error_problem(
+    problem: dict[str, t.Any], *, subproblem_prefix: str = ""
+) -> str:
+    error_type = problem.get(
+        "type", "about:blank"
+    )  # https://www.rfc-editor.org/rfc/rfc7807#section-3.1
+    if "title" in problem:
+        msg = f'Error "{problem["title"]}" ({error_type})'
+    else:
+        msg = f"Error {error_type}"
+    if "detail" in problem:
+        msg += f': "{problem["detail"]}"'
+    subproblems = problem.get("subproblems")
+    if subproblems is not None:
+        msg = f"{msg} Subproblems:"
+        for index, subproblem in enumerate(subproblems):
+            index_str = f"{subproblem_prefix}{index}"
+            subproblem_str = format_error_problem(
+                subproblem, subproblem_prefix=f"{index_str}."
+            )
+            msg = f"{msg}\n({index_str}) {subproblem_str}"
+    return msg
+
+
+class ModuleFailException(Exception):
+    """
+    If raised, module.fail_json() will be called with the given parameters after cleanup.
+    """
+
+    def __init__(self, msg: str, **args: t.Any) -> None:
+        super().__init__(self, msg)
+        self.msg = msg
+        self.module_fail_args = args
+
+    def do_fail(self, *, module: AnsibleModule, **arguments) -> t.NoReturn:
+        module.fail_json(msg=self.msg, other=self.module_fail_args, **arguments)
+
+
+class ACMEProtocolException(ModuleFailException):
+    def __init__(
+        self,
+        *,
+        module: AnsibleModule,
+        msg: str | None = None,
+        info: dict[str, t.Any] | None = None,
+        response=None,
+        content: bytes | None = None,
+        content_json: dict[str, t.Any] | None = None,
+        extras: dict[str, t.Any] | None = 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 response.closed:
+                    raise TypeError
+                content = response.read()
+            except (AttributeError, TypeError):
+                if info is not None:
+                    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):
+            if content is None and isinstance(content_json, bytes):
+                content = content_json
+            content_json = None
+
+        # Try to get hold of JSON decoded content, when content is given and JSON not provided
+        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:
+                pass
+
+        extras = extras or {}
+        error_code = None
+        error_type = None
+
+        if msg is None:
+            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
+            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 = f"status {content_json['status']} (HTTP status: {format_http_status(code)})"
+                else:
+                    code_msg = f"status {format_http_status(code)}"
+                    if code == -1 and info.get("msg"):
+                        code_msg = f"error: {info['msg']}"
+                subproblems = content_json.pop("subproblems", None)
+                add_msg = f" {format_error_problem(content_json)}."
+                extras["problem"] = content_json
+                extras["subproblems"] = subproblems or []
+                if subproblems is not None:
+                    add_msg = f"{add_msg} Subproblems:"
+                    for index, problem in enumerate(subproblems):
+                        problem = format_error_problem(
+                            problem, subproblem_prefix=f"{index}."
+                        )
+                        add_msg = f"{add_msg}\n({index}) {problem}."
+            else:
+                code_msg = f"HTTP status {format_http_status(code)}"
+                if code == -1 and info.get("msg"):
+                    code_msg = f"error: {info['msg']}"
+                if content_json is not None:
+                    add_msg = f" The JSON error result: {content_json}"
+                elif content is not None:
+                    add_msg = f" The raw error result: {to_text(content)}"
+            msg = f"{msg} for {url} with {code_msg}"
+        elif content_json is not None:
+            add_msg = f" The JSON result: {content_json}"
+        elif content is not None:
+            add_msg = f" The raw result: {to_text(content)}"
+
+        super().__init__(f"{msg}.{add_msg}", **extras)
+        self.problem: dict[str, t.Any] = {}
+        self.subproblems: list[dict[str, t.Any]] = []
+        self.error_code = error_code
+        self.error_type = error_type
+        for k, v in extras.items():
+            setattr(self, k, v)
+
+
+class BackendException(ModuleFailException):
+    pass
+
+
+class NetworkException(ModuleFailException):
+    pass
+
+
+class KeyParsingError(ModuleFailException):
+    pass
+
+
+__all__ = (
+    "format_http_status",
+    "format_error_problem",
+    "ModuleFailException",
+    "ACMEProtocolException",
+    "BackendException",
+    "NetworkException",
+    "KeyParsingError",
+)

plugins/module_utils/_acme/io.py

@@ -1,52 +1,61 @@
-# -*- 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 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
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
-__metaclass__ = type
+# Do not use this from other collections or standalone plugins/modules!
 
+from __future__ import annotations
 
 import os
 import shutil
 import tempfile
 import traceback
+import typing as t
 
-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'):
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+
+
+def read_file(fn: str | os.PathLike) -> bytes:
     try:
-        with open(fn, 'r' + mode) as f:
+        with open(fn, "rb") as f:
             return f.read()
     except Exception as e:
-        raise ModuleFailException('Error while reading file "{0}": {1}'.format(fn, e))
+        raise ModuleFailException(f'Error while reading file "{fn}": {e}') from e
 
 
 # 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):
+def write_file(
-    '''
+    *, module: AnsibleModule, dest: str | os.PathLike, content: bytes
+) -> bool:
+    """
     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(
+            f"failed to create temporary content file: {err}",
+            exception=traceback.format_exc(),
+        ) from err
     f.close()
     checksum_src = None
     checksum_dest = None
@@ -54,34 +63,40 @@ 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))
+        raise ModuleFailException(f"Source {tmpsrc} does not exist")
     if not os.access(tmpsrc, os.R_OK):
         os.remove(tmpsrc)
-        raise ModuleFailException("Source %s not readable" % (tmpsrc))
+        raise ModuleFailException(f"Source {tmpsrc} not readable")
     checksum_src = module.sha1(tmpsrc)
     # check if there is no dest file
     if os.path.exists(dest):
         # raise an error if copy has no permission on dest
         if not os.access(dest, os.W_OK):
             os.remove(tmpsrc)
-            raise ModuleFailException("Destination %s not writable" % (dest))
+            raise ModuleFailException(f"Destination {dest} not writable")
         if not os.access(dest, os.R_OK):
             os.remove(tmpsrc)
-            raise ModuleFailException("Destination %s not readable" % (dest))
+            raise ModuleFailException(f"Destination {dest} not readable")
         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))
+            raise ModuleFailException(f"Destination dir {dirname} not writable")
     if checksum_src != checksum_dest:
         try:
             shutil.copyfile(tmpsrc, dest)
             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(
+                f"failed to copy {tmpsrc} to {dest}: {err}",
+                exception=traceback.format_exc(),
+            ) from err
     os.remove(tmpsrc)
     return changed
+
+
+__all__ = ("read_file", "write_file")

plugins/module_utils/_acme/orders.py

@@ -0,0 +1,231 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import time
+import typing as t
+
+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,
+    ModuleFailException,
+)
+from ansible_collections.community.crypto.plugins.module_utils._acme.utils import (
+    nopad_b64,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible_collections.community.crypto.plugins.module_utils._acme.acme import (
+        ACMEClient,
+    )
+
+
+_Order = t.TypeVar("_Order", bound="Order")
+
+
+class Order:
+    def __init__(self, *, url: str) -> None:
+        self.url = url
+
+        self.data: dict[str, t.Any] | None = None
+
+        self.status = None
+        self.identifiers: list[tuple[str, str]] = []
+        self.replaces_cert_id = None
+        self.finalize_uri = None
+        self.certificate_uri = None
+        self.authorization_uris: list[str] = []
+        self.authorizations: dict[str, Authorization] = {}
+
+    def _setup(self, *, client: ACMEClient, data: dict[str, t.Any]) -> None:
+        self.data = data
+
+        self.status = data["status"]
+        self.identifiers = []
+        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 = {}
+
+    @classmethod
+    def from_json(
+        cls: t.Type[_Order], *, client: ACMEClient, data: dict[str, t.Any], url: str
+    ) -> _Order:
+        result = cls(url=url)
+        result._setup(client=client, data=data)
+        return result
+
+    @classmethod
+    def from_url(cls: t.Type[_Order], *, client: ACMEClient, url: str) -> _Order:
+        result = cls(url=url)
+        result.refresh(client=client)
+        return result
+
+    @classmethod
+    def create(
+        cls: t.Type[_Order],
+        *,
+        client: ACMEClient,
+        identifiers: list[tuple[str, str]],
+        replaces_cert_id: str | None = None,
+        profile: str | None = None,
+    ) -> _Order:
+        """
+        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: dict[str, t.Any] = {"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=client, data=result, url=info["location"])
+
+    @classmethod
+    def create_with_error_handling(
+        cls: t.Type[_Order],
+        *,
+        client: ACMEClient,
+        identifiers: list[tuple[str, str]],
+        error_strategy: t.Literal[
+            "auto", "fail", "always", "retry_without_replaces_cert_id"
+        ] = "auto",
+        error_max_retries: int = 3,
+        replaces_cert_id: str | None = None,
+        profile: str | None = None,
+        message_callback: t.Callable[[str], None] | None = None,
+    ) -> _Order:
+        """
+        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=client,
+                    identifiers=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(
+                                f"Stop passing `replaces={replaces_cert_id}` due to error {exc.error_code} {exc.error_type} when creating ACME order"
+                            )
+                        replaces_cert_id = None
+                        continue
+
+                raise
+
+    def refresh(self, *, client: ACMEClient) -> bool:
+        result, dummy = client.get_request(self.url)
+        changed = self.data != result
+        self._setup(client=client, data=result)
+        return changed
+
+    def load_authorizations(self, *, client: ACMEClient) -> None:
+        for auth_uri in self.authorization_uris:
+            authz = Authorization.from_url(client=client, url=auth_uri)
+            self.authorizations[
+                normalize_combined_identifier(authz.combined_identifier)
+            ] = authz
+
+    def wait_for_finalization(self, *, client: ACMEClient) -> None:
+        while True:
+            self.refresh(client=client)
+            if self.status in ["valid", "invalid", "pending", "ready"]:
+                break
+            time.sleep(2)
+
+        if self.status != "valid":
+            raise ACMEProtocolException(
+                module=client.module,
+                msg=f'Failed to wait for order to complete; got status "{self.status}"',
+                content_json=self.data,
+            )
+
+    def finalize(
+        self, *, client: ACMEClient, csr_der: bytes, wait: bool = True
+    ) -> None:
+        """
+        Create a new certificate based on the csr.
+        Return the certificate object as dict
+        https://tools.ietf.org/html/rfc8555#section-7.4
+        """
+        if self.finalize_uri is None:
+            raise ModuleFailException("finalize_uri must be set")
+        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],
+        )
+        # 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.
+
+        if wait:
+            self.wait_for_finalization(client=client)
+        else:
+            self.refresh(client=client)
+            if self.status not in ["procesing", "valid", "invalid"]:
+                raise ACMEProtocolException(
+                    module=client.module,
+                    msg=f'Failed to finalize order; got status "{self.status}"',
+                    info=info,
+                    content_json=result,
+                )
+
+
+__all__ = ("Order",)

plugins/module_utils/_acme/utils.py

@@ -0,0 +1,173 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import base64
+import datetime
+import os
+import re
+import textwrap
+import traceback
+import typing as t
+from urllib.parse import unquote
+
+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,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible_collections.community.crypto.plugins.module_utils._acme.backends import (
+        CertificateInformation,
+        CryptoBackend,
+    )
+
+
+def nopad_b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("utf8").replace("=", "")
+
+
+def der_to_pem(der_cert: bytes) -> str:
+    """
+    Convert the DER format certificate in der_cert to a PEM format certificate and return it.
+    """
+    content = "\n".join(textwrap.wrap(base64.b64encode(der_cert).decode("utf8"), 64))
+    return f"-----BEGIN CERTIFICATE-----\n{content}\n-----END CERTIFICATE-----\n"
+
+
+def pem_to_der(
+    *, pem_filename: str | os.PathLike | None = None, pem_content: str | None = None
+) -> bytes:
+    """
+    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()
+    elif pem_filename is not None:
+        try:
+            with open(pem_filename, "r", encoding="utf-8") as f:
+                lines = list(f)
+        except Exception as err:
+            raise ModuleFailException(
+                f"cannot load PEM file {pem_filename}: {err}",
+                exception=traceback.format_exc(),
+            ) from err
+    else:
+        raise ModuleFailException(
+            "One of pem_filename and pem_content must be provided"
+        )
+    header_line_count = 0
+    for line in lines:
+        if line.startswith("-----"):
+            header_line_count += 1
+            if header_line_count == 2:
+                # If certificate file contains other certs appended
+                # (like intermediate certificates), ignore these.
+                break
+            continue
+        certificate_lines.append(line.strip())
+    return base64.b64decode("".join(certificate_lines))
+
+
+def process_links(
+    *, info: dict[str, t.Any], callback: t.Callable[[str, str], None]
+) -> None:
+    """
+    Process link header, calls callback for every link header with the URL and relation as options.
+
+    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: str,
+    *,
+    relative_with_timezone: bool = True,
+    now: datetime.datetime | None = None,
+) -> datetime.datetime:
+    """
+    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(with_timezone=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(f"Cannot parse Retry-After header value {repr(value)}")
+
+
+def compute_cert_id(
+    *,
+    backend: CryptoBackend,
+    cert_info: CertificateInformation | None = None,
+    cert_filename: str | os.PathLike | None = None,
+    cert_content: str | bytes | None = None,
+    none_if_required_information_is_missing: bool = False,
+) -> str | None:
+    # 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 = (
+        (base64.urlsafe_b64encode(cert_info.authority_key_identifier))
+        .decode("ascii")
+        .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 = (base64.urlsafe_b64encode(serial_bytes)).decode("ascii").replace("=", "")
+
+    # Compose cert ID
+    return f"{aki}.{serial}"
+
+
+__all__ = (
+    "nopad_b64",
+    "der_to_pem",
+    "pem_to_der",
+    "process_links",
+    "parse_retry_after",
+    "compute_cert_id",
+)

plugins/module_utils/_argspec.py

@@ -0,0 +1,124 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+_T = t.TypeVar("_T")
+
+
+def _ensure_list(value: list[_T] | tuple[_T] | None) -> list[_T]:
+    if value is None:
+        return []
+    return list(value)
+
+
+class ArgumentSpec:
+    def __init__(
+        self,
+        argument_spec: dict[str, t.Any] | None = None,
+        *,
+        mutually_exclusive: list[list[str] | tuple[str, ...]] | None = None,
+        required_together: list[list[str] | tuple[str, ...]] | None = None,
+        required_one_of: list[list[str] | tuple[str, ...]] | None = None,
+        required_if: (
+            list[
+                tuple[str, t.Any, list[str] | tuple[str, ...]]
+                | tuple[str, t.Any, list[str] | tuple[str, ...], bool]
+            ]
+            | None
+        ) = None,
+        required_by: dict[str, tuple[str, ...] | list[str]] | None = None,
+    ) -> 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) -> t.Self:
+        self.argument_spec.update(kwargs)
+        return self
+
+    def update(
+        self,
+        *,
+        mutually_exclusive: list[list[str] | tuple[str, ...]] | None = None,
+        required_together: list[list[str] | tuple[str, ...]] | None = None,
+        required_one_of: list[list[str] | tuple[str, ...]] | None = None,
+        required_if: (
+            list[
+                tuple[str, t.Any, list[str] | tuple[str, ...]]
+                | tuple[str, t.Any, list[str] | tuple[str, ...], bool]
+            ]
+            | None
+        ) = None,
+        required_by: dict[str, tuple[str, ...] | list[str]] | None = 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: t.Self) -> t.Self:
+        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: type[_T], args: tuple, **kwargs: t.Any
+    ) -> _T:
+        for forbidden_name in (
+            "argument_spec",
+            "mutually_exclusive",
+            "required_together",
+            "required_one_of",
+            "required_if",
+            "required_by",
+        ):
+            if forbidden_name in kwargs:
+                raise ValueError(
+                    f"You must not provide a {forbidden_name} keyword parameter to create_ansible_module_helper()"
+                )
+        instance = clazz(  # type: ignore
+            *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,
+        )
+        return instance
+
+    def create_ansible_module(self, **kwargs: t.Any) -> AnsibleModule:
+        return self.create_ansible_module_helper(AnsibleModule, (), **kwargs)
+
+
+__all__ = ("ArgumentSpec",)

plugins/module_utils/_crypto/_asn1.py

@@ -0,0 +1,176 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import enum
+import re
+
+from ansible.module_utils.common.text.converters import to_bytes
+
+
+# An ASN.1 serialized as a string in the OpenSSL format:
+#     [modifier,]type[:value]
+#
+# 'modifier':
+#     The modifier can be 'IMPLICIT:<tag_number><tag_class>,' or 'EXPLICIT:<tag_number><tag_class>' where IMPLICIT
+#     changes the tag of the universal value to encode and EXPLICIT prefixes its tag to the existing universal value.
+#     The tag_number must be set while the tag_class can be 'U', 'A', 'P', or 'C" for 'Universal', 'Application',
+#     'Private', or 'Context Specific' with C being the default.
+#
+# 'type':
+#     The underlying ASN.1 type of the value specified. Currently only the following have been implemented:
+#         UTF8: The value must be a UTF-8 encoded string.
+#
+# '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>.*)"
+)
+
+
+class TagClass(enum.Enum):
+    universal = 0
+    application = 1
+    context_specific = 2
+    private = 3
+
+
+# Universal tag numbers that can be encoded.
+class TagNumber(enum.Enum):
+    utf8_string = 12
+
+
+def _pack_octet_integer(value: int) -> bytes:
+    """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()
+
+    # Continue to shift the number by 7 bits and pack into an octet until the
+    # value is fully packed.
+    while value:
+        octet_value = value & 0b01111111
+
+        # First round (last octet) must have the MSB set.
+        if len(octets):
+            octet_value |= 0b10000000
+
+        octets.append(octet_value)
+        value >>= 7
+
+    # Reverse to ensure the higher order octets are first.
+    octets.reverse()
+    return bytes(octets)
+
+
+def serialize_asn1_string_as_der(value: str) -> bytes:
+    """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]"
+        )
+
+    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(
+            f'The ASN.1 serialized string is not a known type "{value_type}", only UTF8 types are supported'
+        )
+
+    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"):
+        b_value = pack_asn1(
+            tag_class=TagClass.universal,
+            constructed=False,
+            tag_number=TagNumber.utf8_string,
+            b_data=b_value,
+        )
+
+    if tag_type:
+        tag_class_enum = {
+            "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_enum != TagClass.universal
+        b_value = pack_asn1(
+            tag_class=tag_class_enum,
+            constructed=constructed,
+            tag_number=int(tag_number),
+            b_data=b_value,
+        )
+
+    return b_value
+
+
+def pack_asn1(
+    *,
+    tag_class: TagClass,
+    constructed: bool,
+    tag_number: TagNumber | int,
+    b_data: bytes,
+) -> bytes:
+    """Pack the value into an ASN.1 data structure.
+
+    The structure for an ASN.1 element is
+
+    | Identifier Octet(s) | Length Octet(s) | Data Octet(s) |
+    """
+    b_asn1_data = bytearray()
+
+    # Bit 8 and 7 denotes the class.
+    identifier_octets = tag_class.value << 6
+    # Bit 6 denotes whether the value is primitive or constructed.
+    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.
+    if isinstance(tag_number, TagNumber):
+        tag_number = tag_number.value
+    if tag_number < 31:
+        identifier_octets |= tag_number
+        b_asn1_data.append(identifier_octets)
+    else:
+        identifier_octets |= 31
+        b_asn1_data.append(identifier_octets)
+        b_asn1_data.extend(_pack_octet_integer(tag_number))
+
+    length = len(b_data)
+
+    # If the length can be encoded in 7 bits only 1 octet is required.
+    if length < 128:
+        b_asn1_data.append(length)
+
+    else:
+        # Otherwise the length must be encoded across multiple octets
+        length_octets = bytearray()
+        while length:
+            length_octets.append(length & 0b11111111)
+            length >>= 8
+
+        length_octets.reverse()  # Reverse to make the higher octets first.
+
+        # The first length octet must have the MSB set alongside the number of
+        # octets the length was encoded in.
+        b_asn1_data.append(len(length_octets) | 0b10000000)
+        b_asn1_data.extend(length_octets)
+
+    return bytes(b_asn1_data) + b_data
+
+
+__all__ = ("TagClass", "TagNumber", "serialize_asn1_string_as_der", "pack_asn1")

plugins/module_utils/_crypto/_obj2txt.py

@@ -4,6 +4,9 @@
 # dynamically by Ansible, still belong to the author of the module, and may assign
 # their own license to the complete work.
 
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
 # 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.
@@ -26,15 +29,15 @@
 #    pyca/cryptography@3057f91ea9a05fb593825006d87a391286a4d828
 #    pyca/cryptography@d607dd7e5bc5c08854ec0c9baff70ba4a35be36f
 
-from __future__ import absolute_import, division, print_function
+from __future__ import annotations
-__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):
+
+def obj2txt(openssl_lib, openssl_ffi, obj) -> str:
     # Set to 80 on the recommendation of
     # https://www.openssl.org/docs/crypto/OBJ_nid2ln.html#return_values
     #
@@ -55,3 +58,6 @@ def obj2txt(openssl_lib, openssl_ffi, obj):
         buf = openssl_ffi.new("char[]", buf_len)
         res = openssl_lib.OBJ_obj2txt(buf, buf_len, obj, 1)
     return openssl_ffi.buffer(buf, res)[:].decode()
+
+
+__all__ = ("obj2txt",)

plugins/module_utils/_crypto/_objects.py

@@ -0,0 +1,38 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+from ansible_collections.community.crypto.plugins.module_utils._crypto._objects_data import (
+    OID_MAP,
+)
+
+
+OID_LOOKUP: dict[str, str] = {}
+NORMALIZE_NAMES: dict[str, str] = {}
+NORMALIZE_NAMES_SHORT: dict[str, str] = {}
+
+for dotted, names in OID_MAP.items():
+    for name in names:
+        if name in NORMALIZE_NAMES and OID_LOOKUP[name] != dotted:
+            raise AssertionError(
+                f'Name collision during setup: "{name}" for OIDs {dotted} and {OID_LOOKUP[name]}'
+            )
+        NORMALIZE_NAMES[name] = names[0]
+        NORMALIZE_NAMES_SHORT[name] = names[-1]
+        OID_LOOKUP[name] = dotted
+for alias, original in [("userID", "userId")]:
+    if alias in NORMALIZE_NAMES:
+        raise AssertionError(
+            f'Name collision during adding aliases: "{alias}" (alias for "{original}") is already mapped to OID {OID_LOOKUP[alias]}'
+        )
+    NORMALIZE_NAMES[alias] = original
+    NORMALIZE_NAMES_SHORT[alias] = NORMALIZE_NAMES_SHORT[original]
+    OID_LOOKUP[alias] = OID_LOOKUP[original]
+
+
+__all__ = ("OID_LOOKUP", "NORMALIZE_NAMES", "NORMALIZE_NAMES_SHORT")

plugins/module_utils/_crypto/basic.py

@@ -0,0 +1,29 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+try:
+    import cryptography  # noqa: F401, pylint: disable=unused-import
+
+    HAS_CRYPTOGRAPHY = True
+except ImportError:
+    # Error handled in the calling module.
+    HAS_CRYPTOGRAPHY = False
+
+
+class OpenSSLObjectError(Exception):
+    pass
+
+
+class OpenSSLBadPassphraseError(OpenSSLObjectError):
+    pass
+
+
+__all__ = ("HAS_CRYPTOGRAPHY", "OpenSSLObjectError", "OpenSSLBadPassphraseError")

plugins/module_utils/_crypto/cryptography_crl.py

@@ -0,0 +1,210 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+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 ansible_collections.community.crypto.plugins.module_utils._crypto._obj2txt import (
+    obj2txt,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    HAS_CRYPTOGRAPHY,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_decode_name,
+)
+
+
+if t.TYPE_CHECKING:
+    import datetime
+
+
+# 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,
+    }
+    REVOCATION_REASON_MAP_INVERSE = {}
+    for k, v in REVOCATION_REASON_MAP.items():
+        REVOCATION_REASON_MAP_INVERSE[v] = k
+
+else:
+    REVOCATION_REASON_MAP = {}
+    REVOCATION_REASON_MAP_INVERSE = {}
+
+
+def cryptography_decode_revoked_certificate(
+    cert: x509.RevokedCertificate,
+) -> dict[str, t.Any]:
+    result = {
+        "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_ci = cert.extensions.get_extension_for_class(x509.CertificateIssuer)
+        result["issuer"] = list(ext_ci.value)
+        result["issuer_critical"] = ext_ci.critical
+    except x509.ExtensionNotFound:
+        pass
+    try:
+        ext_cr = cert.extensions.get_extension_for_class(x509.CRLReason)
+        result["reason"] = ext_cr.value.reason
+        result["reason_critical"] = ext_cr.critical
+    except x509.ExtensionNotFound:
+        pass
+    try:
+        ext_id = cert.extensions.get_extension_for_class(x509.InvalidityDate)
+        result["invalidity_date"] = get_invalidity_date(ext_id.value)
+        result["invalidity_date_critical"] = ext_id.critical
+    except x509.ExtensionNotFound:
+        pass
+    return result
+
+
+def cryptography_dump_revoked(
+    entry: dict[str, t.Any],
+    *,
+    idn_rewrite: t.Literal["ignore", "idna", "unicode"] = "ignore",
+) -> dict[str, t.Any]:
+    return {
+        "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"],
+    }
+
+
+def cryptography_get_signature_algorithm_oid_from_crl(
+    crl: x509.CertificateRevocationList,
+) -> x509.oid.ObjectIdentifier:
+    try:
+        return crl.signature_algorithm_oid
+    except AttributeError:
+        # Older cryptography versions do not have signature_algorithm_oid yet
+        dotted = obj2txt(
+            crl._backend._lib,  # type: ignore[attr-defined]  # pylint: disable=protected-access
+            crl._backend._ffi,  # type: ignore[attr-defined]  # pylint: disable=protected-access
+            crl._x509_crl.sig_alg.algorithm,  # type: ignore[attr-defined]  # pylint: disable=protected-access
+        )
+        return x509.oid.ObjectIdentifier(dotted)
+
+
+def get_next_update(obj: x509.CertificateRevocationList) -> datetime.datetime | None:
+    if CRYPTOGRAPHY_TIMEZONE:
+        return obj.next_update_utc
+    return obj.next_update
+
+
+def get_last_update(obj: x509.CertificateRevocationList) -> datetime.datetime:
+    if CRYPTOGRAPHY_TIMEZONE:
+        return obj.last_update_utc
+    return obj.last_update
+
+
+def get_revocation_date(obj: x509.RevokedCertificate) -> datetime.datetime:
+    if CRYPTOGRAPHY_TIMEZONE:
+        return obj.revocation_date_utc
+    return obj.revocation_date
+
+
+def get_invalidity_date(obj: x509.InvalidityDate) -> datetime.datetime:
+    if CRYPTOGRAPHY_TIMEZONE_INVALIDITY_DATE:
+        return obj.invalidity_date_utc
+    return obj.invalidity_date
+
+
+def set_next_update(
+    builder: x509.CertificateRevocationListBuilder, *, value: datetime.datetime
+) -> x509.CertificateRevocationListBuilder:
+    return builder.next_update(value)
+
+
+def set_last_update(
+    builder: x509.CertificateRevocationListBuilder, *, value: datetime.datetime
+) -> x509.CertificateRevocationListBuilder:
+    return builder.last_update(value)
+
+
+def set_revocation_date(
+    builder: x509.RevokedCertificateBuilder, *, value: datetime.datetime
+) -> x509.RevokedCertificateBuilder:
+    return builder.revocation_date(value)
+
+
+__all__ = (
+    "REVOCATION_REASON_MAP",
+    "REVOCATION_REASON_MAP_INVERSE",
+    "cryptography_decode_revoked_certificate",
+    "cryptography_dump_revoked",
+    "cryptography_get_signature_algorithm_oid_from_crl",
+    "get_next_update",
+    "get_last_update",
+    "get_revocation_date",
+    "get_invalidity_date",
+    "set_next_update",
+    "set_last_update",
+    "set_revocation_date",
+)

plugins/module_utils/_crypto/math.py

@@ -0,0 +1,170 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+
+def binary_exp_mod(f: int, e: int, *, m: int) -> int:
+    """Computes f^e mod m in O(log e) multiplications modulo m."""
+    # Compute len_e = floor(log_2(e))
+    len_e = -1
+    x = e
+    while x > 0:
+        x >>= 1
+        len_e += 1
+    # Compute f**e mod m
+    result = 1
+    for k in range(len_e, -1, -1):
+        result = (result * result) % m
+        if ((e >> k) & 1) != 0:
+            result = (result * f) % m
+    return result
+
+
+def simple_gcd(a: int, b: int) -> int:
+    """Compute GCD of its two inputs."""
+    while b != 0:
+        a, b = b, a % b
+    return a
+
+
+def quick_is_not_prime(n: int) -> bool:
+    """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 could not detect quickly whether it is not prime.
+    """
+    if n <= 2:
+        return n < 2
+    # The constant in the next line is the product of all primes < 200
+    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)
+    return False
+
+
+def count_bytes(no: int) -> int:
+    """
+    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: int) -> int:
+    """
+    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()
+
+
+def convert_int_to_bytes(no: int, *, count: int | None = None) -> bytes:
+    """
+    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 no.to_bytes(count, byteorder="big")
+
+
+def convert_int_to_hex(no: int, *, digits: int | None = None) -> str:
+    """
+    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 = f"{no:x}"
+    if digits is not None and len(value) < digits:
+        value = "0" * (digits - len(value)) + value
+    return value
+
+
+def convert_bytes_to_int(data: bytes) -> int:
+    """
+    Convert a byte string to an unsigned integer in network byte order.
+    """
+    return int.from_bytes(data, byteorder="big", signed=False)
+
+
+__all__ = (
+    "binary_exp_mod",
+    "simple_gcd",
+    "quick_is_not_prime",
+    "count_bytes",
+    "count_bits",
+    "convert_int_to_bytes",
+    "convert_int_to_hex",
+    "convert_bytes_to_int",
+)

plugins/module_utils/_crypto/module_backends/certificate.py

@@ -0,0 +1,417 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import typing as t
+
+from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+    ArgumentSpec,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLBadPassphraseError,
+    OpenSSLObjectError,
+)
+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_privatekey,
+    load_certificate_request,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    import datetime
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+        CertificatePrivateKeyTypes,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        CertificateIssuerPrivateKeyTypes,
+    )
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    from cryptography import x509
+except ImportError:
+    pass
+
+
+class CertificateError(OpenSSLObjectError):
+    pass
+
+
+class CertificateBackend(metaclass=abc.ABCMeta):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        self.module = module
+
+        self.force: bool = module.params["force"]
+        self.ignore_timestamps: bool = module.params["ignore_timestamps"]
+        self.privatekey_path: str | None = module.params["privatekey_path"]
+        privatekey_content: str | None = module.params["privatekey_content"]
+        if privatekey_content is not None:
+            self.privatekey_content: bytes | None = privatekey_content.encode("utf-8")
+        else:
+            self.privatekey_content = None
+        self.privatekey_passphrase: str | None = module.params["privatekey_passphrase"]
+        self.csr_path: str | None = module.params["csr_path"]
+        csr_content = module.params["csr_content"]
+        if csr_content is not None:
+            self.csr_content: bytes | None = csr_content.encode("utf-8")
+        else:
+            self.csr_content = None
+
+        # 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: str = "never_create"
+        self.create_authority_key_identifier: bool = False
+
+        self.privatekey: CertificatePrivateKeyTypes | None = None
+        self.csr: x509.CertificateSigningRequest | None = None
+        self.cert: x509.Certificate | None = None
+        self.existing_certificate: x509.Certificate | None = None
+        self.existing_certificate_bytes: bytes | None = None
+
+        self.check_csr_subject: bool = True
+        self.check_csr_extensions: bool = True
+
+        self.diff_before = self._get_info(None)
+        self.diff_after = self._get_info(None)
+
+    def _get_info(self, data: bytes | None) -> dict[str, t.Any]:
+        if data is None:
+            return {}
+        try:
+            result = get_certificate_info(
+                module=self.module, content=data, prefer_one_fingerprint=True
+            )
+            result["can_parse_certificate"] = True
+            return result
+        except Exception:
+            return {"can_parse_certificate": False}
+
+    @abc.abstractmethod
+    def generate_certificate(self) -> None:
+        """(Re-)Generate certificate."""
+
+    @abc.abstractmethod
+    def get_certificate_data(self) -> bytes:
+        """Return bytes for self.cert."""
+
+    def set_existing(self, certificate_bytes: bytes | None) -> None:
+        """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
+        )
+
+    def has_existing(self) -> bool:
+        """Query whether an existing certificate is/has been there."""
+        return self.existing_certificate_bytes is not None
+
+    def _ensure_private_key_loaded(self) -> None:
+        """Load the provided private key into self.privatekey."""
+        if self.privatekey is not None:
+            return
+        if self.privatekey_path is None and self.privatekey_content is None:
+            return
+        try:
+            self.privatekey = load_certificate_privatekey(
+                path=self.privatekey_path,
+                content=self.privatekey_content,
+                passphrase=self.privatekey_passphrase,
+            )
+        except OpenSSLBadPassphraseError as exc:
+            raise CertificateError(exc) from exc
+
+    def _ensure_csr_loaded(self) -> None:
+        """Load the CSR into self.csr."""
+        if self.csr is not None:
+            return
+        if self.csr_path is None and self.csr_content is None:
+            return
+        self.csr = load_certificate_request(
+            path=self.csr_path,
+            content=self.csr_content,
+        )
+
+    def _ensure_existing_certificate_loaded(self) -> None:
+        """Load the existing certificate into self.existing_certificate."""
+        if self.existing_certificate is not None:
+            return
+        if self.existing_certificate_bytes is None:
+            return
+        self.existing_certificate = load_certificate(
+            path=None,
+            content=self.existing_certificate_bytes,
+        )
+
+    def _check_privatekey(self) -> bool:
+        """Check whether provided parameters match, assuming self.existing_certificate and self.privatekey have been populated."""
+        if self.existing_certificate is None:
+            raise AssertionError(
+                "Contract violation: existing_certificate has not been populated"
+            )
+        if self.privatekey is None:
+            raise AssertionError(
+                "Contract violation: privatekey has not been populated"
+            )
+        return cryptography_compare_public_keys(
+            self.existing_certificate.public_key(), self.privatekey.public_key()
+        )
+
+    def _check_csr(self) -> bool:
+        """Check whether provided parameters match, assuming self.existing_certificate and self.csr have been populated."""
+        if self.existing_certificate is None:
+            raise AssertionError(
+                "Contract violation: existing_certificate has not been populated"
+            )
+        if self.csr is None:
+            raise AssertionError("Contract violation: csr has not been populated")
+        # 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()
+        ):
+            return False
+        # Check 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":
+            # 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,
+                )
+            )
+        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,
+                )
+            )
+        if len(cert_exts) != len(csr_exts):
+            return False
+        for cert_ext in cert_exts:
+            try:
+                csr_ext = self.csr.extensions.get_extension_for_oid(cert_ext.oid)
+                if cert_ext != csr_ext:
+                    return False
+            except cryptography.x509.ExtensionNotFound:
+                return False
+        return True
+
+    def _check_subject_key_identifier(self) -> bool:
+        """Check whether Subject Key Identifier matches, assuming self.existing_certificate and self.csr have been populated."""
+        if self.existing_certificate is None:
+            raise AssertionError(
+                "Contract violation: existing_certificate has not been populated"
+            )
+        if self.csr is None:
+            raise AssertionError("Contract violation: csr has not been populated")
+        # Get hold of certificate's SKI
+        try:
+            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":
+            try:
+                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
+            ):
+                return False
+        else:
+            # 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,
+        *,
+        not_before: datetime.datetime | None = None,
+        not_after: datetime.datetime | None = None,
+    ) -> bool:
+        """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:
+            return True
+        assert self.existing_certificate is not None
+
+        # Check whether private key matches
+        self._ensure_private_key_loaded()
+        if self.privatekey is not None and not self._check_privatekey():
+            return True
+
+        # Check whether CSR matches
+        self._ensure_csr_loaded()
+        if self.csr is not None and not self._check_csr():
+            return True
+
+        # Check SubjectKeyIdentifier
+        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: bool) -> dict[str, t.Any]:
+        """Serialize the object into a dictionary."""
+        result: dict[str, t.Any] = {
+            "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:
+            certificate_bytes = self.get_certificate_data()
+        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["diff"] = {
+            "before": self.diff_before,
+            "after": self.diff_after,
+        }
+        return result
+
+
+class CertificateProvider(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def validate_module_args(self, module: AnsibleModule) -> None:
+        """Check module arguments"""
+
+    @abc.abstractmethod
+    def create_backend(self, module: AnsibleModule) -> CertificateBackend:
+        """Create an implementation for a backend.
+
+        Return value must be instance of CertificateBackend.
+        """
+
+
+def select_backend(
+    *, module: AnsibleModule, provider: CertificateProvider
+) -> CertificateBackend:
+    provider.validate_module_args(module)
+
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+
+    return provider.create_backend(module)
+
+
+def get_certificate_argument_spec() -> ArgumentSpec:
+    return ArgumentSpec(
+        argument_spec={
+            "provider": {
+                "type": "str",
+                "choices": [],
+            },  # choices will be filled by add_XXX_provider_to_argument_spec() in certificate_xxx.py
+            "force": {
+                "type": "bool",
+                "default": False,
+            },
+            "csr_path": {"type": "path"},
+            "csr_content": {"type": "str"},
+            "ignore_timestamps": {"type": "bool", "default": True},
+            "select_crypto_backend": {
+                "type": "str",
+                "default": "auto",
+                "choices": ["auto", "cryptography"],
+            },
+            # General properties of a certificate
+            "privatekey_path": {"type": "path"},
+            "privatekey_content": {"type": "str", "no_log": True},
+            "privatekey_passphrase": {"type": "str", "no_log": True},
+        },
+        mutually_exclusive=[
+            ["csr_path", "csr_content"],
+            ["privatekey_path", "privatekey_content"],
+        ],
+    )
+
+
+__all__ = (
+    "CertificateError",
+    "CertificateBackend",
+    "CertificateProvider",
+    "get_certificate_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/certificate_acme.py

@@ -0,0 +1,145 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import os
+import tempfile
+import traceback
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes
+from ansible_collections.community.crypto.plugins.module_utils._crypto.module_backends.certificate import (
+    CertificateBackend,
+    CertificateError,
+    CertificateProvider,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+        ArgumentSpec,
+    )
+
+
+class AcmeCertificateBackend(CertificateBackend):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        super().__init__(module=module)
+        self.accountkey_path: str = module.params["acme_accountkey_path"]
+        self.challenge_path: str = module.params["acme_challenge_path"]
+        self.use_chain: bool = module.params["acme_chain"]
+        self.acme_directory: str = module.params["acme_directory"]
+        self.cert_bytes: bytes | None = None
+
+        if self.csr_content is None:
+            if self.csr_path is None:
+                raise CertificateError(
+                    "csr_path or csr_content is required for ownca provider"
+                )
+            if not os.path.exists(self.csr_path):
+                raise CertificateError(
+                    f"The certificate signing request file {self.csr_path} does not exist"
+                )
+
+        if not os.path.exists(self.accountkey_path):
+            raise CertificateError(
+                f"The account key {self.accountkey_path} does not exist"
+            )
+
+        if not os.path.exists(self.challenge_path):
+            raise CertificateError(
+                f"The challenge path {self.challenge_path} does not exist"
+            )
+
+        self.acme_tiny_path = self.module.get_bin_path("acme-tiny", required=True)
+
+    def generate_certificate(self) -> None:
+        """(Re-)Generate certificate."""
+
+        command = [self.acme_tiny_path]
+        if self.use_chain:
+            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")
+            try:
+                f.write(self.csr_content)
+            except Exception as err:
+                try:
+                    f.close()
+                except Exception:
+                    pass
+                self.module.fail_json(
+                    msg=f"failed to create temporary CSR file: {err}",
+                    exception=traceback.format_exc(),
+                )
+            f.close()
+            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])
+
+        try:
+            self.cert_bytes = to_bytes(
+                self.module.run_command(command, check_rc=True)[1]
+            )
+        except OSError as exc:
+            raise CertificateError(exc) from exc
+
+    def get_certificate_data(self) -> bytes:
+        """Return bytes for self.cert."""
+        if self.cert_bytes is None:
+            raise AssertionError("Contract violation: cert_bytes is None")
+        return self.cert_bytes
+
+    def dump(self, *, include_certificate: bool) -> dict[str, t.Any]:
+        result = super().dump(include_certificate=include_certificate)
+        result["accountkey"] = self.accountkey_path
+        return result
+
+
+class AcmeCertificateProvider(CertificateProvider):
+    def validate_module_args(self, module: AnsibleModule) -> None:
+        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 create_backend(self, module: AnsibleModule) -> AcmeCertificateBackend:
+        return AcmeCertificateBackend(module=module)
+
+
+def add_acme_provider_to_argument_spec(argument_spec: ArgumentSpec) -> None:
+    argument_spec.argument_spec["provider"]["choices"].append("acme")
+    argument_spec.argument_spec.update(
+        {
+            "acme_accountkey_path": {"type": "path"},
+            "acme_challenge_path": {"type": "path"},
+            "acme_chain": {"type": "bool", "default": False},
+            "acme_directory": {
+                "type": "str",
+                "default": "https://acme-v02.api.letsencrypt.org/directory",
+            },
+        }
+    )
+
+
+__all__ = (
+    "AcmeCertificateBackend",
+    "AcmeCertificateProvider",
+    "add_acme_provider_to_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/certificate_info.py

@@ -0,0 +1,487 @@
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import binascii
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_text
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_decode_name,
+    cryptography_get_extensions_from_cert,
+    cryptography_oid_to_name,
+    get_not_valid_after,
+    get_not_valid_before,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.module_backends.publickey_info import (
+    get_publickey_info,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.support import (
+    get_fingerprint_of_bytes,
+    load_certificate,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+from ansible_collections.community.crypto.plugins.module_utils._time import (
+    get_now_datetime,
+)
+
+
+if t.TYPE_CHECKING:
+    import datetime
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+        ArgumentSpec,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._filter_module import (
+        FilterModuleMock,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import PublicKeyTypes
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule, FilterModuleMock]
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+except ImportError:
+    pass
+
+
+TIMESTAMP_FORMAT = "%Y%m%d%H%M%SZ"
+
+
+class CertificateInfoRetrieval(metaclass=abc.ABCMeta):
+    cert: x509.Certificate
+
+    def __init__(self, *, module: GeneralAnsibleModule, content: bytes) -> None:
+        # content must be a bytes string
+        self.module = module
+        self.content = content
+
+    @abc.abstractmethod
+    def _get_der_bytes(self) -> bytes:
+        pass
+
+    @abc.abstractmethod
+    def _get_signature_algorithm(self) -> str:
+        pass
+
+    @abc.abstractmethod
+    def _get_subject_ordered(self) -> list[list[str]]:
+        pass
+
+    @abc.abstractmethod
+    def _get_issuer_ordered(self) -> list[list[str]]:
+        pass
+
+    @abc.abstractmethod
+    def _get_version(self) -> int | str:
+        pass
+
+    @abc.abstractmethod
+    def _get_key_usage(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_extended_key_usage(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_basic_constraints(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_ocsp_must_staple(self) -> tuple[bool | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_subject_alt_name(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def get_not_before(self) -> datetime.datetime:
+        pass
+
+    @abc.abstractmethod
+    def get_not_after(self) -> datetime.datetime:
+        pass
+
+    @abc.abstractmethod
+    def _get_public_key_pem(self) -> bytes:
+        pass
+
+    @abc.abstractmethod
+    def _get_public_key_object(self) -> PublicKeyTypes:
+        pass
+
+    @abc.abstractmethod
+    def _get_subject_key_identifier(self) -> bytes | None:
+        pass
+
+    @abc.abstractmethod
+    def _get_authority_key_identifier(
+        self,
+    ) -> tuple[bytes | None, list[str] | None, int | None]:
+        pass
+
+    @abc.abstractmethod
+    def _get_serial_number(self) -> int:
+        pass
+
+    @abc.abstractmethod
+    def _get_all_extensions(self) -> dict[str, dict[str, bool | str]]:
+        pass
+
+    @abc.abstractmethod
+    def _get_ocsp_uri(self) -> str | None:
+        pass
+
+    @abc.abstractmethod
+    def _get_issuer_uri(self) -> str | None:
+        pass
+
+    def get_info(
+        self, *, prefer_one_fingerprint: bool = False, der_support_enabled: bool = False
+    ) -> dict[str, t.Any]:
+        result: dict[str, t.Any] = {}
+        self.cert = load_certificate(
+            content=self.content,
+            der_support_enabled=der_support_enabled,
+        )
+
+        result["signature_algorithm"] = self._get_signature_algorithm()
+        subject = self._get_subject_ordered()
+        issuer = self._get_issuer_ordered()
+        result["subject"] = {}
+        for k, v in subject:
+            result["subject"][k] = v
+        result["subject_ordered"] = subject
+        result["issuer"] = {}
+        for k, v in issuer:
+            result["issuer"][k] = v
+        result["issuer_ordered"] = issuer
+        result["version"] = self._get_version()
+        result["key_usage"], result["key_usage_critical"] = self._get_key_usage()
+        result["extended_key_usage"], result["extended_key_usage_critical"] = (
+            self._get_extended_key_usage()
+        )
+        result["basic_constraints"], result["basic_constraints_critical"] = (
+            self._get_basic_constraints()
+        )
+        result["ocsp_must_staple"], result["ocsp_must_staple_critical"] = (
+            self._get_ocsp_must_staple()
+        )
+        result["subject_alt_name"], result["subject_alt_name_critical"] = (
+            self._get_subject_alt_name()
+        )
+
+        not_before = self.get_not_before()
+        not_after = self.get_not_after()
+        result["not_before"] = not_before.strftime(TIMESTAMP_FORMAT)
+        result["not_after"] = not_after.strftime(TIMESTAMP_FORMAT)
+        result["expired"] = not_after < get_now_datetime(
+            with_timezone=CRYPTOGRAPHY_TIMEZONE
+        )
+
+        result["public_key"] = to_text(self._get_public_key_pem())
+
+        public_key_info = get_publickey_info(
+            module=self.module,
+            key=self._get_public_key_object(),
+            prefer_one_fingerprint=prefer_one_fingerprint,
+        )
+        result.update(
+            {
+                "public_key_type": public_key_info["type"],
+                "public_key_data": public_key_info["public_data"],
+                "public_key_fingerprints": public_key_info["fingerprints"],
+            }
+        )
+
+        result["fingerprints"] = get_fingerprint_of_bytes(
+            self._get_der_bytes(), prefer_one=prefer_one_fingerprint
+        )
+
+        ski_bytes = self._get_subject_key_identifier()
+        if ski_bytes is not None:
+            ski = binascii.hexlify(ski_bytes).decode("ascii")
+            ski = ":".join([ski[i : i + 2] for i in range(0, len(ski), 2)])
+        else:
+            ski = None
+        result["subject_key_identifier"] = ski
+
+        aki_bytes, aci, acsn = self._get_authority_key_identifier()
+        if aki_bytes is not None:
+            aki = binascii.hexlify(aki_bytes).decode("ascii")
+            aki = ":".join([aki[i : i + 2] for i in range(0, len(aki), 2)])
+        else:
+            aki = None
+        result["authority_key_identifier"] = aki
+        result["authority_cert_issuer"] = aci
+        result["authority_cert_serial_number"] = acsn
+
+        result["serial_number"] = self._get_serial_number()
+        result["extensions_by_oid"] = self._get_all_extensions()
+        result["ocsp_uri"] = self._get_ocsp_uri()
+        result["issuer_uri"] = self._get_issuer_uri()
+
+        return result
+
+
+class CertificateInfoRetrievalCryptography(CertificateInfoRetrieval):
+    """Validate the supplied cert, using the cryptography backend"""
+
+    def __init__(self, *, module: GeneralAnsibleModule, content: bytes) -> None:
+        super().__init__(module=module, content=content)
+        self.name_encoding = module.params.get("name_encoding", "ignore")
+
+    def _get_der_bytes(self) -> bytes:
+        return self.cert.public_bytes(serialization.Encoding.DER)
+
+    def _get_signature_algorithm(self) -> str:
+        return cryptography_oid_to_name(self.cert.signature_algorithm_oid)
+
+    def _get_subject_ordered(self) -> list[list[str]]:
+        result: list[list[str]] = []
+        for attribute in self.cert.subject:
+            result.append(
+                [cryptography_oid_to_name(attribute.oid), to_text(attribute.value)]
+            )
+        return result
+
+    def _get_issuer_ordered(self) -> list[list[str]]:
+        result = []
+        for attribute in self.cert.issuer:
+            result.append(
+                [cryptography_oid_to_name(attribute.oid), to_text(attribute.value)]
+            )
+        return result
+
+    def _get_version(self) -> int | str:
+        if self.cert.version == x509.Version.v1:
+            return 1
+        if self.cert.version == x509.Version.v3:
+            return 3
+        return "unknown"
+
+    def _get_key_usage(self) -> tuple[list[str] | None, bool]:
+        try:
+            current_key_ext = self.cert.extensions.get_extension_for_class(
+                x509.KeyUsage
+            )
+            current_key_usage = current_key_ext.value
+            key_usage = {
+                "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 key_usage["key_agreement"]:
+                key_usage.update(
+                    {
+                        "encipher_only": current_key_usage.encipher_only,
+                        "decipher_only": current_key_usage.decipher_only,
+                    }
+                )
+
+            key_usage_names = {
+                "digital_signature": "Digital Signature",
+                "content_commitment": "Non Repudiation",
+                "key_encipherment": "Key Encipherment",
+                "data_encipherment": "Data Encipherment",
+                "key_agreement": "Key Agreement",
+                "key_cert_sign": "Certificate Sign",
+                "crl_sign": "CRL Sign",
+                "encipher_only": "Encipher Only",
+                "decipher_only": "Decipher Only",
+            }
+            return (
+                sorted(
+                    [
+                        key_usage_names[name]
+                        for name, value in key_usage.items()
+                        if value
+                    ]
+                ),
+                current_key_ext.critical,
+            )
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_extended_key_usage(self) -> tuple[list[str] | None, bool]:
+        try:
+            ext_keyusage_ext = self.cert.extensions.get_extension_for_class(
+                x509.ExtendedKeyUsage
+            )
+            return (
+                sorted(
+                    [cryptography_oid_to_name(eku) for eku in ext_keyusage_ext.value]
+                ),
+                ext_keyusage_ext.critical,
+            )
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_basic_constraints(self) -> tuple[list[str] | None, bool]:
+        try:
+            ext_keyusage_ext = self.cert.extensions.get_extension_for_class(
+                x509.BasicConstraints
+            )
+            result = []
+            result.append(f"CA:{'TRUE' if ext_keyusage_ext.value.ca else 'FALSE'}")
+            if ext_keyusage_ext.value.path_length is not None:
+                result.append(f"pathlen:{ext_keyusage_ext.value.path_length}")
+            return sorted(result), ext_keyusage_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_ocsp_must_staple(self) -> tuple[bool | None, bool]:
+        try:
+            tlsfeature_ext = self.cert.extensions.get_extension_for_class(
+                x509.TLSFeature
+            )
+            value = (
+                cryptography.x509.TLSFeatureType.status_request in tlsfeature_ext.value
+            )
+            return value, tlsfeature_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_subject_alt_name(self) -> tuple[list[str] | None, bool]:
+        try:
+            san_ext = self.cert.extensions.get_extension_for_class(
+                x509.SubjectAlternativeName
+            )
+            result = [
+                cryptography_decode_name(san, idn_rewrite=self.name_encoding)
+                for san in san_ext.value
+            ]
+            return result, san_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def get_not_before(self) -> datetime.datetime:
+        return get_not_valid_before(self.cert)
+
+    def get_not_after(self) -> datetime.datetime:
+        return get_not_valid_after(self.cert)
+
+    def _get_public_key_pem(self) -> bytes:
+        return self.cert.public_key().public_bytes(
+            serialization.Encoding.PEM,
+            serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+
+    def _get_public_key_object(self) -> PublicKeyTypes:
+        return self.cert.public_key()
+
+    def _get_subject_key_identifier(self) -> bytes | None:
+        try:
+            ext = self.cert.extensions.get_extension_for_class(
+                x509.SubjectKeyIdentifier
+            )
+            return ext.value.digest
+        except cryptography.x509.ExtensionNotFound:
+            return None
+
+    def _get_authority_key_identifier(
+        self,
+    ) -> tuple[bytes | None, list[str] | None, int | None]:
+        try:
+            ext = self.cert.extensions.get_extension_for_class(
+                x509.AuthorityKeyIdentifier
+            )
+            issuer = None
+            if ext.value.authority_cert_issuer is not None:
+                issuer = [
+                    cryptography_decode_name(san, idn_rewrite=self.name_encoding)
+                    for san in ext.value.authority_cert_issuer
+                ]
+            return (
+                ext.value.key_identifier,
+                issuer,
+                ext.value.authority_cert_serial_number,
+            )
+        except cryptography.x509.ExtensionNotFound:
+            return None, None, None
+
+    def _get_serial_number(self) -> int:
+        return self.cert.serial_number
+
+    def _get_all_extensions(self) -> dict[str, dict[str, bool | str]]:
+        return cryptography_get_extensions_from_cert(self.cert)
+
+    def _get_ocsp_uri(self) -> str | None:
+        try:
+            ext = self.cert.extensions.get_extension_for_class(
+                x509.AuthorityInformationAccess
+            )
+            for desc in ext.value:
+                if desc.access_method == x509.oid.AuthorityInformationAccessOID.OCSP:
+                    if isinstance(desc.access_location, x509.UniformResourceIdentifier):
+                        return desc.access_location.value
+        except x509.ExtensionNotFound:
+            pass
+        return None
+
+    def _get_issuer_uri(self) -> str | None:
+        try:
+            ext = self.cert.extensions.get_extension_for_class(
+                x509.AuthorityInformationAccess
+            )
+            for desc in ext.value:
+                if (
+                    desc.access_method
+                    == x509.oid.AuthorityInformationAccessOID.CA_ISSUERS
+                ):
+                    if isinstance(desc.access_location, x509.UniformResourceIdentifier):
+                        return desc.access_location.value
+        except x509.ExtensionNotFound:
+            pass
+        return None
+
+
+def get_certificate_info(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes,
+    prefer_one_fingerprint: bool = False,
+) -> dict[str, t.Any]:
+    info = CertificateInfoRetrievalCryptography(module=module, content=content)
+    return info.get_info(prefer_one_fingerprint=prefer_one_fingerprint)
+
+
+def select_backend(
+    *, module: GeneralAnsibleModule, content: bytes
+) -> CertificateInfoRetrieval:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return CertificateInfoRetrievalCryptography(module=module, content=content)
+
+
+__all__ = ("CertificateInfoRetrieval", "get_certificate_info", "select_backend")

plugins/module_utils/_crypto/module_backends/certificate_ownca.py

@@ -0,0 +1,374 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import os
+import typing as t
+from random import randrange
+
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLBadPassphraseError,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_compare_public_keys,
+    cryptography_key_needs_digest_for_signing,
+    cryptography_verify_certificate_signature,
+    get_not_valid_after,
+    get_not_valid_before,
+    is_potential_certificate_issuer_public_key,
+    set_not_valid_after,
+    set_not_valid_before,
+)
+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,
+    load_certificate_issuer_privatekey,
+    select_message_digest,
+)
+from ansible_collections.community.crypto.plugins.module_utils._time import (
+    get_relative_time_option,
+)
+
+
+if t.TYPE_CHECKING:
+    import datetime
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+        ArgumentSpec,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        CertificateIssuerPrivateKeyTypes,
+    )
+
+
+try:
+    import cryptography
+    from cryptography import x509
+    from cryptography.hazmat.primitives.serialization import Encoding
+except ImportError:
+    pass
+
+
+class OwnCACertificateBackendCryptography(CertificateBackend):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        super().__init__(module=module)
+
+        self.create_subject_key_identifier: t.Literal[
+            "create_if_not_provided", "always_create", "never_create"
+        ] = module.params["ownca_create_subject_key_identifier"]
+        self.create_authority_key_identifier: bool = module.params[
+            "ownca_create_authority_key_identifier"
+        ]
+        self.notBefore = get_relative_time_option(
+            module.params["ownca_not_before"],
+            input_name="ownca_not_before",
+            with_timezone=CRYPTOGRAPHY_TIMEZONE,
+        )
+        self.notAfter = get_relative_time_option(
+            module.params["ownca_not_after"],
+            input_name="ownca_not_after",
+            with_timezone=CRYPTOGRAPHY_TIMEZONE,
+        )
+        self.digest = select_message_digest(module.params["ownca_digest"])
+        self.serial_number = x509.random_serial_number()
+        self.ca_cert_path: str | None = module.params["ownca_path"]
+        ca_cert_content: str | None = module.params["ownca_content"]
+        if ca_cert_content is not None:
+            self.ca_cert_content: bytes | None = ca_cert_content.encode("utf-8")
+        else:
+            self.ca_cert_content = None
+        self.ca_privatekey_path: str | None = module.params["ownca_privatekey_path"]
+        ca_privatekey_content: str | None = module.params["ownca_privatekey_content"]
+        if ca_privatekey_content is not None:
+            self.ca_privatekey_content: bytes | None = ca_privatekey_content.encode(
+                "utf-8"
+            )
+        else:
+            self.ca_privatekey_content = None
+        self.ca_privatekey_passphrase: str | None = module.params[
+            "ownca_privatekey_passphrase"
+        ]
+
+        if self.csr_content is None:
+            if self.csr_path is None:
+                raise CertificateError(
+                    "csr_path or csr_content is required for ownca provider"
+                )
+            if not os.path.exists(self.csr_path):
+                raise CertificateError(
+                    f"The certificate signing request file {self.csr_path} does not exist"
+                )
+        if self.ca_cert_path is not None and not os.path.exists(self.ca_cert_path):
+            raise CertificateError(
+                f"The CA certificate file {self.ca_cert_path} does not exist"
+            )
+        if self.ca_privatekey_path is not None and not os.path.exists(
+            self.ca_privatekey_path
+        ):
+            raise CertificateError(
+                f"The CA private key file {self.ca_privatekey_path} does not exist"
+            )
+
+        self._ensure_csr_loaded()
+        self.ca_cert = load_certificate(
+            path=self.ca_cert_path,
+            content=self.ca_cert_content,
+        )
+        if not is_potential_certificate_issuer_public_key(self.ca_cert.public_key()):
+            raise CertificateError(
+                "CA certificate's public key cannot be used to sign certificates"
+            )
+        try:
+            self.ca_private_key = load_certificate_issuer_privatekey(
+                path=self.ca_privatekey_path,
+                content=self.ca_privatekey_content,
+                passphrase=self.ca_privatekey_passphrase,
+            )
+        except OpenSSLBadPassphraseError as exc:
+            module.fail_json(msg=str(exc))
+
+        if not cryptography_compare_public_keys(
+            self.ca_cert.public_key(), self.ca_private_key.public_key()
+        ):
+            raise CertificateError(
+                "The CA private key does not belong to the CA certificate"
+            )
+
+        if cryptography_key_needs_digest_for_signing(self.ca_private_key):
+            if self.digest is None:
+                raise CertificateError(
+                    f"The digest {module.params['ownca_digest']} is not supported with the cryptography backend"
+                )
+        else:
+            self.digest = None
+
+    def generate_certificate(self) -> None:
+        """(Re-)Generate certificate."""
+        if self.csr is None:
+            raise AssertionError("Contract violation: csr has not been populated")
+        cert_builder = x509.CertificateBuilder()
+        cert_builder = cert_builder.subject_name(self.csr.subject)
+        cert_builder = cert_builder.issuer_name(self.ca_cert.subject)
+        cert_builder = cert_builder.serial_number(self.serial_number)
+        cert_builder = set_not_valid_before(cert_builder, self.notBefore)
+        cert_builder = set_not_valid_after(cert_builder, self.notAfter)
+        cert_builder = cert_builder.public_key(self.csr.public_key())
+        has_ski = False
+        for extension in self.csr.extensions:
+            if isinstance(extension.value, x509.SubjectKeyIdentifier):
+                if self.create_subject_key_identifier == "always_create":
+                    continue
+                has_ski = True
+            if self.create_authority_key_identifier and isinstance(
+                extension.value, x509.AuthorityKeyIdentifier
+            ):
+                continue
+            cert_builder = cert_builder.add_extension(
+                extension.value, critical=extension.critical
+            )
+        if not has_ski and self.create_subject_key_identifier != "never_create":
+            cert_builder = cert_builder.add_extension(
+                x509.SubjectKeyIdentifier.from_public_key(self.csr.public_key()),
+                critical=False,
+            )
+        if self.create_authority_key_identifier:
+            try:
+                ext = self.ca_cert.extensions.get_extension_for_class(
+                    x509.SubjectKeyIdentifier
+                )
+                cert_builder = cert_builder.add_extension(
+                    (
+                        x509.AuthorityKeyIdentifier.from_issuer_subject_key_identifier(
+                            ext.value
+                        )
+                    ),
+                    critical=False,
+                )
+            except cryptography.x509.ExtensionNotFound:
+                public_key = self.ca_cert.public_key()
+                assert is_potential_certificate_issuer_public_key(public_key)
+                cert_builder = cert_builder.add_extension(
+                    x509.AuthorityKeyIdentifier.from_issuer_public_key(public_key),
+                    critical=False,
+                )
+
+        certificate = cert_builder.sign(
+            private_key=self.ca_private_key,
+            algorithm=self.digest,
+        )
+
+        self.cert = certificate
+
+    def get_certificate_data(self) -> bytes:
+        """Return bytes for self.cert."""
+        if self.cert is None:
+            raise AssertionError("Contract violation: cert has not been populated")
+        return self.cert.public_bytes(Encoding.PEM)
+
+    def needs_regeneration(
+        self,
+        *,
+        not_before: datetime.datetime | None = None,
+        not_after: datetime.datetime | None = None,
+    ) -> bool:
+        if super().needs_regeneration(
+            not_before=self.notBefore, not_after=self.notAfter
+        ):
+            return True
+
+        self._ensure_existing_certificate_loaded()
+        assert self.existing_certificate is not None
+
+        # Check whether certificate is signed by CA certificate
+        if not cryptography_verify_certificate_signature(
+            certificate=self.existing_certificate,
+            signer_public_key=self.ca_cert.public_key(),
+        ):
+            return True
+
+        # Check subject
+        if self.ca_cert.subject != self.existing_certificate.issuer:
+            return True
+
+        # Check AuthorityKeyIdentifier
+        if self.create_authority_key_identifier:
+            try:
+                ext_ski = self.ca_cert.extensions.get_extension_for_class(
+                    x509.SubjectKeyIdentifier
+                )
+                expected_ext = (
+                    x509.AuthorityKeyIdentifier.from_issuer_subject_key_identifier(
+                        ext_ski.value
+                    )
+                )
+            except cryptography.x509.ExtensionNotFound:
+                public_key = self.ca_cert.public_key()
+                assert is_potential_certificate_issuer_public_key(public_key)
+                expected_ext = x509.AuthorityKeyIdentifier.from_issuer_public_key(
+                    public_key
+                )
+
+            try:
+                ext_aki = self.existing_certificate.extensions.get_extension_for_class(
+                    x509.AuthorityKeyIdentifier
+                )
+                if ext_aki.value != expected_ext:
+                    return True
+            except cryptography.x509.ExtensionNotFound:
+                return True
+
+        return False
+
+    def dump(self, *, include_certificate: bool) -> dict[str, t.Any]:
+        result = super().dump(include_certificate=include_certificate)
+        result.update(
+            {
+                "ca_cert": self.ca_cert_path,
+                "ca_privatekey": self.ca_privatekey_path,
+            }
+        )
+
+        if self.module.check_mode:
+            result.update(
+                {
+                    "notBefore": self.notBefore.strftime("%Y%m%d%H%M%SZ"),
+                    "notAfter": self.notAfter.strftime("%Y%m%d%H%M%SZ"),
+                    "serial_number": self.serial_number,
+                }
+            )
+        else:
+            if self.cert is None:
+                self.cert = self.existing_certificate
+            assert self.cert is not None
+            result.update(
+                {
+                    "notBefore": get_not_valid_before(self.cert).strftime(
+                        "%Y%m%d%H%M%SZ"
+                    ),
+                    "notAfter": get_not_valid_after(self.cert).strftime(
+                        "%Y%m%d%H%M%SZ"
+                    ),
+                    "serial_number": self.cert.serial_number,
+                }
+            )
+
+        return result
+
+
+def generate_serial_number() -> int:
+    """Generate a serial number for a certificate"""
+    while True:
+        result = randrange(0, 1 << 160)
+        if result >= 1000:
+            return result
+
+
+class OwnCACertificateProvider(CertificateProvider):
+    def validate_module_args(self, module: AnsibleModule) -> None:
+        if (
+            module.params["ownca_path"] is None
+            and module.params["ownca_content"] is None
+        ):
+            module.fail_json(
+                msg="One of ownca_path and ownca_content must be specified for the ownca provider."
+            )
+        if (
+            module.params["ownca_privatekey_path"] is None
+            and module.params["ownca_privatekey_content"] is None
+        ):
+            module.fail_json(
+                msg="One of ownca_privatekey_path and ownca_privatekey_content must be specified for the ownca provider."
+            )
+
+    def create_backend(
+        self, module: AnsibleModule
+    ) -> OwnCACertificateBackendCryptography:
+        return OwnCACertificateBackendCryptography(module=module)
+
+
+def add_ownca_provider_to_argument_spec(argument_spec: ArgumentSpec) -> None:
+    argument_spec.argument_spec["provider"]["choices"].append("ownca")
+    argument_spec.argument_spec.update(
+        {
+            "ownca_path": {"type": "path"},
+            "ownca_content": {"type": "str"},
+            "ownca_privatekey_path": {"type": "path"},
+            "ownca_privatekey_content": {"type": "str", "no_log": True},
+            "ownca_privatekey_passphrase": {"type": "str", "no_log": True},
+            "ownca_digest": {"type": "str", "default": "sha256"},
+            "ownca_version": {"type": "int", "default": 3, "choices": [3]},  # not used
+            "ownca_not_before": {"type": "str", "default": "+0s"},
+            "ownca_not_after": {"type": "str", "default": "+3650d"},
+            "ownca_create_subject_key_identifier": {
+                "type": "str",
+                "default": "create_if_not_provided",
+                "choices": ["create_if_not_provided", "always_create", "never_create"],
+            },
+            "ownca_create_authority_key_identifier": {"type": "bool", "default": True},
+        }
+    )
+    argument_spec.mutually_exclusive.extend(
+        [
+            ["ownca_path", "ownca_content"],
+            ["ownca_privatekey_path", "ownca_privatekey_content"],
+        ]
+    )
+
+
+__all__ = (
+    "OwnCACertificateBackendCryptography",
+    "OwnCACertificateProvider",
+    "add_ownca_provider_to_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/certificate_selfsigned.py

@@ -0,0 +1,274 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import os
+import typing as t
+from random import randrange
+
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    CRYPTOGRAPHY_TIMEZONE,
+    cryptography_key_needs_digest_for_signing,
+    cryptography_verify_certificate_signature,
+    get_not_valid_after,
+    get_not_valid_before,
+    is_potential_certificate_issuer_private_key,
+    set_not_valid_after,
+    set_not_valid_before,
+)
+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 (
+    select_message_digest,
+)
+from ansible_collections.community.crypto.plugins.module_utils._time import (
+    get_relative_time_option,
+)
+
+
+if t.TYPE_CHECKING:
+    import datetime
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+        ArgumentSpec,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        CertificateIssuerPrivateKeyTypes,
+    )
+
+
+try:
+    import cryptography
+    from cryptography import x509
+    from cryptography.hazmat.primitives.serialization import Encoding
+except ImportError:
+    pass
+
+
+class SelfSignedCertificateBackendCryptography(CertificateBackend):
+    privatekey: CertificateIssuerPrivateKeyTypes
+
+    def __init__(self, *, module: AnsibleModule) -> None:
+        super().__init__(module=module)
+
+        self.create_subject_key_identifier: t.Literal[
+            "create_if_not_provided", "always_create", "never_create"
+        ] = module.params["selfsigned_create_subject_key_identifier"]
+        self.notBefore = get_relative_time_option(
+            module.params["selfsigned_not_before"],
+            input_name="selfsigned_not_before",
+            with_timezone=CRYPTOGRAPHY_TIMEZONE,
+        )
+        self.notAfter = get_relative_time_option(
+            module.params["selfsigned_not_after"],
+            input_name="selfsigned_not_after",
+            with_timezone=CRYPTOGRAPHY_TIMEZONE,
+        )
+        self.digest = select_message_digest(module.params["selfsigned_digest"])
+        self.serial_number = x509.random_serial_number()
+
+        if self.csr_path is not None and not os.path.exists(self.csr_path):
+            raise CertificateError(
+                f"The certificate signing request file {self.csr_path} does not exist"
+            )
+        if self.privatekey_path is not None and not os.path.exists(
+            self.privatekey_path
+        ):
+            raise CertificateError(
+                f"The private key file {self.privatekey_path} does not exist"
+            )
+
+        self._module = module
+
+        self._ensure_private_key_loaded()
+        if self.privatekey is None:
+            raise CertificateError("Private key has not been provided")
+        if not is_potential_certificate_issuer_private_key(self.privatekey):
+            raise CertificateError("Private key cannot be used to sign certificates")
+
+        if cryptography_key_needs_digest_for_signing(self.privatekey):
+            if self.digest is None:
+                raise CertificateError(
+                    f"The digest {module.params['selfsigned_digest']} is not supported with the cryptography backend"
+                )
+        else:
+            self.digest = None
+
+        self._ensure_csr_loaded()
+        if self.csr is None:
+            # Create empty CSR on the fly
+            csr = cryptography.x509.CertificateSigningRequestBuilder()
+            csr = csr.subject_name(cryptography.x509.Name([]))
+            self.csr = csr.sign(self.privatekey, self.digest)
+
+    def generate_certificate(self) -> None:
+        """(Re-)Generate certificate."""
+        if self.csr is None:
+            raise AssertionError("Contract violation: csr has not been populated")
+        if self.privatekey is None:
+            raise AssertionError(
+                "Contract violation: privatekey has not been populated"
+            )
+        try:
+            cert_builder = x509.CertificateBuilder()
+            cert_builder = cert_builder.subject_name(self.csr.subject)
+            cert_builder = cert_builder.issuer_name(self.csr.subject)
+            cert_builder = cert_builder.serial_number(self.serial_number)
+            cert_builder = set_not_valid_before(cert_builder, self.notBefore)
+            cert_builder = set_not_valid_after(cert_builder, self.notAfter)
+            cert_builder = cert_builder.public_key(self.privatekey.public_key())
+            has_ski = False
+            for extension in self.csr.extensions:
+                if isinstance(extension.value, x509.SubjectKeyIdentifier):
+                    if self.create_subject_key_identifier == "always_create":
+                        continue
+                    has_ski = True
+                cert_builder = cert_builder.add_extension(
+                    extension.value, critical=extension.critical
+                )
+            if not has_ski and self.create_subject_key_identifier != "never_create":
+                cert_builder = cert_builder.add_extension(
+                    x509.SubjectKeyIdentifier.from_public_key(
+                        self.privatekey.public_key()
+                    ),
+                    critical=False,
+                )
+        except ValueError as e:
+            raise CertificateError(str(e)) from e
+
+        certificate = cert_builder.sign(
+            private_key=self.privatekey,
+            algorithm=self.digest,
+        )
+
+        self.cert = certificate
+
+    def get_certificate_data(self) -> bytes:
+        """Return bytes for self.cert."""
+        if self.cert is None:
+            raise AssertionError("Contract violation: cert has not been populated")
+        return self.cert.public_bytes(Encoding.PEM)
+
+    def needs_regeneration(
+        self,
+        *,
+        not_before: datetime.datetime | None = None,
+        not_after: datetime.datetime | None = None,
+    ) -> bool:
+        assert self.privatekey is not None
+
+        if super().needs_regeneration(
+            not_before=self.notBefore, not_after=self.notAfter
+        ):
+            return True
+
+        self._ensure_existing_certificate_loaded()
+        assert self.existing_certificate is not None
+
+        # Check whether certificate is signed by private key
+        if not cryptography_verify_certificate_signature(
+            certificate=self.existing_certificate,
+            signer_public_key=self.privatekey.public_key(),
+        ):
+            return True
+
+        return False
+
+    def dump(self, *, include_certificate: bool) -> dict[str, t.Any]:
+        result = super().dump(include_certificate=include_certificate)
+
+        if self.module.check_mode:
+            result.update(
+                {
+                    "notBefore": self.notBefore.strftime("%Y%m%d%H%M%SZ"),
+                    "notAfter": self.notAfter.strftime("%Y%m%d%H%M%SZ"),
+                    "serial_number": self.serial_number,
+                }
+            )
+        else:
+            if self.cert is None:
+                self.cert = self.existing_certificate
+            assert self.cert is not None
+            result.update(
+                {
+                    "notBefore": get_not_valid_before(self.cert).strftime(
+                        "%Y%m%d%H%M%SZ"
+                    ),
+                    "notAfter": get_not_valid_after(self.cert).strftime(
+                        "%Y%m%d%H%M%SZ"
+                    ),
+                    "serial_number": self.cert.serial_number,
+                }
+            )
+
+        return result
+
+
+def generate_serial_number() -> int:
+    """Generate a serial number for a certificate"""
+    while True:
+        result = randrange(0, 1 << 160)
+        if result >= 1000:
+            return result
+
+
+class SelfSignedCertificateProvider(CertificateProvider):
+    def validate_module_args(self, module: AnsibleModule) -> None:
+        if (
+            module.params["privatekey_path"] is None
+            and module.params["privatekey_content"] is None
+        ):
+            module.fail_json(
+                msg="One of privatekey_path and privatekey_content must be specified for the selfsigned provider."
+            )
+
+    def create_backend(
+        self, module: AnsibleModule
+    ) -> SelfSignedCertificateBackendCryptography:
+        return SelfSignedCertificateBackendCryptography(module=module)
+
+
+def add_selfsigned_provider_to_argument_spec(argument_spec: ArgumentSpec) -> None:
+    argument_spec.argument_spec["provider"]["choices"].append("selfsigned")
+    argument_spec.argument_spec.update(
+        {
+            "selfsigned_version": {
+                "type": "int",
+                "default": 3,
+                "choices": [3],
+            },  # not used
+            "selfsigned_digest": {"type": "str", "default": "sha256"},
+            "selfsigned_not_before": {
+                "type": "str",
+                "default": "+0s",
+                "aliases": ["selfsigned_notBefore"],
+            },
+            "selfsigned_not_after": {
+                "type": "str",
+                "default": "+3650d",
+                "aliases": ["selfsigned_notAfter"],
+            },
+            "selfsigned_create_subject_key_identifier": {
+                "type": "str",
+                "default": "create_if_not_provided",
+                "choices": ["create_if_not_provided", "always_create", "never_create"],
+            },
+        }
+    )
+
+
+__all__ = (
+    "SelfSignedCertificateBackendCryptography",
+    "SelfSignedCertificateProvider",
+    "add_selfsigned_provider_to_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/crl_info.py

@@ -0,0 +1,132 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_crl import (
+    TIMESTAMP_FORMAT,
+    cryptography_decode_revoked_certificate,
+    cryptography_dump_revoked,
+    cryptography_get_signature_algorithm_oid_from_crl,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    cryptography_oid_to_name,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.pem import (
+    identify_pem_format,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._filter_module import (
+        FilterModuleMock,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        PrivateKeyTypes,
+    )
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule, FilterModuleMock]
+
+
+# crypto_utils
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    from cryptography import x509
+except ImportError:
+    pass
+
+
+class CRLInfoRetrieval:
+    def __init__(
+        self,
+        *,
+        module: GeneralAnsibleModule,
+        content: bytes,
+        list_revoked_certificates: bool = True,
+    ) -> None:
+        # content must be a bytes string
+        self.module = module
+        self.content = content
+        self.list_revoked_certificates = list_revoked_certificates
+        self.name_encoding = module.params.get("name_encoding", "ignore")
+
+    def get_info(self) -> dict[str, t.Any]:
+        crl_pem = identify_pem_format(self.content)
+        try:
+            if crl_pem:
+                crl = x509.load_pem_x509_crl(self.content)
+            else:
+                crl = x509.load_der_x509_crl(self.content)
+        except ValueError as e:
+            self.module.fail_json(msg=f"Error while decoding CRL: {e}")
+
+        result: dict[str, t.Any] = {
+            "changed": False,
+            "format": "pem" if crl_pem else "der",
+            "last_update": None,
+            "next_update": None,
+            "digest": None,
+            "issuer_ordered": None,
+            "issuer": None,
+        }
+
+        result["last_update"] = crl.last_update.strftime(TIMESTAMP_FORMAT)
+        result["next_update"] = (
+            crl.next_update.strftime(TIMESTAMP_FORMAT) if crl.next_update else None
+        )
+        result["digest"] = cryptography_oid_to_name(
+            cryptography_get_signature_algorithm_oid_from_crl(crl)
+        )
+        issuer = []
+        for attribute in crl.issuer:
+            issuer.append([cryptography_oid_to_name(attribute.oid), attribute.value])
+        result["issuer_ordered"] = issuer
+        issuer_dict = {}
+        for k, v in issuer:
+            issuer_dict[k] = v
+        result["issuer"] = issuer_dict
+        if self.list_revoked_certificates:
+            result["revoked_certificates"] = []
+            for cert in crl:
+                entry = cryptography_decode_revoked_certificate(cert)
+                result["revoked_certificates"].append(
+                    cryptography_dump_revoked(entry, idn_rewrite=self.name_encoding)
+                )
+
+        return result
+
+
+def get_crl_info(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes,
+    list_revoked_certificates: bool = True,
+) -> dict[str, t.Any]:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    info = CRLInfoRetrieval(
+        module=module,
+        content=content,
+        list_revoked_certificates=list_revoked_certificates,
+    )
+    return info.get_info()
+
+
+__all__ = ("CRLInfoRetrieval", "get_crl_info")

plugins/module_utils/_crypto/module_backends/csr.py

@@ -0,0 +1,939 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import binascii
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_text
+from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+    ArgumentSpec,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLBadPassphraseError,
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_crl import (
+    REVOCATION_REASON_MAP,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    cryptography_get_basic_constraints,
+    cryptography_get_name,
+    cryptography_key_needs_digest_for_signing,
+    cryptography_name_to_oid,
+    cryptography_parse_key_usage_params,
+    cryptography_parse_relative_distinguished_name,
+    is_potential_certificate_issuer_public_key,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.module_backends.csr_info import (
+    get_csr_info,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.support import (
+    load_certificate_issuer_privatekey,
+    load_certificate_request,
+    parse_name_field,
+    parse_ordered_name_field,
+    select_message_digest,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+        CertificatePrivateKeyTypes,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        CertificateIssuerPrivateKeyTypes,
+        PrivateKeyTypes,
+    )
+
+    _ET = t.TypeVar("_ET", bound="cryptography.x509.ExtensionType")
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    import cryptography.exceptions
+    import cryptography.hazmat.backends
+    import cryptography.hazmat.primitives.hashes
+    import cryptography.hazmat.primitives.serialization
+    import cryptography.x509
+    import cryptography.x509.oid
+except ImportError:
+    pass
+
+
+class CertificateSigningRequestError(OpenSSLObjectError):
+    pass
+
+
+# From the object called `module`, only the following properties are used:
+#
+#  - module.params[]
+#  - module.warn(msg: str)
+#  - module.fail_json(msg: str, **kwargs)
+
+
+class CertificateSigningRequestBackend(metaclass=abc.ABCMeta):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        self.module = module
+        self.digest: str = module.params["digest"]
+        self.privatekey_path: str | None = module.params["privatekey_path"]
+        privatekey_content: str | None = module.params["privatekey_content"]
+        if privatekey_content is not None:
+            self.privatekey_content: bytes | None = privatekey_content.encode("utf-8")
+        else:
+            self.privatekey_content = None
+        self.privatekey_passphrase: str | None = module.params["privatekey_passphrase"]
+        self.version: t.Literal[1] = module.params["version"]
+        self.subjectAltName: list[str] | None = module.params["subject_alt_name"]
+        self.subjectAltName_critical: bool = module.params["subject_alt_name_critical"]
+        self.keyUsage: list[str] | None = module.params["key_usage"]
+        self.keyUsage_critical: bool = module.params["key_usage_critical"]
+        self.extendedKeyUsage: list[str] | None = module.params["extended_key_usage"]
+        self.extendedKeyUsage_critical: bool = module.params[
+            "extended_key_usage_critical"
+        ]
+        self.basicConstraints: list[str] | None = module.params["basic_constraints"]
+        self.basicConstraints_critical: bool = module.params[
+            "basic_constraints_critical"
+        ]
+        self.ocspMustStaple: bool = module.params["ocsp_must_staple"]
+        self.ocspMustStaple_critical: bool = module.params["ocsp_must_staple_critical"]
+        self.name_constraints_permitted: list[str] = (
+            module.params["name_constraints_permitted"] or []
+        )
+        self.name_constraints_excluded: list[str] = (
+            module.params["name_constraints_excluded"] or []
+        )
+        self.name_constraints_critical: bool = module.params[
+            "name_constraints_critical"
+        ]
+        self.create_subject_key_identifier: bool = module.params[
+            "create_subject_key_identifier"
+        ]
+        subject_key_identifier: str | None = module.params["subject_key_identifier"]
+        authority_key_identifier: str | None = module.params["authority_key_identifier"]
+        self.authority_cert_issuer: list[str] | None = module.params[
+            "authority_cert_issuer"
+        ]
+        self.authority_cert_serial_number: int = module.params[
+            "authority_cert_serial_number"
+        ]
+        self.crl_distribution_points: (
+            list[cryptography.x509.DistributionPoint] | None
+        ) = None
+        self.csr: cryptography.x509.CertificateSigningRequest | None = None
+        self.privatekey: CertificateIssuerPrivateKeyTypes | None = None
+
+        if self.create_subject_key_identifier and subject_key_identifier is not None:
+            module.fail_json(
+                msg="subject_key_identifier cannot be specified if create_subject_key_identifier is true"
+            )
+
+        self.ordered_subject = False
+        self.subject = [
+            ("C", module.params["country_name"]),
+            ("ST", module.params["state_or_province_name"]),
+            ("L", module.params["locality_name"]),
+            ("O", module.params["organization_name"]),
+            ("OU", module.params["organizational_unit_name"]),
+            ("CN", module.params["common_name"]),
+            ("emailAddress", module.params["email_address"]),
+        ]
+        self.subject = [(entry[0], entry[1]) for entry in self.subject if entry[1]]
+
+        try:
+            if module.params["subject"]:
+                self.subject = self.subject + parse_name_field(
+                    module.params["subject"], name_field_name="subject"
+                )
+            if module.params["subject_ordered"]:
+                if self.subject:
+                    raise CertificateSigningRequestError(
+                        "subject_ordered cannot be combined with any other subject field"
+                    )
+                self.subject = parse_ordered_name_field(
+                    module.params["subject_ordered"], name_field_name="subject_ordered"
+                )
+                self.ordered_subject = True
+        except ValueError as exc:
+            raise CertificateSigningRequestError(str(exc)) from exc
+
+        self.using_common_name_for_san = False
+        if not self.subjectAltName and module.params["use_common_name_for_san"]:
+            for sub in self.subject:
+                if sub[0] in ("commonName", "CN"):
+                    self.subjectAltName = [f"DNS:{sub[1]}"]
+                    self.using_common_name_for_san = True
+                    break
+
+        self.subject_key_identifier: bytes | None = None
+        if subject_key_identifier is not None:
+            try:
+                self.subject_key_identifier = binascii.unhexlify(
+                    subject_key_identifier.replace(":", "")
+                )
+            except Exception as e:
+                raise CertificateSigningRequestError(
+                    f"Cannot parse subject_key_identifier: {e}"
+                ) from e
+
+        self.authority_key_identifier: bytes | None = None
+        if authority_key_identifier is not None:
+            try:
+                self.authority_key_identifier = binascii.unhexlify(
+                    authority_key_identifier.replace(":", "")
+                )
+            except Exception as e:
+                raise CertificateSigningRequestError(
+                    f"Cannot parse authority_key_identifier: {e}"
+                ) from e
+
+        self.existing_csr: cryptography.x509.CertificateSigningRequest | None = None
+        self.existing_csr_bytes: bytes | None = None
+
+        self.diff_before = self._get_info(data=None)
+        self.diff_after = self._get_info(data=None)
+
+    def _get_info(self, *, data: bytes | None) -> dict[str, t.Any]:
+        if data is None:
+            return {}
+        try:
+            result = get_csr_info(
+                module=self.module,
+                content=data,
+                validate_signature=False,
+                prefer_one_fingerprint=True,
+            )
+            result["can_parse_csr"] = True
+            return result
+        except Exception:
+            return {"can_parse_csr": False}
+
+    @abc.abstractmethod
+    def generate_csr(self) -> None:
+        """(Re-)Generate CSR."""
+
+    @abc.abstractmethod
+    def get_csr_data(self) -> bytes:
+        """Return bytes for self.csr."""
+
+    def set_existing(self, *, csr_bytes: bytes | None) -> None:
+        """Set existing CSR bytes. None indicates that the CSR does not exist."""
+        self.existing_csr_bytes = csr_bytes
+        self.diff_after = self.diff_before = self._get_info(
+            data=self.existing_csr_bytes
+        )
+
+    def has_existing(self) -> bool:
+        """Query whether an existing CSR is/has been there."""
+        return self.existing_csr_bytes is not None
+
+    def _ensure_private_key_loaded(self) -> None:
+        """Load the provided private key into self.privatekey."""
+        if self.privatekey is not None:
+            return
+        try:
+            self.privatekey = load_certificate_issuer_privatekey(
+                path=self.privatekey_path,
+                content=self.privatekey_content,
+                passphrase=self.privatekey_passphrase,
+            )
+        except OpenSSLBadPassphraseError as exc:
+            raise CertificateSigningRequestError(exc) from exc
+
+    @abc.abstractmethod
+    def _check_csr(self) -> bool:
+        """Check whether provided parameters, assuming self.existing_csr and self.privatekey have been populated."""
+
+    def needs_regeneration(self) -> bool:
+        """Check whether a regeneration is necessary."""
+        if self.existing_csr_bytes is None:
+            return True
+        try:
+            self.existing_csr = load_certificate_request(
+                content=self.existing_csr_bytes,
+            )
+        except Exception:
+            return True
+        self._ensure_private_key_loaded()
+        return not self._check_csr()
+
+    def dump(self, *, include_csr: bool) -> dict[str, t.Any]:
+        """Serialize the object into a dictionary."""
+        result: dict[str, t.Any] = {
+            "privatekey": self.privatekey_path,
+            "subject": self.subject,
+            "subjectAltName": self.subjectAltName,
+            "keyUsage": self.keyUsage,
+            "extendedKeyUsage": self.extendedKeyUsage,
+            "basicConstraints": self.basicConstraints,
+            "ocspMustStaple": self.ocspMustStaple,
+            "name_constraints_permitted": self.name_constraints_permitted,
+            "name_constraints_excluded": self.name_constraints_excluded,
+        }
+        # Get hold of CSR bytes
+        csr_bytes = self.existing_csr_bytes
+        if self.csr is not None:
+            csr_bytes = self.get_csr_data()
+        self.diff_after = self._get_info(data=csr_bytes)
+        if include_csr:
+            # Store result
+            result["csr"] = csr_bytes.decode("utf-8") if csr_bytes else None
+
+        result["diff"] = {
+            "before": self.diff_before,
+            "after": self.diff_after,
+        }
+        return result
+
+
+def parse_crl_distribution_points(
+    *, module: AnsibleModule, crl_distribution_points: list[dict[str, t.Any]]
+) -> list[cryptography.x509.DistributionPoint]:
+    result = []
+    for index, parse_crl_distribution_point in enumerate(crl_distribution_points):
+        try:
+            full_name = None
+            relative_name = None
+            crl_issuer = None
+            reasons = None
+            if parse_crl_distribution_point["full_name"] is not None:
+                if not parse_crl_distribution_point["full_name"]:
+                    raise OpenSSLObjectError("full_name must not be empty")
+                full_name = [
+                    cryptography_get_name(name, what="full name")
+                    for name in parse_crl_distribution_point["full_name"]
+                ]
+            if parse_crl_distribution_point["relative_name"] is not None:
+                if not parse_crl_distribution_point["relative_name"]:
+                    raise OpenSSLObjectError("relative_name must not be empty")
+                relative_name = cryptography_parse_relative_distinguished_name(
+                    parse_crl_distribution_point["relative_name"]
+                )
+            if parse_crl_distribution_point["crl_issuer"] is not None:
+                if not parse_crl_distribution_point["crl_issuer"]:
+                    raise OpenSSLObjectError("crl_issuer must not be empty")
+                crl_issuer = [
+                    cryptography_get_name(name, what="CRL issuer")
+                    for name in parse_crl_distribution_point["crl_issuer"]
+                ]
+            if parse_crl_distribution_point["reasons"] is not None:
+                reasons_list = []
+                for reason in parse_crl_distribution_point["reasons"]:
+                    reasons_list.append(REVOCATION_REASON_MAP[reason])
+                reasons = frozenset(reasons_list)
+            result.append(
+                cryptography.x509.DistributionPoint(
+                    full_name=full_name,
+                    relative_name=relative_name,
+                    crl_issuer=crl_issuer,
+                    reasons=reasons,
+                )
+            )
+        except (OpenSSLObjectError, ValueError) as e:
+            raise OpenSSLObjectError(
+                f"Error while parsing CRL distribution point #{index}: {e}"
+            ) from e
+    return result
+
+
+# Implementation with using cryptography
+class CertificateSigningRequestCryptographyBackend(CertificateSigningRequestBackend):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        super().__init__(module=module)
+        if self.version != 1:
+            module.warn(
+                "The cryptography backend only supports version 1. (The only valid value according to RFC 2986.)"
+            )
+
+        crl_distribution_points: list[dict[str, t.Any]] | None = module.params[
+            "crl_distribution_points"
+        ]
+        if crl_distribution_points:
+            self.crl_distribution_points = parse_crl_distribution_points(
+                module=module, crl_distribution_points=crl_distribution_points
+            )
+
+    def generate_csr(self) -> None:
+        """(Re-)Generate CSR."""
+        self._ensure_private_key_loaded()
+        assert self.privatekey is not None
+
+        csr = cryptography.x509.CertificateSigningRequestBuilder()
+        try:
+            csr = csr.subject_name(
+                cryptography.x509.Name(
+                    [
+                        cryptography.x509.NameAttribute(
+                            cryptography_name_to_oid(entry[0]), to_text(entry[1])
+                        )
+                        for entry in self.subject
+                    ]
+                )
+            )
+        except ValueError as e:
+            raise CertificateSigningRequestError(e) from e
+
+        if self.subjectAltName:
+            csr = csr.add_extension(
+                cryptography.x509.SubjectAlternativeName(
+                    [cryptography_get_name(name) for name in self.subjectAltName]
+                ),
+                critical=self.subjectAltName_critical,
+            )
+
+        if self.keyUsage:
+            params = cryptography_parse_key_usage_params(self.keyUsage)
+            csr = csr.add_extension(
+                cryptography.x509.KeyUsage(**params), critical=self.keyUsage_critical
+            )
+
+        if self.extendedKeyUsage:
+            usages = [
+                cryptography_name_to_oid(usage) for usage in self.extendedKeyUsage
+            ]
+            csr = csr.add_extension(
+                cryptography.x509.ExtendedKeyUsage(usages),
+                critical=self.extendedKeyUsage_critical,
+            )
+
+        if self.basicConstraints:
+            params = {}
+            ca, path_length = cryptography_get_basic_constraints(self.basicConstraints)
+            csr = csr.add_extension(
+                cryptography.x509.BasicConstraints(ca, path_length),
+                critical=self.basicConstraints_critical,
+            )
+
+        if self.ocspMustStaple:
+            csr = csr.add_extension(
+                cryptography.x509.TLSFeature(
+                    [cryptography.x509.TLSFeatureType.status_request]
+                ),
+                critical=self.ocspMustStaple_critical,
+            )
+
+        if self.name_constraints_permitted or self.name_constraints_excluded:
+            try:
+                csr = csr.add_extension(
+                    cryptography.x509.NameConstraints(
+                        [
+                            cryptography_get_name(
+                                name, what="name constraints permitted"
+                            )
+                            for name in self.name_constraints_permitted
+                        ]
+                        or None,
+                        [
+                            cryptography_get_name(
+                                name, what="name constraints excluded"
+                            )
+                            for name in self.name_constraints_excluded
+                        ]
+                        or None,
+                    ),
+                    critical=self.name_constraints_critical,
+                )
+            except TypeError as e:
+                raise OpenSSLObjectError(
+                    f"Error while parsing name constraint: {e}"
+                ) from e
+
+        if self.create_subject_key_identifier:
+            if not is_potential_certificate_issuer_public_key(
+                self.privatekey.public_key()
+            ):
+                raise OpenSSLObjectError(
+                    "Private key can not be used to create subject key identifier"
+                )
+            csr = csr.add_extension(
+                cryptography.x509.SubjectKeyIdentifier.from_public_key(
+                    self.privatekey.public_key()
+                ),
+                critical=False,
+            )
+        elif self.subject_key_identifier is not None:
+            csr = csr.add_extension(
+                cryptography.x509.SubjectKeyIdentifier(self.subject_key_identifier),
+                critical=False,
+            )
+
+        if (
+            self.authority_key_identifier is not None
+            or self.authority_cert_issuer is not None
+            or self.authority_cert_serial_number is not None
+        ):
+            issuers = None
+            if self.authority_cert_issuer is not None:
+                issuers = [
+                    cryptography_get_name(n, what="authority cert issuer")
+                    for n in self.authority_cert_issuer
+                ]
+            csr = csr.add_extension(
+                cryptography.x509.AuthorityKeyIdentifier(
+                    self.authority_key_identifier,
+                    issuers,
+                    self.authority_cert_serial_number,
+                ),
+                critical=False,
+            )
+
+        if self.crl_distribution_points:
+            csr = csr.add_extension(
+                cryptography.x509.CRLDistributionPoints(self.crl_distribution_points),
+                critical=False,
+            )
+
+        # csr.sign() does not accept some digests we theoretically could have in digest.
+        # For that reason we use type t.Any here. csr.sign() will complain if
+        # the digest is not acceptable.
+        digest: t.Any | None = None
+        if cryptography_key_needs_digest_for_signing(self.privatekey):
+            digest = select_message_digest(self.digest)
+            if digest is None:
+                raise CertificateSigningRequestError(
+                    f'Unsupported digest "{self.digest}"'
+                )
+        try:
+            self.csr = csr.sign(self.privatekey, digest)
+        except UnicodeError as e:
+            # This catches IDNAErrors, which happens when a bad name is passed as a SAN
+            # (https://github.com/ansible-collections/community.crypto/issues/105).
+            # For older cryptography versions, this is handled by idna, which raises
+            # an idna.core.IDNAError. Later versions of cryptography deprecated and stopped
+            # requiring idna, whence we cannot easily handle this error. Fortunately, in
+            # most versions of idna, IDNAError extends UnicodeError. There is only version
+            # 2.3 where it extends Exception instead (see
+            # https://github.com/kjd/idna/commit/ebefacd3134d0f5da4745878620a6a1cba86d130
+            # and then
+            # https://github.com/kjd/idna/commit/ea03c7b5db7d2a99af082e0239da2b68aeea702a).
+            msg = f"Error while creating CSR: {e}\n"
+            if self.using_common_name_for_san:
+                self.module.fail_json(
+                    msg=msg
+                    + "This is probably caused because the Common Name is used as a SAN."
+                    " Specifying use_common_name_for_san=false might fix this."
+                )
+            self.module.fail_json(
+                msg=msg
+                + "This is probably caused by an invalid Subject Alternative DNS Name."
+            )
+
+    def get_csr_data(self) -> bytes:
+        """Return bytes for self.csr."""
+        if self.csr is None:
+            raise AssertionError("Violated contract: csr is not populated")
+        return self.csr.public_bytes(
+            cryptography.hazmat.primitives.serialization.Encoding.PEM
+        )
+
+    def _check_csr(self) -> bool:
+        """Check whether provided parameters, assuming self.existing_csr and self.privatekey have been populated."""
+        if self.existing_csr is None:
+            raise AssertionError("Violated contract: existing_csr is not populated")
+        if self.privatekey is None:
+            raise AssertionError("Violated contract: privatekey is not populated")
+
+        def _check_subject(csr: cryptography.x509.CertificateSigningRequest) -> bool:
+            subject = [
+                (cryptography_name_to_oid(entry[0]), to_text(entry[1]))
+                for entry in self.subject
+            ]
+            current_subject = [(sub.oid, sub.value) for sub in csr.subject]
+            if self.ordered_subject:
+                return subject == current_subject
+            return set(subject) == set(current_subject)
+
+        def _find_extension(
+            extensions: cryptography.x509.Extensions, exttype: type[_ET]
+        ) -> cryptography.x509.Extension[_ET] | None:
+            return next(
+                (ext for ext in extensions if isinstance(ext.value, exttype)), None
+            )
+
+        def _check_subjectAltName(extensions: cryptography.x509.Extensions) -> bool:
+            current_altnames_ext = _find_extension(
+                extensions, cryptography.x509.SubjectAlternativeName
+            )
+            current_altnames = (
+                [to_text(altname) for altname in current_altnames_ext.value]
+                if current_altnames_ext
+                else []
+            )
+            altnames = (
+                [
+                    to_text(cryptography_get_name(altname))
+                    for altname in self.subjectAltName
+                ]
+                if self.subjectAltName
+                else []
+            )
+            if set(altnames) != set(current_altnames):
+                return False
+            if altnames and current_altnames_ext:
+                if current_altnames_ext.critical != self.subjectAltName_critical:
+                    return False
+            return True
+
+        def _check_keyUsage(extensions: cryptography.x509.Extensions) -> bool:
+            current_keyusage_ext = _find_extension(
+                extensions, cryptography.x509.KeyUsage
+            )
+            if not self.keyUsage:
+                return current_keyusage_ext is None
+            if current_keyusage_ext is None:
+                return False
+            params = cryptography_parse_key_usage_params(self.keyUsage)
+            for param, value in params.items():
+                # TODO: check whether getattr() with '_' prepended is really needed
+                if getattr(current_keyusage_ext.value, "_" + param) != value:
+                    return False
+            return current_keyusage_ext.critical == self.keyUsage_critical
+
+        def _check_extenededKeyUsage(extensions: cryptography.x509.Extensions) -> bool:
+            current_usages_ext = _find_extension(
+                extensions, cryptography.x509.ExtendedKeyUsage
+            )
+            current_usages = (
+                [str(usage) for usage in current_usages_ext.value]
+                if current_usages_ext
+                else []
+            )
+            usages = (
+                [
+                    str(cryptography_name_to_oid(usage))
+                    for usage in self.extendedKeyUsage
+                ]
+                if self.extendedKeyUsage
+                else []
+            )
+            if set(current_usages) != set(usages):
+                return False
+            if usages and current_usages_ext:
+                if current_usages_ext.critical != self.extendedKeyUsage_critical:
+                    return False
+            return True
+
+        def _check_basicConstraints(extensions: cryptography.x509.Extensions) -> bool:
+            bc_ext = _find_extension(extensions, cryptography.x509.BasicConstraints)
+            current_ca = bc_ext.value.ca if bc_ext else False
+            current_path_length = bc_ext.value.path_length if bc_ext else None
+            ca, path_length = cryptography_get_basic_constraints(self.basicConstraints)
+            # Check CA flag
+            if ca != current_ca:
+                return False
+            # Check path length
+            if path_length != current_path_length:
+                return False
+            # Check criticality
+            if self.basicConstraints:
+                return (
+                    bc_ext is not None
+                    and bc_ext.critical == self.basicConstraints_critical
+                )
+            return bc_ext is None
+
+        def _check_ocspMustStaple(extensions: cryptography.x509.Extensions) -> bool:
+            tlsfeature_ext = _find_extension(extensions, cryptography.x509.TLSFeature)
+            if self.ocspMustStaple:
+                if (
+                    not tlsfeature_ext
+                    or tlsfeature_ext.critical != self.ocspMustStaple_critical
+                ):
+                    return False
+                return (
+                    cryptography.x509.TLSFeatureType.status_request
+                    in tlsfeature_ext.value
+                )
+            return tlsfeature_ext is None
+
+        def _check_nameConstraints(extensions: cryptography.x509.Extensions) -> bool:
+            current_nc_ext = _find_extension(
+                extensions, cryptography.x509.NameConstraints
+            )
+            current_nc_perm = (
+                [
+                    to_text(altname)
+                    for altname in current_nc_ext.value.permitted_subtrees or []
+                ]
+                if current_nc_ext
+                else []
+            )
+            current_nc_excl = (
+                [
+                    to_text(altname)
+                    for altname in current_nc_ext.value.excluded_subtrees or []
+                ]
+                if current_nc_ext
+                else []
+            )
+            nc_perm = [
+                to_text(
+                    cryptography_get_name(altname, what="name constraints permitted")
+                )
+                for altname in self.name_constraints_permitted
+            ]
+            nc_excl = [
+                to_text(
+                    cryptography_get_name(altname, what="name constraints excluded")
+                )
+                for altname in self.name_constraints_excluded
+            ]
+            if set(nc_perm) != set(current_nc_perm) or set(nc_excl) != set(
+                current_nc_excl
+            ):
+                return False
+            if (nc_perm or nc_excl) and current_nc_ext:
+                if current_nc_ext.critical != self.name_constraints_critical:
+                    return False
+            return True
+
+        def _check_subject_key_identifier(
+            extensions: cryptography.x509.Extensions,
+        ) -> bool:
+            ext = _find_extension(extensions, cryptography.x509.SubjectKeyIdentifier)
+            if (
+                self.create_subject_key_identifier
+                or self.subject_key_identifier is not None
+            ):
+                if not ext or ext.critical:
+                    return False
+                if self.create_subject_key_identifier:
+                    assert self.privatekey is not None
+                    digest = cryptography.x509.SubjectKeyIdentifier.from_public_key(
+                        self.privatekey.public_key()
+                    ).digest
+                    return ext.value.digest == digest
+                return ext.value.digest == self.subject_key_identifier
+            return ext is None
+
+        def _check_authority_key_identifier(
+            extensions: cryptography.x509.Extensions,
+        ) -> bool:
+            ext = _find_extension(extensions, cryptography.x509.AuthorityKeyIdentifier)
+            if (
+                self.authority_key_identifier is not None
+                or self.authority_cert_issuer is not None
+                or self.authority_cert_serial_number is not None
+            ):
+                if not ext or ext.critical:
+                    return False
+                aci = None
+                csr_aci = None
+                if self.authority_cert_issuer is not None:
+                    aci = [
+                        to_text(cryptography_get_name(n, what="authority cert issuer"))
+                        for n in self.authority_cert_issuer
+                    ]
+                if ext.value.authority_cert_issuer is not None:
+                    csr_aci = [to_text(n) for n in ext.value.authority_cert_issuer]
+                return (
+                    ext.value.key_identifier == self.authority_key_identifier
+                    and csr_aci == aci
+                    and ext.value.authority_cert_serial_number
+                    == self.authority_cert_serial_number
+                )
+            return ext is None
+
+        def _check_crl_distribution_points(
+            extensions: cryptography.x509.Extensions,
+        ) -> bool:
+            ext = _find_extension(extensions, cryptography.x509.CRLDistributionPoints)
+            if self.crl_distribution_points is None:
+                return ext is None
+            if not ext:
+                return False
+            return list(ext.value) == self.crl_distribution_points
+
+        def _check_extensions(csr: cryptography.x509.CertificateSigningRequest) -> bool:
+            extensions = csr.extensions
+            return (
+                _check_subjectAltName(extensions)
+                and _check_keyUsage(extensions)
+                and _check_extenededKeyUsage(extensions)
+                and _check_basicConstraints(extensions)
+                and _check_ocspMustStaple(extensions)
+                and _check_subject_key_identifier(extensions)
+                and _check_authority_key_identifier(extensions)
+                and _check_nameConstraints(extensions)
+                and _check_crl_distribution_points(extensions)
+            )
+
+        def _check_signature(csr: cryptography.x509.CertificateSigningRequest) -> bool:
+            if not csr.is_signature_valid:
+                return False
+            # To check whether public key of CSR belongs to private key,
+            # encode both public keys and compare PEMs.
+            key_a = csr.public_key().public_bytes(
+                cryptography.hazmat.primitives.serialization.Encoding.PEM,
+                cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo,
+            )
+            assert self.privatekey is not None
+            key_b = self.privatekey.public_key().public_bytes(
+                cryptography.hazmat.primitives.serialization.Encoding.PEM,
+                cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo,
+            )
+            return key_a == key_b
+
+        return (
+            _check_subject(self.existing_csr)
+            and _check_extensions(self.existing_csr)
+            and _check_signature(self.existing_csr)
+        )
+
+
+def select_backend(
+    module: AnsibleModule,
+) -> CertificateSigningRequestCryptographyBackend:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return CertificateSigningRequestCryptographyBackend(module=module)
+
+
+def get_csr_argument_spec() -> ArgumentSpec:
+    return ArgumentSpec(
+        argument_spec={
+            "digest": {"type": "str", "default": "sha256"},
+            "privatekey_path": {"type": "path"},
+            "privatekey_content": {"type": "str", "no_log": True},
+            "privatekey_passphrase": {"type": "str", "no_log": True},
+            "version": {"type": "int", "default": 1, "choices": [1]},
+            "subject": {"type": "dict"},
+            "subject_ordered": {"type": "list", "elements": "dict"},
+            "country_name": {"type": "str", "aliases": ["C", "countryName"]},
+            "state_or_province_name": {
+                "type": "str",
+                "aliases": ["ST", "stateOrProvinceName"],
+            },
+            "locality_name": {"type": "str", "aliases": ["L", "localityName"]},
+            "organization_name": {"type": "str", "aliases": ["O", "organizationName"]},
+            "organizational_unit_name": {
+                "type": "str",
+                "aliases": ["OU", "organizationalUnitName"],
+            },
+            "common_name": {"type": "str", "aliases": ["CN", "commonName"]},
+            "email_address": {"type": "str", "aliases": ["E", "emailAddress"]},
+            "subject_alt_name": {
+                "type": "list",
+                "elements": "str",
+                "aliases": ["subjectAltName"],
+            },
+            "subject_alt_name_critical": {
+                "type": "bool",
+                "default": False,
+                "aliases": ["subjectAltName_critical"],
+            },
+            "use_common_name_for_san": {
+                "type": "bool",
+                "default": True,
+                "aliases": ["useCommonNameForSAN"],
+            },
+            "key_usage": {"type": "list", "elements": "str", "aliases": ["keyUsage"]},
+            "key_usage_critical": {
+                "type": "bool",
+                "default": False,
+                "aliases": ["keyUsage_critical"],
+            },
+            "extended_key_usage": {
+                "type": "list",
+                "elements": "str",
+                "aliases": ["extKeyUsage", "extendedKeyUsage"],
+            },
+            "extended_key_usage_critical": {
+                "type": "bool",
+                "default": False,
+                "aliases": ["extKeyUsage_critical", "extendedKeyUsage_critical"],
+            },
+            "basic_constraints": {
+                "type": "list",
+                "elements": "str",
+                "aliases": ["basicConstraints"],
+            },
+            "basic_constraints_critical": {
+                "type": "bool",
+                "default": False,
+                "aliases": ["basicConstraints_critical"],
+            },
+            "ocsp_must_staple": {
+                "type": "bool",
+                "default": False,
+                "aliases": ["ocspMustStaple"],
+            },
+            "ocsp_must_staple_critical": {
+                "type": "bool",
+                "default": False,
+                "aliases": ["ocspMustStaple_critical"],
+            },
+            "name_constraints_permitted": {"type": "list", "elements": "str"},
+            "name_constraints_excluded": {"type": "list", "elements": "str"},
+            "name_constraints_critical": {"type": "bool", "default": False},
+            "create_subject_key_identifier": {"type": "bool", "default": False},
+            "subject_key_identifier": {"type": "str"},
+            "authority_key_identifier": {"type": "str"},
+            "authority_cert_issuer": {"type": "list", "elements": "str"},
+            "authority_cert_serial_number": {"type": "int"},
+            "crl_distribution_points": {
+                "type": "list",
+                "elements": "dict",
+                "options": {
+                    "full_name": {"type": "list", "elements": "str"},
+                    "relative_name": {"type": "list", "elements": "str"},
+                    "crl_issuer": {"type": "list", "elements": "str"},
+                    "reasons": {
+                        "type": "list",
+                        "elements": "str",
+                        "choices": [
+                            "key_compromise",
+                            "ca_compromise",
+                            "affiliation_changed",
+                            "superseded",
+                            "cessation_of_operation",
+                            "certificate_hold",
+                            "privilege_withdrawn",
+                            "aa_compromise",
+                        ],
+                    },
+                },
+                "mutually_exclusive": [("full_name", "relative_name")],
+                "required_one_of": [("full_name", "relative_name", "crl_issuer")],
+            },
+            "select_crypto_backend": {
+                "type": "str",
+                "default": "auto",
+                "choices": ["auto", "cryptography"],
+            },
+        },
+        required_together=[
+            ["authority_cert_issuer", "authority_cert_serial_number"],
+        ],
+        mutually_exclusive=[
+            ["privatekey_path", "privatekey_content"],
+            ["subject", "subject_ordered"],
+        ],
+        required_one_of=[
+            ["privatekey_path", "privatekey_content"],
+        ],
+    )
+
+
+__all__ = (
+    "CertificateSigningRequestError",
+    "CertificateSigningRequestBackend",
+    "select_backend",
+    "get_csr_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/csr_info.py

@@ -0,0 +1,399 @@
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import binascii
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_text
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    cryptography_decode_name,
+    cryptography_get_extensions_from_csr,
+    cryptography_oid_to_name,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.module_backends.publickey_info import (
+    get_publickey_info,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.support import (
+    load_certificate_request,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._filter_module import (
+        FilterModuleMock,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        CertificatePublicKeyTypes,
+        PrivateKeyTypes,
+    )
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule, FilterModuleMock]
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    from cryptography import x509
+    from cryptography.hazmat.primitives import serialization
+except ImportError:
+    pass
+
+
+TIMESTAMP_FORMAT = "%Y%m%d%H%M%SZ"
+
+
+class CSRInfoRetrieval(metaclass=abc.ABCMeta):
+    csr: x509.CertificateSigningRequest
+
+    def __init__(
+        self, *, module: GeneralAnsibleModule, content: bytes, validate_signature: bool
+    ) -> None:
+        self.module = module
+        self.content = content
+        self.validate_signature = validate_signature
+
+    @abc.abstractmethod
+    def _get_subject_ordered(self) -> list[list[str]]:
+        pass
+
+    @abc.abstractmethod
+    def _get_key_usage(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_extended_key_usage(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_basic_constraints(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_ocsp_must_staple(self) -> tuple[bool | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_subject_alt_name(self) -> tuple[list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_name_constraints(self) -> tuple[list[str] | None, list[str] | None, bool]:
+        pass
+
+    @abc.abstractmethod
+    def _get_public_key_pem(self) -> bytes:
+        pass
+
+    @abc.abstractmethod
+    def _get_public_key_object(self) -> CertificatePublicKeyTypes:
+        pass
+
+    @abc.abstractmethod
+    def _get_subject_key_identifier(self) -> bytes | None:
+        pass
+
+    @abc.abstractmethod
+    def _get_authority_key_identifier(
+        self,
+    ) -> tuple[bytes | None, list[str] | None, int | None]:
+        pass
+
+    @abc.abstractmethod
+    def _get_all_extensions(self) -> dict[str, dict[str, bool | str]]:
+        pass
+
+    @abc.abstractmethod
+    def _is_signature_valid(self) -> bool:
+        pass
+
+    def get_info(self, *, prefer_one_fingerprint: bool = False) -> dict[str, t.Any]:
+        result: dict[str, t.Any] = {}
+        self.csr = load_certificate_request(
+            content=self.content,
+        )
+
+        subject = self._get_subject_ordered()
+        result["subject"] = {}
+        for k, v in subject:
+            result["subject"][k] = v
+        result["subject_ordered"] = subject
+        result["key_usage"], result["key_usage_critical"] = self._get_key_usage()
+        result["extended_key_usage"], result["extended_key_usage_critical"] = (
+            self._get_extended_key_usage()
+        )
+        result["basic_constraints"], result["basic_constraints_critical"] = (
+            self._get_basic_constraints()
+        )
+        result["ocsp_must_staple"], result["ocsp_must_staple_critical"] = (
+            self._get_ocsp_must_staple()
+        )
+        result["subject_alt_name"], result["subject_alt_name_critical"] = (
+            self._get_subject_alt_name()
+        )
+        (
+            result["name_constraints_permitted"],
+            result["name_constraints_excluded"],
+            result["name_constraints_critical"],
+        ) = self._get_name_constraints()
+
+        result["public_key"] = to_text(self._get_public_key_pem())
+
+        public_key_info = get_publickey_info(
+            module=self.module,
+            key=self._get_public_key_object(),
+            prefer_one_fingerprint=prefer_one_fingerprint,
+        )
+        result.update(
+            {
+                "public_key_type": public_key_info["type"],
+                "public_key_data": public_key_info["public_data"],
+                "public_key_fingerprints": public_key_info["fingerprints"],
+            }
+        )
+
+        ski_bytes = self._get_subject_key_identifier()
+        ski = None
+        if ski_bytes is not None:
+            ski = binascii.hexlify(ski_bytes).decode("ascii")
+            ski = ":".join([ski[i : i + 2] for i in range(0, len(ski), 2)])
+        result["subject_key_identifier"] = ski
+
+        aki_bytes, aci, acsn = self._get_authority_key_identifier()
+        aki = None
+        if aki_bytes is not None:
+            aki = binascii.hexlify(aki_bytes).decode("ascii")
+            aki = ":".join([aki[i : i + 2] for i in range(0, len(aki), 2)])
+        result["authority_key_identifier"] = aki
+        result["authority_cert_issuer"] = aci
+        result["authority_cert_serial_number"] = acsn
+
+        result["extensions_by_oid"] = self._get_all_extensions()
+
+        result["signature_valid"] = self._is_signature_valid()
+        if self.validate_signature and not result["signature_valid"]:
+            self.module.fail_json(msg="CSR signature is invalid!", **result)
+        return result
+
+
+class CSRInfoRetrievalCryptography(CSRInfoRetrieval):
+    """Validate the supplied CSR, using the cryptography backend"""
+
+    def __init__(
+        self, *, module: GeneralAnsibleModule, content: bytes, validate_signature: bool
+    ) -> None:
+        super().__init__(
+            module=module, content=content, validate_signature=validate_signature
+        )
+        self.name_encoding: t.Literal["ignore", "idna", "unicode"] = module.params.get(
+            "name_encoding", "ignore"
+        )
+
+    def _get_subject_ordered(self) -> list[list[str]]:
+        result: list[list[str]] = []
+        for attribute in self.csr.subject:
+            result.append(
+                [cryptography_oid_to_name(attribute.oid), to_text(attribute.value)]
+            )
+        return result
+
+    def _get_key_usage(self) -> tuple[list[str] | None, bool]:
+        try:
+            current_key_ext = self.csr.extensions.get_extension_for_class(x509.KeyUsage)
+            current_key_usage = current_key_ext.value
+            key_usage = {
+                "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 key_usage["key_agreement"]:
+                key_usage.update(
+                    {
+                        "encipher_only": current_key_usage.encipher_only,
+                        "decipher_only": current_key_usage.decipher_only,
+                    }
+                )
+
+            key_usage_names = {
+                "digital_signature": "Digital Signature",
+                "content_commitment": "Non Repudiation",
+                "key_encipherment": "Key Encipherment",
+                "data_encipherment": "Data Encipherment",
+                "key_agreement": "Key Agreement",
+                "key_cert_sign": "Certificate Sign",
+                "crl_sign": "CRL Sign",
+                "encipher_only": "Encipher Only",
+                "decipher_only": "Decipher Only",
+            }
+            return (
+                sorted(
+                    [
+                        key_usage_names[name]
+                        for name, value in key_usage.items()
+                        if value
+                    ]
+                ),
+                current_key_ext.critical,
+            )
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_extended_key_usage(self) -> tuple[list[str] | None, bool]:
+        try:
+            ext_keyusage_ext = self.csr.extensions.get_extension_for_class(
+                x509.ExtendedKeyUsage
+            )
+            return (
+                sorted(
+                    [cryptography_oid_to_name(eku) for eku in ext_keyusage_ext.value]
+                ),
+                ext_keyusage_ext.critical,
+            )
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_basic_constraints(self) -> tuple[list[str] | None, bool]:
+        try:
+            ext_keyusage_ext = self.csr.extensions.get_extension_for_class(
+                x509.BasicConstraints
+            )
+            result = [f"CA:{'TRUE' if ext_keyusage_ext.value.ca else 'FALSE'}"]
+            if ext_keyusage_ext.value.path_length is not None:
+                result.append(f"pathlen:{ext_keyusage_ext.value.path_length}")
+            return sorted(result), ext_keyusage_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_ocsp_must_staple(self) -> tuple[bool | None, bool]:
+        try:
+            # This only works with cryptography >= 2.1
+            tlsfeature_ext = self.csr.extensions.get_extension_for_class(
+                x509.TLSFeature
+            )
+            value = (
+                cryptography.x509.TLSFeatureType.status_request in tlsfeature_ext.value
+            )
+            return value, tlsfeature_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_subject_alt_name(self) -> tuple[list[str] | None, bool]:
+        try:
+            san_ext = self.csr.extensions.get_extension_for_class(
+                x509.SubjectAlternativeName
+            )
+            result = [
+                cryptography_decode_name(san, idn_rewrite=self.name_encoding)
+                for san in san_ext.value
+            ]
+            return result, san_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, False
+
+    def _get_name_constraints(self) -> tuple[list[str] | None, list[str] | None, bool]:
+        try:
+            nc_ext = self.csr.extensions.get_extension_for_class(x509.NameConstraints)
+            permitted = [
+                cryptography_decode_name(san, idn_rewrite=self.name_encoding)
+                for san in nc_ext.value.permitted_subtrees or []
+            ]
+            excluded = [
+                cryptography_decode_name(san, idn_rewrite=self.name_encoding)
+                for san in nc_ext.value.excluded_subtrees or []
+            ]
+            return permitted, excluded, nc_ext.critical
+        except cryptography.x509.ExtensionNotFound:
+            return None, None, False
+
+    def _get_public_key_pem(self) -> bytes:
+        return self.csr.public_key().public_bytes(
+            serialization.Encoding.PEM,
+            serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+
+    def _get_public_key_object(self) -> CertificatePublicKeyTypes:
+        return self.csr.public_key()
+
+    def _get_subject_key_identifier(self) -> bytes | None:
+        try:
+            ext = self.csr.extensions.get_extension_for_class(x509.SubjectKeyIdentifier)
+            return ext.value.digest
+        except cryptography.x509.ExtensionNotFound:
+            return None
+
+    def _get_authority_key_identifier(
+        self,
+    ) -> tuple[bytes | None, list[str] | None, int | None]:
+        try:
+            ext = self.csr.extensions.get_extension_for_class(
+                x509.AuthorityKeyIdentifier
+            )
+            issuer = None
+            if ext.value.authority_cert_issuer is not None:
+                issuer = [
+                    cryptography_decode_name(san, idn_rewrite=self.name_encoding)
+                    for san in ext.value.authority_cert_issuer
+                ]
+            return (
+                ext.value.key_identifier,
+                issuer,
+                ext.value.authority_cert_serial_number,
+            )
+        except cryptography.x509.ExtensionNotFound:
+            return None, None, None
+
+    def _get_all_extensions(self) -> dict[str, dict[str, bool | str]]:
+        return cryptography_get_extensions_from_csr(self.csr)
+
+    def _is_signature_valid(self) -> bool:
+        return self.csr.is_signature_valid
+
+
+def get_csr_info(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes,
+    validate_signature: bool = True,
+    prefer_one_fingerprint: bool = False,
+) -> dict[str, t.Any]:
+    info = CSRInfoRetrievalCryptography(
+        module=module, content=content, validate_signature=validate_signature
+    )
+    return info.get_info(prefer_one_fingerprint=prefer_one_fingerprint)
+
+
+def select_backend(
+    *, module: GeneralAnsibleModule, content: bytes, validate_signature: bool = True
+) -> CSRInfoRetrieval:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return CSRInfoRetrievalCryptography(
+        module=module, content=content, validate_signature=validate_signature
+    )
+
+
+__all__ = ("CSRInfoRetrieval", "get_csr_info", "select_backend")

plugins/module_utils/_crypto/module_backends/privatekey.py

@@ -0,0 +1,676 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import base64
+import traceback
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes
+from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+    ArgumentSpec,
+)
+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 (
+    PrivateKeyConsistencyError,
+    PrivateKeyParseError,
+    get_privatekey_info,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.pem import (
+    identify_private_key_format,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.support import (
+    get_fingerprint_of_privatekey,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        PrivateKeyTypes,
+    )
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule]
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    import cryptography.exceptions
+    import cryptography.hazmat.backends
+    import cryptography.hazmat.primitives.asymmetric.dsa
+    import cryptography.hazmat.primitives.asymmetric.ec
+    import cryptography.hazmat.primitives.asymmetric.ed448
+    import cryptography.hazmat.primitives.asymmetric.ed25519
+    import cryptography.hazmat.primitives.asymmetric.rsa
+    import cryptography.hazmat.primitives.asymmetric.utils
+    import cryptography.hazmat.primitives.asymmetric.x448
+    import cryptography.hazmat.primitives.asymmetric.x25519
+    import cryptography.hazmat.primitives.serialization
+except ImportError:
+    pass
+
+
+class PrivateKeyError(OpenSSLObjectError):
+    pass
+
+
+# From the object called `module`, only the following properties are used:
+#
+#  - module.params[]
+#  - module.warn(msg: str)
+#  - module.fail_json(msg: str, **kwargs)
+
+
+class PrivateKeyBackend(metaclass=abc.ABCMeta):
+    def __init__(self, *, module: GeneralAnsibleModule) -> None:
+        self.module = module
+        self.type: t.Literal[
+            "DSA", "ECC", "Ed25519", "Ed448", "RSA", "X25519", "X448"
+        ] = module.params["type"]
+        self.size: int = module.params["size"]
+        self.curve: str | None = module.params["curve"]
+        self.passphrase: str | None = module.params["passphrase"]
+        self.cipher: str = module.params["cipher"]
+        self.format: t.Literal["pkcs1", "pkcs8", "raw", "auto", "auto_ignore"] = (
+            module.params["format"]
+        )
+        self.format_mismatch: t.Literal["regenerate", "convert"] = module.params.get(
+            "format_mismatch", "regenerate"
+        )
+        self.regenerate: t.Literal[
+            "never", "fail", "partial_idempotence", "full_idempotence", "always"
+        ] = module.params.get("regenerate", "full_idempotence")
+
+        self.private_key: PrivateKeyTypes | None = None
+
+        self.existing_private_key: PrivateKeyTypes | None = None
+        self.existing_private_key_bytes: bytes | None = None
+
+        self.diff_before = self._get_info(data=None)
+        self.diff_after = self._get_info(data=None)
+
+    def _get_info(self, *, data: bytes | None) -> dict[str, t.Any]:
+        if data is None:
+            return {}
+        result: dict[str, t.Any] = {"can_parse_key": False}
+        try:
+            result.update(
+                get_privatekey_info(
+                    module=self.module,
+                    content=data,
+                    passphrase=self.passphrase,
+                    return_private_key_data=False,
+                    prefer_one_fingerprint=True,
+                )
+            )
+        except PrivateKeyConsistencyError as exc:
+            result.update(exc.result)
+        except PrivateKeyParseError as exc:
+            result.update(exc.result)
+        except Exception:
+            pass
+        return result
+
+    @abc.abstractmethod
+    def generate_private_key(self) -> None:
+        """(Re-)Generate private key."""
+
+    def convert_private_key(self) -> None:
+        """Convert existing private key (self.existing_private_key) to new private key (self.private_key).
+
+        This is effectively a copy without active conversion. The conversion is done
+        during load and store; get_private_key_data() uses the destination format to
+        serialize the key.
+        """
+        self._ensure_existing_private_key_loaded()
+        self.private_key = self.existing_private_key
+
+    @abc.abstractmethod
+    def get_private_key_data(self) -> bytes:
+        """Return bytes for self.private_key."""
+
+    def set_existing(self, *, privatekey_bytes: bytes | None) -> None:
+        """Set existing private key bytes. None indicates that the key does not exist."""
+        self.existing_private_key_bytes = privatekey_bytes
+        self.diff_after = self.diff_before = self._get_info(
+            data=self.existing_private_key_bytes
+        )
+
+    def has_existing(self) -> bool:
+        """Query whether an existing private key is/has been there."""
+        return self.existing_private_key_bytes is not None
+
+    @abc.abstractmethod
+    def _check_passphrase(self) -> bool:
+        """Check whether provided passphrase matches, assuming self.existing_private_key_bytes has been populated."""
+
+    @abc.abstractmethod
+    def _ensure_existing_private_key_loaded(self) -> None:
+        """Make sure that self.existing_private_key is populated from self.existing_private_key_bytes."""
+
+    @abc.abstractmethod
+    def _check_size_and_type(self) -> bool:
+        """Check whether provided size and type matches, assuming self.existing_private_key has been populated."""
+
+    @abc.abstractmethod
+    def _check_format(self) -> bool:
+        """Check whether the key file format, assuming self.existing_private_key and self.existing_private_key_bytes has been populated."""
+
+    def needs_regeneration(self) -> bool:
+        """Check whether a regeneration is necessary."""
+        if self.regenerate == "always":
+            return True
+        if not self.has_existing():
+            # key does not exist
+            return True
+        if not self._check_passphrase():
+            if self.regenerate == "full_idempotence":
+                return True
+            self.module.fail_json(
+                msg="Unable to read the key. The key is protected with a another passphrase / no passphrase or broken."
+                " Will not proceed. To force regeneration, call the module with `generate`"
+                " set to `full_idempotence` or `always`, or with `force=true`."
+            )
+        self._ensure_existing_private_key_loaded()
+        if self.regenerate != "never":
+            if not self._check_size_and_type():
+                if self.regenerate in ("partial_idempotence", "full_idempotence"):
+                    return True
+                self.module.fail_json(
+                    msg="Key has wrong type and/or size."
+                    " Will not proceed. To force regeneration, call the module with `generate`"
+                    " set to `partial_idempotence`, `full_idempotence` or `always`, or with `force=true`."
+                )
+        # During generation step, regenerate if format does not match and format_mismatch == 'regenerate'
+        if self.format_mismatch == "regenerate" and self.regenerate != "never":
+            if not self._check_format():
+                if self.regenerate in ("partial_idempotence", "full_idempotence"):
+                    return True
+                self.module.fail_json(
+                    msg="Key has wrong format."
+                    " Will not proceed. To force regeneration, call the module with `generate`"
+                    " set to `partial_idempotence`, `full_idempotence` or `always`, or with `force=true`."
+                    " To convert the key, set `format_mismatch` to `convert`."
+                )
+        return False
+
+    def needs_conversion(self) -> bool:
+        """Check whether a conversion is necessary. Must only be called if needs_regeneration() returned False."""
+        # During conversion step, convert if format does not match and format_mismatch == 'convert'
+        self._ensure_existing_private_key_loaded()
+        return (
+            self.has_existing()
+            and self.format_mismatch == "convert"
+            and not self._check_format()
+        )
+
+    def _get_fingerprint(self) -> dict[str, str] | None:
+        if self.private_key:
+            return get_fingerprint_of_privatekey(self.private_key)
+        try:
+            self._ensure_existing_private_key_loaded()
+        except Exception:
+            # Ignore errors
+            pass
+        if self.existing_private_key:
+            return get_fingerprint_of_privatekey(self.existing_private_key)
+        return None
+
+    def dump(self, *, include_key: bool) -> dict[str, t.Any]:
+        """Serialize the object into a dictionary."""
+
+        if not self.private_key:
+            try:
+                self._ensure_existing_private_key_loaded()
+            except Exception:
+                # Ignore errors
+                pass
+        result: dict[str, t.Any] = {
+            "type": self.type,
+            "size": self.size,
+            "fingerprint": self._get_fingerprint(),
+        }
+        if self.type == "ECC":
+            result["curve"] = self.curve
+        # Get hold of private key bytes
+        pk_bytes = self.existing_private_key_bytes
+        if self.private_key is not None:
+            pk_bytes = self.get_private_key_data()
+        self.diff_after = self._get_info(data=pk_bytes)
+        if include_key:
+            # Store result
+            if pk_bytes:
+                if identify_private_key_format(pk_bytes) == "raw":
+                    result["privatekey"] = base64.b64encode(pk_bytes)
+                else:
+                    result["privatekey"] = pk_bytes.decode("utf-8")
+            else:
+                result["privatekey"] = None
+
+        result["diff"] = {
+            "before": self.diff_before,
+            "after": self.diff_after,
+        }
+        return result
+
+
+class _Curve:
+    def __init__(
+        self,
+        *,
+        name: str,
+        ectype: str,
+        deprecated: bool,
+    ) -> None:
+        self.name = name
+        self.ectype = ectype
+        self.deprecated = deprecated
+
+    def _get_ec_class(
+        self, *, module: GeneralAnsibleModule
+    ) -> type[cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve]:
+        ecclass = cryptography.hazmat.primitives.asymmetric.ec.__dict__.get(self.ectype)  # type: ignore
+        if ecclass is None:
+            module.fail_json(
+                msg=f"Your cryptography version does not support {self.ectype}"
+            )
+        return ecclass
+
+    def create(
+        self, *, size: int, module: GeneralAnsibleModule
+    ) -> cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve:
+        ecclass = self._get_ec_class(module=module)
+        return ecclass()
+
+    def verify(
+        self,
+        *,
+        privatekey: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey,
+        module: GeneralAnsibleModule,
+    ) -> bool:
+        ecclass = self._get_ec_class(module=module)
+        return isinstance(privatekey.private_numbers().public_numbers.curve, ecclass)
+
+
+# Implementation with using cryptography
+class PrivateKeyCryptographyBackend(PrivateKeyBackend):
+
+    def _add_curve(
+        self,
+        name: str,
+        ectype: str,
+        *,
+        deprecated: bool = False,
+    ) -> None:
+        self.curves[name] = _Curve(name=name, ectype=ectype, deprecated=deprecated)
+
+    def __init__(self, module: GeneralAnsibleModule) -> None:
+        super().__init__(module=module)
+
+        self.curves: dict[str, _Curve] = {}
+        self._add_curve("secp224r1", "SECP224R1")
+        self._add_curve("secp256k1", "SECP256K1")
+        self._add_curve("secp256r1", "SECP256R1")
+        self._add_curve("secp384r1", "SECP384R1")
+        self._add_curve("secp521r1", "SECP521R1")
+        self._add_curve("secp192r1", "SECP192R1", deprecated=True)
+        self._add_curve("sect163k1", "SECT163K1", deprecated=True)
+        self._add_curve("sect163r2", "SECT163R2", deprecated=True)
+        self._add_curve("sect233k1", "SECT233K1", deprecated=True)
+        self._add_curve("sect233r1", "SECT233R1", deprecated=True)
+        self._add_curve("sect283k1", "SECT283K1", deprecated=True)
+        self._add_curve("sect283r1", "SECT283R1", deprecated=True)
+        self._add_curve("sect409k1", "SECT409K1", deprecated=True)
+        self._add_curve("sect409r1", "SECT409R1", deprecated=True)
+        self._add_curve("sect571k1", "SECT571K1", deprecated=True)
+        self._add_curve("sect571r1", "SECT571R1", deprecated=True)
+        self._add_curve("brainpoolP256r1", "BrainpoolP256R1", deprecated=True)
+        self._add_curve("brainpoolP384r1", "BrainpoolP384R1", deprecated=True)
+        self._add_curve("brainpoolP512r1", "BrainpoolP512R1", deprecated=True)
+
+    def _get_wanted_format(self) -> t.Literal["pkcs1", "pkcs8", "raw"]:
+        if self.format not in ("auto", "auto_ignore"):
+            return self.format  # type: ignore
+        if self.type in ("X25519", "X448", "Ed25519", "Ed448"):
+            return "pkcs8"
+        return "pkcs1"
+
+    def generate_private_key(self) -> None:
+        """(Re-)Generate private key."""
+        try:
+            if self.type == "RSA":
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.rsa.generate_private_key(
+                        public_exponent=65537,  # OpenSSL always uses this
+                        key_size=self.size,
+                    )
+                )
+            if self.type == "DSA":
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.dsa.generate_private_key(
+                        key_size=self.size
+                    )
+                )
+            if self.type == "X25519":
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey.generate()
+                )
+            if self.type == "X448":
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.x448.X448PrivateKey.generate()
+                )
+            if self.type == "Ed25519":
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey.generate()
+                )
+            if self.type == "Ed448":
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey.generate()
+                )
+            if self.type == "ECC" and self.curve in self.curves:
+                if self.curves[self.curve].deprecated:
+                    self.module.warn(
+                        f"Elliptic curves of type {self.curve} should not be used for new keys!"
+                    )
+                self.private_key = (
+                    cryptography.hazmat.primitives.asymmetric.ec.generate_private_key(
+                        curve=self.curves[self.curve].create(
+                            size=self.size, module=self.module
+                        ),
+                    )
+                )
+        except cryptography.exceptions.UnsupportedAlgorithm:
+            self.module.fail_json(
+                msg=f"Cryptography backend does not support the algorithm required for {self.type}"
+            )
+
+    def get_private_key_data(self) -> bytes:
+        """Return bytes for self.private_key"""
+        if self.private_key is None:
+            raise AssertionError("private_key not set")
+        # Select export format and encoding
+        try:
+            export_format_txt = self._get_wanted_format()
+            export_encoding = cryptography.hazmat.primitives.serialization.Encoding.PEM
+            if export_format_txt == "pkcs1":
+                # "TraditionalOpenSSL" format is PKCS1
+                export_format = (
+                    cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL
+                )
+            elif export_format_txt == "pkcs8":
+                export_format = (
+                    cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8
+                )
+            elif export_format_txt == "raw":
+                export_format = (
+                    cryptography.hazmat.primitives.serialization.PrivateFormat.Raw
+                )
+                export_encoding = (
+                    cryptography.hazmat.primitives.serialization.Encoding.Raw
+                )
+            else:
+                # pylint does not notice that all possible values for export_format_txt have been covered.
+                raise AssertionError("Can never be reached")  # pragma: no cover
+        except AttributeError:
+            self.module.fail_json(
+                msg=f'Cryptography backend does not support the selected output format "{self.format}"'
+            )
+
+        # Select key encryption
+        encryption_algorithm: (
+            cryptography.hazmat.primitives.serialization.KeySerializationEncryption
+        ) = cryptography.hazmat.primitives.serialization.NoEncryption()
+        if self.cipher and self.passphrase:
+            if self.cipher == "auto":
+                encryption_algorithm = cryptography.hazmat.primitives.serialization.BestAvailableEncryption(
+                    to_bytes(self.passphrase)
+                )
+            else:
+                self.module.fail_json(
+                    msg='Cryptography backend can only use "auto" for cipher option.'
+                )
+
+        # Serialize key
+        try:
+            return self.private_key.private_bytes(
+                encoding=export_encoding,
+                format=export_format,
+                encryption_algorithm=encryption_algorithm,
+            )
+        except ValueError:
+            self.module.fail_json(
+                msg=f'Cryptography backend cannot serialize the private key in the required format "{self.format}"'
+            )
+        except Exception:
+            self.module.fail_json(
+                msg=f'Error while serializing the private key in the required format "{self.format}"',
+                exception=traceback.format_exc(),
+            )
+
+    def _load_privatekey(self) -> PrivateKeyTypes:
+        data = self.existing_private_key_bytes
+        if data is None:
+            raise AssertionError("existing_private_key_bytes not set")
+        try:
+            # Interpret bytes depending on format.
+            key_format = identify_private_key_format(data)
+            if key_format == "raw":
+                if len(data) == 56:
+                    return cryptography.hazmat.primitives.asymmetric.x448.X448PrivateKey.from_private_bytes(
+                        data
+                    )
+                if len(data) == 57:
+                    return cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey.from_private_bytes(
+                        data
+                    )
+                if len(data) == 32:
+                    if self.type == "X25519":
+                        return cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey.from_private_bytes(
+                            data
+                        )
+                    if self.type == "Ed25519":
+                        return cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey.from_private_bytes(
+                            data
+                        )
+                    try:
+                        return cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey.from_private_bytes(
+                            data
+                        )
+                    except Exception:
+                        return cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey.from_private_bytes(
+                            data
+                        )
+                raise PrivateKeyError("Cannot load raw key")
+
+            return cryptography.hazmat.primitives.serialization.load_pem_private_key(
+                data,
+                None if self.passphrase is None else to_bytes(self.passphrase),
+            )
+        except Exception as e:
+            raise PrivateKeyError(e) from e
+
+    def _ensure_existing_private_key_loaded(self) -> None:
+        if self.existing_private_key is None and self.has_existing():
+            self.existing_private_key = self._load_privatekey()
+
+    def _check_passphrase(self) -> bool:
+        if self.existing_private_key_bytes is None:
+            raise AssertionError("existing_private_key_bytes not set")
+        try:
+            key_format = identify_private_key_format(self.existing_private_key_bytes)
+            if key_format == "raw":
+                # Raw keys cannot be encrypted. To avoid incompatibilities, we try to
+                # actually load the key (and return False when this fails).
+                self._load_privatekey()
+                # Loading the key succeeded. Only return True when no passphrase was
+                # provided.
+                return self.passphrase is None
+            return bool(
+                cryptography.hazmat.primitives.serialization.load_pem_private_key(
+                    self.existing_private_key_bytes,
+                    None if self.passphrase is None else to_bytes(self.passphrase),
+                )
+            )
+        except Exception:
+            return False
+
+    def _check_size_and_type(self) -> bool:
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey,
+        ):
+            return (
+                self.type == "RSA" and self.size == self.existing_private_key.key_size
+            )
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey,
+        ):
+            return (
+                self.type == "DSA" and self.size == self.existing_private_key.key_size
+            )
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey,
+        ):
+            return self.type == "X25519"
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.x448.X448PrivateKey,
+        ):
+            return self.type == "X448"
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey,
+        ):
+            return self.type == "Ed25519"
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey,
+        ):
+            return self.type == "Ed448"
+        if isinstance(
+            self.existing_private_key,
+            cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey,
+        ):
+            if self.type != "ECC":
+                return False
+            if self.curve not in self.curves:
+                return False
+            return self.curves[self.curve].verify(
+                privatekey=self.existing_private_key, module=self.module
+            )
+
+        return False
+
+    def _check_format(self) -> bool:
+        if self.existing_private_key_bytes is None:
+            raise AssertionError("existing_private_key_bytes not set")
+        if self.format == "auto_ignore":
+            return True
+        try:
+            key_format = identify_private_key_format(self.existing_private_key_bytes)
+            return key_format == self._get_wanted_format()
+        except Exception:
+            return False
+
+
+def select_backend(module: GeneralAnsibleModule) -> PrivateKeyBackend:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return PrivateKeyCryptographyBackend(module=module)
+
+
+def get_privatekey_argument_spec() -> ArgumentSpec:
+    return ArgumentSpec(
+        argument_spec={
+            "size": {"type": "int", "default": 4096},
+            "type": {
+                "type": "str",
+                "default": "RSA",
+                "choices": ["DSA", "ECC", "Ed25519", "Ed448", "RSA", "X25519", "X448"],
+            },
+            "curve": {
+                "type": "str",
+                "choices": [
+                    "secp224r1",
+                    "secp256k1",
+                    "secp256r1",
+                    "secp384r1",
+                    "secp521r1",
+                    "secp192r1",
+                    "brainpoolP256r1",
+                    "brainpoolP384r1",
+                    "brainpoolP512r1",
+                    "sect163k1",
+                    "sect163r2",
+                    "sect233k1",
+                    "sect233r1",
+                    "sect283k1",
+                    "sect283r1",
+                    "sect409k1",
+                    "sect409r1",
+                    "sect571k1",
+                    "sect571r1",
+                ],
+            },
+            "passphrase": {"type": "str", "no_log": True},
+            "cipher": {"type": "str", "default": "auto"},
+            "format": {
+                "type": "str",
+                "default": "auto_ignore",
+                "choices": ["pkcs1", "pkcs8", "raw", "auto", "auto_ignore"],
+            },
+            "format_mismatch": {
+                "type": "str",
+                "default": "regenerate",
+                "choices": ["regenerate", "convert"],
+            },
+            "select_crypto_backend": {
+                "type": "str",
+                "choices": ["auto", "cryptography"],
+                "default": "auto",
+            },
+            "regenerate": {
+                "type": "str",
+                "default": "full_idempotence",
+                "choices": [
+                    "never",
+                    "fail",
+                    "partial_idempotence",
+                    "full_idempotence",
+                    "always",
+                ],
+            },
+        },
+        required_if=[
+            ("type", "ECC", ["curve"]),
+        ],
+    )
+
+
+__all__ = (
+    "PrivateKeyError",
+    "PrivateKeyBackend",
+    "select_backend",
+    "get_privatekey_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/privatekey_convert.py

@@ -0,0 +1,313 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import traceback
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes
+from ansible_collections.community.crypto.plugins.module_utils._argspec import (
+    ArgumentSpec,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    cryptography_compare_private_keys,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.pem import (
+    identify_private_key_format,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+from ansible_collections.community.crypto.plugins.module_utils._io import load_file
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        PrivateKeyTypes,
+    )
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    import cryptography.exceptions
+    import cryptography.hazmat.backends
+    import cryptography.hazmat.primitives.asymmetric.dsa
+    import cryptography.hazmat.primitives.asymmetric.ec
+    import cryptography.hazmat.primitives.asymmetric.ed448
+    import cryptography.hazmat.primitives.asymmetric.ed25519
+    import cryptography.hazmat.primitives.asymmetric.rsa
+    import cryptography.hazmat.primitives.asymmetric.utils
+    import cryptography.hazmat.primitives.asymmetric.x448
+    import cryptography.hazmat.primitives.asymmetric.x25519
+    import cryptography.hazmat.primitives.serialization
+except ImportError:
+    pass
+
+
+class PrivateKeyError(OpenSSLObjectError):
+    pass
+
+
+# From the object called `module`, only the following properties are used:
+#
+#  - module.params[]
+#  - module.warn(msg: str)
+#  - module.fail_json(msg: str, **kwargs)
+
+
+class PrivateKeyConvertBackend(metaclass=abc.ABCMeta):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        self.module = module
+        self.src_path: str | None = module.params["src_path"]
+        self.src_content: str | None = module.params["src_content"]
+        self.src_passphrase: str | None = module.params["src_passphrase"]
+        self.format: t.Literal["pkcs1", "pkcs8", "raw"] = module.params["format"]
+        self.dest_passphrase: str | None = module.params["dest_passphrase"]
+
+        self.src_private_key: PrivateKeyTypes | None = None
+        if self.src_path is not None:
+            self.src_private_key_bytes = load_file(path=self.src_path, module=module)
+        else:
+            if self.src_content is None:
+                raise AssertionError("src_content is None")
+            self.src_private_key_bytes = self.src_content.encode("utf-8")
+
+        self.dest_private_key: PrivateKeyTypes | None = None
+        self.dest_private_key_bytes: bytes | None = None
+
+    @abc.abstractmethod
+    def get_private_key_data(self) -> bytes:
+        """Return bytes for self.src_private_key in output format."""
+
+    def set_existing_destination(self, *, privatekey_bytes: bytes | None) -> None:
+        """Set existing private key bytes. None indicates that the key does not exist."""
+        self.dest_private_key_bytes = privatekey_bytes
+
+    def has_existing_destination(self) -> bool:
+        """Query whether an existing private key is/has been there."""
+        return self.dest_private_key_bytes is not None
+
+    @abc.abstractmethod
+    def _load_private_key(
+        self,
+        *,
+        data: bytes,
+        passphrase: str | None,
+        current_hint: PrivateKeyTypes | None = None,
+    ) -> tuple[str, PrivateKeyTypes]:
+        """Check whether data can be loaded as a private key with the provided passphrase. Return tuple (type, private_key)."""
+
+    def needs_conversion(self) -> bool:
+        """Check whether a conversion is necessary. Must only be called if needs_regeneration() returned False."""
+        dummy, self.src_private_key = self._load_private_key(
+            data=self.src_private_key_bytes, passphrase=self.src_passphrase
+        )
+
+        if not self.has_existing_destination():
+            return True
+        assert self.dest_private_key_bytes is not None
+
+        try:
+            key_format, self.dest_private_key = self._load_private_key(
+                data=self.dest_private_key_bytes,
+                passphrase=self.dest_passphrase,
+                current_hint=self.src_private_key,
+            )
+        except Exception:
+            return True
+
+        return key_format != self.format or not cryptography_compare_private_keys(
+            self.dest_private_key, self.src_private_key
+        )
+
+    def dump(self) -> dict[str, t.Any]:
+        """Serialize the object into a dictionary."""
+        return {}
+
+
+# Implementation with using cryptography
+class PrivateKeyConvertCryptographyBackend(PrivateKeyConvertBackend):
+    def __init__(self, *, module: AnsibleModule) -> None:
+        super().__init__(module=module)
+
+    def get_private_key_data(self) -> bytes:
+        """Return bytes for self.src_private_key in output format"""
+        if self.src_private_key is None:
+            raise AssertionError("src_private_key not set")
+        # Select export format and encoding
+        try:
+            export_encoding = cryptography.hazmat.primitives.serialization.Encoding.PEM
+            if self.format == "pkcs1":
+                # "TraditionalOpenSSL" format is PKCS1
+                export_format = (
+                    cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL
+                )
+            elif self.format == "pkcs8":
+                export_format = (
+                    cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8
+                )
+            elif self.format == "raw":
+                export_format = (
+                    cryptography.hazmat.primitives.serialization.PrivateFormat.Raw
+                )
+                export_encoding = (
+                    cryptography.hazmat.primitives.serialization.Encoding.Raw
+                )
+            else:
+                # pylint does not notice that all possible values for self.format have been covered.
+                raise AssertionError("Can never be reached")  # pragma: no cover
+        except AttributeError:
+            self.module.fail_json(
+                msg=f'Cryptography backend does not support the selected output format "{self.format}"'
+            )
+
+        # Select key encryption
+        encryption_algorithm: (
+            cryptography.hazmat.primitives.serialization.KeySerializationEncryption
+        ) = cryptography.hazmat.primitives.serialization.NoEncryption()
+        if self.dest_passphrase:
+            encryption_algorithm = (
+                cryptography.hazmat.primitives.serialization.BestAvailableEncryption(
+                    to_bytes(self.dest_passphrase)
+                )
+            )
+
+        # Serialize key
+        try:
+            return self.src_private_key.private_bytes(
+                encoding=export_encoding,
+                format=export_format,
+                encryption_algorithm=encryption_algorithm,
+            )
+        except ValueError:
+            self.module.fail_json(
+                msg=f'Cryptography backend cannot serialize the private key in the required format "{self.format}"'
+            )
+        except Exception:
+            self.module.fail_json(
+                msg=f'Error while serializing the private key in the required format "{self.format}"',
+                exception=traceback.format_exc(),
+            )
+
+    def _load_private_key(
+        self,
+        *,
+        data: bytes,
+        passphrase: str | None,
+        current_hint: PrivateKeyTypes | None = None,
+    ) -> tuple[str, PrivateKeyTypes]:
+        try:
+            # Interpret bytes depending on format.
+            key_format = identify_private_key_format(data)
+            if key_format == "raw":
+                if passphrase is not None:
+                    raise PrivateKeyError("Cannot load raw key with passphrase")
+                if len(data) == 56:
+                    return (
+                        key_format,
+                        cryptography.hazmat.primitives.asymmetric.x448.X448PrivateKey.from_private_bytes(
+                            data
+                        ),
+                    )
+                if len(data) == 57:
+                    return (
+                        key_format,
+                        cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey.from_private_bytes(
+                            data
+                        ),
+                    )
+                if len(data) == 32:
+                    if isinstance(
+                        current_hint,
+                        cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey,
+                    ):
+                        try:
+                            return (
+                                key_format,
+                                cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey.from_private_bytes(
+                                    data
+                                ),
+                            )
+                        except Exception:
+                            return (
+                                key_format,
+                                cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey.from_private_bytes(
+                                    data
+                                ),
+                            )
+                    else:
+                        try:
+                            return (
+                                key_format,
+                                cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey.from_private_bytes(
+                                    data
+                                ),
+                            )
+                        except Exception:
+                            return (
+                                key_format,
+                                cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey.from_private_bytes(
+                                    data
+                                ),
+                            )
+                raise PrivateKeyError("Cannot load raw key")
+
+            return (
+                key_format,
+                cryptography.hazmat.primitives.serialization.load_pem_private_key(
+                    data,
+                    None if passphrase is None else to_bytes(passphrase),
+                ),
+            )
+        except Exception as e:
+            raise PrivateKeyError(e) from e
+
+
+def select_backend(module: AnsibleModule) -> PrivateKeyConvertBackend:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return PrivateKeyConvertCryptographyBackend(module=module)
+
+
+def get_privatekey_argument_spec() -> ArgumentSpec:
+    return ArgumentSpec(
+        argument_spec={
+            "src_path": {"type": "path"},
+            "src_content": {"type": "str"},
+            "src_passphrase": {"type": "str", "no_log": True},
+            "dest_passphrase": {"type": "str", "no_log": True},
+            "format": {
+                "type": "str",
+                "required": True,
+                "choices": ["pkcs1", "pkcs8", "raw"],
+            },
+        },
+        mutually_exclusive=[
+            ["src_path", "src_content"],
+        ],
+        required_one_of=[
+            ["src_path", "src_content"],
+        ],
+    )
+
+
+__all__ = (
+    "PrivateKeyError",
+    "PrivateKeyConvertBackend",
+    "select_backend",
+    "get_privatekey_argument_spec",
+)

plugins/module_utils/_crypto/module_backends/privatekey_info.py

@@ -0,0 +1,369 @@
+# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
+# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.math import (
+    binary_exp_mod,
+    quick_is_not_prime,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.module_backends.publickey_info import (
+    _get_cryptography_public_key_info,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.support import (
+    get_fingerprint_of_bytes,
+    load_privatekey,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._filter_module import (
+        FilterModuleMock,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        PrivateKeyTypes,
+    )
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule, FilterModuleMock]
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    from cryptography.hazmat.primitives import serialization
+except ImportError:
+    pass
+
+SIGNATURE_TEST_DATA = b"1234"
+
+
+def _get_cryptography_private_key_info(
+    key: PrivateKeyTypes, *, need_private_key_data: bool = False
+) -> tuple[str, dict[str, t.Any], dict[str, t.Any]]:
+    key_type, key_public_data = _get_cryptography_public_key_info(key.public_key())
+    key_private_data: dict[str, t.Any] = {}
+    if need_private_key_data:
+        if isinstance(key, cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey):
+            rsa_private_numbers = key.private_numbers()
+            key_private_data["p"] = rsa_private_numbers.p
+            key_private_data["q"] = rsa_private_numbers.q
+            key_private_data["exponent"] = rsa_private_numbers.d
+        elif isinstance(
+            key, cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey
+        ):
+            dsa_private_numbers = key.private_numbers()
+            key_private_data["x"] = dsa_private_numbers.x
+        elif isinstance(
+            key, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
+        ):
+            ecc_private_numbers = key.private_numbers()
+            key_private_data["multiplier"] = ecc_private_numbers.private_value
+    return key_type, key_public_data, key_private_data
+
+
+def _check_dsa_consistency(
+    *, key_public_data: dict[str, t.Any], key_private_data: dict[str, t.Any]
+) -> bool | None:
+    # Get parameters
+    p: int | None = key_public_data.get("p")
+    if p is None:
+        return None
+    q: int | None = key_public_data.get("q")
+    if q is None:
+        return None
+    g: int | None = key_public_data.get("g")
+    if g is None:
+        return None
+    y: int | None = key_public_data.get("y")
+    if y is None:
+        return None
+    x: int | None = key_private_data.get("x")
+    if x is None:
+        return None
+    # Make sure that g is not 0, 1 or -1 in Z/pZ
+    if g < 2 or g >= p - 1:
+        return False
+    # Make sure that x is in range
+    if x < 1 or x >= q:
+        return False
+    # Check whether q divides p-1
+    if (p - 1) % q != 0:
+        return False
+    # Check that g**q mod p == 1
+    if binary_exp_mod(g, q, m=p) != 1:
+        return False
+    # Check whether g**x mod p == y
+    if binary_exp_mod(g, x, m=p) != y:
+        return False
+    # Check (quickly) whether p or q are not primes
+    if quick_is_not_prime(q) or quick_is_not_prime(p):
+        return False
+    return True
+
+
+def _is_cryptography_key_consistent(
+    key: PrivateKeyTypes,
+    *,
+    key_public_data: dict[str, t.Any],
+    key_private_data: dict[str, t.Any],
+    warn_func: t.Callable[[str], None] | None = None,
+) -> bool | None:
+    if isinstance(key, cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey):
+        # key._backend was removed in cryptography 42.0.0
+        backend = getattr(key, "_backend", None)
+        if backend is not None:
+            return bool(backend._lib.RSA_check_key(key._rsa_cdata))  # type: ignore  # pylint: disable=protected-access
+    if isinstance(key, cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey):
+        result = _check_dsa_consistency(
+            key_public_data=key_public_data, key_private_data=key_private_data
+        )
+        if result is not None:
+            return result
+        signature = key.sign(
+            SIGNATURE_TEST_DATA, cryptography.hazmat.primitives.hashes.SHA256()
+        )
+        try:
+            key.public_key().verify(
+                signature,
+                SIGNATURE_TEST_DATA,
+                cryptography.hazmat.primitives.hashes.SHA256(),
+            )
+            return True
+        except cryptography.exceptions.InvalidSignature:
+            return False
+    if isinstance(
+        key, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
+    ):
+        signature = key.sign(
+            SIGNATURE_TEST_DATA,
+            cryptography.hazmat.primitives.asymmetric.ec.ECDSA(
+                cryptography.hazmat.primitives.hashes.SHA256()
+            ),
+        )
+        try:
+            key.public_key().verify(
+                signature,
+                SIGNATURE_TEST_DATA,
+                cryptography.hazmat.primitives.asymmetric.ec.ECDSA(
+                    cryptography.hazmat.primitives.hashes.SHA256()
+                ),
+            )
+            return True
+        except cryptography.exceptions.InvalidSignature:
+            return False
+    has_simple_sign_function = False
+    if isinstance(
+        key, cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey
+    ):
+        has_simple_sign_function = True
+    if isinstance(key, cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey):
+        has_simple_sign_function = True
+    if has_simple_sign_function:
+        signature = key.sign(SIGNATURE_TEST_DATA)  # type: ignore
+        try:
+            key.public_key().verify(signature, SIGNATURE_TEST_DATA)  # type: ignore
+            return True
+        except cryptography.exceptions.InvalidSignature:
+            return False
+    # For X25519 and X448, there's no test yet.
+    if warn_func is not None:
+        warn_func(f"Cannot determine consistency for key of type {type(key)}")
+    return None
+
+
+class PrivateKeyConsistencyError(OpenSSLObjectError):
+    def __init__(self, msg: str, *, result: dict[str, t.Any]) -> None:
+        super().__init__(msg)
+        self.error_message = msg
+        self.result = result
+
+
+class PrivateKeyParseError(OpenSSLObjectError):
+    def __init__(self, msg: str, *, result: dict[str, t.Any]) -> None:
+        super().__init__(msg)
+        self.error_message = msg
+        self.result = result
+
+
+class PrivateKeyInfoRetrieval(metaclass=abc.ABCMeta):
+    key: PrivateKeyTypes
+
+    def __init__(
+        self,
+        *,
+        module: GeneralAnsibleModule,
+        content: bytes,
+        passphrase: str | None = None,
+        return_private_key_data: bool = False,
+        check_consistency: bool = False,
+    ):
+        self.module = module
+        self.content = content
+        self.passphrase = passphrase
+        self.return_private_key_data = return_private_key_data
+        self.check_consistency = check_consistency
+
+    @abc.abstractmethod
+    def _get_public_key(self, *, binary: bool) -> bytes:
+        pass
+
+    @abc.abstractmethod
+    def _get_key_info(
+        self, *, need_private_key_data: bool = False
+    ) -> tuple[str, dict[str, t.Any], dict[str, t.Any]]:
+        pass
+
+    @abc.abstractmethod
+    def _is_key_consistent(
+        self, *, key_public_data: dict[str, t.Any], key_private_data: dict[str, t.Any]
+    ) -> bool | None:
+        pass
+
+    def get_info(self, *, prefer_one_fingerprint: bool = False) -> dict[str, t.Any]:
+        result: dict[str, t.Any] = {
+            "can_parse_key": False,
+            "key_is_consistent": None,
+        }
+        priv_key_detail = self.content
+        try:
+            self.key = load_privatekey(
+                path=None,
+                content=priv_key_detail,
+                passphrase=(
+                    to_bytes(self.passphrase)
+                    if self.passphrase is not None
+                    else self.passphrase
+                ),
+            )
+            result["can_parse_key"] = True
+        except OpenSSLObjectError as exc:
+            raise PrivateKeyParseError(str(exc), result=result) from exc
+
+        result["public_key"] = to_text(self._get_public_key(binary=False))
+        pk = self._get_public_key(binary=True)
+        result["public_key_fingerprints"] = (
+            get_fingerprint_of_bytes(pk, prefer_one=prefer_one_fingerprint)
+            if pk is not None
+            else {}
+        )
+
+        key_type, key_public_data, key_private_data = self._get_key_info(
+            need_private_key_data=self.return_private_key_data or self.check_consistency
+        )
+        result["type"] = key_type
+        result["public_data"] = key_public_data
+        if self.return_private_key_data:
+            result["private_data"] = key_private_data
+
+        if self.check_consistency:
+            result["key_is_consistent"] = self._is_key_consistent(
+                key_public_data=key_public_data, key_private_data=key_private_data
+            )
+            if result["key_is_consistent"] is False:
+                # Only fail when it is False, to avoid to fail on None (which means "we do not know")
+                msg = (
+                    "Private key is not consistent! (See "
+                    "https://blog.hboeck.de/archives/888-How-I-tricked-Symantec-with-a-Fake-Private-Key.html)"
+                )
+                raise PrivateKeyConsistencyError(msg, result=result)
+        return result
+
+
+class PrivateKeyInfoRetrievalCryptography(PrivateKeyInfoRetrieval):
+    """Validate the supplied private key, using the cryptography backend"""
+
+    def __init__(
+        self, *, module: GeneralAnsibleModule, content: bytes, **kwargs
+    ) -> None:
+        super().__init__(module=module, content=content, **kwargs)
+
+    def _get_public_key(self, *, binary: bool) -> bytes:
+        return self.key.public_key().public_bytes(
+            serialization.Encoding.DER if binary else serialization.Encoding.PEM,
+            serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+
+    def _get_key_info(
+        self, *, need_private_key_data: bool = False
+    ) -> tuple[str, dict[str, t.Any], dict[str, t.Any]]:
+        return _get_cryptography_private_key_info(
+            self.key, need_private_key_data=need_private_key_data
+        )
+
+    def _is_key_consistent(
+        self, *, key_public_data: dict[str, t.Any], key_private_data: dict[str, t.Any]
+    ) -> bool | None:
+        return _is_cryptography_key_consistent(
+            self.key,
+            key_public_data=key_public_data,
+            key_private_data=key_private_data,
+            warn_func=self.module.warn,
+        )
+
+
+def get_privatekey_info(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes,
+    passphrase: str | None = None,
+    return_private_key_data: bool = False,
+    prefer_one_fingerprint: bool = False,
+) -> dict[str, t.Any]:
+    info = PrivateKeyInfoRetrievalCryptography(
+        module=module,
+        content=content,
+        passphrase=passphrase,
+        return_private_key_data=return_private_key_data,
+    )
+    return info.get_info(prefer_one_fingerprint=prefer_one_fingerprint)
+
+
+def select_backend(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes,
+    passphrase: str | None = None,
+    return_private_key_data: bool = False,
+    check_consistency: bool = False,
+) -> PrivateKeyInfoRetrieval:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return PrivateKeyInfoRetrievalCryptography(
+        module=module,
+        content=content,
+        passphrase=passphrase,
+        return_private_key_data=return_private_key_data,
+        check_consistency=check_consistency,
+    )
+
+
+__all__ = (
+    "PrivateKeyConsistencyError",
+    "PrivateKeyParseError",
+    "PrivateKeyInfoRetrieval",
+    "get_privatekey_info",
+    "select_backend",
+)

plugins/module_utils/_crypto/module_backends/publickey_info.py

@@ -0,0 +1,204 @@
+# Copyright (c) 2020-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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import typing as t
+
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLObjectError,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.support import (
+    get_fingerprint_of_bytes,
+    load_publickey,
+)
+from ansible_collections.community.crypto.plugins.module_utils._cryptography_dep import (
+    COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+    assert_required_cryptography_version,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._filter_module import (
+        FilterModuleMock,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        PublicKeyTypes,
+    )
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule, FilterModuleMock]
+
+
+MINIMAL_CRYPTOGRAPHY_VERSION = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION
+
+try:
+    import cryptography
+    import cryptography.hazmat.primitives.asymmetric.ed448
+    import cryptography.hazmat.primitives.asymmetric.ed25519
+    import cryptography.hazmat.primitives.asymmetric.x448
+    import cryptography.hazmat.primitives.asymmetric.x25519
+    from cryptography.hazmat.primitives import serialization
+except ImportError:
+    pass
+
+
+def _get_cryptography_public_key_info(
+    key: PublicKeyTypes,
+) -> tuple[str, dict[str, t.Any]]:
+    key_public_data: dict[str, t.Any] = {}
+    if isinstance(key, cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey):
+        key_type = "RSA"
+        rsa_public_numbers = key.public_numbers()
+        key_public_data["size"] = key.key_size
+        key_public_data["modulus"] = rsa_public_numbers.n
+        key_public_data["exponent"] = rsa_public_numbers.e
+    elif isinstance(key, cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey):
+        key_type = "DSA"
+        dsa_parameter_numbers = key.parameters().parameter_numbers()
+        dsa_public_numbers = key.public_numbers()
+        key_public_data["size"] = key.key_size
+        key_public_data["p"] = dsa_parameter_numbers.p
+        key_public_data["q"] = dsa_parameter_numbers.q
+        key_public_data["g"] = dsa_parameter_numbers.g
+        key_public_data["y"] = dsa_public_numbers.y
+    elif isinstance(
+        key, cryptography.hazmat.primitives.asymmetric.x25519.X25519PublicKey
+    ):
+        key_type = "X25519"
+    elif isinstance(key, cryptography.hazmat.primitives.asymmetric.x448.X448PublicKey):
+        key_type = "X448"
+    elif isinstance(
+        key, cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey
+    ):
+        key_type = "Ed25519"
+    elif isinstance(
+        key, cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey
+    ):
+        key_type = "Ed448"
+    elif isinstance(
+        key, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey
+    ):
+        key_type = "ECC"
+        ecc_public_numbers = key.public_numbers()
+        key_public_data["curve"] = key.curve.name
+        key_public_data["x"] = ecc_public_numbers.x
+        key_public_data["y"] = ecc_public_numbers.y
+        key_public_data["exponent_size"] = key.curve.key_size
+    else:
+        key_type = f"unknown ({type(key)})"
+    return key_type, key_public_data
+
+
+class PublicKeyParseError(OpenSSLObjectError):
+    def __init__(self, msg: str, *, result: dict[str, t.Any]) -> None:
+        super().__init__(msg)
+        self.error_message = msg
+        self.result = result
+
+
+class PublicKeyInfoRetrieval(metaclass=abc.ABCMeta):
+    def __init__(
+        self,
+        *,
+        module: GeneralAnsibleModule,
+        content: bytes | None = None,
+        key: PublicKeyTypes | None = None,
+    ) -> None:
+        # content must be a bytes string
+        self.module = module
+        self.content = content
+        self.key = key
+
+    @abc.abstractmethod
+    def _get_public_key(self, binary: bool) -> bytes:
+        pass
+
+    @abc.abstractmethod
+    def _get_key_info(self) -> tuple[str, dict[str, t.Any]]:
+        pass
+
+    def get_info(self, *, prefer_one_fingerprint: bool = False) -> dict[str, t.Any]:
+        result: dict[str, t.Any] = {}
+        if self.key is None:
+            try:
+                self.key = load_publickey(content=self.content)
+            except OpenSSLObjectError as e:
+                raise PublicKeyParseError(str(e), result={}) from e
+
+        pk = self._get_public_key(binary=True)
+        result["fingerprints"] = (
+            get_fingerprint_of_bytes(pk, prefer_one=prefer_one_fingerprint)
+            if pk is not None
+            else {}
+        )
+
+        key_type, key_public_data = self._get_key_info()
+        result["type"] = key_type
+        result["public_data"] = key_public_data
+        return result
+
+
+class PublicKeyInfoRetrievalCryptography(PublicKeyInfoRetrieval):
+    """Validate the supplied public key, using the cryptography backend"""
+
+    def __init__(
+        self,
+        *,
+        module: GeneralAnsibleModule,
+        content: bytes | None = None,
+        key: PublicKeyTypes | None = None,
+    ) -> None:
+        super().__init__(module=module, content=content, key=key)
+
+    def _get_public_key(self, binary: bool) -> bytes:
+        if self.key is None:
+            raise AssertionError("key must be set")
+        return self.key.public_bytes(
+            serialization.Encoding.DER if binary else serialization.Encoding.PEM,
+            serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+
+    def _get_key_info(self) -> tuple[str, dict[str, t.Any]]:
+        if self.key is None:
+            raise AssertionError("key must be set")
+        return _get_cryptography_public_key_info(self.key)
+
+
+def get_publickey_info(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes | None = None,
+    key: PublicKeyTypes | None = None,
+    prefer_one_fingerprint: bool = False,
+) -> dict[str, t.Any]:
+    info = PublicKeyInfoRetrievalCryptography(module=module, content=content, key=key)
+    return info.get_info(prefer_one_fingerprint=prefer_one_fingerprint)
+
+
+def select_backend(
+    *,
+    module: GeneralAnsibleModule,
+    content: bytes | None = None,
+    key: PublicKeyTypes | None = None,
+) -> PublicKeyInfoRetrieval:
+    assert_required_cryptography_version(
+        module, minimum_cryptography_version=MINIMAL_CRYPTOGRAPHY_VERSION
+    )
+    return PublicKeyInfoRetrievalCryptography(module=module, content=content, key=key)
+
+
+__all__ = (
+    "PublicKeyParseError",
+    "PublicKeyInfoRetrieval",
+    "get_publickey_info",
+    "select_backend",
+)

plugins/module_utils/_crypto/pem.py

@@ -0,0 +1,141 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import typing as t
+
+
+PEM_START = "-----BEGIN "
+PEM_END_START = "-----END "
+PEM_END = "-----"
+PKCS8_PRIVATEKEY_NAMES = ("PRIVATE KEY", "ENCRYPTED PRIVATE KEY")
+PKCS1_PRIVATEKEY_SUFFIX = " PRIVATE KEY"
+
+
+def identify_pem_format(content: bytes, *, encoding: str = "utf-8") -> bool:
+    """Given the contents of a binary file, tests whether this could be a PEM file."""
+    try:
+        first_pem = extract_first_pem(content.decode(encoding))
+        if first_pem is None:
+            return False
+        lines = first_pem.splitlines(False)
+        if (
+            lines[0].startswith(PEM_START)
+            and lines[0].endswith(PEM_END)
+            and len(lines[0]) > len(PEM_START) + len(PEM_END)
+        ):
+            return True
+    except UnicodeDecodeError:
+        pass
+    return False
+
+
+def identify_private_key_format(
+    content: bytes, *, encoding: str = "utf-8"
+) -> t.Literal["raw", "pkcs1", "pkcs8", "unknown-pem"]:
+    """Given the contents of a private key file, identifies its format."""
+    # See https://github.com/openssl/openssl/blob/master/crypto/pem/pem_pkey.c#L40-L85
+    # (PEM_read_bio_PrivateKey)
+    # and https://github.com/openssl/openssl/blob/master/include/openssl/pem.h#L46-L47
+    # (PEM_STRING_PKCS8, PEM_STRING_PKCS8INF)
+    try:
+        first_pem = extract_first_pem(content.decode(encoding))
+        if first_pem is None:
+            return "raw"
+        lines = first_pem.splitlines(False)
+        if (
+            lines[0].startswith(PEM_START)
+            and lines[0].endswith(PEM_END)
+            and len(lines[0]) > len(PEM_START) + len(PEM_END)
+        ):
+            name = lines[0][len(PEM_START) : -len(PEM_END)]
+            if name in PKCS8_PRIVATEKEY_NAMES:
+                return "pkcs8"
+            if len(name) > len(PKCS1_PRIVATEKEY_SUFFIX) and name.endswith(
+                PKCS1_PRIVATEKEY_SUFFIX
+            ):
+                return "pkcs1"
+            return "unknown-pem"
+    except UnicodeDecodeError:
+        pass
+    return "raw"
+
+
+def split_pem_list(text: str, *, keep_inbetween: bool = False) -> list[str]:
+    """
+    Split concatenated PEM objects into a list of strings, where each is one PEM object.
+    """
+    result = []
+    current: list[str] | None = [] if keep_inbetween else None
+    for line in text.splitlines(True):
+        if line.strip():
+            if not keep_inbetween and line.startswith("-----BEGIN "):
+                current = []
+            if current is not None:
+                current.append(line)
+                if line.startswith("-----END "):
+                    result.append("".join(current))
+                    current = [] if keep_inbetween else None
+    return result
+
+
+def extract_first_pem(text: str) -> str | None:
+    """
+    Given one PEM or multiple concatenated PEM objects, return only the first one, or None if there is none.
+    """
+    all_pems = split_pem_list(text)
+    if not all_pems:
+        return None
+    return all_pems[0]
+
+
+def _extract_type(line: str, *, start: str = PEM_START) -> str | None:
+    if not line.startswith(start):
+        return None
+    if not line.endswith(PEM_END):
+        return None
+    return line[len(start) : -len(PEM_END)]
+
+
+def extract_pem(content: str, *, strict: bool = False) -> tuple[str, str]:
+    lines = content.splitlines()
+    if len(lines) < 3:
+        raise ValueError(f"PEM must have at least 3 lines, have only {len(lines)}")
+    header_type = _extract_type(lines[0])
+    if header_type is None:
+        raise ValueError(
+            f"First line is not of format {PEM_START}...{PEM_END}: {lines[0]!r}"
+        )
+    footer_type = _extract_type(lines[-1], start=PEM_END_START)
+    if strict:
+        if header_type != footer_type:
+            raise ValueError(
+                f"Header type ({header_type}) is different from footer type ({footer_type})"
+            )
+        for idx, line in enumerate(lines[1:-2]):
+            if len(line) != 64:
+                raise ValueError(f"Line {idx} has length {len(line)} instead of 64")
+        if not (0 < len(lines[-2]) <= 64):
+            raise ValueError(
+                f"Last line has length {len(lines[-2])}, should be in (0, 64]"
+            )
+    return header_type, "".join(lines[1:-1])
+
+
+__all__ = (
+    "PEM_START",
+    "PEM_END_START",
+    "PEM_END",
+    "PKCS8_PRIVATEKEY_NAMES",
+    "PKCS1_PRIVATEKEY_SUFFIX",
+    "identify_pem_format",
+    "identify_private_key_format",
+    "split_pem_list",
+    "extract_first_pem",
+    "extract_pem",
+)

plugins/module_utils/_crypto/support.py

@@ -0,0 +1,447 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import errno
+import hashlib
+import os
+import typing as t
+
+from ansible.module_utils.common.text.converters import to_bytes
+from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+    is_potential_certificate_issuer_private_key,
+    is_potential_certificate_private_key,
+)
+from ansible_collections.community.crypto.plugins.module_utils._crypto.pem import (
+    identify_pem_format,
+)
+
+
+try:
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.serialization import load_pem_private_key
+except ImportError:
+    # Error handled in the calling module.
+    pass
+
+from ansible_collections.community.crypto.plugins.module_utils._crypto.basic import (
+    OpenSSLBadPassphraseError,
+    OpenSSLObjectError,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.module_utils._crypto.cryptography_support import (
+        CertificatePrivateKeyTypes,
+    )
+    from cryptography.hazmat.primitives.asymmetric.types import (
+        CertificateIssuerPrivateKeyTypes,
+        PrivateKeyTypes,
+        PublicKeyTypes,
+    )
+
+
+# This list of preferred fingerprints is used when prefer_one=True is supplied to the
+# fingerprinting methods.
+PREFERRED_FINGERPRINTS = (
+    "sha256",
+    "sha3_256",
+    "sha512",
+    "sha3_512",
+    "sha384",
+    "sha3_384",
+    "sha1",
+    "md5",
+)
+
+
+def get_fingerprint_of_bytes(
+    source: bytes, *, prefer_one: bool = False
+) -> dict[str, str]:
+    """Generate the fingerprint of the given bytes."""
+
+    fingerprint = {}
+
+    algorithms: t.Iterable[str] = hashlib.algorithms_guaranteed
+
+    if prefer_one:
+        # Sort algorithms to have the ones in PREFERRED_FINGERPRINTS at the beginning
+        prefered_algorithms = [
+            algorithm for algorithm in PREFERRED_FINGERPRINTS if algorithm in algorithms
+        ]
+        prefered_algorithms += sorted(
+            [
+                algorithm
+                for algorithm in algorithms
+                if algorithm not in PREFERRED_FINGERPRINTS
+            ]
+        )
+        algorithms = prefered_algorithms
+
+    for algo in algorithms:
+        f = getattr(hashlib, algo)
+        try:
+            h = f(source)
+        except ValueError:
+            # This can happen for hash algorithms not supported in FIPS mode
+            # (https://github.com/ansible/ansible/issues/67213)
+            continue
+        try:
+            # Certain hash functions have a hexdigest() which expects a length parameter
+            pubkey_digest = h.hexdigest()
+        except TypeError:
+            pubkey_digest = h.hexdigest(32)
+        fingerprint[algo] = ":".join(
+            pubkey_digest[i : i + 2] for i in range(0, len(pubkey_digest), 2)
+        )
+        if prefer_one:
+            break
+
+    return fingerprint
+
+
+def get_fingerprint_of_privatekey(
+    privatekey: PrivateKeyTypes, *, prefer_one: bool = False
+) -> dict[str, str]:
+    """Generate the fingerprint of the public key."""
+
+    publickey = privatekey.public_key().public_bytes(
+        serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+    )
+
+    return get_fingerprint_of_bytes(publickey, prefer_one=prefer_one)
+
+
+def get_fingerprint(
+    *,
+    path: os.PathLike | str | None = None,
+    passphrase: str | bytes | None = None,
+    content: bytes | None = None,
+    prefer_one: bool = False,
+) -> dict[str, str]:
+    """Generate the fingerprint of the public key."""
+
+    privatekey = load_privatekey(
+        path=path,
+        passphrase=passphrase,
+        content=content,
+        check_passphrase=False,
+    )
+
+    return get_fingerprint_of_privatekey(privatekey, prefer_one=prefer_one)
+
+
+def load_privatekey(
+    *,
+    path: os.PathLike | str | None = None,
+    passphrase: str | bytes | None = None,
+    check_passphrase: bool = True,
+    content: bytes | None = None,
+) -> PrivateKeyTypes:
+    """Load the specified OpenSSL private key.
+
+    The content can also be specified via content; in that case,
+    this function will not load the key from disk.
+    """
+
+    try:
+        if content is None:
+            if path is None:
+                raise OpenSSLObjectError("Must provide either path or content")
+            with open(path, "rb") as b_priv_key_fh:
+                priv_key_detail = b_priv_key_fh.read()
+        else:
+            priv_key_detail = content
+    except (IOError, OSError) as exc:
+        raise OpenSSLObjectError(exc) from exc
+
+    try:
+        return load_pem_private_key(
+            priv_key_detail,
+            None if passphrase is None else to_bytes(passphrase),
+        )
+    except TypeError as exc:
+        raise OpenSSLBadPassphraseError(
+            "Wrong or empty passphrase provided for private key"
+        ) from exc
+    except ValueError as exc:
+        raise OpenSSLBadPassphraseError(
+            "Wrong passphrase provided for private key"
+        ) from exc
+
+
+def load_certificate_privatekey(
+    *,
+    path: os.PathLike | str | None = None,
+    content: bytes | None = None,
+    passphrase: str | bytes | None = None,
+    check_passphrase: bool = True,
+) -> CertificatePrivateKeyTypes:
+    """
+    Load the specified OpenSSL private key that can be used as a private key for certificates.
+    """
+    private_key = load_privatekey(
+        path=path,
+        passphrase=passphrase,
+        check_passphrase=check_passphrase,
+        content=content,
+    )
+    if not is_potential_certificate_private_key(private_key):
+        raise OpenSSLObjectError(
+            f"Key of type {type(private_key)} not supported for certificates"
+        )
+    return private_key
+
+
+def load_certificate_issuer_privatekey(
+    *,
+    path: os.PathLike | str | None = None,
+    content: bytes | None = None,
+    passphrase: str | bytes | None = None,
+    check_passphrase: bool = True,
+) -> CertificateIssuerPrivateKeyTypes:
+    """
+    Load the specified OpenSSL private key that can be used for issuing certificates.
+    """
+    private_key = load_privatekey(
+        path=path,
+        passphrase=passphrase,
+        check_passphrase=check_passphrase,
+        content=content,
+    )
+    if not is_potential_certificate_issuer_private_key(private_key):
+        raise OpenSSLObjectError(
+            f"Key of type {type(private_key)} not supported for issuing certificates"
+        )
+    return private_key
+
+
+def load_publickey(
+    *, path: os.PathLike | str | None = None, content: bytes | None = None
+) -> PublicKeyTypes:
+    if content is None:
+        if path is None:
+            raise OpenSSLObjectError("Must provide either path or content")
+        try:
+            with open(path, "rb") as b_priv_key_fh:
+                content = b_priv_key_fh.read()
+        except (IOError, OSError) as exc:
+            raise OpenSSLObjectError(exc) from exc
+
+    try:
+        return serialization.load_pem_public_key(content)
+    except Exception as e:
+        raise OpenSSLObjectError(f"Error while deserializing key: {e}") from e
+
+
+def load_certificate(
+    *,
+    path: os.PathLike | str | None = None,
+    content: bytes | None = None,
+    der_support_enabled: bool = False,
+) -> x509.Certificate:
+    """Load the specified certificate."""
+
+    try:
+        if content is None:
+            if path is None:
+                raise OpenSSLObjectError("Must provide either path or content")
+            with open(path, "rb") as cert_fh:
+                cert_content = cert_fh.read()
+        else:
+            cert_content = content
+    except (IOError, OSError) as exc:
+        raise OpenSSLObjectError(exc) from exc
+    if der_support_enabled is False or identify_pem_format(cert_content):
+        try:
+            return x509.load_pem_x509_certificate(cert_content)
+        except ValueError as exc:
+            raise OpenSSLObjectError(exc) from exc
+    elif der_support_enabled:
+        try:
+            return x509.load_der_x509_certificate(cert_content)
+        except ValueError as exc:
+            raise OpenSSLObjectError(f"Cannot parse DER certificate: {exc}") from exc
+
+
+def load_certificate_request(
+    *, path: os.PathLike | str | None = None, content: bytes | None = None
+) -> x509.CertificateSigningRequest:
+    """Load the specified certificate signing request."""
+    try:
+        if content is None:
+            if path is None:
+                raise OpenSSLObjectError("Must provide either path or content")
+            with open(path, "rb") as csr_fh:
+                csr_content = csr_fh.read()
+        else:
+            csr_content = content
+    except (IOError, OSError) as exc:
+        raise OpenSSLObjectError(exc) from exc
+    try:
+        return x509.load_pem_x509_csr(csr_content)
+    except ValueError as exc:
+        raise OpenSSLObjectError(exc) from exc
+
+
+def parse_name_field(
+    input_dict: dict[str, list[str | bytes] | str | bytes],
+    *,
+    name_field_name: str | None = None,
+) -> list[tuple[str, str | bytes]]:
+    """Take a dict with key: value or key: list_of_values mappings and return a list of tuples"""
+
+    def error_str(key: str) -> str:
+        if name_field_name is None:
+            return f"{key}"
+        return f"{key} in {name_field_name}"
+
+    result = []
+    for key, value in input_dict.items():
+        if isinstance(value, list):
+            for entry in value:
+                if not isinstance(entry, (str, bytes)):
+                    raise TypeError(f"Values {error_str(key)} must be strings")
+                if not entry:
+                    raise ValueError(
+                        f"Values for {error_str(key)} must not be empty strings"
+                    )
+                result.append((key, entry))
+        elif isinstance(value, (str, bytes)):
+            if not value:
+                raise ValueError(
+                    f"Value for {error_str(key)} must not be an empty string"
+                )
+            result.append((key, value))
+        else:
+            raise TypeError(
+                f"Value for {error_str(key)} must be either a string or a list of strings"
+            )
+    return result
+
+
+def parse_ordered_name_field(
+    input_list: list[dict[str, list[str | bytes] | str | bytes]],
+    *,
+    name_field_name: str,
+) -> list[tuple[str, str | bytes]]:
+    """Take a dict with key: value or key: list_of_values mappings and return a list of tuples"""
+
+    result = []
+    for index, entry in enumerate(input_list):
+        if len(entry) != 1:
+            raise ValueError(
+                f"Entry #{index + 1} in {name_field_name} must be a dictionary with exactly one key-value pair"
+            )
+        try:
+            result.extend(parse_name_field(entry, name_field_name=name_field_name))
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"Error while processing entry #{index + 1} in {name_field_name}: {exc}"
+            ) from exc
+    return result
+
+
+@t.overload
+def select_message_digest(
+    digest_string: t.Literal["sha256", "sha384", "sha512", "sha1", "md5"],
+) -> hashes.SHA256 | hashes.SHA384 | hashes.SHA512 | hashes.SHA1 | hashes.MD5: ...
+
+
+@t.overload
+def select_message_digest(
+    digest_string: str,
+) -> (
+    hashes.SHA256 | hashes.SHA384 | hashes.SHA512 | hashes.SHA1 | hashes.MD5 | None
+): ...
+
+
+def select_message_digest(
+    digest_string: str,
+) -> hashes.SHA256 | hashes.SHA384 | hashes.SHA512 | hashes.SHA1 | hashes.MD5 | None:
+    if digest_string == "sha256":
+        return hashes.SHA256()
+    if digest_string == "sha384":
+        return hashes.SHA384()
+    if digest_string == "sha512":
+        return hashes.SHA512()
+    if digest_string == "sha1":
+        return hashes.SHA1()
+    if digest_string == "md5":
+        return hashes.MD5()
+    return None
+
+
+class OpenSSLObject(metaclass=abc.ABCMeta):
+
+    def __init__(self, *, path: str, state: str, force: bool, check_mode: bool) -> None:
+        self.path = path
+        self.state = state
+        self.force = force
+        self.name = os.path.basename(path)
+        self.changed = False
+        self.check_mode = check_mode
+
+    def check(self, module: AnsibleModule, *, perms_required: bool = True) -> bool:
+        """Ensure the resource is in its desired state."""
+
+        def _check_state() -> bool:
+            return os.path.exists(self.path)
+
+        def _check_perms(module: AnsibleModule) -> bool:
+            file_args = module.load_file_common_arguments(module.params)
+            if module.check_file_absent_if_check_mode(file_args["path"]):
+                return False
+            return not module.set_fs_attributes_if_different(file_args, False)
+
+        if not perms_required:
+            return _check_state()
+
+        return _check_state() and _check_perms(module)
+
+    @abc.abstractmethod
+    def dump(self) -> dict[str, t.Any]:
+        """Serialize the object into a dictionary."""
+
+    @abc.abstractmethod
+    def generate(self, module: AnsibleModule) -> None:
+        """Generate the resource."""
+
+    def remove(self, module: AnsibleModule) -> None:
+        """Remove the resource from the filesystem."""
+        if self.check_mode:
+            if os.path.exists(self.path):
+                self.changed = True
+            return
+
+        try:
+            os.remove(self.path)
+            self.changed = True
+        except OSError as exc:
+            if exc.errno != errno.ENOENT:
+                raise OpenSSLObjectError(exc) from exc
+
+
+__all__ = (
+    "get_fingerprint_of_bytes",
+    "get_fingerprint_of_privatekey",
+    "get_fingerprint",
+    "load_privatekey",
+    "load_certificate_privatekey",
+    "load_certificate_issuer_privatekey",
+    "load_publickey",
+    "load_certificate",
+    "load_certificate_request",
+    "parse_name_field",
+    "parse_ordered_name_field",
+    "select_message_digest",
+    "OpenSSLObject",
+)

plugins/module_utils/_cryptography_dep.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2025 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+"""
+Module utils for cryptography requirements.
+
+Must be kept in sync with plugins/doc_fragments/cryptography_dep.py.
+"""
+
+from __future__ import annotations
+
+import traceback
+import typing as t
+
+from ansible.module_utils.basic import missing_required_lib
+from ansible_collections.community.crypto.plugins.module_utils._version import (
+    LooseVersion,
+)
+
+
+if t.TYPE_CHECKING:
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible_collections.community.crypto.plugins.plugin_utils._action_module import (
+        AnsibleActionModule,
+    )
+    from ansible_collections.community.crypto.plugins.plugin_utils._filter_module import (
+        FilterModuleMock,
+    )
+
+    GeneralAnsibleModule = t.Union[AnsibleModule, AnsibleActionModule, FilterModuleMock]
+
+
+_CRYPTOGRAPHY_IMP_ERR: str | None = None
+_CRYPTOGRAPHY_FILE: str | None = None
+try:
+    import cryptography
+    from cryptography import x509  # noqa: F401, pylint: disable=unused-import
+
+    CRYPTOGRAPHY_VERSION = LooseVersion(cryptography.__version__)
+    _CRYPTOGRAPHY_FILE = cryptography.__file__
+except ImportError:
+    _CRYPTOGRAPHY_IMP_ERR = traceback.format_exc()
+    CRYPTOGRAPHY_FOUND = False
+    CRYPTOGRAPHY_VERSION = LooseVersion("0.0")
+else:
+    CRYPTOGRAPHY_FOUND = True
+
+
+# Corresponds to the community.crypto.cryptography_dep.minimum doc fragment
+COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION = "3.3"
+
+
+def assert_required_cryptography_version(
+    module: GeneralAnsibleModule,
+    *,
+    minimum_cryptography_version: str = COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION,
+) -> None:
+    if not CRYPTOGRAPHY_FOUND:
+        module.fail_json(
+            msg=missing_required_lib(f"cryptography >= {minimum_cryptography_version}"),
+            exception=_CRYPTOGRAPHY_IMP_ERR,
+        )
+    if CRYPTOGRAPHY_VERSION < LooseVersion(minimum_cryptography_version):
+        module.fail_json(
+            msg=(
+                f"Cannot detect the required Python library cryptography (>= {minimum_cryptography_version})."
+                f" Only found a too old version ({CRYPTOGRAPHY_VERSION}) at {_CRYPTOGRAPHY_FILE}."
+            ),
+        )
+
+
+__all__ = (
+    "COLLECTION_MINIMUM_CRYPTOGRAPHY_VERSION",
+    "CRYPTOGRAPHY_FOUND",
+    "CRYPTOGRAPHY_VERSION",
+    "assert_required_cryptography_version",
+)

plugins/module_utils/_gnupg/cli.py

@@ -0,0 +1,88 @@
+# 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
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+from __future__ import annotations
+
+import abc
+import os
+
+
+class GPGError(Exception):
+    pass
+
+
+class GPGRunner(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def run_command(
+        self, command: list[str], *, check_rc: bool = True, data: bytes | None = None
+    ) -> tuple[int, str, str]:
+        """
+        Run ``[gpg] + command`` and return ``(rc, stdout, stderr)``.
+
+        If ``data`` is not ``None``, it will be provided as stdin.
+        The code assumes it is a bytes string.
+
+        Returned stdout and stderr are native Python strings.
+        Pass ``check_rc=False`` to allow return codes != 0.
+
+        Raises a ``GPGError`` in case of errors.
+        """
+
+
+def get_fingerprint_from_stdout(*, stdout: str) -> str:
+    lines = stdout.splitlines(False)
+    for line in lines:
+        if line.startswith("fpr:"):
+            parts = line.split(":")
+            if len(parts) <= 9 or not parts[9]:
+                raise GPGError(
+                    f'Result line "{line}" does not have fingerprint as 10th component'
+                )
+            return parts[9]
+    raise GPGError(f'Cannot extract fingerprint from stdout "{stdout}"')
+
+
+def get_fingerprint_from_file(*, gpg_runner: GPGRunner, path: str) -> str:
+    if not os.path.exists(path):
+        raise GPGError(f"{path} does not exist")
+    stdout = gpg_runner.run_command(
+        [
+            "--no-keyring",
+            "--with-colons",
+            "--import-options",
+            "show-only",
+            "--import",
+            path,
+        ],
+        check_rc=True,
+    )[1]
+    return get_fingerprint_from_stdout(stdout=stdout)
+
+
+def get_fingerprint_from_bytes(*, gpg_runner: GPGRunner, content: bytes) -> str:
+    stdout = gpg_runner.run_command(
+        [
+            "--no-keyring",
+            "--with-colons",
+            "--import-options",
+            "show-only",
+            "--import",
+            "/dev/stdin",
+        ],
+        data=content,
+        check_rc=True,
+    )[1]
+    return get_fingerprint_from_stdout(stdout=stdout)
+
+
+__all__ = (
+    "GPGError",
+    "GPGRunner",
+    "get_fingerprint_from_stdout",
+    "get_fingerprint_from_file",
+    "get_fingerprint_from_bytes",
+)