vault_pki

Manage the Vault (or OpenBao) PKI secret engine and Vault-issued X.509 certificates.

Added in version 1.1.0.

Important

This module requires the general Vault setup.

saltext.vault.states.vault_pki.certificate_managed(name, common_name=None, role_name=None, private_key=None, csr=None, mount='pki', ttl='720h', ttl_remaining='168h', issuer_ref=None, encoding='pem', append_ca_chain=False, sign_verbatim=False, private_key_passphrase=None, reissue=False, *, alt_names=None, exclude_cn_from_sans=False, not_after=None, serial_number=None, user_ids=None, key_usage=None, ext_key_usage=None, ext_key_usage_oids=None, **kwargs)[source]

Ensure an X.509 certificate is present as specified.

Note

This state can use the sign-verbatim endpoint, which allows minute control of the certificate’s subject name and most extensions (see sign_verbatim below). If not used, only CN is preserved from the CSR subject, any other subject name attributes are taken from the role instead. Check this issue for more information.

Changed in version 1.9.0: Now compares all certificate subject attributes and extensions, including those that are derived from PKI role parameters and issuer URL configuration. This requires read access to the role, issuer and mount default URL configuration. If read access to any of these endpoints is denied, this state is most likely not idempotent anymore.

Also, when issuer_ref is unspecified, now uses the generic {mount}/sign* endpoints instead of the issuer-specific {mount}/issuer/{issuer_ref}/sign/{role_name} with the explicit issuer_ref from the role.

Required policy:

# Need to read the role configuration in case of missing issuer_ref
# and to more accurately predict changes.
path "{mount}/roles/{role_name}" {
    capabilities = ["read"]
}

# Read mount default urls to account for cert extensions
# if the issuer has no configured URLs.
path "<mount>/config/urls" {
    capabilities = ["read"]
}

# Read issuer for URL configuration and CA chain. issuer_ref becomes `default` if unspecified
path "{mount}/issuer/{issuer_ref}" {
    capabilities = ["read"]
}

# When sign_verbatim is false and not specifying issuer_ref
path "<mount>/sign/<role_name>" {
    capabilities = ["update"]
}

# When sign_verbatim is false and specifying issuer_ref
path "<mount>/issuer/<issuer_ref>/sign/<role_name>" {
    capabilities = ["update"]
}

# When sign_verbatim is true and neither specifying issuer_ref nor role_name
path "<mount>/sign-verbatim" {
    capabilities = ["update"]
}

# When sign_verbatim is true and specifying role_name, but not issuer_ref
path "<mount>/sign-verbatim/<role_name>" {
    capabilities = ["update"]
}

# When sign_verbatim is true and specifying issuer_ref, but not role_name
path "<mount>/issuer/<issuer_ref>/sign-verbatim" {
    capabilities = ["update"]
}

# When sign_verbatim is true and specifying both issuer_ref and role_name
path "<mount>/issuer/<issuer_ref>/sign-verbatim/<role_name>" {
    capabilities = ["update"]
}
name

Path to the managed certificate file.

common_name

Subject common name (CN) for the certificate. Required, unless the role explicitly sets require_cn to false or sign_verbatim is true. Ignored (i.e. also not required) when a csr is passed that specifies it and the role’s use_csr_common_name is true (the default value).

role_name

PKI role to use for issuing the certificate. Required, unless sign_verbatim is true.

private_key

Path or text of the private key to use for signing the CSR and thus as the private key for the certificate. Either this or csr is required.

csr

Added in version 1.9.0.

Path or text of the CSR to use for issuing the certificate. Either this or private_key is required.

mount

Mount path the PKI backend is mounted to. Defaults to pki.

ttl

Specifies the requested Time To Live (after which the certificate will be expired). This cannot be larger than the engine’s max (or, if not set, the system max). Can be an integer, which is interpreted as seconds, or a time string such as 1h. Hour is the largest suffix. Defaults to 720h or 30 days.

ttl_remaining

If an existing certificate’s remaining Time To Live undercuts this period, renew it. Can be an integer, which is interpreted as seconds, or a time string such as 1h. Hour is the largest suffix. Defaults to 168h or 7 days.

issuer_ref

Override the specified role’s issuer for the certificate. Defaults to the one specified in the role.

encoding

