acme_challenge_cert_helper – Prepare certificates required for ACME challenges such as tls-alpn-01

From Get docs
Ansible/docs/2.7/modules/acme challenge cert helper module


acme_challenge_cert_helper – Prepare certificates required for ACME challenges such as tls-alpn-01

New in version 2.7.


Synopsis

  • Prepares certificates for ACME challenges such as tls-alpn-01.
  • The raw data is provided by the acme_certificate module, and needs to be converted to a certificate to be used for challenge validation. This module provides a simple way to generate the required certificates.
  • The tls-alpn-01 implementation is based on the draft-05 version of the specification.

Requirements

The below requirements are needed on the host that executes this module.

  • cryptography >= 1.3

Parameters

Parameter Choices/Defaults Comments

challenge

- / required

  • tls-alpn-01

The challenge type.

challenge_data

- / required

The challenge_data entry provided by acme_certificate for the challenge.

private_key_content

-

Content of the private key to use for this challenge certificate.

Mutually exclusive with private_key_src.

private_key_src

-

Path to a file containing the private key file to use for this challenge certificate.

Mutually exclusive with private_key_content.



Examples

- name: Create challenges for a given CRT for sample.com
  acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    challenge: tls-alpn-01
    csr: /etc/pki/cert/csr/sample.com.csr
    dest: /etc/httpd/ssl/sample.com.crt
  register: sample_com_challenge

- name: Create certificates for challenges
  acme_challenge_cert_helper:
    challenge: tls-alpn-01
    challenge_data: "{{ item.value['tls-alpn-01'] }}"
    private_key_src: /etc/pki/cert/key/sample.com.key
  with_items: "{{ sample_com_challenge.challenge_data }}"
  register: sample_com_challenge_certs

- name: Install challenge certificates
  # We need to set up HTTPS such that for the domain,
  # regular_certificate is delivered for regular connections,
  # except if ALPN selects the "acme-tls/1"; then, the
  # challenge_certificate must be delivered.
  # This can for example be achieved with very new versions
  # of NGINX; search for ssl_preread and
  # ssl_preread_alpn_protocols for information on how to
  # route by ALPN protocol.
  ...:
    domain: "{{ item.domain }}"
    challenge_certificate: "{{ item.challenge_certificate }}"
    regular_certificate: "{{ item.regular_certificate }}"
    private_key: /etc/pki/cert/key/sample.com.key
  with_items: "{{ sample_com_challenge_certs.results }}"

- name: Create certificate for a given CSR for sample.com
  acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    challenge: tls-alpn-01
    csr: /etc/pki/cert/csr/sample.com.csr
    dest: /etc/httpd/ssl/sample.com.crt
    data: "{{ sample_com_challenge }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description

challenge_certificate

string

always

The challenge certificate in PEM format.


domain

string

always

The domain the challenge is for.


regular_certificate

string

always

A self-signed certificate for the challenge domain.

If no existing certificate exists, can be used to set-up https in the first place if that is needed for providing the challenge.





Status

Authors

  • Felix Fontein (@felixfontein)

Hint

If you notice any issues in this documentation you can edit this document to improve it.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/acme_challenge_cert_helper_module.html