salt.modules.tls¶

A salt module for SSL/TLS. Can create a Certificate Authority (CA) or use Self-Signed certificates.

ca.cert_base_path: '/etc/pki'

salt.modules.tls.ca_exists(ca_name, cacert_path=None)¶

Verify whether a Certificate Authority (CA) already exists

ca_name

name of the CA

cacert_path

absolute path to ca certificates root directory

CLI Example:

salt '*' tls.ca_exists test_ca /etc/certs

salt.modules.tls.cert_base_path(cacert_path=None)¶

Return the base path for certs from CLI or from options

CLI Example:

salt '*' tls.cert_base_path

salt.modules.tls.create_ca(ca_name, bits=2048, days=365, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='SaltStack', OU=None, emailAddress='xyz@pdq.net', fixmode=False, cacert_path=None, digest='sha256')¶

Create a Certificate Authority (CA)

ca_name

name of the CA

bits

number of RSA key bits, Default is 2048

days

number of days the CA will be valid, Default is 365

CN

common name in the request, Default is localhost

C

country, Default is US

ST

state, Default is Utah

L

locality, Default is Salt Lake City

O

organization, Default is SaltStack

OU

organizational unit, Default is None

emailAddress

email address for the CA owner, Default is xyz@pdq.net

cacert_path

absolute path to ca certificates root directory

digest

The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, "md5" or "sha1". Default: 'sha256'

Writes out a CA certificate based upon defined config values. If the file already exists, the function just returns assuming the CA certificate already exists.

If the following values were set:

ca.cert_base_path='/etc/pki'
ca_name='koji'

the resulting CA, and corresponding key, would be written in the following location:

/etc/pki/koji/koji_ca_cert.crt
/etc/pki/koji/koji_ca_cert.key

CLI Example:

salt '*' tls.create_ca test_ca

salt.modules.tls.create_ca_signed_cert(ca_name, CN, days=365, cacert_path=None, digest='sha256', **extensions)¶

Create a Certificate (CERT) signed by a named Certificate Authority (CA)

If the certificate file already exists, the function just returns assuming the CERT already exists.

The CN must match an existing CSR generated by create_csr. If it does not, this method does nothing.

ca_name

name of the CA

CN

common name matching the certificate signing request

days

number of days certificate is valid, Default is 365 (1 year)

cacert_path

absolute path to ca certificates root directory

digest

The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, "md5" or "sha1". Default: 'sha256'

**extensions

X509 V3 certificate extension

Writes out a Certificate (CERT). If the file already exists, the function just returns assuming the CERT already exists.

The CN must match an existing CSR generated by create_csr. If it does not, this method does nothing.

If the following values were set:

ca.cert_base_path='/etc/pki'
ca_name='koji'
CN='test.egavas.org'

the resulting signed certificate would be written in the following location:

/etc/pki/koji/certs/test.egavas.org.crt

CLI Example:

salt '*' tls.create_ca_signed_cert test localhost

salt.modules.tls.create_csr(ca_name, bits=2048, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='SaltStack', OU=None, emailAddress='xyz@pdq.net', subjectAltName=None, cacert_path=None, digest='sha256')¶

Create a Certificate Signing Request (CSR) for a particular Certificate Authority (CA)

ca_name

name of the CA

bits

number of RSA key bits, Default is 2048

CN

common name in the request, Default is localhost

C

country, Default is US

ST

state, Default is Utah

L

locality, Default is Salt Lake City

O

organization. Must the same as CA certificate or an error will be raised, Default is SaltStack

OU

organizational unit, Default is None

emailAddress

email address for the request, Default is xyz@pdq.net

subjectAltName

valid subjectAltNames in full form, e.g. to add DNS entry you would call this function with this value: ['DNS:myapp.foo.comm']

cacert_path

absolute path to ca certificates root directory

digest

The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, "md5" or "sha1". Default: 'sha256'

Writes out a Certificate Signing Request (CSR) If the file already exists, the function just returns assuming the CSR already exists.

If the following values were set:

ca.cert_base_path='/etc/pki'
ca_name='koji'
CN='test.egavas.org'

the resulting CSR, and corresponding key, would be written in the following location:

/etc/pki/koji/certs/test.egavas.org.csr
/etc/pki/koji/certs/test.egavas.org.key

CLI Example:

salt '*' tls.create_csr test

salt.modules.tls.create_pkcs12(ca_name, CN, passphrase='', cacert_path=None)¶

Create a PKCS#12 browser certificate for a particular Certificate (CN)

ca_name

name of the CA

CN

common name matching the certificate signing request

passphrase

used to unlock the PKCS#12 certificate when loaded into the browser

cacert_path

absolute path to ca certificates root directory

If the following values were set:

ca.cert_base_path='/etc/pki'
ca_name='koji'
CN='test.egavas.org'

the resulting signed certificate would be written in the following location:

/etc/pki/koji/certs/test.egavas.org.p12

CLI Example:

salt '*' tls.create_pkcs12 test localhost

salt.modules.tls.create_self_signed_cert(tls_dir='tls', bits=2048, days=365, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='SaltStack', OU=None, emailAddress='xyz@pdq.net', cacert_path=None, digest='sha256')¶

Create a Self-Signed Certificate (CERT)

tls_dir

location appended to the ca.cert_base_path, Default is tls

bits

number of RSA key bits, Default is 2048

days

validity of certificate, Default is 365

CN

common name in the request, Default is localhost

C

country, Default is US

ST

state, Default is Utah

L

locality, Default is Salt Lake City

O

organization. Must the same as CA certificate or an error will be raised, Default is SaltStack

OU

organizational unit, Default is None

emailAddress

email address for the request, Default is xyz@pdq.net

cacert_path

absolute path to ca certificates root directory

digest

The message digest algorithm. Must be a string describing a digest algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically). For example, "md5" or "sha1". Default: 'sha256'

Writes out a Self-Signed Certificate (CERT). If the file already exists, the function just returns.

If the following values were set:

ca.cert_base_path='/etc/pki'
tls_dir='koji'
CN='test.egavas.org'

the resulting CERT, and corresponding key, would be written in the following location:

/etc/pki/koji/certs/test.egavas.org.crt
/etc/pki/koji/certs/test.egavas.org.key

CLI Examples:

salt '*' tls.create_self_signed_cert
salt 'minion' tls.create_self_signed_cert CN='test.mysite.org'

salt.modules.tls.get_ca(ca_name, as_text=False, cacert_path=None)¶

Get the certificate path or content

ca_name

name of the CA

as_text

if true, return the certificate content instead of the path

cacert_path

absolute path to ca certificates root directory

CLI Example:

salt '*' tls.get_ca test_ca as_text=False cacert_path=/etc/certs

salt.modules.tls.maybe_fix_ssl_version(ca_name, cacert_path=None)¶

Check that the X509 version is correct (was incorrectly set in previous salt versions). This will fix the version if needed.

ca_name

ca authority name

cacert_path

absolute path to ca certificates root directory

CLI Example:

salt '*' tls.maybe_fix_ssl_version test_ca /etc/certs

salt.modules.tls.set_ca_path(cacert_path)¶

If wanted, store the aforementioned cacert_path in context to be used as the basepath for further operations

CLI Example:

salt '*' tls.set_ca_path /etc/certs