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.

API method docs.

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.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)[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 which means 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; 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.

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.

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 of the default issuer to set.

mount

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

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

Generate a new root issuer.

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

API method docs.

Required policy:

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

CLI Example:

salt '*' vault_pki.generate_root my-root
common_name

Common Name to be used for the CA.

mount

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

type

Specifies the type of the root to create. If exported, the private key is returned in the response; if internal, 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_type

Specifies the desired key type; must be rsa, ed25519 or ec. Defaults to rsa.

key_bits

Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with key_type=rsa, allowed values are: 2048 (default), 3072, 4096 or 8192; with key_type=ec, allowed values are: 224, 256 (default), 384, or 521; ignored with key_type=ed25519.

max_path_length

Specifies the maximum path length to encode in the generated certificate. -1 means no limit, unless the signing certificate has a maximum path length set, in which case the path length is set to one less than that of the signing certificate. A limit of 0 means a literal path length of zero.

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

Delete private key from Vault.

API method docs.

Required policy:

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

CLI Example:

salt '*' vault_pki.delete_key ref
ref

Ref of the key. Could be 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

Ref of the issuer. Could be 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.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

Ref of the issuer, i.e. name or issuer_id. Defaults to default issuer.

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, mount='pki', issuer_ref=None, alt_names=None, ttl=None, format='pem', exclude_cn_from_sans=False, **kwargs)[source]

Generate and issue a new certificate and private key.

API method docs.

Required policy:

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

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

CLI Example:

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

Name of the role to be used for issuing the certificate.

common_name

Common name to be set for the certificate.

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

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

<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 expires). This cannot be larger than the engine’s max (or, if not set, the system max).

format

Can be either pem or der. Defaults to pem.

exclude_cn_from_sans

If set to true, the Common Name is not part of the SANs.

kwargs

Any additional parameter accepted by the Vault API.

saltext.vault.modules.vault_pki.sign_certificate(role_name, common_name, 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, **kwargs)[source]

Issue a new 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 = ["create", "update"]
}

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

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

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

# When passing `private_key` and including otherName SANs
path "<mount>/roles/<role_name>" {
    capabilities = ["read"]
}

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

Name of the role to be used for issuing the certificate.

common_name

Common name to be set for the certificate.

mount

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

csr

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

private_key

Private key for which 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.

private_key_passphrase

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

digest

Digest to be used for generating the CSR. Not used in case of private_key. 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

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

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

Note

As of writing this, otherName SANs require very recent releases of the x509_v2 module, which is used to generate a CSR when csr is not specified. If you need to make this work, in the affected role, set use_csr_sans to false, which circumvents this issue.

ttl

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

sign_verbatim

If set to true, the resulting certificate follows the CSR exactly. Otherwise, only CN can be set for the subject, any other subject parameter (like O) is ignored.

Warning

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

encoding

Can be either pem or der. Defaults to pem.

exclude_cn_from_sans

If set to true, the Common Name is not part of the SANs.

kwargs

Any additional parameter accepted by the Vault API or the x509_v2 module

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

Revoke issued certificate.

API method docs.

Required policy:

path "<mount>/revoke" {
    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
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.

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.