Refactor x509_certificate module, add x509_certificate_pipe module (#135)

* Move documentation to doc fragment.

* Prepare module backends.

* Linting.

* Fix comments.

* First shot at actually moving code.

* Forgot SKI check.

* Remove unused imports.

* Improve check mode.

* Fix 'returned'.

* Move csr_* checks.

* Explicitly specify parameter.

* Add x509_certificate_pipe module.

* Update other seealsos.

* Forgot to remove doc fragment.

* Adjust to work with macOS 10.15.

* Update plugins/module_utils/crypto/module_backends/certificate_entrust.py

Co-authored-by: Chris Trufan <31186388+ctrufan@users.noreply.github.com>

* Add changelog fragments for entrust bugfix and module refactorings.

* Restore old behavior of Entrust backend when existing certificate cannot be parsed.

* Update plugins/modules/x509_certificate_pipe.py

Co-authored-by: Chris Trufan <31186388+ctrufan@users.noreply.github.com>

* Remove Entrust provider from x509_certificate_pipe for now.

* Add own CA tests.

* One more fix for Entrust provider, when csr_content is used.

* Update plugins/modules/x509_certificate_pipe.py

Co-authored-by: Chris Trufan <31186388+ctrufan@users.noreply.github.com>

* Fix another broken example.

* Revert "Remove Entrust provider from x509_certificate_pipe for now."

This reverts commit 6ee5d7d4f99f0fe2218276a2d3f1f38b676c29b9.

* ci_complete

* Apply suggestions from code review

Co-authored-by: MarkusTeufelberger <mteufelberger@mgit.at>

* Improve example.

* Improve readability of example, add another one.

* Extend descriptions of csr_* for selfsigned.

* Improve documentation.

* Move deprecation message up.

* Explain empty choices.

Co-authored-by: Chris Trufan <31186388+ctrufan@users.noreply.github.com>
Co-authored-by: MarkusTeufelberger <mteufelberger@mgit.at>

tests/integration/targets/x509_certificate_pipe/aliases

@@ -0,0 +1,2 @@
+shippable/posix/group1
+destructive

tests/integration/targets/x509_certificate_pipe/meta/main.yml

@@ -0,0 +1,3 @@
+dependencies:
+  - setup_openssl
+  - setup_pyopenssl

tests/integration/targets/x509_certificate_pipe/tasks/impl.yml

@@ -0,0 +1,237 @@
+---
+- name: "({{ select_crypto_backend }}) Generate privatekey"
+  openssl_privatekey:
+    path: '{{ output_dir }}/{{ item }}.pem'
+    size: 2048
+  loop:
+    - privatekey
+    - privatekey2
+
+- name: "({{ select_crypto_backend }}) Generate CSRs"
+  openssl_csr:
+    privatekey_path: '{{ output_dir }}/{{ item.key }}.pem'
+    path: '{{ output_dir }}/{{ item.name }}.csr'
+    subject:
+      commonName: '{{ item.cn }}'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  loop:
+  - name: cert
+    key: privatekey
+    cn: www.ansible.com
+  - name: cert-2
+    key: privatekey
+    cn: ansible.com
+  - name: cert-3
+    key: privatekey2
+    cn: example.com
+  - name: cert-4
+    key: privatekey2
+    cn: example.org
+
+## Self Signed
+
+- name: "({{ select_crypto_backend }}) Generate self-signed certificate (check mode)"
+  x509_certificate_pipe:
+    provider: selfsigned
+    privatekey_path: '{{ output_dir }}/privatekey.pem'
+    selfsigned_not_before: 20181023133742Z
+    selfsigned_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  check_mode: yes
+  register: generate_certificate_check
+
+- name: "({{ select_crypto_backend }}) Generate self-signed certificate"
+  x509_certificate_pipe:
+    provider: selfsigned
+    privatekey_path: '{{ output_dir }}/privatekey.pem'
+    selfsigned_not_before: 20181023133742Z
+    selfsigned_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  register: generate_certificate
+
+- name: "({{ select_crypto_backend }}) Generate self-signed certificate (idempotent)"
+  x509_certificate_pipe:
+    provider: selfsigned
+    content: "{{ generate_certificate.certificate }}"
+    privatekey_path: '{{ output_dir }}/privatekey.pem'
+    selfsigned_not_before: 20181023133742Z
+    selfsigned_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  register: generate_certificate_idempotent
+
+- name: "({{ select_crypto_backend }}) Generate self-signed certificate (idempotent, check mode)"
+  x509_certificate_pipe:
+    provider: selfsigned
+    content: "{{ generate_certificate.certificate }}"
+    privatekey_path: '{{ output_dir }}/privatekey.pem'
+    selfsigned_not_before: 20181023133742Z
+    selfsigned_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  check_mode: yes
+  register: generate_certificate_idempotent_check
+
+- name: "({{ select_crypto_backend }}) Generate self-signed certificate (changed)"
+  x509_certificate_pipe:
+    provider: selfsigned
+    content: "{{ generate_certificate.certificate }}"
+    privatekey_path: '{{ output_dir }}/privatekey.pem'
+    selfsigned_not_before: 20181023133742Z
+    selfsigned_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-2.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  register: generate_certificate_changed
+
+- name: "({{ select_crypto_backend }}) Generate self-signed certificate (changed, check mode)"
+  x509_certificate_pipe:
+    provider: selfsigned
+    content: "{{ generate_certificate.certificate }}"
+    privatekey_path: '{{ output_dir }}/privatekey.pem'
+    selfsigned_not_before: 20181023133742Z
+    selfsigned_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-2.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  check_mode: yes
+  register: generate_certificate_changed_check
+
+- name: "({{ select_crypto_backend }}) Validate certificate (test - privatekey modulus)"
+  shell: '{{ openssl_binary }} rsa -noout -modulus -in {{ output_dir }}/privatekey.pem'
+  register: privatekey_modulus
+
+- name: "({{ select_crypto_backend }}) Validate certificate (test - Common Name)"
+  shell: "{{ openssl_binary }} x509 -noout -subject -in /dev/stdin -nameopt oneline,-space_eq"
+  args:
+    stdin: "{{ generate_certificate.certificate }}"
+  register: certificate_cn
+
+- name: "({{ select_crypto_backend }}) Validate certificate (test - certificate modulus)"
+  shell: '{{ openssl_binary }} x509 -noout -modulus -in /dev/stdin'
+  args:
+    stdin: "{{ generate_certificate.certificate }}"
+  register: certificate_modulus
+
+- name: "({{ select_crypto_backend }}) Validate certificate (assert)"
+  assert:
+    that:
+      - certificate_cn.stdout.split('=')[-1] == 'www.ansible.com'
+      - certificate_modulus.stdout == privatekey_modulus.stdout
+
+- name: "({{ select_crypto_backend }}) Validate certificate (check mode, idempotency)"
+  assert:
+    that:
+      - generate_certificate_check is changed
+      - generate_certificate is changed
+      - generate_certificate_idempotent is not changed
+      - generate_certificate_idempotent_check is not changed
+      - generate_certificate_changed is changed
+      - generate_certificate_changed_check is changed
+
+## Own CA
+
+- name: "({{ select_crypto_backend }}) Generate own CA certificate (check mode)"
+  x509_certificate_pipe:
+    provider: ownca
+    ownca_content: '{{ generate_certificate.certificate }}'
+    ownca_privatekey_path: '{{ output_dir }}/privatekey.pem'
+    ownca_not_before: 20181023133742Z
+    ownca_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-3.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  check_mode: yes
+  register: ownca_generate_certificate_check
+
+- name: "({{ select_crypto_backend }}) Generate own CA certificate"
+  x509_certificate_pipe:
+    provider: ownca
+    ownca_content: '{{ generate_certificate.certificate }}'
+    ownca_privatekey_path: '{{ output_dir }}/privatekey.pem'
+    ownca_not_before: 20181023133742Z
+    ownca_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-3.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  register: ownca_generate_certificate
+
+- name: "({{ select_crypto_backend }}) Generate own CA certificate (idempotent)"
+  x509_certificate_pipe:
+    provider: ownca
+    content: "{{ ownca_generate_certificate.certificate }}"
+    ownca_content: '{{ generate_certificate.certificate }}'
+    ownca_privatekey_path: '{{ output_dir }}/privatekey.pem'
+    ownca_not_before: 20181023133742Z
+    ownca_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-3.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  register: ownca_generate_certificate_idempotent
+
+- name: "({{ select_crypto_backend }}) Generate own CA certificate (idempotent, check mode)"
+  x509_certificate_pipe:
+    provider: ownca
+    content: "{{ ownca_generate_certificate.certificate }}"
+    ownca_content: '{{ generate_certificate.certificate }}'
+    ownca_privatekey_path: '{{ output_dir }}/privatekey.pem'
+    ownca_not_before: 20181023133742Z
+    ownca_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-3.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  check_mode: yes
+  register: ownca_generate_certificate_idempotent_check
+
+- name: "({{ select_crypto_backend }}) Generate own CA certificate (changed)"
+  x509_certificate_pipe:
+    provider: ownca
+    content: "{{ ownca_generate_certificate.certificate }}"
+    ownca_content: '{{ generate_certificate.certificate }}'
+    ownca_privatekey_path: '{{ output_dir }}/privatekey.pem'
+    ownca_not_before: 20181023133742Z
+    ownca_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-4.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  register: ownca_generate_certificate_changed
+
+- name: "({{ select_crypto_backend }}) Generate own CA certificate (changed, check mode)"
+  x509_certificate_pipe:
+    provider: ownca
+    content: "{{ ownca_generate_certificate.certificate }}"
+    ownca_content: '{{ generate_certificate.certificate }}'
+    ownca_privatekey_path: '{{ output_dir }}/privatekey.pem'
+    ownca_not_before: 20181023133742Z
+    ownca_not_after: 20191023133742Z
+    csr_path: '{{ output_dir }}/cert-4.csr'
+    select_crypto_backend: '{{ select_crypto_backend }}'
+  check_mode: yes
+  register: ownca_generate_certificate_changed_check
+
+- name: "({{ select_crypto_backend }}) Validate certificate (test - privatekey modulus)"
+  shell: '{{ openssl_binary }} rsa -noout -modulus -in {{ output_dir }}/privatekey2.pem'
+  register: privatekey_modulus
+
+- name: "({{ select_crypto_backend }}) Validate certificate (test - Common Name)"
+  shell: "{{ openssl_binary }} x509 -noout -subject -in /dev/stdin -nameopt oneline,-space_eq"
+  args:
+    stdin: "{{ ownca_generate_certificate.certificate }}"
+  register: certificate_cn
+
+- name: "({{ select_crypto_backend }}) Validate certificate (test - certificate modulus)"
+  shell: '{{ openssl_binary }} x509 -noout -modulus -in /dev/stdin'
+  args:
+    stdin: "{{ ownca_generate_certificate.certificate }}"
+  register: certificate_modulus
+
+- name: "({{ select_crypto_backend }}) Validate certificate (assert)"
+  assert:
+    that:
+      - certificate_cn.stdout.split('=')[-1] == 'example.com'
+      - certificate_modulus.stdout == privatekey_modulus.stdout
+
+- name: "({{ select_crypto_backend }}) Validate certificate (check mode, idempotency)"
+  assert:
+    that:
+      - ownca_generate_certificate_check is changed
+      - ownca_generate_certificate is changed
+      - ownca_generate_certificate_idempotent is not changed
+      - ownca_generate_certificate_idempotent_check is not changed
+      - ownca_generate_certificate_changed is changed
+      - ownca_generate_certificate_changed_check is changed

tests/integration/targets/x509_certificate_pipe/tasks/main.yml

@@ -0,0 +1,39 @@
+---
+####################################################################
+# WARNING: These are designed specifically for Ansible tests       #
+# and should not be used as examples of how to write Ansible roles #
+####################################################################
+
+- name: Prepare private key for backend autodetection test
+  openssl_privatekey:
+    path: '{{ output_dir }}/privatekey_backend_selection.pem'
+- name: Run module with backend autodetection
+  x509_certificate_pipe:
+    provider: selfsigned
+    privatekey_path: '{{ output_dir }}/privatekey_backend_selection.pem'
+
+- block:
+  - name: Running tests with pyOpenSSL backend
+    include_tasks: impl.yml
+    vars:
+      select_crypto_backend: pyopenssl
+
+  when: pyopenssl_version.stdout is version('0.15', '>=')
+
+- name: Remove output directory
+  file:
+    path: "{{ output_dir }}"
+    state: absent
+
+- name: Re-create output directory
+  file:
+    path: "{{ output_dir }}"
+    state: directory
+
+- block:
+  - name: Running tests with cryptography backend
+    include_tasks: impl.yml
+    vars:
+      select_crypto_backend: cryptography
+
+  when: cryptography_version.stdout is version('1.6', '>=')