`vault_pki`¶

Manage the Vault (or OpenBao) PKI secret engine, request X.509 certificates.

Added in version 1.1.0.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault_pki.list_roles(mount='pki')[source]¶

List configured PKI roles.

Required policy:

path "<mount>/roles" {
    capabilities = ["list"]
}

CLI Example:

salt '*' vault_pki.list_roles

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

saltext.vault.modules.vault_pki.read_role(name, mount='pki')[source]¶

Get configuration of specific PKI role.

API method docs.

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_role my_role

name: Name of the role.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.write_role(name, mount='pki', issuer_ref=None, ttl=None, max_ttl=None, allow_localhost=None, allowed_domains=None, server_flag=None, client_flag=None, key_usage=None, no_store=None, require_cn=None, **kwargs)[source]¶

Create or update PKI role.

API method docs.

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["create", "update", "patch"]
}

CLI Example:

salt '*' vault_pki.write_role myrole

name: Name of the role.
mount: Mount path the PKI backend is mounted to. Defaults to pki.
issuer_ref: Name or ID of the issuer which should be used with this role. If not set, the default issuer is used.
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.
allow_localhost: Specifies if clients can request certificates for localhost as one of the requested common names.
allowed_domains: Specifies the domains this role is allowed to issue certificates for. This is used with the allow_bare_domains, allow_subdomains, and allow_glob_domains options to determine the type of matching between these domains and the values of common name, DNS-typed SAN entries, and Email-typed SAN entries. When allow_any_name is used, this attribute has no effect.
server_flag: Specifies if certificates are flagged for server authentication use. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field. If not set, defaults to true.
client_flag: Specifies if certificates are flagged for client authentication use. See RFC 5280 Section 4.2.1.12 for information about the Extended Key Usage field. If not set, defaults to true.
key_usage: Specifies the allowed key usage constraint on issued certificates. If unset, defaults to ["DigitalSignature", "KeyAgreement", "KeyEncipherment"]
no_store: If set, certificates issued/signed against this role are not stored in the storage backend.
require_cn: If set to false, makes the common_name field optional while generating a certificate. Defaults to true.
kwargs:: Any other params which can be understood by the Vault API.

saltext.vault.modules.vault_pki.delete_role(name, mount='pki')[source]¶

Delete PKI role from Vault.

API method docs.

Required policy:

path "<mount>/roles/<name>" {
    capabilities = ["delete"]
}

CLI Example:

salt '*' vault_pki.delete_role myrole

name: Name of the role.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.list_issuers(mount='pki')[source]¶

List issuers information.

Returns { "<issuer_id>" : { "is_default": False, "issuer_name": "...", "key_id": "...", "serial_number": "...."}}

API method docs.

Required policy:

path "<mount>/issuers" {
    capabilities = ["list"]
}

CLI Example:

salt '*' vault_pki.list_issuers

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

saltext.vault.modules.vault_pki.get_issuer_id(ref='default', mount='pki')[source]¶

Added in version 1.9.0.

Get the issuer ID of a reference, which can be an issuer ID or an issuer name. Ensures the returned issuer ID exists.

Required policy: See list_issuers()

CLI Example:

salt '*' vault_pki.get_issuer_id foobar

ref: Reference to an issuer. Either issuer_name or issuer_id. Defaults to default.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.read_issuer(ref='default', mount='pki')[source]¶

Read an issuer’s information.

API method docs.

Required policy:

path "<mount>/issuer/<name>" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_issuer

ref: Reference of the issuer. Can be issuer ID, issuer name or literal default which means default issuer. Defaults to default.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.update_issuer(ref='default', mount='pki', manual_chain=None, usage=None, aia_urls=None, crl_endpoints=None, ocsp_servers=None, name=None, aia_url_templating=None, delta_crl_endpoints=None, leaf_not_after_behavior=None, revocation_signature_algorithm=None)[source]¶

Update issuer’s information.

API method docs.

Required policy:

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

CLI Example:

salt '*' vault_pki.update_issuer ref usage=["crl-signing"]

ref

Reference of the issuer. Can be issuer ID, issuer name or literal default, referring to the default issuer. Defaults to default.