Encoding of the managed certificate file. Valid options are pem, pkcs7_pem, der, pkcs7_der. Defaults to pem.

append_ca_chain

Whether to append the CA chain to the certificate. Defaults to false.

Note

This appends all CA chain certificates of the selected issuer except self-signed (root) ones.

sign_verbatim

If set to true, the resulting certificate follows the CSR more or less exactly, including extensions. Otherwise, only CN can be set for the subject, any other subject parameters (like O) are taken from the role.

Warning

This option uses a potentially dangerous endpoint. Be careful when using that option, as roles are not restricting what can be issued anymore.

private_key_passphrase

Password for the private key if encrypted.

reissue

Always reissue the certificate. Defaults to false.

alt_names

Any alternative names to add to the certificate. Can be specified either as dict ({ "<type>": "<value>" }), a dict of lists ({ "<type>": ["<value1>", "<value2>", ...] }) or list of SAN strings (["<type1>:<value1>", ...]).

<type> can be dns, email, uri, ip or any OID for otherName SANs. <value> is the corresponding value. Note that otherName SANs need to omit UTF8:.

Ignored when a csr is passed and the role’s use_csr_sans is true (the default value).

exclude_cn_from_sans

If set to true, the Common Name is not added to the SANs. Useful if the CN is not a hostname or email address. Has no effect when sign_verbatim is true.

not_after

Absolute value of the Not After field of the certificate in UTC format YYYY-MM-ddTHH:MM:SSZ. When set, ttl is ignored.

serial_number

Single value for the subject SERIALNUMBER (OID: 2.5.4.5) name attribute (NOT the certificate’s serial number!).

user_ids

List of User ID (UID) subject attributes. Each one is added to the generated CSR’s subject Name as a distinct RDN.

key_usage

When sign_verbatim is true, list of key usages to encode onto the certificate if the CSR does not specify a keyUsage extension. For non-verbatim issuance, this parameter must not be specified because Vault takes it from the role. Valid values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage - simply drop the KeyUsage part of the value. Values are case-insensitive. Pass an empty list to specify no constraints.

ext_key_usage

When sign_verbatim is true, list of extended key usages to encode onto the certificate if the CSR does not specify a extendedKeyUsage extension. For non-verbatim issuance, this parameter must not be specified because Vault takes it from the role. Valid values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage - simply drop the ExtKeyUsage part of the value. Values are case-insensitive. Pass an empty list to specify no constraints.

ext_key_usage_oids

When sign_verbatim is true, list of extended key usage oids to encode onto the certificate if the CSR does not specify a extendedKeyUsage extension. Useful for adding EKUs not supported by the Go standard library. For non-verbatim issuance, this parameter must not be specified because Vault takes it from the role.

kwargs

Most parameters for the file.managed state or any of the ones for the Vault PKI sign_certificate execution module function are passed through.

Hint

This is a high-level state, which connects several different functions:

  • Vault API (sign-certificate or sign-verbatim, depending on the value of sign_verbatim). Completely unknown keyword parameters end up there.

  • x509.create_csr: Used to generate a CSR that Vault should sign. Any subject name attribute parameters (O, OU etc.) and most extension parameters (certificatePolicies, keyUsage, extendedKeyUsage etc.) end up here. Note that Vault does not follow the CSR literally, even sign-verbatim e.g. prohibits basicConstraints with CA: true. The CN and subjectAltName parameters are synced with common_name and alt_names respectively, so specifying them directly has no effect. Ignored when csr is defined.

  • file.managed: Parameters such as user, group and mode end up influencing the certificate file on disk. Note: encoding is a valid parameter for both this function and file.managed. If you need to pass it to the latter, specify it as file_encoding instead.

saltext.vault.states.vault_pki.role_managed(name, mount='pki', issuer_ref=None, ttl=None, max_ttl=None, **kwargs)[source]

Ensures PKI role is present and configured as required.

name

Name of the role.

mount

Mount path the PKI backend is mounted to. Defaults to pki.

issuer_ref

Issuer reference for the role. Can be name, id or literal default.

ttl

Specifies the Time To Live value to be used for the validity period of the requested certificate, provided as a string duration with time suffix. Hour is the largest suffix. The value specified is strictly used for future validity. If not set, uses the system default value or the value of max_ttl, whichever is shorter.

