salt.modules.x509_v2¶

# /etc/salt/minion.d/x509.conf

features:
  x509_v2: true

# /etc/salt/master.d/peer.conf

peer:
  .*:
    - x509.sign_remote_certificate

# /etc/salt/master.d/peer.conf

peer:
  .*:
    - x509.sign_remote_certificate

peer_run:
  ca_server:
    - match.compound_matches

x509_signing_policies:
  www:
    - minions: 'www*'
    - signing_private_key: /etc/pki/ca.key
    - signing_cert: /etc/pki/ca.crt
    - C: US
    - ST: Utah
    - L: Salt Lake City
    - basicConstraints: "critical, CA:false"
    - keyUsage: "critical, cRLSign, keyCertSign"
    - subjectKeyIdentifier: hash
    - authorityKeyIdentifier: keyid,issuer:always
    - days_valid: 90
    - copypath: /etc/pki/issued_certs/

# x509, x509_v2 in 3006.*
peer:
  ca_server:
    - match.compound

# x509_v2 from 3007.0 onwards
peer_run:
  ca_server:
    - match.compound_matches

salt.modules.x509_v2.create_certificate(ca_server=None, signing_policy=None, encoding='pem', append_certs=None, pkcs12_passphrase=None, pkcs12_encryption_compat=False, pkcs12_friendlyname=None, path=None, overwrite=True, raw=False, **kwargs)¶

Create an X.509 certificate and return an encoded version of it.

Note

All parameters that take a public key, private key or certificate can be specified either as a PEM/hex/base64 string or a path to a local file encoded in all supported formats for the type.

CLI Example:

salt '*' x509.create_certificate signing_private_key='/etc/pki/myca.key' csr='/etc/pki/my.csr'

ca_server

Request a remotely signed certificate from ca_server. For this to work, a signing_policy must be specified, and that same policy must be configured on the ca_server. See Signing policies for details. Also, the Salt master must permit peers to call the sign_remote_certificate function, see Peer communication.

signing_policy

The name of a configured signing policy. Parameters specified in there are hardcoded and cannot be overridden. This is required for remote signing, otherwise optional. See Signing policies for details.

encoding

Specify the encoding of the resulting certificate. It can be returned as a pem (or pkcs7_pem) string or several (base64-encoded) binary formats (der, pkcs7_der, pkcs12). Defaults to pem.

append_certs

A list of additional certificates to append to the new one, e.g. to create a CA chain.

Note

Mind that when der encoding is in use, appending certificatees is prohibited.

copypath

Create a copy of the issued certificate in PEM format in this directory. The file will be named <serial_number>.crt if prepend_cn is False.

prepend_cn

When copypath is set, prepend the common name of the certificate to the file name like so: <CN>-<serial_number>.crt. Defaults to false.

pkcs12_passphrase

When encoding a certificate as pkcs12, encrypt it with this passphrase.

Note

PKCS12 encryption is very weak and should not be relied on for security.

pkcs12_encryption_compat

OpenSSL 3 and cryptography v37 switched to a much more secure default encryption for PKCS12, which might be incompatible with some systems. This forces the legacy encryption. Defaults to False.

pkcs12_friendlyname

When encoding a certificate as pkcs12, a name for the certificate can be included.

path

Instead of returning the certificate, write it to this file path.

overwrite

If path is specified and the file exists, overwrite it. Defaults to true.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

digest

The hashing algorithm to use for the signature. Valid values are: sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384, sha3_512. Defaults to sha256. This will be ignored for ed25519 and ed448 key types.

private_key

The private key corresponding to the public key the certificate should be issued for. This is one way of specifying the public key that will be included in the certificate, the other ones being public_key and csr.

private_key_passphrase

If private_key is specified and encrypted, the passphrase to decrypt it.

public_key

The public key the certificate should be issued for. Other ways of passing the required information are private_key and csr. If neither are set, the public key of the signing_private_key will be included, i.e. a self-signed certificate is generated.

csr

A certificate signing request to use as a base for generating the certificate. The following information will be respected, depending on configuration: * public key * extensions, if not otherwise specified (arguments, signing_policy)