mount

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

manual_chain

Chain of issuer references to build this issuer’s computed CAChain field from, when non-empty.

usage

Allowed usages for this issuer. Valid options are:

read-only - to allow this issuer to be read; implicit; 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.

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.

ocsp_servers

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

name

Added in version 1.9.0.

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

aia_url_templating

Added in version 1.9.0.

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

delta_crl_endpoints

Added in version 1.9.0.

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

leaf_not_after_behavior

Added in version 1.9.0.

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. (Vault 1.18.2+ only)
truncate: Silently truncate the requested NotAfter to that of the issuer.
permit: Allow signed certificate validities to exceed that of the issuer.

revocation_signature_algorithm

Added in version 1.9.0.

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

saltext.vault.modules.vault_pki.read_issuer_certificate(name='default', mount='pki', include_chain=False)[source]¶

Read an issuer’s certificate. Returns certificate(s) in PEM format

API method docs.

Required policy: See read_issuer()

CLI Example:

salt '*' vault_pki.read_issuer_certificate

name: Name of the issuer. Can be issuer ID, issuer name or literal default which means default issuer. Defaults to default.
mount: Mount path the PKI backend is mounted to. Defaults to pki.
include_chain: If set to true, appends the CA chain to the certificate (in case of intermediate issuer)

saltext.vault.modules.vault_pki.get_default_issuer(mount='pki')[source]¶

Return the issuer ID of the default issuer.

API method docs.

Required policy: See list_issuers()

CLI Example:

salt '*' vault_pki.get_default_issuer

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

saltext.vault.modules.vault_pki.set_default_issuer(name, mount='pki')[source]¶

Set the default issuer.

API method docs.

Required policy:

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

CLI Example:

salt '*' vault_pki.set_default_issuer myca

name: Name or ID of the default issuer to set.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.get_key_id(ref, mount='pki')[source]¶

Added in version 1.9.0.

Get the key ID of a reference, which can be a key ID or a key name. Ensures the returned key ID exists.

Required policy: See list_keys()

CLI Example:

salt '*' vault_pki.get_key_id foobar

ref: Reference to a key. Either key_name or key_id.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.list_keys(mount='pki')[source]¶

Added in version 1.9.0.

Get a mapping of keys provisioned in this mount to some of their properties (currently only key_name).

API method docs.

Required policy:

path "<mount>/keys" {
    capabilities = ["list"]
}

CLI Example:

salt '*' vault_pki.list_keys

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

saltext.vault.modules.vault_pki.generate_key(key_type='internal', key_name=None, key_algo=None, key_bits=None, managed_key_name=None, managed_key_id=None, mount='pki')[source]¶

Added in version 1.9.0.

Generate a new private key for use in the PKI mount. This key can be used with generate_root() and generate_intermediate(), using the key_type=existing variant by passing the returned key_id as key_ref.

API method docs.

Required policy:

path "<mount>/keys/generate/<key_type>" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.generate_key key_name=my_rsa_key key_bits=4096
salt '*' vault_pki.generate_key exported key_algo=ed25519

key_type

Key type to generate. Valid values are:

internal: The private key is not returned and cannot be retrieved later.
exported: The private key is returned in the response.
kms: Request a key from a key management system. The private key is not returned and cannot be retrieved later.

Defaults to internal.

key_name

Specify a name for the generated key. Optional.

key_algo

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

key_bits

Number of bits to use for the generated key. Valid values depend on the key_type:

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.

mount

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

saltext.vault.modules.vault_pki.generate_root(common_name, mount='pki', key_type='internal', issuer_name=None, key_name=None, ttl=None, key_algo='rsa', key_bits=0, max_path_length=-1, key_ref=None, managed_key_name=None, managed_key_id=None, encoding=None, **kwargs)[source]¶

Generate a new root issuer.

Returns { "certificate" : "-----BEGIN CERTIFICATE...", "issuer_id": "...", "key_id": "...", }. If key_type is exported, also returns the private key.

API method docs.

Required policy:

path "<mount>/root/generate/<key_type>" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.generate_root my-root

common_name

Subject common name (CN) for the certificate. Required.