max_ttl

Specifies the maximum Time To Live provided as a string duration with time suffix. Hour is the largest suffix. If not set, defaults to the system maximum lease TTL.

kwargs

Any other parameter accepted by the Vault write_role execution module function or Vault update role API method.

saltext.vault.states.vault_pki.role_absent(name, mount='pki')[source]

Ensure PKI role is absent.

name

Name of the role.

mount

Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.states.vault_pki.intermediate_issuer_managed(name, days_remaining=30, key_ref=None, rotate_key=False, key_type=None, key_algo=None, key_bits=None, max_path_length=0, managed_key_name=None, managed_key_id=None, issuer_name=None, leaf_not_after_behavior=None, usage=None, revocation_signature_algorithm=None, aia_urls=None, crl_endpoints=None, delta_crl_endpoints=None, ocsp_servers=None, aia_url_templating=None, mount='pki', **kwargs)[source]

Added in version 1.9.0.

Ensure an issuer representing an intermediate CA is present as the default issuer on the mount. Rotates the issuer when necessary by generating a new certificate via x509.create_certificate. Does not support certificate import.

Required policy:

# read default issuer to check for necessary changes
path "<mount>/issuer/default" {
    capabilities = ["read"]
}

# when key_ref is not set
path "<mount>/keys/generate/<key_type>" {
    capabilities = ["create", "update"]
}

# generate a CSR to derive the public key
path "<mount>/intermediate/generate/<key_type>" {
    capabilities = ["create", "update"]
}

# import the signed cert
path "<mount>/intermediate/set-signed" {
    capabilities = ["create", "update"]
}

# set default issuer
path "<mount>/config/issuers" {
    capabilities = ["create", "update"]
}

# update issuer configuration
path "<mount>/issuer/<name>" {
    capabilities = ["patch"]
}

Certificate/Key configuration:

name

Common name (CN) of the certificate subject.

days_remaining

Attempt to recreate the certificate if the number of days the certificate is valid for is less than the number specified. Defaults to 30.

key_ref

Instead of managing the key, use the one associated with this key ID/name. When specified, disables key generation/rotation.

rotate_key

When rotating the default issuer, rotate its key along with it. Defaults to false. Not respected when key_ref is specified.

Note

Key parameters are not managed statefully, meaning changes to key_type, key_algo and key_bits are only applied when generating a new key. key_ref changes are applied though.

key_type

Type of key to generate when necessary and key_ref is not specified. Either internal, exported or kms. Defaults to internal.

key_algo

Key algorithm. Either rsa, ed25519 or ec. Defaults to rsa.

key_bits

Number of bits to use for the generated keys. Valid values depend on the key_algo.

  • rsa: 2048 (default), 3072, 4096, 8192.

  • ec: 224, 256 (default), 384, 521

  • ed25519: ignored

Defaults to 0 (universal default).

managed_key_name

When key_type is kms, the managed key’s configured name. Either this or managed_key_id is required then.

managed_key_id

When key_type is kms, the managed key’s UUID. Either this or managed_key_name is required then.

max_path_length

basicConstraints pathlen parameter, which indicates the maximum number of CAs that can appear below this one in a chain. If set to 0, this CA can only issue leaf certificates, not other CAs. A negative value means no limit, unless the issuer certificate has a maximum path length, in which case it means one less than the issuer’s pathlen. Defaults to 0.

kwargs

Unknown keyword arguments are passed to x509.create_certificate. See there for details.

The following arguments are enforced by this function:

  • CN

  • basicConstraints

  • csr

  • format

  • private_key (empty)

  • public_key (empty)

  • raw (empty)

These receive defaults if not specified:

  • keyUsage: [critical, cRLSign, keyCertSign]

  • subjectKeyIdentifier: hash

  • authorityKeyIdentifier: keyid:always,issuer

Issuer configuration:

issuer_name

Custom name for the issuer. Must be unique and not equal to default.

leaf_not_after_behavior

Behavior of a leaf’s NotAfter field during issuance when it exceeds the issuer’s validity. Valid options:

  • err: Error, unless during CA/ACME issuance. (default)

  • always_enforce_err: Error, including during CA/ACME issuance.

  • truncate: Silently truncate the requested NotAfter to that of the issuer.

  • permit: Allow signed certificate validities to exceed that of the issuer.