signing_cert

The CA certificate to be used for signing the issued certificate.

signing_private_key

The private key corresponding to the public key in signing_cert. Required.

signing_private_key_passphrase

If signing_private_key is encrypted, the passphrase to decrypt it.

serial_number

A serial number to be embedded in the certificate. If unspecified, will autogenerate one. This should be an integer, either in decimal or hexadecimal notation.

not_before

Set a specific date the certificate should not be valid before. The format should follow %Y-%m-%d %H:%M:%S and will be interpreted as GMT/UTC. Defaults to the time of issuance.

not_after

Set a specific date the certificate should not be valid after. The format should follow %Y-%m-%d %H:%M:%S and will be interpreted as GMT/UTC. If unspecified, defaults to the current time plus days_valid days.

days_valid

If not_after is unspecified, the number of days from the time of issuance the certificate should be valid for. Defaults to 30.

subject

The subject's distinguished name embedded in the certificate. This is one way of passing this information (see kwargs below for the other). This argument will be preferred and allows to control the order of RDNs in the DN as well as to embed RDNs with multiple attributes. This can be specified as an RFC4514-encoded string (CN=example.com,O=Example Inc,C=US, mind that the rendered order is reversed from what is embedded), a list of RDNs encoded as in RFC4514 (["C=US", "O=Example Inc", "CN=example.com"]) or a dictionary ({"CN": "example.com", "C": "US", "O": "Example Inc"}, default ordering). Multiple name attributes per RDN are concatenated with a +.

Note

Parsing of RFC4514 strings requires at least cryptography release 37.

kwargs

Embedded X.509v3 extensions and the subject's distinguished name can be controlled via supplemental keyword arguments. See the following for an overview.

Subject properties in kwargs

C, ST, L, STREET, O, OU, CN, MAIL, SN, GN, UID, SERIALNUMBER

X.509v3 extensions in kwargs

Most extensions can be configured using the same string format as OpenSSL, while some require adjustments. In general, since the strings are parsed to dicts/lists, you can always use the latter formats directly. Marking an extension as critical is done by including it at the beginning of the configuration string, in the list or as a key in the dictionary with the value true.

Examples (some showcase dict/list correspondance):

basicConstraints

critical, CA:TRUE, pathlen:1 or

- basicConstraints:
    critical: true
    ca: true
    pathlen: 1

keyUsage

critical, cRLSign, keyCertSign or

- keyUsage:
    - critical
    - cRLSign
    - keyCertSign

subjectKeyIdentifier

This can be an explicit value or hash, in which case the value will be set to the SHA1 hash of some encoding of the associated public key, depending on the underlying algorithm (RSA/ECDSA/EdDSA).

authorityKeyIdentifier

keyid:always, issuer

subjectAltName

There is support for all OpenSSL-defined types except otherName.

email:me@example.com,DNS:example.com or

# mind this being a list, not a dict
- subjectAltName:
    - email:me@example.com
    - DNS:example.com

issuerAltName

The syntax is the same as for subjectAltName, except that the additional value issuer:copy is supported, which will copy the values of subjectAltName in the issuer's certificate.

authorityInfoAccess

OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer

crlDistributionPoints

When set to a string value, items are interpreted as fullnames:

URI:http://example.com/myca.crl, URI:http://example.org/my.crl

There is also support for more attributes using the full form:

- crlDistributionPoints:
    - fullname: URI:http://example.com/myca.crl
      crlissuer: DNS:example.org
      reasons:
        - keyCompromise
    - URI:http://example.org/my.crl

certificatePolicies

critical, 1.2.4.5, 1.1.3.4

Again, there is support for more attributes using the full form:

- certificatePolicies:
    critical: true
    1.2.3.4.5: https://my.ca.com/pratice_statement
    1.2.4.5.6:
      - https://my.ca.com/pratice_statement
      - organization: myorg
        noticeNumbers: [1, 2, 3]
        text: mytext

policyConstraints

requireExplicitPolicy:3,inhibitPolicyMapping:1

inhibitAnyPolicy

