maxhoesel.smallstep.step_ca_certificate module – Manage a step-ca-signed certificate on the target system

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_ca_certificate.

New in maxhoesel.smallstep 0.3.0

Synopsis 

Creates, updates, revokes or deletes a CA-issued certificate on the target system. This module exposes mostly the same parameters as the upstream step ca certificate, step ca renew/rekey and step ca revoke commands, depending on the selected certificate state.

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
acme string	ACME directory url to be used for requesting certificates via the ACME protocol. Use this parameter to define an ACME server other than the Step CA. If this flag is absent and an ACME provisioner has been selected then the ca_url parameter must be defined.
attestation_ca_root path	The path to the PEM file with trusted roots when connecting to the Attestation CA.
attestation_ca_url string	The base url of the Attestation CA to use.
attestation_uri string	The KMS uri used for attestation.
ca_config path	The path to the certificate authority configuration file on the host.
ca_url string	URI of the targeted Step Certificate Authority. Used if the module is run in online mode (default) and the hosts `step-cli` is not configured to trust the CA.
console boolean	Complete the flow while remaining inside the terminal Choices: `false` `true`
contact list / elements=string	The email-address used for contact as part of the ACME protocol. These contacts may be used to warn of certificate expiration or other certificate lifetime events. Must be a list
crt_file path / required	File to write the certificate (PEM format).
curve aliases: crv string	The elliptic curve to use for EC and OKP key types. Corresponds to the “crv” JWK parameter. Valid curves are defined in JWA RFC7518. If unset, default is P-256 for EC keys and Ed25519 for OKP keys. Choices: `"P-256"` `"P-384"` `"P-521"` `"Ed25519"`
force boolean	If true and state=present, a new certificate will be generated each time this module is executed, regardless of existing certificates. Choices: `false` `true`
http_listen string	Use a non-standard http address, behind a reverse proxy or load balancer, for serving ACME challenges. The default address is :80, which requires super user (sudo) privileges. This flag must be used in conjunction with the standalone param.
k8ssa_token_path path	Configure the file from which to read the kubernetes service account token.
key_file path / required	File to write the private key (PEM format).
kms string	The uri to configure a Cloud KMS or an HSM.
kty string	The kty to build the certificate upon. If unset, default is EC. kty is a case-sensitive string. Choices: `"EC"` `"OKP"` `"RSA"`
name aliases: subject string	The Common Name, DNS Name, or IP address that will be set as the Subject Common Name for the certificate. If no Subject Alternative Names (SANs) are configured (via the san parameter) then the subject will be set as the only SAN. Required if state=present.
nebula_cert path	Certificate file in PEM format to store in the ‘nebula’ header of a JWT.
nebula_key path	Private key file, used to sign a JWT, corresponding to the certificate that will be stored in the ‘nebula’ header.
not_after string	The time/duration when the certificate validity period ends. If a time is used it is expected to be in RFC 3339 format. If a duration is used, it is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
not_before string	The time/duration when the certificate validity period starts. If a time is used it is expected to be in RFC 3339 format. If a duration is used, it is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.
offline boolean	Don’t contact the CA. Offline mode uses the configuration, certificates, and keys created with step ca init, but can accept a different configuration file using the ca_config flag. Choices: `false` `true`
provisioner aliases: issuer string	The provisioner name to use. Required if state=present.
provisioner_password string	The password to decrypt the one-time token generating key. Will be passed to step-cli through a temporary file. Mutually exclusive with provisioner_password_file
provisioner_password_file path	The path to the file containing the password to decrypt the one-time token generating key. Mutually exclusive with provisioner_password
revoke_on_delete boolean	If state=absent, attempt to revoke the certificate before deleting it Choices: `false` `true` ← (default)
revoke_reason string	The string representing the reason for which the cert is being revoked. Only has an effect if state=revoked or state=absent and revoke_on_delete=True
revoke_reason_code string	The reasonCode specifies the reason for revocation - chose from a list of common revocation reasons. If unset, the default is Unspecified. See https://smallstep.com/docs/step-cli/reference/ca/revoke for a list of codes
root path	The path to the PEM file used as the root certificate authority. Used if the module is run in online mode (default) and the hosts `step-cli` is not configured to trust the CA.
san list / elements=string	Add dns/ip/email/uri Subject Alternative Name(s) (SANs) that should be authorized. The san parameter and the token parameter are mutually exclusive. Must be a list.
set list / elements=string	The key=value pair with template data variables to send to the CA. Must be a list.
set_file path	The path of a JSON file with the template data to send to the CA.
size integer	The size (in bits) of the key for RSA and oct key types. RSA keys require a minimum key size of 2048 bits. If unset, default is 2048 bits for RSA keys and 128 bits for oct keys.
standalone boolean	Get a certificate using the ACME protocol and standalone mode for validation. Standalone is a mode in which the step process will run a server that will will respond to ACME challenge validation requests. Standalone is the default mode for serving challenge validation requests. Choices: `false` `true`
state string	State that the certificate should be in. If state=present, the certificate will be (re-)issued if it doesn’t exist, is invalid/expired or if its SAN/private key parameters change. If state=revoked, the certificate will be revoked with the CA If state=absent, the certificate will be removed from the host (and optionally revoked with the CA beforehand, see revoke_on_delete. Choices: `"present"` ← (default) `"revoked"` `"absent"`
step_cli_executable path	Name (or absolute path) of the `step-cli` executable to use Default: `"step-cli"`
token string	The one-time token used to authenticate with the CA in order to create the certificate.
tpm_storage_directory path	The directory where TPM keys and certificates will be stored
verify_roots string	Root certificates to use when checking an existing certificates validity. Only required if your CA root is not in the system truststore. 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.
webroot path	Specify a path to use as a ‘web root’ for validation in the ACME protocol. Webroot is a mode in which the step process will write a challenge file to a location being served by an existing fileserver in order to respond to ACME challenge validation requests.
x5c_cert string	Certificate (chain) in PEM format to store in the ‘x5c’ header of a JWT.
x5c_key path	Private key path, used to sign a JWT, corresponding to the certificate that will be stored in the ‘x5c’ header.

Notes 

Note

Check mode is supported.
This module attempts to detect when a certificates parameters have changed, but may not detect all changes. Currently, the following parameters are checked for changes: san, kty, curve, size. Note that the key parameters are only checked if kty is set

Examples 

# See https://smallstep.com/docs/step-cli/reference/ca/certificate for more examples
- name: Ensure valid certificate exists
  maxhoesel.smallstep.step_ca_certificate:
    name: "{{ ansible_fqdn }}"
    crt_file: "/etc/ssl/my.cert"
    key_file: "/etc/ssl/my.key"
    provisioner: "jwk"
    provisioner_password_file: "/path/to/password_file"
    san:
    - foo.bar
    kty: EC
    crv: P-256
    not_after: 24h

- name: Use custom root to verify existing cert
  maxhoesel.smallstep.step_ca_certificate:
    name: "{{ ansible_fqdn }}"
    crt_file: "/etc/ssl/my.cert"
    key_file: "/etc/ssl/my.key"
    provisioner: "jwk"
    provisioner_password_file: "/path/to/password_file"
    san:
    - foo.bar
    kty: EC
    crv: P-256
    not_after: 24h
    # If the certificate already exists, this certificate will be used to validate it.
    # If the validation fails, a new certificate will be created.
    # Only required if your CA root is not in the system truststore
    verify_roots: "/path/to/custom/root_ca.crt"

- name: Ensure cert is revoked
  maxhoesel.smallstep.step_ca_certificate:
    name: "{{ ansible_fqdn }}"
    crt_file: "/etc/ssl/my.cert"
    key_file: "/etc/ssl/my.key"
    state: revoked

- name: Ensure cert is absent (and revoke if first if it isn't)
  maxhoesel.smallstep.step_ca_certificate:
    name: "{{ ansible_fqdn }}"
    crt_file: "/etc/ssl/my.cert"
    key_file: "/etc/ssl/my.key"
    state: absent
    revoke_on_delete: true

Authors

Max Hösel (@maxhoesel)

maxhoesel.smallstep.step_ca_certificate module – Manage a step-ca-signed certificate on the target system

Synopsis

Requirements

Parameters

Notes

Examples