mount

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

key_type

Changed in version 1.9.0: This parameter used to be called type.

Key type of the root to generate. Valid values are:

existing: Use an existing key for the generated root, specified in key_ref.
internal: The private key is not returned and cannot be retrieved later.
exported: The private key is returned in the response.
kms: Request a key from a key management system. The private key is not returned and cannot be retrieved later.

Defaults to internal.

issuer_name

Provides a name to the specified issuer. The name must be unique across all issuers and not be the reserved value default.

key_name

When a new key is created with this request, optionally specifies the name for this. The global ref default may not be used as a name.

ttl

Specifies the requested Time To Live (after which the certificate expires). This cannot be larger than the engine’s max (or, if not set, the system max).

key_algo

Changed in version 1.9.0: This parameter used to be called key_type, which now refers to key generation/exportability instead.

Specifies the desired key algorithm, either rsa, ed25519 or ec. Defaults to rsa.

key_bits

Number of bits to use for the generated key. Valid values depend on the key_type:

rsa: 2048 (default), 3072, 4096, 8192.
ec: 224, 256 (default), 384, 521
ed25519: ignored

Defaults to 0 (universal default).

max_path_length

key_ref

Reference to an existing private key on this mount, either key_name or key_id. Required when key_type is existing, otherwise ignored.

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.

encoding

Changed in version 1.9.0: This parameter used to be called format. To align it with other endpoints, it was renamed to encoding. The previous name still works, but is warned about.

Output format. Can be either pem or der. Defaults to pem.

kwargs

Unknown keyword arguments are passed through to the Vault API. See the API method docs linked above for details. Here is an incomplete list:

key_name
private_key_format
pkcs12_encoder/pkcs12_password/jks_password/jks_private_key_alias
alt_names/ip_sans/uri_sans/other_sans (in contrast to other functions in this module, no special handling for alt_names is applied)
exclude_cn_from_sans
key_usage
permitted_dns_domains/excluded_dns_domains (no special handling for permitted_alt_names/excluded_alt_names either)
permitted_ip_ranges/excluded_ip_ranges
permitted_email_addresses/excluded_email_addresses
permitted_uri_domains/excluded_uri_domains
ou
organization
country
locality
province
street_address
postal_code
serial_number
signature_bits
not_before_duration
not_after
use_pss

saltext.vault.modules.vault_pki.generate_intermediate_csr(key_type='internal', key_name=None, key_algo=None, key_bits=None, key_ref=None, managed_key_name=None, managed_key_id=None, encoding='pem', mount='pki', **kwargs)[source]¶

Added in version 1.9.0.

Generate a new CSR for signing, optionally generating a new private key. To create an issuer, the CSR must be signed and the resulting certificate imported.

API method docs.

Required policy:

path "<mount>/intermediate/generate/<key_type>" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.generate_intermediate_csr "My Intermediate CA"
salt '*' vault_pki.generate_intermediate_csr "My Intermediate CA" key_type=existing key_ref=existing_key
salt '*' vault_pki.generate_intermediate_csr "My Intermediate CA" key_type=exported

key_type

Key type of the (future) intermediate issuer to generate. Valid values are:

existing: Use an existing key, specified in key_ref.
internal: The private key is not returned and cannot be retrieved later.
exported: The private key is returned in the response.
kms: Request a key from a key management system. The private key is not returned and cannot be retrieved later.

Defaults to internal.

key_name

Specify a name for the generated key. Optional.

key_algo

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

key_bits

Number of bits to use for the generated key. Valid values depend on the key_type:

rsa: 2048 (default), 3072, 4096, 8192.
ec: 224, 256 (default), 384, 521
ed25519: ignored

Defaults to 0 (universal default).

key_ref

Reference to an existing private key on this mount, either key_name or key_id. Required when key_type is existing, otherwise ignored.

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.

encoding

Output format. Can be either pem or der. Defaults to pem.

mount

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

kwargs

Unknown keyword arguments are passed through to the Vault API. See the API method docs linked above for details. Here is an incomplete list:

alt_names/ip_sans/uri_sans/other_sans (in contrast to other functions in this module, no special handling for alt_names is applied)
exclude_cn_from_sans
key_usage
add_basic_constraints
common_name
ou
organization
country
locality
province
street_address
postal_code
serial_number
signature_bits

saltext.vault.modules.vault_pki.generate_intermediate(common_name, issuer_ref=None, issuer_mount=None, key_type='internal', key_name=None, key_algo=None, key_bits=None, key_ref=None, managed_key_name=None, managed_key_id=None, days_valid=180, not_after=None, not_before_duration=30, max_path_length=0, alt_names=None, exclude_cn_from_sans=False, key_usage=None, 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, mount='pki', **kwargs)[source]¶

Added in version 1.9.0.

Generate an intermediate issuer by signing its certificate either via another Vault issuer or a Salt-internal CA.

A Vault issuer is selected by specifying issuer_ref. This function then works like sign_intermediate(), but without the ability to force verbatim signing or passing a pregenerated CSR.

When issuer_ref is unspecified, we rely on x509.create_certificate. Any unknown keyword arguments to this function are passed through. Vault-style parameters like alt_names are translated transparently (into subjectAltName and its format, in this example). You can still pass x509_v2-style parameters directly, these translations only happen when the respective x509.create_certificate parameter is not found in kwargs. Some x509.create_certificate parameters are enforced by this function, see kwargs below. The final certificate also depends on a signing_policy, if passed. It can override any parameter.

Required policy: see generate_intermediate_csr(), import_issuer_intermediate() and, if issuer_ref is specified, sign_intermediate()

CLI Example:

salt '*' vault_pki.generate_intermediate "My Salt-issued intermediate CA" ca_server=ca_minion signing_policy=vault_intermediate
salt '*' vault_pki.generate_intermediate "My Vault-issued intermediate CA" issuer_ref=root_issuer issuer_mount=pki_root

common_name

Subject CN. Required.

Note

When issuer_ref is unspecified, the final CN can differ from this value because of signing policy merging.

issuer_ref

Issuer name/ID of the issuer that should sign this issuer’s certificate. If unspecified, uses a Salt-internal CA via x509.create_certificate to sign it instead.

issuer_mount

When issuer_ref is specified and the issuer is on a different mount, specify it here. Defaults to the value of mount.

key_type

Key type of the (future) intermediate issuer to generate. Valid values are:

existing: Use an existing key, specified in key_ref.
internal: The private key is not returned and cannot be retrieved later.
exported: The private key is returned in the response.
kms: Request a key from a key management system. The private key is not returned and cannot be retrieved later.

Defaults to internal.

key_name

Specify a name for the generated key. Optional.

key_algo

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

key_bits

Number of bits to use for the generated key. Valid values depend on the key_type:

rsa: 2048 (default), 3072, 4096, 8192.
ec: 224, 256 (default), 384, 521
ed25519: ignored

Defaults to 0 (universal default).

key_ref

Reference to an existing private key on this mount, either key_name or key_id. Required when key_type is existing, otherwise ignored.

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.

days_valid

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

Hint

Translated into not_after when a Vault issuer signs the certificate, hence not subject to the mount’s max_lease_ttl.

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.

not_before_duration

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

Has no effect when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

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.

Forcibly translated into basicConstraints when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

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

Translated into subjectAltName when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

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 a Salt-internal CA issues the certificate (issuer_ref is unspecified).

key_usage

(Requires Vault 1.20+ or OpenBao when issuer_ref is specified) List of key usages to add to the existing set of key usages (CRLSign,CertSign). Per the CAB Forum requirements, Vault ignores values other than DigitalSignature.

Translated into keyUsage when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

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+ when issuer_ref is specified.

Translated into nameConstraints when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

excluded_alt_names

(Vault 1.19+ only when issuer_ref is specified) 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.

Translated into nameConstraints when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

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)

Translated into subject when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

Note

The resulting subject format depends on whether a signing_policy was specified or not, because a signing policy that defines any subject attribute would override the default format completely.