The value is just an integer: - inhibitAnyPolicy: 1

nameConstraints

critical,permitted;IP:192.168.0.0/255.255.0.0,permitted;email:.example.com,excluded;email:.com

- nameConstraints:
    critical: true
    permitted:
      - IP:192.168.0.0/24
      - email:.example.com
    excluded:
      - email:.com

noCheck

This extension does not take any values, except critical. Just the presence in the keyword args will include it.

tlsfeature

status_request

For more information, visit the OpenSSL docs.

salt.modules.x509_v2.create_crl(signing_private_key, revoked, signing_cert=None, signing_private_key_passphrase=None, include_expired=False, days_valid=None, digest='sha256', encoding='pem', extensions=None, path=None, raw=False, **kwargs)¶

Create a certificate revocation list.

CLI Example:

salt '*' x509.create_crl signing_cert=/etc/pki/ca.crt                 signing_private_key=/etc/pki/ca.key                 revoked="[{'certificate': '/etc/pki/certs/www1.crt', 'revocation_date': '2015-03-01 00:00:00'}]"

signing_private_key

Your certificate authority's private key. It will be used to sign the CRL. Required.

revoked

A list of dicts containing all the certificates to revoke. Each dict represents one certificate. A dict must contain either the key serial_number with the value of the serial number to revoke, or certificate with some reference to the certificate to revoke.

The dict can optionally contain the revocation_date key. If this key is omitted, the revocation date will be set to now. It should be a string in the format "%Y-%m-%d %H:%M:%S".

The dict can also optionally contain the not_after key. This is redundant if the certificate key is included, since it will be sourced from the certificate. If the certificate key is not included, this can be used for the logic behind the include_expired parameter. It should be a string in the format "%Y-%m-%d %H:%M:%S".

The dict can also optionally contain the extensions key, which allows to set CRL entry-specific extensions. The following extensions are supported:

certificateIssuer

Identifies the certificate issuer associated with an entry in an indirect CRL. The format is the same as for subjectAltName.

CRLReason

Identifies the reason for certificate revocation. Available choices are unspecified, keyCompromise, CACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn, aACompromise and removeFromCRL.

invalidityDate

Provides the date on which the certificate likely became invalid. The value should be a string in the same format as revocation_date.

signing_cert

The CA certificate to be used for signing the CRL.

signing_private_key_passphrase

If signing_private_key is encrypted, the passphrase to decrypt it.

include_expired

Also include already expired certificates in the CRL. Defaults to false.

days_valid

The number of days the CRL should be valid for. This sets the Next Update field. Defaults to 100 (until v3009) or 7 (from v3009 onwards).

digest

The hashing algorithm to use for the signature. Valid values are: sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384, sha3_512. Defaults to sha256. This will be ignored for ed25519 and ed448 key types.

encoding

Specify the encoding of the resulting certificate revocation list. It can be returned as a pem string or base64-encoded der. Defaults to pem.

extensions

Add CRL extensions. The following are available:

authorityKeyIdentifier

See x509.create_certificate.

authorityInfoAccess

See x509.create_certificate.

cRLNumber

Specifies a sequential number for each CRL issued by a CA. Values must be integers.

deltaCRLIndicator

If the CRL is a delta CRL, this value points to the cRLNumber of the base cRL. Values must be integers.

freshestCRL

Identifies how delta CRL information is obtained. The format is the same as crlDistributionPoints.

issuerAltName

See x509.create_certificate.

issuingDistributionPoint

Identifies the CRL distribution point for a particular CRL and indicates what kinds of revocation it covers. The format is comparable to crlDistributionPoints. Specify as follows:

issuingDistributionPoint:
  fullname:  # or relativename with RDN
    - URI:http://example.com/myca.crl
  onlysomereasons:
    - keyCompromise
  onlyuser: true
  onlyCA: true
  onlyAA: true
  indirectCRL: false

path

Instead of returning the CRL, write it to this file path.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

salt.modules.x509_v2.create_csr(private_key, private_key_passphrase=None, digest='sha256', encoding='pem', path=None, raw=False, **kwargs)¶

Create a certificate signing request.

