`vault_pki`¶

Manage the Vault 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.

CLI Example:

salt '*' vault_pki.list_roles

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

CLI Example:

salt '*' vault_pki.read_role

name: The name of the role.
mount: The 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.

CLI Example:

salt '*' vault_pki.write_role myrole

name: The name of the role.
mount: The mount path the PKI backend is mounted to. Defaults to pki.
issuer_ref: Name or id of the issuer which will be used with this role. If not set, default issuer will be 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 will not be 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 understand by Vault API.

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

Delete PKI role from Vault.

API method docs.

CLI Example:

salt '*' vault_pki.delete_role myrole

name: The name of the role.
mount: The 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.

CLI Example:

salt '*' vault_pki.list_issuers

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

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

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

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

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: The mount path the PKI backend is mounted to. Defaults to pki.
include_chain: If set to true will append 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.

CLI Example:

salt '*' vault_pki.get_default_issuer

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

CLI Example:

salt '*' vault_pki.set_default_issuer myca

mount: The 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 it will also return the private key.

API method docs.

CLI Example:

salt '*' vault_pki.generate_root my-root

common_name: The common name to be used for the CA
mount: The 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 will be returned in the response; if internal, the private key will not be 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 will be expired). 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.

CLI Example:

salt '*' vault_pki.delete_key ref

ref: Ref of the key. Could be name or key_id.
mount: The 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.

CLI Example:

salt '*' vault_pki.delete_issuer ref

ref: Ref of the issuer. Could be name or issuer_id.
mount: The mount path the PKI backend is mounted to. Defaults to pki.
include_key: If set to true will also delete the private key if imported. Defaults to false, so private key will be 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 will return None.

API method docs.

CLI Example:

salt '*' vault_pki.read_issuer_crl ref

ref: Ref of the issuer. Could be name or issuer_id. Defaults to default issuer.
mount: The mount path the PKI backend is mounted to. Defaults to pki.
delta: If set to true, will return 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.

CLI Example:

salt '*' vault_pki.list_revoked_certificates

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

CLI Example:

salt '*' vault_pki.list_certificates

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

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

The 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 with private key.

API method docs.

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: The mount path the PKI backend is mounted to. Defaults to pki.
issuer_ref: Override role’s issuer. 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"}) or list of SANs (["<type>:<value>"]).
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).
format: Can be either pem or der. Defaults to pem.
exclude_cn_from_sans: If set to true, Common name will not be part of the SANs.
kwargs: Any additional parameter accepted by 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 existing private key or CSR.

API method docs.

API method docs

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: The mount path the PKI backend is mounted to. Defaults to pki.
csr: Pass the CSR which will be used for issuing the certificate. Either csr or private_key parameter can be set, not both.
private_key: The 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: The 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: Override role’s issuer. 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"}) or list of SANs (["<type>:<value>"]).
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).
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, Common name will not be part of the SANs.
kwargs: Any additional parameter accepted by Vault API or x509_v2 module

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

Revoke issued certificate.

API method docs.

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: The 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 will be returned until the configuration is set.

API method docs.

CLI Example:

salt '*' vault_pki.get_urls

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

vault_pki¶

`vault_pki`¶