community.crypto.certificate_complete_chain module – Complete certificate chain given a set of untrusted and root certificates

Note

This module is part of the community.crypto collection (version 2.16.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.crypto. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.crypto.certificate_complete_chain.

Synopsis

  • This module completes a given chain of certificates in PEM format by finding intermediate certificates from a given set of certificates, until it finds a root certificate in another given set of certificates.

  • This can for example be used to find the root certificate for a certificate chain returned by community.crypto.acme_certificate.

  • Note that this module does not check for validity of the chains. It only checks that issuer and subject match, and that the signature is correct. It ignores validity dates and key usage completely. If you need to verify that a generated chain is valid, please use openssl verify ....

Requirements

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

  • cryptography >= 1.5

Parameters

Parameter

Comments

input_chain

string / required

A concatenated set of certificates in PEM format forming a chain.

The module will try to complete this chain.

intermediate_certificates

list / elements=path

A list of filenames or directories.

A filename is assumed to point to a file containing one or more certificates in PEM format. All certificates in this file will be added to the set of root certificates.

If a directory name is given, all files in the directory and its subdirectories will be scanned and tried to be parsed as concatenated certificates in PEM format.

Symbolic links will be followed.

Default: []

root_certificates

list / elements=path / required

A list of filenames or directories.

A filename is assumed to point to a file containing one or more certificates in PEM format. All certificates in this file will be added to the set of root certificates.

If a directory name is given, all files in the directory and its subdirectories will be scanned and tried to be parsed as concatenated certificates in PEM format.

Symbolic links will be followed.

Attributes

Attribute

Support

Description

check_mode

Support: full

This action does not modify state.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: N/A

This action does not modify state.

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

# Given a leaf certificate for www.ansible.com and one or more intermediate
# certificates, finds the associated root certificate.
- name: Find root certificate
  community.crypto.certificate_complete_chain:
    input_chain: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com-fullchain.pem') }}"
    root_certificates:
    - /etc/ca-certificates/
  register: www_ansible_com
- name: Write root certificate to disk
  ansible.builtin.copy:
    dest: /etc/ssl/csr/www.ansible.com-root.pem
    content: "{{ www_ansible_com.root }}"

# Given a leaf certificate for www.ansible.com, and a list of intermediate
# certificates, finds the associated root certificate.
- name: Find root certificate
  community.crypto.certificate_complete_chain:
    input_chain: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.pem') }}"
    intermediate_certificates:
    - /etc/ssl/csr/www.ansible.com-chain.pem
    root_certificates:
    - /etc/ca-certificates/
  register: www_ansible_com
- name: Write complete chain to disk
  ansible.builtin.copy:
    dest: /etc/ssl/csr/www.ansible.com-completechain.pem
    content: "{{ ''.join(www_ansible_com.complete_chain) }}"
- name: Write root chain (intermediates and root) to disk
  ansible.builtin.copy:
    dest: /etc/ssl/csr/www.ansible.com-rootchain.pem
    content: "{{ ''.join(www_ansible_com.chain) }}"

Return Values

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

Key

Description

chain

list / elements=string

The chain added to the given input chain. Includes the root certificate.

Returned as a list of PEM certificates.

Returned: success

complete_chain

list / elements=string

The completed chain, including leaf, all intermediates, and root.

Returned as a list of PEM certificates.

Returned: success

root

string

The root certificate in PEM format.

Returned: success

Authors

  • Felix Fontein (@felixfontein)