CLI Example:

salt '*' x509.create_csr private_key='/etc/pki/myca.key' CN='My Cert'

private_key

The private key corresponding to the public key the certificate should be issued for. The CSR will be signed by it. Required.

private_key_passphrase

If private_key is encrypted, the passphrase to decrypt it.

digest

The hashing algorithm to use for the signature. Valid values are: sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256, sha3_224, sha3_256, sha3_384, sha3_512. Defaults to sha256. This will be ignored for ed25519 and ed448 key types.

encoding

Specify the encoding of the resulting certificate signing request. It can be returned as a pem string or base64-encoded der. Defaults to pem.

path

Instead of returning the CSR, write it to this file path.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

kwargs

Embedded X.509v3 extensions and the subject's distinguished name can be controlled via supplemental keyword arguments. See x509.create_certificate for an overview. Mind that some extensions are not available for CSR (authorityInfoAccess, authorityKeyIdentifier, issuerAltName, crlDistributionPoints).

salt.modules.x509_v2.create_private_key(algo='rsa', keysize=None, passphrase=None, encoding='pem', pkcs12_encryption_compat=False, path=None, raw=False, **kwargs)¶

Create a private key.

CLI Example:

salt '*' x509.create_private_key algo=ec keysize=384

algo

The digital signature scheme the private key should be based on. Available: rsa, ec, ed25519, ed448. Defaults to rsa.

keysize

For rsa, specifies the bitlength of the private key (2048, 3072, 4096). For ec, specifies the NIST curve to use (256, 384, 521). Irrelevant for Edwards-curve schemes (ed25519, ed448). Defaults to 2048 for RSA and 256 for EC.

passphrase

If this is specified, the private key will be encrypted using this passphrase. The encryption algorithm cannot be selected, it will be determined automatically as the best available one.

encoding

Specify the encoding of the resulting private key. It can be returned as a pem string, base64-encoded der or base64-encoded pkcs12. Defaults to pem.

pkcs12_encryption_compat

Some operating systems are incompatible with the encryption defaults for PKCS12 used since OpenSSL v3. This switch triggers a fallback to PBESv1SHA1And3KeyTripleDESCBC. Please consider the notes on PKCS12 encryption.

path

Instead of returning the private key, write it to this file path. Note that this does not use safe permissions and should be avoided.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

salt.modules.x509_v2.encode_certificate(certificate, encoding='pem', append_certs=None, private_key=None, private_key_passphrase=None, pkcs12_passphrase=None, pkcs12_encryption_compat=False, pkcs12_friendlyname=None, raw=False)¶

Create an encoded representation of a certificate, optionally including other structures. This can be used to create certificate chains, convert a certificate into a different encoding or embed the corresponding private key (for pkcs12).

CLI Example:

salt '*' x509.encode_certificate /etc/pki/my.crt pem /etc/pki/ca.crt

certificate

The certificate to encode.

encoding

Specify the encoding of the resulting certificate. It can be returned as a pem (or pkcs7_pem) string or several (base64-encoded) binary formats (der, pkcs7_der, pkcs12). Defaults to pem.

append_certs

A list of additional certificates to encode with the new one, e.g. to create a CA chain.

Note

Mind that when der encoding is in use, appending certificatees is prohibited.

private_key

For pkcs12, the private key corresponding to the public key of the certificate to be embedded.

private_key_passphrase

For pkcs12, if the private key to embed is encrypted, specify the corresponding passphrase.

pkcs12_passphrase

For pkcs12, the container can be encrypted. Specify the passphrase to use here. Mind that PKCS12 encryption should not be relied on for security purposes, see note above in x509.create_certificate.

pkcs12_encryption_compat

OpenSSL 3 and cryptography v37 switched to a much more secure default encryption for PKCS12, which might be incompatible with some systems. This forces the legacy encryption. Defaults to False.

pkcs12_friendlyname

When encoding a certificate as pkcs12, a name for the certificate can be included.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

salt.modules.x509_v2.encode_crl(crl, encoding='pem', raw=False)¶

Create an encoded representation of a certificate revocation list.