If no signing_policy is specified, it becomes a string that faithfully recreates subjects as rendered by Vault.
When it is specified, it becomes a dictionary (e.g. {CN: Foo}), which allows merging of attributes from a signing policy that defines subject as a dictionary itself (e.g. + {C: US} => CN=Foo,C=US). There are several tradeoffs to using a dict: Parameters with more than one value are ignored, postal_code is ignored and the subject name’s RDN order differs a bit from the one Vault renders.

This translation is only meant as a helper, you can always specify subject yourself. It’s possible to use a list of RDN strings here and in the signing policy, which results in the signing policy’s list being prepended to the one passed in here (i.e. appended when visualizing its rfc4514 string representation).

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 the issuer’s key length.

Has no effect when a Salt-internal CA issues the certificate (issuer_ref is unspecified).

mount

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

kwargs

Unknown keyword arguments are passed to the certificate signing function, which depends on whether issuer_ref is specified:

A non-empty issuer_ref means we rely on sign_intermediate().

Note that its sign_verbatim parameter is forced to false and its csr parameter is enforced by this function, so CSR generation arguments won’t have any effect and you can’t pass a pre-generated CSR.
No issuer_ref means we rely on x509.create_certificate. See there for details.

The following arguments are enforced by this function:
- basicConstraints ({critical: true, ca: true, pathlen: <max_path_length>})
- csr
- format
- private_key/public_key/path/raw/serial_number (empty)
These receive defaults from specified Vault-style parameters to this function:
- subject
- subjectAltName (not critical)
- nameConstraints (critical)
- keyUsage (critical)
These receive defaults if not specified at all:
- keyUsage: [critical, cRLSign, keyCertSign]
- subjectKeyIdentifier: hash
- authorityKeyIdentifier: keyid:always

saltext.vault.modules.vault_pki.delete_key(ref, mount='pki')[source]¶

Delete a private key from Vault. There must be no issuers depending on the key for this to succeed.

API method docs.

Required policy:

path "<mount>/key/<ref>" {
    capabilities = ["delete"]
}

CLI Example:

salt '*' vault_pki.delete_key ref

ref: Reference to the key, either key_name or key_id.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.delete_issuer(ref, mount='pki', include_key=False)[source]¶

Delete issuer from Vault.

API method docs.

Required policy:

path "<mount>/issuer/<ref>" {
    capabilities = ["delete"]
}

CLI Example:

salt '*' vault_pki.delete_issuer ref

ref: Reference to the issuer, either issuer_name or issuer_id.
mount: Mount path the PKI backend is mounted to. Defaults to pki.
include_key: If set to true, also deletes the private key if imported. Defaults to false, i.e. the private key is preserved.

saltext.vault.modules.vault_pki.import_issuer_intermediate(cert, chain=None, mount='pki')[source]¶

Added in version 1.9.0.

Import a CA certificate issued for an existing key on this mount.

API method docs.

Required policy:

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

CLI Example:

salt '*' vault_pki.import_issuer_intermediate /etc/tls/my_intermediate_cert.pem

cert: Certificate to import. Any input accepted by the x509_v2 modules is accepted. Included CA chain is respected when chain is not specified.
chain: CA chain for the certificate. Defaults to the chain in cert, if present.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.import_issuer(cert, chain=None, private_key=None, private_key_passphrase=None, mount='pki')[source]¶

Added in version 1.9.0.

Import a CA certificate and (optionally) corresponding private key.

API method docs.

Required policy:

# without private_key
path "<mount>/issuer/import/cert" {
    capabilities = ["create", "update"]
}

# with private_key
path "<mount>/issuer/import/bundle" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.import_issuer /etc/tls/my_intermediate_cert.pem
salt '*' vault_pki.import_issuer /etc/tls/my_intermediate_cert.pem private_key=/etc/tls/my_intermediate.key

cert: Certificate to import. Any input accepted by the x509_v2 modules is accepted. Included CA chain is respected when chain is not specified.
chain: CA chain for the certificate. Defaults to the chain in cert, if present.
private_key: Import corresponding private key for cert. Optional.
private_key_passphrase: When private_key is specified and encrypted, the passphrase to decrypt it.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.read_issuer_crl(ref='default', mount='pki', delta=False)[source]¶

Get issuer CRL.

Note

If CA cannot sign CRLs, returns None.

API method docs.

