`vault_pki`¶

SSH wrapper for the vault_pki execution module.

See there for documentation.

Setup notes¶

In addition to the regular Vault setup, using sign_certificate and revoke_certificate requires the x509_v2 module to be active on the target.

This means:

The global Python installation on the target needs to have the cryptography library installed.

On Salt releases below 3008, you need to include the following in your master configuration:

# e.g. /etc/salt/master.d/salt_ssh.conf

ssh_minion_opts:
  features:
    x509_v2: true

saltext.vault.wrapper.vault_pki.delete_issuer(ref, mount='pki', include_key=False)¶

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.wrapper.vault_pki.delete_key(ref, mount='pki')¶

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.wrapper.vault_pki.delete_role(name, mount='pki')¶

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.wrapper.vault_pki.generate_intermediate(key_ref, common_name, max_path_length=0, mount='pki', **kwargs)¶

Added in version 1.9.0.

Generate an intermediate CA from an existing key by signing it via x509.create_certificate.

Required policy: see generate_intermediate_csr() and import_intermediate()

CLI Example:

salt '*' vault_pki.generate_intermediate my-existing-named-key "My Intermediate CA"

key_ref

Reference to an existing private key on this mount, either key_name or key_id.

common_name

Subject CN. Required.

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.

mount

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

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

saltext.vault.wrapper.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, mount='pki', **kwargs)¶

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_root my-root

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.

kwargs: Unknown keyword arguments are passed through. See the API method docs linked above for details.

saltext.vault.wrapper.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')¶

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.wrapper.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, **kwargs)¶

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.

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

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.

kwargs

Unknown keyword arguments are passed through. See the API method docs linked above for details.

saltext.vault.wrapper.vault_pki.get_default_issuer(mount='pki')¶

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.wrapper.vault_pki.get_key_id(ref, mount='pki')¶

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.wrapper.vault_pki.issue_certificate(role_name, common_name=None, mount='pki', issuer_ref=None, alt_names=None, ttl=None, format='pem', exclude_cn_from_sans=False, **kwargs)¶

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 = ["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

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

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.

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.wrapper.vault_pki.list_certificates(mount='pki')¶

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.wrapper.vault_pki.list_issuers(mount='pki')¶

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.wrapper.vault_pki.list_keys(mount='pki')¶

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.wrapper.vault_pki.list_revoked_certificates(mount='pki')¶

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.wrapper.vault_pki.list_roles(mount='pki')¶

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.wrapper.vault_pki.read_certificate(serial, mount='pki')¶

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.wrapper.vault_pki.read_certificate_full(serial, mount='pki')¶

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.wrapper.vault_pki.read_issuer(ref='default', mount='pki')¶

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.wrapper.vault_pki.read_issuer_certificate(name='default', mount='pki', include_chain=False)¶

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.wrapper.vault_pki.read_issuer_crl(ref='default', mount='pki', delta=False)¶

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.wrapper.vault_pki.read_role(name, mount='pki')¶

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.wrapper.vault_pki.read_urls(mount='pki')¶

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.wrapper.vault_pki.revoke_certificate(serial=None, certificate=None, private_key=None, private_key_passphrase=None, mount='pki')¶

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.wrapper.vault_pki.set_default_issuer(name, mount='pki')¶

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.wrapper.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, **kwargs)¶

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 = ["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 be used 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.

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

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

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

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.wrapper.vault_pki.write_urls(issuing_certificates=None, crl_endpoints=None, delta_crl_endpoints=None, ocsp_servers=None, aia_url_templating=None, mount='pki')¶

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: The mount path the PKI backend is mounted to. Defaults to pki.

saltext.vault.wrapper.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.wrapper.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.
chain: CA chain for the certificate. Defaults to the chain in cert, if present.
private_key: Import corresponding private key for cert. Optional.

Important

Specifying this parameter means the private key leaves the remote minion.
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.

vault_pki¶

Setup notes¶

`vault_pki`¶