CLI Example:

salt '*' x509.encode_crl /etc/pki/my.crl der

crl

The certificate revocation list to encode.

encoding

Specify the encoding of the resulting certificate revocation list. It can be returned as a pem string or base64-encoded der. Defaults to pem.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

salt.modules.x509_v2.encode_csr(csr, encoding='pem', raw=False)¶

Create an encoded representation of a certificate signing request.

CLI Example:

salt '*' x509.encode_csr /etc/pki/my.csr der

csr

The certificate signing request to encode.

encoding

Specify the encoding of the resulting certificate signing request. It can be returned as a pem string or base64-encoded der. Defaults to pem.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

salt.modules.x509_v2.encode_private_key(private_key, encoding='pem', passphrase=None, private_key_passphrase=None, pkcs12_encryption_compat=False, raw=False)¶

Create an encoded representation of a private key.

CLI Example:

salt '*' x509.encode_private_key /etc/pki/my.key der

private_key

The private key to encode.

encoding

Specify the encoding of the resulting private key. It can be returned as a pem string, base64-encoded der and base64-encoded pkcs12. Defaults to pem.

passphrase

If this is specified, the private key will be encrypted using this passphrase. The encryption algorithm cannot be selected, it will be determined automatically as the best available one.

private_key_passphrase

New in version 3006.2.

If the current private_key is encrypted, the passphrase to decrypt it.

pkcs12_encryption_compat

Some operating systems are incompatible with the encryption defaults for PKCS12 used since OpenSSL v3. This switch triggers a fallback to PBESv1SHA1And3KeyTripleDESCBC. Please consider the notes on PKCS12 encryption.

raw

Return the encoded raw bytes instead of a string. Defaults to false.

salt.modules.x509_v2.expired(certificate)¶

Returns a dict containing limited details of a certificate and whether the certificate has expired.

CLI Example:

salt '*' x509.expired /etc/pki/mycert.crt

certificate

The certificate to check.

salt.modules.x509_v2.expires(certificate, days=0)¶

Determine whether a certificate will expire or has expired already. Returns a boolean only.

CLI Example:

salt '*' x509.expires /etc/pki/my.crt days=7

certificate

The certificate to check.

days

If specified, determine expiration x days in the future. Defaults to 0, which checks for the current time.

salt.modules.x509_v2.get_pem_entries(glob_path)¶

Returns a dict containing PEM entries in files matching a glob.

CLI Example:

salt '*' x509.get_pem_entries "/etc/pki/*.crt"

glob_path

A path representing certificates to be read and returned.

salt.modules.x509_v2.get_pem_entry(text, pem_type=None)¶

Returns a properly formatted PEM string from the input text, fixing any whitespace or line-break issues.

CLI Example:

salt '*' x509.get_pem_entry "-----BEGIN CERTIFICATE REQUEST-----MIICyzCC Ar8CAQI...-----END CERTIFICATE REQUEST"

text

Text containing the X509 PEM entry to be returned or path to a file containing the text.

pem_type

If specified, this function will only return a pem of a certain type, for example 'CERTIFICATE' or 'CERTIFICATE REQUEST'.

salt.modules.x509_v2.get_private_key_size(private_key, passphrase=None)¶

Return information about the keysize of a private key (RSA/EC).

CLI Example:

salt '*' x509.get_private_key_size /etc/pki/my.key

private_key

The private key to check.

passphrase

If private_key is encrypted, the passphrase to decrypt it.

salt.modules.x509_v2.get_public_key(key, passphrase=None, asObj=None)¶

Returns a PEM-encoded public key derived from some reference. The reference should be a public key, certificate, private key or CSR.

CLI Example:

salt '*' x509.get_public_key /etc/pki/my.key

key

A reference to the structure to look the public key up for.

passphrase

If key is encrypted, the passphrase to decrypt it.

salt.modules.x509_v2.get_signing_policy(signing_policy, ca_server=None)¶

Returns the specified named signing policy.

CLI Example:

salt '*' x509.get_signing_policy www

signing_policy

The name of the signing policy to return.

ca_server

