salt.modules.x509
Manage X509 certificates
New in version 2015.8.0.
- depends
-
M2Crypto
-
Create an X509 certificate.
- path:
-
Path to write the certificate to.
- text:
-
If
True
, return the PEM text without writing to a file. DefaultFalse
. - overwrite:
-
If
True
(default), create_certificate will overwrite the entire PEM file. Set False to preserve existing private keys and dh params that may exist in the PEM file. - kwargs:
-
Any of the properties below can be included as additional keyword arguments.
- 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. Seesigning_policy
for details. Also, the salt master must permit peers to call thesign_remote_certificate
function.Example:
/etc/salt/master.d/peer.conf
peer: .*: - x509.sign_remote_certificate
- subject properties:
-
Any of the values below can be included to set subject properties Any other subject properties supported by OpenSSL should also work.
- C:
-
2 letter Country code
- CN:
-
Certificate common name, typically the FQDN.
- Email:
-
Email address
- GN:
-
Given Name
- L:
-
Locality
- O:
-
Organization
- OU:
-
Organization Unit
- SN:
-
SurName
- ST:
-
State or Province
- signing_private_key:
-
A path or string of the private key in PEM format that will be used to sign this certificate. If neither
signing_cert
,public_key
, orcsr
are included, it will be assumed that this is a self-signed certificate, and the public key matchingsigning_private_key
will be used to create the certificate. - signing_private_key_passphrase:
-
Passphrase used to decrypt the signing_private_key.
- signing_cert:
-
A certificate matching the private key that will be used to sign this certificate. This is used to populate the issuer values in the resulting certificate. Do not include this value for self-signed certificates.
- public_key:
-
The public key to be included in this certificate. This can be sourced from a public key, certificate, CSR or private key. If a private key is used, the matching public key from the private key will be generated before any processing is done. This means you can request a certificate from a remote CA using a private key file as your public_key and only the public key will be sent across the network to the CA. If neither
public_key
orcsr
are specified, it will be assumed that this is a self-signed certificate, and the public key derived fromsigning_private_key
will be used. Specify eitherpublic_key
orcsr
, not both. Because you can input a CSR as a public key or as a CSR, it is important to understand the difference. If you import a CSR as a public key, only the public key will be added to the certificate, subject or extension information in the CSR will be lost. - public_key_passphrase:
-
If the public key is supplied as a private key, this is the passphrase used to decrypt it.
- csr:
-
A file or PEM string containing a certificate signing request. This will be used to supply the subject, extensions and public key of a certificate. Any subject or extensions specified explicitly will overwrite any in the CSR.
- basicConstraints:
-
X509v3 Basic Constraints extension.
- extensions:
-
The following arguments set X509v3 Extension values. If the value starts with
critical
, the extension will be marked as critical.Some special extensions are
subjectKeyIdentifier
andauthorityKeyIdentifier
.subjectKeyIdentifier
can be an explicit value or it can be the special stringhash
.hash
will set the subjectKeyIdentifier equal to the SHA1 hash of the modulus of the public key in this certificate. Note that this is not the exact same hashing method used by OpenSSL when using the hash value.authorityKeyIdentifier
Use values acceptable to the openssl CLI tools. This will automatically populateauthorityKeyIdentifier
with thesubjectKeyIdentifier
ofsigning_cert
. If this is a self-signed cert these values will be the same.- basicConstraints:
-
X509v3 Basic Constraints
- keyUsage:
-
X509v3 Key Usage
- extendedKeyUsage:
-
X509v3 Extended Key Usage
- subjectKeyIdentifier:
-
X509v3 Subject Key Identifier
- issuerAltName:
-
X509v3 Issuer Alternative Name
- subjectAltName:
-
X509v3 Subject Alternative Name
- crlDistributionPoints:
-
X509v3 CRL Distribution Points
- issuingDistributionPoint:
-
X509v3 Issuing Distribution Point
- certificatePolicies:
-
X509v3 Certificate Policies
- policyConstraints:
-
X509v3 Policy Constraints
- inhibitAnyPolicy:
-
X509v3 Inhibit Any Policy
- nameConstraints:
-
X509v3 Name Constraints
- noCheck:
-
X509v3 OCSP No Check
- nsComment:
-
Netscape Comment
- nsCertType:
-
Netscape Certificate Type
- days_valid:
-
The number of days this certificate should be valid. This sets the
notAfter
property of the certificate. Defaults to 365. - version:
-
The version of the X509 certificate. Defaults to 3. This is automatically converted to the version value, so
version=3
sets the certificate version field to 0x2. - serial_number:
-
The serial number to assign to this certificate. If omitted a random serial number of size
serial_bits
is generated. - serial_bits:
-
The number of bits to use when randomly generating a serial number. Defaults to 64.
- algorithm:
-
The hashing algorithm to be used for signing this certificate. Defaults to sha256.
- copypath:
-
An additional path to copy the resulting certificate to. Can be used to maintain a copy of all certificates issued for revocation purposes.
- prepend_cn:
-
If set to True, the CN and a dash will be prepended to the copypath's filename.
- Example:
-
/etc/pki/issued_certs/www.example.com-DE:CA:FB:AD:00:00:00:00.crt
- signing_policy:
-
A signing policy that should be used to create this certificate. Signing policies should be defined in the minion configuration, or in a minion pillar. It should be a YAML formatted list of arguments which will override any arguments passed to this function. If the
minions
key is included in the signing policy, only minions matching that pattern (see match.glob and match.compound) will be permitted to remotely request certificates from that policy. In order tomatch.compound
to work salt master must peers permit peers to call it.Example:
/etc/salt/master.d/peer.conf
peer: .*: - match.compound
Example:
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/
The above signing policy can be invoked with
signing_policy=www
- not_before:
-
Initial validity date for the certificate. This date must be specified in the format '%Y-%m-%d %H:%M:%S'.
New in version 3001.
- not_after:
-
Final validity date for the certificate. This date must be specified in the format '%Y-%m-%d %H:%M:%S'.
New in version 3001.
CLI Example:
salt '*' x509.create_certificate path=/etc/pki/myca.crt signing_private_key='/etc/pki/myca.key' csr='/etc/pki/myca.csr'}
salt.modules.x509.create_certificate(path=None, text=False, overwrite=True, ca_server=None, **kwargs)
-
Create a CRL
- Depends
-
PyOpenSSL Python module
- path:
-
Path to write the CRL to.
- text:
-
If
True
, return the PEM text without writing to a file. DefaultFalse
. - signing_private_key:
-
A path or string of the private key in PEM format that will be used to sign the CRL. This is required.
- signing_private_key_passphrase:
-
Passphrase to decrypt the private key.
- signing_cert:
-
A certificate matching the private key that will be used to sign the CRL. This is 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, orcertificate
with either the PEM encoded text of the certificate, or a path 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. If 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 thecertificate
key is included. If theCertificate
key is not included, this can be used for the logic behind theinclude_expired
parameter. If should be a string in the format "%Y-%m-%d %H:%M:%S".The dict can also optionally contain the
reason
key. This is the reason code for the revocation. Available choices areunspecified
,keyCompromise
,CACompromise
,affiliationChanged
,superseded
,cessationOfOperation
andcertificateHold
. - include_expired:
-
Include expired certificates in the CRL. Default is
False
. - days_valid:
-
The number of days that the CRL should be valid. This sets the Next Update field in the CRL.
- digest:
-
The digest to use for signing the CRL. This has no effect on versions of pyOpenSSL less than 0.14
CLI Example:
salt '*' x509.create_crl path=/etc/pki/mykey.key \ signing_private_key=/etc/pki/ca.key \ signing_cert=/etc/pki/ca.crt \ revoked="{'compromized-web-key': {'certificate': '/etc/pki/certs/www1.crt', 'revocation_date': '2015-03-01 00:00:00'}}"
salt.modules.x509.create_crl(path=None, text=False, signing_private_key=None, signing_private_key_passphrase=None, signing_cert=None, revoked=None, include_expired=False, days_valid=100, digest='')
-
Create a certificate signing request.
- path:
-
Path to write the certificate to.
- text:
-
If
True
, return the PEM text without writing to a file. DefaultFalse
. - algorithm:
-
The hashing algorithm to be used for signing this request. Defaults to sha256.
- kwargs:
-
The subject, extension and version arguments from
x509.create_certificate
can be used.
CLI Example:
salt '*' x509.create_csr path=/etc/pki/myca.csr public_key='/etc/pki/myca.key' CN='My Cert'
salt.modules.x509.create_csr(path=None, text=False, **kwargs)
-
Creates a private key in PEM format.
- path:
-
The path to write the file to, either
path
ortext
are required. - text:
-
If
True
, return the PEM text without writing to a file. DefaultFalse
. - bits:
-
Length of the private key in bits. Default 2048
- passphrase:
-
Passphrase for encrypting the private key
- cipher:
-
Cipher for encrypting the private key. Has no effect if passphrase is None.
- verbose:
-
Provide visual feedback on stdout. Default True
New in version 2016.11.0.
CLI Example:
salt '*' x509.create_private_key path=/etc/pki/mykey.key
salt.modules.x509.create_private_key(path=None, text=False, bits=2048, passphrase=None, cipher='aes_128_cbc', verbose=True)
-
Returns a dict containing limited details of a certificate and whether the certificate has expired.
New in version 2016.11.0.
- certificate:
-
The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate.
CLI Example:
salt '*' x509.expired "/etc/pki/mycert.crt"
salt.modules.x509.expired(certificate)
-
Returns a dict containing PEM entries in files matching a glob
- glob_path:
-
A path to certificates to be read and returned.
CLI Example:
salt '*' x509.get_pem_entries "/etc/pki/*.crt"
salt.modules.x509.get_pem_entries(glob_path)
-
Returns a properly formatted PEM string from the input text fixing any whitespace or line-break issues
- 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'.
CLI Example:
salt '*' x509.get_pem_entry "-----BEGIN CERTIFICATE REQUEST-----MIICyzCC Ar8CAQI...-----END CERTIFICATE REQUEST"
salt.modules.x509.get_pem_entry(text, pem_type=None)
-
Returns the bit length of a private key in PEM format.
- private_key:
-
A path or PEM encoded string containing a private key.
CLI Example:
salt '*' x509.get_private_key_size /etc/pki/mycert.key
salt.modules.x509.get_private_key_size(private_key, passphrase=None)
-
Returns a string containing the public key in PEM format.
- key:
-
A path or PEM encoded string containing a CSR, Certificate or Private Key from which a public key can be retrieved.
CLI Example:
salt '*' x509.get_public_key /etc/pki/mycert.cer
salt.modules.x509.get_public_key(key, passphrase=None, asObj=False)
-
Returns the details of a names signing policy, including the text of the public key that will be used to sign it. Does not return the private key.
CLI Example:
salt '*' x509.get_signing_policy www
salt.modules.x509.get_signing_policy(signing_policy_name)
-
Returns a dict containing details of a certificate. Input can be a PEM string or file path.
- certificate:
-
The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate.
CLI Example:
salt '*' x509.read_certificate /etc/pki/mycert.crt
salt.modules.x509.read_certificate(certificate)
-
Returns a dict containing details of all certificates matching a glob
- glob_path:
-
A path to certificates to be read and returned.
CLI Example:
salt '*' x509.read_certificates "/etc/pki/*.crt"
salt.modules.x509.read_certificates(glob_path)
-
Returns a dict containing details of a certificate revocation list. Input can be a PEM string or file path.
- Depends
-
OpenSSL command line tool
- crl:
-
A path or PEM encoded string containing the CRL to read.
CLI Example:
salt '*' x509.read_crl /etc/pki/mycrl.crl
salt.modules.x509.read_crl(crl)
-
Returns a dict containing details of a certificate request.
- Depends
-
OpenSSL command line tool
- csr:
-
A path or PEM encoded string containing the CSR to read.
CLI Example:
salt '*' x509.read_csr /etc/pki/mycert.csr
salt.modules.x509.read_csr(csr)
-
Request a certificate to be remotely signed according to a signing policy.
- argdic:
-
A dict containing all the arguments to be passed into the create_certificate function. This will become kwargs when passed to create_certificate.
- kwargs:
-
kwargs delivered from publish.publish
CLI Example:
salt '*' x509.sign_remote_certificate argdic="{'public_key': '/etc/pki/www.key', 'signing_policy': 'www'}" __pub_id='www1'
salt.modules.x509.sign_remote_certificate(argdic, **kwargs)
-
Validate a CRL against a certificate. Parses openssl command line output, this is a workaround for M2Crypto's inability to get them from CSR objects.
- crl:
-
The CRL to verify
- cert:
-
The certificate to verify the CRL against
CLI Example:
salt '*' x509.verify_crl crl=/etc/pki/myca.crl cert=/etc/pki/myca.crt
salt.modules.x509.verify_crl(crl, cert)
-
Verify that 'private_key' matches 'public_key'
- private_key:
-
The private key to verify, can be a string or path to a private key in PEM format.
- public_key:
-
The public key to verify, can be a string or path to a PEM formatted certificate, CSR, or another private key.
- passphrase:
-
Passphrase to decrypt the private key.
CLI Example:
salt '*' x509.verify_private_key private_key=/etc/pki/myca.key \ public_key=/etc/pki/myca.crt
salt.modules.x509.verify_private_key(private_key, public_key, passphrase=None)
-
Verify that
certificate
has been signed bysigning_pub_key
- certificate:
-
The certificate to verify. Can be a path or string containing a PEM formatted certificate.
- signing_pub_key:
-
The public key to verify, can be a string or path to a PEM formatted certificate, CSR, or private key.
- signing_pub_key_passphrase:
-
Passphrase to the signing_pub_key if it is an encrypted private key.
CLI Example:
salt '*' x509.verify_signature /etc/pki/mycert.pem \ signing_pub_key=/etc/pki/myca.crt
salt.modules.x509.verify_signature(certificate, signing_pub_key=None, signing_pub_key_passphrase=None)
-
Returns a dict containing details of a certificate and whether the certificate will expire in the specified number of days. Input can be a PEM string or file path.
New in version 2016.11.0.
- certificate:
-
The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate.
CLI Example:
salt '*' x509.will_expire "/etc/pki/mycert.crt" days=30
salt.modules.x509.will_expire(certificate, days)
-
Writes out a PEM string fixing any formatting or whitespace issues before writing.
- 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 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
orPUBLIC KEY
. Adding this will allow the function to take input that may contain multiple PEM types.
CLI Example:
salt '*' x509.write_pem "-----BEGIN CERTIFICATE-----MIIGMzCCBBugA..." path=/etc/pki/mycert.crt
salt.modules.x509.write_pem(text, path, overwrite=True, pem_type=None)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.x509.html