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
    Choices:
  • 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.