Required policy:

path "<mount>/issuer/<ref>" {
    capabilities = ["read"]
}

path "<mount>/issuer/<ref>/crl" {
    capabilities = ["read"]
}

path "<mount>/issuer/<ref>/crl/delta" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_issuer_crl ref

ref: Reference to the issuer, either issuer_name or issuer_id. Defaults to default.
mount: Mount path the PKI backend is mounted to. Defaults to pki.
delta: If set to true, returns delta CRL instead of complete one.

saltext.vault.modules.vault_pki.list_revoked_certificates(mount='pki')[source]¶

List revoked certificates serial numbers

API method docs.

Required policy:

path "<mount>/certs/revoked" {
    capabilities = ["list"]
}

CLI Example:

salt '*' vault_pki.list_revoked_certificates

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

saltext.vault.modules.vault_pki.list_certificates(mount='pki')[source]¶

List issued certificates serial numbers

API method docs.

Required policy:

path "<mount>/certs" {
    capabilities = ["list"]
}

CLI Example:

salt '*' vault_pki.list_certificates

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

saltext.vault.modules.vault_pki.read_certificate(serial, mount='pki')[source]¶

Read issued certificate. Returns certificate in PEM format

API method docs.

Required policy:

path "<mount>/cert/<serial>" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_certificate 7e:85:c5:d1:85:94:9a:46:08:b5:1b:9c:22:cb:35:e5:ea:f3:56:3f

serial

Specifies the serial of the key to read. Valid values are:

<serial> for the certificate with the given serial number, in hyphen-separated or colon-separated hexadecimal.
ca for the default issuer’s CA certificate
crl for the default issuer’s CRL
ca_chain for the default issuer’s CA trust chain.

mount

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

saltext.vault.modules.vault_pki.read_certificate_full(serial, mount='pki')[source]¶

Added in version 1.7.0.

Get full certificate information as a dictionary, including the certificate (certificate) and its CA chain certificates (ca_chain, a list of strings) in PEM format.

API method docs.

Required policy:

path "<mount>/cert/<serial>" {
    capabilities = ["read"]
}

path "<mount>/issuer/<name>" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_certificate_full 7e:85:c5:d1:85:94:9a:46:08:b5:1b:9c:22:cb:35:e5:ea:f3:56:3f

serial

Specifies the serial of the certificate to read. Valid values are:

<serial> for the certificate with the given serial number, in hyphen-separated or colon-separated hexadecimal.
ca for the default issuer’s CA certificate
crl for the default issuer’s CRL
ca_chain for the default issuer’s CA trust chain.

mount

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

saltext.vault.modules.vault_pki.issue_certificate(role_name, common_name=None, mount='pki', issuer_ref=None, alt_names=None, ttl=None, encoding=None, exclude_cn_from_sans=False, **kwargs)[source]¶

Generate and issue a new leaf certificate and private key.

API method docs.

Required policy:

# When not specifying issuer_ref
path "<mount>/issue/<role_name>" {
    capabilities = ["update"]
}

# When specifying issuer_ref
path "<mount>/issuer/<issuer_ref>/issue/<role_name>" {
    capabilities = ["update"]
}

CLI Example:

salt '*' vault_pki.issue_certificate myrole common_name="www.example.com"

role_name

PKI role to use for issuing the certificate. Required.

common_name

Subject common name (CN) for the certificate. Required, unless the role explicitly sets require_cn to false.

mount

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

issuer_ref

Specify an explicit issuer instead of taking it from the role definition. Can be issuer_name or issuer_id.

alt_names

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

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.

encoding

Changed in version 1.9.0: This parameter used to be called format. To align it with other endpoints, it was renamed to encoding. The previous name still works, but is warned about.

Output format. Can be either pem or der. Defaults to pem.

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.

kwargs

Any additional parameter accepted by the Vault API.

saltext.vault.modules.vault_pki.sign_certificate(role_name=None, common_name=None, mount='pki', csr=None, private_key=None, private_key_passphrase=None, digest='sha256', issuer_ref=None, alt_names=None, ttl=None, sign_verbatim=False, encoding='pem', exclude_cn_from_sans=False, serial_number=None, user_ids=None, not_after=None, key_usage=None, ext_key_usage=None, ext_key_usage_oids=None, **kwargs)[source]¶