usage

Allowed usages for this issuer. Valid options are:

  • read-only - to allow this issuer to be read; implict; always allowed;

  • issuing-certificates - to allow this issuer to be used for issuing other certificates;

  • crl-signing - to allow this issuer to be used for signing CRLs. This is separate from the CRLSign KeyUsage on the x509 certificate, but this usage cannot be set unless that KeyUsage is allowed on the x509 certificate;

  • ocsp-signing - to allow this issuer to be used for signing OCSP responses.

revocation_signature_algorithm

Which signature algorithm to use when building CRLs. See Go’s x509.SignatureAlgorithm constant for possible values. Default (empty string) is to autoselect.

aia_urls

Specifies the URL values for the Issuing Certificate field as an array.

crl_endpoints

Specifies the URL values for the CRL Distribution Points field as an array.

delta_crl_endpoints

(Requires Vault 1.20+ or OpenBao) Specifies the URL values for the Delta CRL Distribution Points field. This can be an array or a comma- separated string list.

ocsp_servers

Specifies the URL values for the OCSP Servers field as an array.

aia_url_templating

Render aia_urls/crl_endpoints/ocsp_servers/delta_crl_endpoints as templates. Supported variables: {{issuer_id}}, {{cluster_path}}, {{cluster_aia_path}}.

mount

Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.states.vault_pki.root_issuer_managed(name, days_remaining=90, key_ref=None, rotate_key=False, key_type=None, key_algo=None, key_bits=None, managed_key_name=None, managed_key_id=None, alt_names=None, days_valid=3650, max_path_length=-1, key_usage=None, exclude_cn_from_sans=False, permitted_alt_names=None, excluded_alt_names=None, ou=None, organization=None, country=None, locality=None, province=None, street_address=None, postal_code=None, serial_number=None, signature_bits=0, not_before_duration=30, not_after=None, issuer_name=None, leaf_not_after_behavior=None, usage=None, revocation_signature_algorithm=None, aia_urls=None, crl_endpoints=None, delta_crl_endpoints=None, ocsp_servers=None, aia_url_templating=None, mount='pki')[source]

Added in version 1.9.0.

Ensure an issuer representing a root CA is present as the default issuer on the mount. Rotates the issuer when necessary.

Required policy:

# read default issuer to check for necessary changes
path "<mount>/issuer/default" {
    capabilities = ["read"]
}

# Read mount default urls to account for cert extensions
path "<mount>/config/urls" {
    capabilities = ["read"]
}

# when key_ref is not set
path "<mount>/keys/generate/<key_type>" {
    capabilities = ["create", "update"]
}

# when key_ref is set
path "<mount>/keys" {
    capabilities = ["list"]
}

# set default issuer
path "<mount>/config/issuers" {
    capabilities = ["create", "update"]
}

# update issuer configuration
path "<mount>/issuer/<name>" {
    capabilities = ["patch"]
}

Certificate/Key configuration:

name

Common name (CN) of the certificate subject.

days_remaining

Attempt to recreate the certificate if the number of days the certificate is valid for is less than the number specified. Defaults to 30.

key_ref

Instead of managing the key, use the one associated with this key ID/name. When specified, disables key generation/rotation.

rotate_key

When rotating the default issuer, rotate its key along with it. Defaults to false. Not respected when key_ref is specified.

Note

Key parameters are not managed statefully, meaning changes to key_type, key_algo and key_bits are only applied when generating a new key. key_ref changes are applied though.

key_type

Type of key to generate when necessary and key_ref is not specified. Either internal, exported or kms. Defaults to internal.

key_algo

Key algorithm. Either rsa, ed25519 or ec. Defaults to rsa.

key_bits

Number of bits to use for the generated keys. Valid values depend on the key_algo.

  • rsa: 2048 (default), 3072, 4096, 8192.

  • ec: 224, 256 (default), 384, 521

  • ed25519: ignored

Defaults to 0 (universal default).

managed_key_name

When key_type is kms, the managed key’s configured name. Either this or managed_key_id is required then.

managed_key_id

When key_type is kms, the managed key’s UUID. Either this or managed_key_name is required then.

signature_bits