If this is set, the CA server will be queried for the signing policy instead of looking it up locally.

salt.modules.x509_v2.read_certificate(certificate)¶

Returns a dict containing details of a certificate.

CLI Example:

salt '*' x509.read_certificate /etc/pki/mycert.crt

certificate

The certificate to read.

salt.modules.x509_v2.read_certificates(glob_path)¶

Returns a dict containing details of all certificates matching a glob.

CLI Example:

salt '*' x509.read_certificates "/etc/pki/*.crt"

glob_path

A path to certificates to be read and returned.

salt.modules.x509_v2.read_crl(crl)¶

Returns a dict containing details of a certificate revocation list.

CLI Example:

salt '*' x509.read_crl /etc/pki/my.crl

crl

The certificate revocation list to read.

salt.modules.x509_v2.read_csr(csr)¶

Returns a dict containing details of a certificate signing request.

CLI Example:

salt '*' x509.read_csr /etc/pki/mycert.csr

csr

The certificate signing request to read.

salt.modules.x509_v2.sign_remote_certificate(signing_policy, kwargs, get_signing_policy_only=False, **more_kwargs)¶

Request a certificate to be remotely signed according to a signing policy. This is mostly for internal use and does not make much sense on the CLI.

CLI Example:

salt '*' x509.sign_remote_certificate www kwargs="{'public_key': '/etc/pki/www.key'}"

signing_policy

The name of the signing policy to use. Required.

kwargs

A dict containing all the arguments to be passed into the x509.create_certificate function.

get_signing_policy_only

Only return the named signing policy. Defaults to false.

salt.modules.x509_v2.verify_crl(crl, cert)¶

Verify that a signature on a certificate revocation list was made by the private key corresponding to the public key associated with the specified certificate.

CLI Example:

salt '*' x509.verify_crl /etc/pki/my.crl /etc/pki/my.crt

crl

The certificate revocation list to check the signature on.

cert

The certificate (or any reference that can be passed to get_public_key) to retrieve the public key from.

salt.modules.x509_v2.verify_private_key(private_key, public_key, passphrase=None)¶

Verify that a private key belongs to the specified public key.

CLI Example:

salt '*' x509.verify_private_key /etc/pki/my.key /etc/pki/my.crt

private_key

The private key to check.

public_key

The certificate (or any reference that can be passed to get_public_key) to retrieve the public key from.

passphrase

If private_key is encrypted, the passphrase to decrypt it.

salt.modules.x509_v2.verify_signature(certificate, signing_pub_key=None, signing_pub_key_passphrase=None)¶

Verify that a signature on a certificate was made by the private key corresponding to the public key associated with the specified certificate.

CLI Example:

salt '*' x509.verify_signature /etc/pki/my.key /etc/pki/my.crt

certificate

The certificate to check the signature on.

signing_pub_key

Any reference that can be passed to get_public_key to retrieve the public key of the signing entity from. If unspecified, will take the public key of certificate, i.e. verify a self-signed certificate.

signing_pub_key_passphrase

If signing_pub_key is encrypted, the passphrase to decrypt it.

salt.modules.x509_v2.will_expire(certificate, days)¶

Returns a dict containing details of a certificate and whether the certificate will expire in the specified number of days.

CLI Example:

salt '*' x509.will_expire "/etc/pki/mycert.crt" days=30

certificate

The certificate to check.

days

The number of days in the future to check the validity for.

salt.modules.x509_v2.write_pem(text, path, overwrite=True, pem_type=None)¶

Writes out a PEM string, fixing any formatting or whitespace issues before writing.

CLI Example:

salt '*' x509.write_pem "-----BEGIN CERTIFICATE-----MIIGMzCCBBugA..." path=/etc/pki/mycert.crt

text

PEM string input to be written out.

path

Path of the file to write the PEM out to.

overwrite

If True (default), write_pem will overwrite the entire PEM file. Set to False to preserve existing private keys and DH params that may exist in the PEM file.

pem_type

The PEM type to be saved, for example CERTIFICATE or PUBLIC KEY. Adding this will allow the function to take input that may contain multiple PEM types.