Issue a new leaf certificate from an existing private key or CSR.

API method docs.

API method docs

Required policy:

# 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"]
}

CLI Example:

salt '*' vault_pki.sign_certificate myrole common_name="www.example.com" private_key=/private/key/path.key
salt '*' vault_pki.sign_certificate myrole common_name="www.example.com" csr=/csr/path.csr

role_name

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

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

mount

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

csr

Pass the CSR which should be used for issuing the certificate. Can be text or path. Either csr or private_key parameter can be set, not both.

private_key

Private key for which a certificate should be issued. Can be text or path. Either csr or private_key parameter can be set, not both.

Note

This parameter requires the x509_v2 execution module to be available. When this parameter is set, a CSR is generated in place. You can influence the resulting CSR by providing keyword arguments for x509.create_csr, which are passed through. See kwargs below.

private_key_passphrase

Passphrase for the private_key, if encrypted. Not used in case of csr.

digest

Digest to use for generating the CSR. Not used in case of csr. Defaults to sha256

issuer_ref

Specify an explicit issuer instead of taking it from the role definition. Can be issuer_name or issuer_id.

alt_names

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

ttl

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.

encoding

Output format. Can be either pem or der. Defaults to pem.

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.

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.

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.

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 an 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 an 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

Any additional parameter accepted by the Vault API or, if private_key is set, the x509_v2 module. Note that CN and subjectAltName are overwritten with the common_name/alt_names parameters to this function, regardless of sign_verbatim.

saltext.vault.modules.vault_pki.sign_intermediate(common_name=None, private_key=None, private_key_passphrase=None, csr=None, digest='sha256', issuer_ref=None, sign_verbatim=False, encoding='pem', signature_bits=0, ttl=None, not_before_duration=30, not_after=None, alt_names=None, exclude_cn_from_sans=False, max_path_length=None, key_usage=None, 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, mount='pki', **kwargs)[source]¶

Added in version 1.9.0.

Issue a new CA certificate from an existing private key or CSR.

API method docs.

Required policy:

# When issuer_ref is not specified
path "<mount>/root/sign-intermediate" {
    capabilities = ["update"]
}

# When issuer_ref is specified
path "<mount>/issuer/<issuer_ref>/sign-intermediate" {
    capabilities = ["update"]
}

CLI Example:

salt '*' vault_pki.sign_intermediate common_name="www.my.ca" private_key=/private/key/path.key
salt '*' vault_pki.sign_intermediate common_name="www.my.ca" csr=/csr/path.csr

common_name

Subject common name (CN) for 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.

private_key_passphrase

Password for the private key if encrypted.

csr

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

digest

Digest to use for generating the CSR. Not used in case of csr. Defaults to sha256

issuer_ref

Specify issuer_name or issuer_id of intended issuer. Defaults to the mount default issuer.

sign_verbatim

If set to true, the resulting certificate follows the CSR more or less exactly, including the full subject and all extensions (exception: basicConstraints). Defaults to false.

When this is true and a private_key is used (i.e. a CSR is generated by this function), most keyword arguments for x509.create_csr are effective, including subject.

When this is false, most attributes of csr/any CSR generation parameters are ignored.

encoding

Output format. Can be either pem or der. Defaults to pem.

signature_bits

ttl

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, ttl is ignored.

alt_names

<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 sign_verbatim is true.

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.

max_path_length

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 CAB Forum requirements, Vault ignores values other than DigitalSignature. Ignored when a csr is passed and sign_verbatim is true.

permitted_alt_names

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. Ignored when a csr is passed and sign_verbatim is true.

Subject DN fields

Most of these can be single strings or lists of strings (for multiple values). Ignored when a csr is passed and sign_verbatim is true.

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)

mount

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

kwargs

Any additional parameter accepted by the Vault API or, if private_key is set, x509.create_csr. The latter arguments are ignored, unless sign_verbatim is true.

saltext.vault.modules.vault_pki.revoke_certificate(serial=None, certificate=None, private_key=None, private_key_passphrase=None, mount='pki')[source]¶

