salt.modules.tls¶

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

depends:

depends:	PyOpenSSL Python module (0.10 or later, 0.14 or later for X509 extension support)
configuration:	Add the following values in /etc/salt/minion for the CA module to function properly: ca.cert_base_path: '/etc/pki'

PyOpenSSL Python module (0.10 or later, 0.14 or later for

X509 extension support)

configuration:

Add the following values in /etc/salt/minion for the CA module to function properly:

ca.cert_base_path: '/etc/pki'

CLI Example #1 Creating a CA, a server request and its signed certificate:

# salt-call tls.create_ca my_little     days=5     CN='My Little CA'     C=US     ST=Utah     L=Salt Lake City     O=Saltstack     [email protected]

Created Private Key: "/etc/pki/my_little/my_little_ca_cert.key"
Created CA "my_little_ca": "/etc/pki/my_little_ca/my_little_ca_cert.crt"

# salt-call tls.create_csr my_little CN=www.thisisnot.coms
Created Private Key: "/etc/pki/my_little/certs/www.thisisnot.coms.key
Created CSR for "www.thisisnot.coms": "/etc/pki/my_little/certs/www.thisisnot.coms.csr"

# salt-call tls.create_ca_signed_cert my_little CN=www.thisisnot.coms
Created Certificate for "www.thisisnot.coms": /etc/pki/my_little/certs/www.thisisnot.coms.crt"

CLI Example #2: Creating a client request and its signed certificate

# salt-call tls.create_csr my_little CN=DBReplica_No.1 cert_type=client
Created Private Key: "/etc/pki/my_little/certs//DBReplica_No.1.key."
Created CSR for "DBReplica_No.1": "/etc/pki/my_little/certs/DBReplica_No.1.csr."

# salt-call tls.create_ca_signed_cert my_little CN=DBReplica_No.1
Created Certificate for "DBReplica_No.1": "/etc/pki/my_little/certs/DBReplica_No.1.crt"

CLI Example #3: Creating both a server and client req + cert for the same CN

# salt-call tls.create_csr my_little CN=MasterDBReplica_No.2          cert_type=client
Created Private Key: "/etc/pki/my_little/certs/MasterDBReplica_No.2.key."
Created CSR for "DBReplica_No.1": "/etc/pki/my_little/certs/MasterDBReplica_No.2.csr."

# salt-call tls.create_ca_signed_cert my_little CN=MasterDBReplica_No.2
Created Certificate for "DBReplica_No.1": "/etc/pki/my_little/certs/DBReplica_No.1.crt"

# salt-call tls.create_csr my_little CN=MasterDBReplica_No.2         cert_type=server
Certificate "MasterDBReplica_No.2" already exists

(doh!)

# salt-call tls.create_csr my_little CN=MasterDBReplica_No.2         cert_type=server type_ext=True
Created Private Key: "/etc/pki/my_little/certs/DBReplica_No.1_client.key."
Created CSR for "DBReplica_No.1": "/etc/pki/my_little/certs/DBReplica_No.1_client.csr."

# salt-call tls.create_ca_signed_cert my_little CN=MasterDBReplica_No.2
Certificate "MasterDBReplica_No.2" already exists

(DOH!)

# salt-call tls.create_ca_signed_cert my_little CN=MasterDBReplica_No.2         cert_type=server type_ext=True
Created Certificate for "MasterDBReplica_No.2": "/etc/pki/my_little/certs/MasterDBReplica_No.2_server.crt"

CLI Example #4: Create a server req + cert with non-CN filename for the cert

# salt-call tls.create_csr my_little CN=www.anothersometh.ing         cert_type=server type_ext=True
Created Private Key: "/etc/pki/my_little/certs/www.anothersometh.ing_server.key."
Created CSR for "DBReplica_No.1": "/etc/pki/my_little/certs/www.anothersometh.ing_server.csr."

# salt-call tls_create_ca_signed_cert my_little CN=www.anothersometh.ing         cert_type=server cert_filename="something_completely_different"
Created Certificate for "www.anothersometh.ing": /etc/pki/my_little/certs/something_completely_different.crt

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

Verify whether a Certificate Authority (CA) already exists

ca_name: name of the CA
cacert_path: absolute path to ca certificates root directory
ca_filename: alternative filename for the CA

New in version 2015.5.3.

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

cacert_path: absolute path to ca certificates root directory

CLI Example:

salt '*' tls.cert_base_path

salt.modules.tls.cert_info(cert_path, digest='sha256')¶

Return information for a particular certificate

cert_path: path to the cert file
digest: what digest to use for fingerprinting

CLI Example:

salt '*' tls.cert_info /dir/for/certs/cert.pem

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, ca_filename=None, digest='sha256', onlyif=None, unless=None, replace=False)¶

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 "Centerville", the city where SaltStack originated
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
ca_filename: alternative filename for the CA

New in version 2015.5.3.
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'
replace: Replace this certificate even if it exists

New in version 2015.5.1.

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, ca_filename=None, cert_path=None, cert_filename=None, digest='sha256', cert_type=None, type_ext=False, replace=False)¶

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

ca_filename

alternative filename for the CA

New in version 2015.5.3.

cert_path

full path to the certificates directory

cert_filename

alternative filename for the certificate, useful when using special characters in the CN. If this option is set it will override the certificate filename output effects of cert_type. type_ext will be completely overridden.

New in version 2015.5.3.

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'

replace

Replace this certificate even if it exists

New in version 2015.5.1.

cert_type

string. Either 'server' or 'client' (see create_csr() for details).

If create_csr(type_ext=True) this function must be called with the same cert_type so it can find the CSR file.

