saltext.vault.utils.vault.pki

Vault PKI helpers

Added in version 1.1.0.

saltext.vault.utils.vault.pki.check_cert_for_changes(current: str, issuer: str, private_key: str | None, csr: str | None, encoding: Literal['pem', 'pkcs7_pem', 'der', 'pkcs7_der'] = 'pem', sign_verbatim: bool = False, *, alt_names: dict[str, str | list[str]] | list[str] | None, append_chain: list[str] | str | None, common_name: str | None, exclude_cn_from_sans: bool, expire_tolerance: int | str | None, ext_key_usage: list[str] | str | None, ext_key_usage_oids: list[str] | str | None, key_usage: list[str] | str | None, not_after: str | None, private_key_passphrase: str | None, role_info: dict[str, Any], serial_number: str | None, ttl: int, urls: dict[str, list[str] | bool], user_ids: list[str] | str | None, **kwargs) → dict[str, Any]

Check whether an existing on-disk leaf certificate matches expected parameters.

current

Path of the existing certificate on disk.

issuer

Issuer certificate.

private_key

Path of the private key on disk/encoded private key.

encoding

Requested certificate encoding. Defaults to pem.

sign_verbatim

Whether the sign-verbatim endpoint is used. Defaults to false.

alt_names

Requested Subject Alternative Names.

append_chain

List of certificates to append. Fails with der encoding.

common_name

Subject CN name attribute.

exclude_cn_from_sans

Whether the subject CN should be included in the SANs (either as email or dns type). Has no effect when sign_verbatim is true.

expire_tolerance

Otherwise called ttl_remaining, minimum TTL to allow before requesting a fresh certificate.

ext_key_usage

When sign_verbatim is true, default Extended Key Usages if the CSR carries none.

ext_key_usage_oids

When sign_verbatim is true, additional OIDs for the default Extended Key Usages if the CSR carries none.

key_usage

When sign_verbatim is true, default Key Usages if the CSR carries none.

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.

private_key_passphrase

Passphrase for private_key

role_info

Return value of read_role.

serial_number

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

ttl

Requested Time To Live, already normalized to integer-valued seconds.

urls

Dictionary of issuer/mount-default authority URLs, which end up in the AuthorityInformationAccess, CRLDistributionPoints and FreshestCRL extensions.

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

All other kwargs passed to the cert signing endpoint or as CSR generation params.

saltext.vault.utils.vault.pki.check_root_issuer_for_changes(current, *, alt_names: dict[str, str | list[str]] | list[str] | None, common_name: str, country: list[str] | str | None, days_remaining: int, days_valid: int, exclude_cn_from_sans: bool, excluded_alt_names: dict[str, str | list[str]] | list[str] | None, key_usage: list[str] | str | None, locality: list[str] | str | None, max_path_length: int, not_after: str | None, not_before_duration: str | int, organization: list[str] | str | None, ou: list[str] | str | None, permitted_alt_names: dict[str, str | list[str]] | list[str] | None, postal_code: list[str] | str | None, province: list[str] | str | None, replace_key: bool, rotate_key: bool, signature_bits: int, street_address: list[str] | str | None, serial_number: str | None, urls: dict[str, list[str] | bool])

Check whether an existing root CA issuer certificate matches expected parameters.

current

Existing certificate text.

alt_names

Requested Subject Alternative Names.

common_name

Subject CN (commonName) name attribute.

country

Subject C (countryName) name attribute(s).

days_remaining

Minimum TTL in days to allow before requesting a fresh certificate.

days_valid

Requested Time To Live in integer days.

exclude_cn_from_sans

Whether the subject CN should be included in the SANs (either as email or dns type).

excluded_alt_names

List of alternative names for which certificates are not allowed to be issued or signed by this CA certificate.

key_usage

List of key usages to add to the existing set of key usages (CRLSign,CertSign).

locality

Subject L (localityName) name attribute(s).

max_path_length

Basic Constraints pathlen parameter.

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.

organization

Subject O (organizationName) name attribute(s).

ou

Subject OU (organizationalUnitName) name attribute(s).

permitted_alt_names

List of alternative names for which certificates are allowed to be issued or signed by this CA certificate.

postal_code

Subject postalCode name attribute(s).

province

Subject ST (stateOrProvinceName) name attribute(s).

signature_bits

Number of bits to use in the signature algorithm. Valid: 256 (SHA-2-256), 384 (SHA-2-384), 512 (SHA-2-512).

street_address

Subject street (streetAddress) name attribute(s).

serial_number

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

urls

Dictionary of issuer/mount-default authority URLs, which end up in the AuthorityInformationAccess, CRLDistributionPoints and FreshestCRL extensions.

saltext.vault.utils.vault.pki.norm_sans(sans: dict[str, str | list[str]] | list[str], *, allow_other_name: bool = True) → dict[str, list[str]]

Normalize all allowed input structures for SubjectAlternativeNames (alt_names parameter) or NameConstraints (permitted_alt_names, excluded_alt_names) into a dict of lists with uppercase keys.

sans

User input. 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 (unless allow_other_name is false). <value> is the corresponding value. Note that otherName SANs need to omit UTF8:.

allow_other_name

Whether to parse unknown <type> values as otherName SAN OIDs. When false, raises an exception for types other than dns, email, uri and ip. Intended to parse General Names for the NameConstraints extension.

saltext.vault.utils.vault.pki.split_sans(sans: dict[str, list[str]]) → tuple[list[str], list[str], list[str], list[str]]

Render a normalized dict of lists of GeneralNames for the subjectAltName extension into a format Vault understands and return each type separately. Returns a tuple of (dns_or_email_sans, ip_sans, uri_sans, other_sans).

sans

Normalized dict of lists ({"<type>": ["<value>", ...]}) as output by norm_sans().

saltext.vault.utils.vault.pki.split_name_constraints(sans: dict[str, list[str]]) → tuple[list[str], list[str], list[str], list[str]]

Render a normalized dict of lists of GeneralNames for the nameConstraints extension into a format Vault understands and return each type separately. Returns a tuple of (dns_nc, email_nc, ip_nc, uri_nc).

sans

Normalized dict of lists ({"<type>": ["<value>", ...]}) as output by norm_sans() with allow_other_name being false.

saltext.vault.utils.vault.pki.split_csr_kwargs(kwargs: dict[str, Any]) → tuple[dict[str, Any], dict[str, Any]]

Split known parameters for x509.create_csr from a dict of passed keyword arguments. Returns a tuple of (csr_args, extra_args).

kwargs

Keyword arguments passed to the function.

saltext.vault.utils.vault.pki.sync_verbatim_csr_subject(csr_args, *, serial_number, user_ids)

Ensure user_ids and serial_number work when signing verbatim.

saltext.vault.utils.vault.pki.get_ski(cert: str | bytes | Certificate) → str | None

Get a certificate’s subjectKeyIdentifier in pretty hex.