maxhoesel.smallstep.step_certificate_info module – Retrieve certificate details and validation status

Note

This module is part of the maxhoesel.smallstep collection (version 0.24.5).

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 maxhoesel.smallstep. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: maxhoesel.smallstep.step_certificate_info.

New in maxhoesel.smallstep 1.0.0

Synopsis

  • This module runs step certificate inspect on the specified file and returns its JSON/PEM-formatted output. If the certificate file contains multiple certificates (i.e., it is a certificate “bundle”) the first certificate in the bundle will be output. Pass the bundle option to return all certificates in the order in which they appear in the bundle. Additionally, this module also returns the validation status of the certificate (see return values), as determined by step certificate verify

Requirements

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

  • step-cli must be installed on the remote host. You can set the executable name/path with step_cli_executable.

Parameters

Parameter

Comments

bundle

boolean

Print all certificates in the order in which they appear in the bundle. If the output format is ‘json’ then output a list of certificates, even if the bundle only contains one certificate. This flag will result in an error if the input bundle includes any PEM that does not have type CERTIFICATE.

Choices:

  • false ← (default)

  • true

format

string

What format to return. Determines which of the return values will be populated.

Choices:

  • "json" ← (default)

  • "text"

  • "text-short"

  • "pem"

insecure

boolean

Use an insecure client to retrieve a remote peer certificate. Useful for debugging invalid certificates remotely.

Choices:

  • false ← (default)

  • true

path

aliases: crt_file

path / required

Path to a certificate or certificate signing request (CSR) to inspect

roots

string

Root certificate(s) that will be used to verify the authenticity of the remote server. Case-sensitive string, may be one of: Relative or full path to a file - All certificates in the file will be used for path validation. Comma-separated list of relative or full file paths - Every PEM encoded certificate from each file will be used for path validation. Relative or full path to a directory - Every PEM encoded certificate from each file in the directory will be used for path validation.

server_name

aliases: servername

string

TLS Server Name Indication that should be sent to request a specific certificate from the server.

step_cli_executable

path

Name (or absolute path) of the step-cli executable to use

Default: "step-cli"

Notes

Note

  • Check mode is supported.

Examples

# See https://smallstep.com/docs/step-cli/reference/certificate/inspect for more examples

- name: Inspect a local certificate bundle
  maxhoesel.smallstep.step_certificate_info:
    path: /path/to/certificate.crt
    bundle: true

Return Values

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

Key

Description

json

any

The certificate data returned by step-cli, as a JSON data structure.

Returned: When format=json

pem

string

The certificate data returned by step-cli, in PEM format

Returned: When format=pem

text

string

The certificate data returned by step-cli, in text format

Returned: When format=text or format=text-short

valid

boolean

Whether the certificate passed verification by step certificate verify

Returned: always

validity_fail_reason

string

Reason for failed certificate validity check, as output by step-cli.

Returned: When valid=false

Authors

  • Max Hösel (@maxhoesel)