salt.modules.x509

Manage X509 certificates

depends:	M2Crypto

salt.modules.x509.create_certificate(path=None, text=False, overwrite=True, ca_server=None, **kwargs)

Create an X509 certificate.

path:

Path to write the certificate to.

text:

If True, return the PEM text without writing to a file. Default False.

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. See signing_policy for details. Also the salt master must permit peers to call the sign_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, or csr are included, it will be assumed that this is a self-signed certificate, and the public key matching signing_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 or csr are specified, it will be assumed that this is a self-signed certificate, and the public key derived from signing_private_key will be used. Specify either public_key or csr, 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 and authorityKeyIdentifier.

subjectKeyIdentifier can be an explicit value or it can be the special string hash. 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 populate authorityKeyIdentifier with the subjectKeyIdentifier of signing_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.

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

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_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 CRL

Depends:	PyOpenSSL Python module

path:

Path to write the crl to.

text:

If True, return the PEM text without writing to a file. Default False.

signing_private_key:

A path or string of the private key in PEM format that will be used to sign this 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 this 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, or certificate 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 the certificate key is included. If the Certificate key is not included, this can be used for the logic behind the include_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 are unspecified, keyCompromise, CACompromise, affiliationChanged, superseded, cessationOfOperation and certificateHold.

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_csr(path=None, text=False, **kwargs)

Create a certificate signing request.

path:

Path to write the certificate to.

text:

If True, return the PEM text without writing to a file. Default False.

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_private_key(path=None, text=False, bits=2048, passphrase=None, cipher='aes_128_cbc', verbose=True)

Creates a private key in PEM format.

path:

The path to write the file to, either path or text are required.

text:

If True, return the PEM text without writing to a file. Default False.

bits:

Length of the private key in bits. Default 2048

passphrase:

Passphrase for encryting the private key

cipher:

Cipher for encrypting the private key. Has no effect if passhprase 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.expired(certificate)

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.get_pem_entries(glob_path)

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_entry(text, pem_type=None)

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_private_key_size(private_key, passphrase=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_public_key(key, passphrase=None, asObj=False)

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_signing_policy(signing_policy_name)

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.read_certificate(certificate)

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_certificates(glob_path)

Returns a dict containing details of a 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_crl(crl)

Returns a dict containing details of a certificate revocation list. Input can be a PEM string or file path.

Depends:	OpenSSL command line tool

csl:

A path or PEM encoded string containing the CSL to read.

CLI Example:

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

salt.modules.x509.read_csr(csr)

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.sign_remote_certificate(argdic, **kwargs)

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.verify_crl(crl, cert)

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_private_key(private_key, public_key, passphrase=None)

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_signature(certificate, signing_pub_key=None, signing_pub_key_passphrase=None)

Verify that certificate has been signed by signing_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.will_expire(certificate, days)

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.write_pem(text, path, overwrite=True, pem_type=None)

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 or PUBLIC 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