Number of bits to use in the signature algorithm. Valid: 256 (SHA-2-256), 384 (SHA-2-384), 512 (SHA-2-512). Defaults to 0, which automatically selects an algorithm based on key_algo and key_bits of the issuer’s private key.

days_valid

Number of days the certificate should be valid for when (re-)issued. Not respected when not_after is set explicitly. Defaults to 3650 (10 years).

not_before_duration

Duration by which to backdate the NotBefore property. Defaults to 30s.

not_after

Absolute value of the Not After field of the certificate in UTC format YYYY-MM-ddTHH:MM:SSZ. When set, days_valid is ignored.

alt_names

Any alternative names to add to the certificate. Can be specified either as dict ({ "<type>": "<value>" }), a dict of lists ({ "<type>": ["<value1>", "<value2>", ...] }) or list of SAN strings (["<type1>:<value1>", ...]).

<type> can be dns, email, uri, ip or any OID for otherName SANs. <value> is the corresponding value. Note that otherName SANs need to omit UTF8:.

max_path_length

basicConstraints pathlen parameter, which indicates the maximum number of CAs that can appear below this one in a chain. If set to 0, this CA can only issue leaf certificates, not other CAs. A negative value means no limit, unless the issuer certificate has a maximum path length, in which case it means one less than the issuer’s pathlen. Defaults to 0.

key_usage

(Requires Vault 1.20+ or OpenBao) List of key usages to add to the existing set of key usages (CRLSign,CertSign). Per the CA/B Forum, Vault ignores additional values other than DigitalSignature.

exclude_cn_from_sans

If set to true, the Common Name is not added to the SANs. Useful if the CN is not a hostname or email address.

permitted_alt_names

List of alternative names for which certificates are allowed to be issued or signed by this CA certificate. The format is similar to the one for alt_names, but <type> can only be dns, email, uri and ip.

Important

Types other than dns require Vault 1.19+.

excluded_alt_names

(Vault 1.19+ only) List of alternative names for which certificates are not allowed to be issued or signed by this CA certificate. The format is similar to the one for alt_names, but <type> can only be dns, email, uri and ip.

Subject DN fields

Most of these can be single strings or lists of strings (for multiple values).

  • ou

  • organization

  • country

  • locality

  • province

  • street_address

  • postal_code

  • serial_number (only a single value; NOT the certificate’s serial number, just the SERIALNUMBER name attribute)

Issuer configuration:

issuer_name

Custom name for the issuer. Must be unique and not equal to default.

leaf_not_after_behavior

Behavior of a leaf’s NotAfter field during issuance when it exceeds the issuer’s validity. Valid options:

  • err: Error, unless during CA/ACME issuance. (default)

  • always_enforce_err: Error, including during CA/ACME issuance.

  • truncate: Silently truncate the requested NotAfter to that of the issuer.

  • permit: Allow signed certificate validities to exceed that of the issuer.

usage

Allowed usages for this issuer. Valid options are:

  • read-only - to allow this issuer to be read; implict; always allowed;

  • issuing-certificates - to allow this issuer to be used for issuing other certificates;

  • crl-signing - to allow this issuer to be used for signing CRLs. This is separate from the CRLSign KeyUsage on the x509 certificate, but this usage cannot be set unless that KeyUsage is allowed on the x509 certificate;

  • ocsp-signing - to allow this issuer to be used for signing OCSP responses.

revocation_signature_algorithm

Which signature algorithm to use when building CRLs. See Go’s x509.SignatureAlgorithm constant for possible values. Default (empty string) is to autoselect.

aia_urls

Specifies the URL values for the Issuing Certificate field as an array.

crl_endpoints

Specifies the URL values for the CRL Distribution Points field as an array.

delta_crl_endpoints

(Requires Vault 2.0+ or OpenBao) Specifies the URL values for the Delta CRL Distribution Points field. This can be an array or a comma- separated string list.

Note

This parameter is supported in Vault 1.20+, but not added as a FreshestCRL extension to the root issuer certificate, leading to non-idempotency of this state.

ocsp_servers

Specifies the URL values for the OCSP Servers field as an array.

aia_url_templating

Render aia_urls/crl_endpoints/ocsp_servers/delta_crl_endpoints as templates. Supported variables: {{issuer_id}}, {{cluster_path}}, {{cluster_aia_path}}.

mount

Mount path the PKI backend is mounted to. Defaults to pki.