Note

create_csr() defaults to cert_type='server'; therefore, if it was also called with type_ext, cert_type becomes a required argument for create_ca_signed_cert()

type_ext

bool. If set True, use cert_type as an extension to the CN when formatting the filename.

e.g.: some_subject_CN_server.crt or some_subject_CN_client.crt

This facilitates the context where both types are required for the same subject

If cert_filename is not None, setting type_ext has no effect

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, ca_filename=None, csr_path=None, csr_filename=None, digest='sha256', type_ext=False, cert_type='server', replace=False)¶

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 "Centerville", the city where SaltStack originated

O

organization, default is "SaltStack" NOTE: Must the same as CA certificate or an error will be raised

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:

examples: ['DNS:somednsname.com',: 'DNS:1.2.3.4', 'IP:1.2.3.4', 'IP:2001:4801:7821:77:be76:4eff:fe11:e51', 'email:me@i.like.pie.com']

Note

some libraries do not properly query IP: prefixes, instead looking for the given req. source with a DNS: prefix. To be thorough, you may want to include both DNS: and IP: entries if you are using subjectAltNames for destinations for your TLS connections.

e.g.:

requests to https://1.2.3.4 will fail from python's requests library w/out the second entry in the above list

New in version Beryllium.

cert_type

Specify the general certificate type. Can be either server or client. Indicates the set of common extensions added to the CSR.

server: {: 'basicConstraints': 'CA:FALSE', 'extendedKeyUsage': 'serverAuth', 'keyUsage': 'digitalSignature, keyEncipherment'

}

client: {: 'basicConstraints': 'CA:FALSE', 'extendedKeyUsage': 'clientAuth', 'keyUsage': 'nonRepudiation, digitalSignature, keyEncipherment'

}

type_ext

boolean. Whether or not to extend the filename with CN_[cert_type] This can be useful if a server and client certificate are needed for the same CN. Defaults to False to avoid introducing an unexpected file naming pattern

The files normally named some_subject_CN.csr and some_subject_CN.key will then be saved

replace

Replace this signing request even if it exists

New in version 2015.5.1.

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_empty_crl(ca_name, cacert_path=None, ca_filename=None, crl_file=None)¶

Create an empty Certificate Revocation List.

New in version Beryllium.

ca_name: name of the CA
cacert_path: absolute path to ca certificates root directory
ca_filename: alternative filename for the CA

New in version 2015.5.3.
crl_file: full path to the CRL file

CLI Example:

salt '*' tls.create_empty_crl ca_name='koji'                 ca_filename='ca'                 crl_file='/etc/openvpn/team1/crl.pem'

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

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
replace: Replace this certificate even if it exists

New in version 2015.5.1.

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, cert_filename=None, digest='sha256', replace=False)¶

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
CN: common name in the request, default is "localhost"
C: country, default is "US"
ST: state, default is "Utah"
L: locality, default is "Centerville", the city where SaltStack originated
O: organization, default is "SaltStack" NOTE: Must the same as CA certificate or an error will be raised
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'
replace: Replace this certificate even if it exists

New in version 2015.5.1.

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 Example:

salt '*' tls.create_self_signed_cert

Passing options from the command line:

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.get_ca_signed_cert(ca_name, CN='localhost', as_text=False, cacert_path=None, cert_filename=None)¶

Get the certificate path or content

ca_name: name of the CA
CN: common name of the certificate
as_text: if true, return the certificate content instead of the path
cacert_path: absolute path to certificates root directory
cert_filename: alternative filename for the certificate, useful when using special characters in the CN

New in version 2015.5.3.

CLI Example:

salt '*' tls.get_ca_signed_cert test_ca CN=localhost as_text=False cacert_path=/etc/certs

salt.modules.tls.get_ca_signed_key(ca_name, CN='localhost', as_text=False, cacert_path=None, key_filename=None)¶

Get the certificate path or content

ca_name

name of the CA

CN

common name of the certificate

as_text

if true, return the certificate content instead of the path

cacert_path

absolute path to certificates root directory

key_filename

alternative filename for the key, useful when using special characters

New in version 2015.5.3.

in the CN

CLI Example:

salt '*' tls.get_ca_signed_key                 test_ca CN=localhost                 as_text=False                 cacert_path=/etc/certs

salt.modules.tls.get_extensions(cert_type)¶

Fetch X509 and CSR extension definitions from tls:extensions: (common|server|client) or set them to standard defaults.

New in version Beryllium.

cert_type:: The type of certificate such as server or client.

CLI Example:

salt '*' tls.get_extensions client

salt.modules.tls.maybe_fix_ssl_version(ca_name, cacert_path=None, ca_filename=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
ca_filename: alternative filename for the CA

New in version 2015.5.3.

CLI Example:

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

salt.modules.tls.revoke_cert(ca_name, CN, cacert_path=None, ca_filename=None, cert_path=None, cert_filename=None, crl_file=None)¶

Revoke a certificate.

New in version Beryllium.

ca_name: Name of the CA.
CN: Common name matching the certificate signing request.
cacert_path: Absolute path to ca certificates root directory.
ca_filename: Alternative filename for the CA.
cert_path: Path to the cert file.
cert_filename: Alternative filename for the certificate, useful when using special characters in the CN.
crl_file: Full path to the CRL file.

CLI Example:

salt '*' tls.revoke_cert ca_name='koji'                 ca_filename='ca'                 crl_file='/etc/openvpn/team1/crl.pem'

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

You are viewing docs for the previous stable release, 2015.5.11. Switch to docs for the latest stable release, 2016.3.2, or to a recent doc build from the develop branch.

saltstack.com