Revoke an issued certificate.

API method docs.

Required policy:

# when `private_key` is unspecified
path "<mount>/revoke" {
    capabilities = ["create", "update"]
}

# when `private_key` is passed
path "<mount>/revoke-with-key" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.revoke_certificate 7e:85:c5:d1:85:94:9a:46:08:b5:1b:9c:22:cb:35:e5:ea:f3:56:3f
salt '*' vault_pki.revoke_certificate certificate=/etc/tls/my_cert.pem
salt '*' vault_pki.revoke_certificate certificate=/etc/tls/my_cert.pem private_key=/etc/tls/my_key.pem

serial: Specifies the serial of the certificate to revoke. Either serial or certificate must be specified.
certificate: Specifies the certificate (PEM or path) to revoke. Either serial or certificate must be specified.

Note

This parameter requires the x509_v2 execution module to be available.
private_key: Added in version 1.9.0.

Private key corresponding to the certificate issued by Vault that is attempted to be revoked. Optional. When this is passed, a different, less trusted API endpoint is used.
private_key_passphrase: Added in version 1.9.0.

Passphrase for private_key, if specified and encrypted. Optional.
mount: Mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.modules.vault_pki.read_urls(mount='pki')[source]¶

Fetch the URLs to be encoded in generated certificates. No URL configuration is returned until the configuration is set.

API method docs.

Required policy:

path "<mount>/config/urls" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_urls

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

saltext.vault.modules.vault_pki.write_urls(issuing_certificates=None, crl_endpoints=None, delta_crl_endpoints=None, ocsp_servers=None, aia_url_templating=None, mount='pki')[source]¶

Added in version 1.9.0.

Set issuing certificate endpoints, CRL distribution points, and OCSP server endpoints that will be encoded into issued certificates. This behaves as PATCH. To unset a value, set it to an empty string.

API method docs.

Required policy:

path "<mount>/config/urls" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.set_urls ocsp_servers=ocsp.my.ca

issuing_certificates: Specifies the URL values for the Issuing Certificate field as a list. (see RFC 5280 Section 4.2.2.1 for details)
crl_endpoints: Specifies the URL values for the CRL Distribution Points field as a list. (see RFC 5280 Section 4.2.1.13 for details)
delta_crl_endpoints: (Requires Vault 1.20+ or OpenBao) Specifies the URL values for the Delta CRL Distribution Points field. (see RFC 5280 Section 4.2.1.15 for details)
ocsp_servers: Specifies the URL values for the OCSP Servers field as a list. (see RFC 5280 Section 4.2.2.1 for details)
aia_url_templating: Render issuing_certificates/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.modules.vault_pki.read_cluster_config(mount='pki')[source]¶

Added in version 1.9.0.

Fetch cluster-local configuration, which is used in templated AIA URLs. path populates {{cluster_path}} and aia_path populates {{cluster_aia_path}}.

API method docs.

Required policy:

path "<mount>/config/cluster" {
    capabilities = ["read"]
}

CLI Example:

salt '*' vault_pki.read_cluster_config

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

saltext.vault.modules.vault_pki.write_cluster_config(path=None, aia_path=None, mount='pki')[source]¶

Added in version 1.9.0.

Set cluster-local configuration, which is used in templated AIA URLs.

API method docs.

Required policy:

path "<mount>/config/cluster" {
    capabilities = ["create", "update"]
}

CLI Example:

salt '*' vault_pki.write_cluster_config path='https://pr-a.vault.example.com/v1/ns1/pki-root'

path: URL of this performance replication cluster’s API mount path, including any namespaces as path components. Example: https://pr-a.vault.example.com/v1/ns1/pki-root.
aia_path: URL of this performance replication cluster’s AIA distribution point; may refer to an external, non-Vault responder. This is for resolving AIA URLs and providing the {{cluster_aia_path}} template parameter and will not be used for other purposes. As such, unlike path, this can safely use an insecure transit mechanism (like HTTP without TLS).
mount: Mount path the PKI backend is mounted to. Defaults to pki.

vault_pki¶

`vault_pki`¶