salt.modules.tls
A salt module for SSL/TLS. Can create a Certificate Authority (CA) or use Self-Signed certificates.
- 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'
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.example.com Created Private Key: "/etc/pki/my_little/certs/www.example.com.key Created CSR for "www.example.com": "/etc/pki/my_little/certs/www.example.com.csr" # salt-call tls.create_ca_signed_cert my_little CN=www.example.com Created Certificate for "www.example.com": /etc/pki/my_little/certs/www.example.com.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
-
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.ca_exists(ca_name, cacert_path=None, ca_filename=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_base_path(cacert_path=None)
-
Return information for a particular certificate
- cert
-
path to the certifiate PEM file or string
Changed in version 2018.3.4.
- digest
-
what digest to use for fingerprinting
CLI Example:
salt '*' tls.cert_info /dir/for/certs/cert.pem
salt.modules.tls.cert_info(cert, 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 "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 None
- 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 with appropriate permissions:
/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(ca_name, bits=2048, days=365, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='SaltStack', OU=None, emailAddress=None, fixmode=False, cacert_path=None, ca_filename=None, digest='sha256', onlyif=None, unless=None, 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, settingtype_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_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 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 None
- 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:[email protected]']
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 2015.8.0.
- 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 with appropriate permissions:
/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_csr(ca_name, bits=2048, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='SaltStack', OU=None, emailAddress=None, 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 an empty Certificate Revocation List.
New in version 2015.8.0.
- 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
- 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'
CLI Example:
salt '*' tls.create_empty_crl ca_name='koji' ca_filename='ca' crl_file='/etc/openvpn/team1/crl.pem'
salt.modules.tls.create_empty_crl(ca_name, cacert_path=None, ca_filename=None, crl_file=None, digest='sha256')
-
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_pkcs12(ca_name, CN, passphrase='', cacert_path=None, 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 None
- 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 with appropriate permissions:
/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.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=None, cacert_path=None, cert_filename=None, digest='sha256', replace=False)
-
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(ca_name, as_text=False, cacert_path=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_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
- 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_ca_signed_key(ca_name, CN='localhost', as_text=False, cacert_path=None, key_filename=None)
-
New in version 2019.2.0.
Get a certificate's expiration date
- cert
-
Full path to the certificate
- date_format
-
By default this will return the expiration date in YYYY-MM-DD format, use this to specify a different strftime format string. Note that the expiration time will be in UTC.
CLI Examples:
salt '*' tls.get_expiration_date /path/to/foo.crt salt '*' tls.get_expiration_date /path/to/foo.crt date_format='%d/%m/%Y'
salt.modules.tls.get_expiration_date(cert, date_format='%Y-%m-%d')
-
Fetch X509 and CSR extension definitions from tls:extensions: (common|server|client) or set them to standard defaults.
New in version 2015.8.0.
- cert_type:
-
The type of certificate such as
server
orclient
.
CLI Example:
salt '*' tls.get_extensions client
salt.modules.tls.get_extensions(cert_type)
-
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.maybe_fix_ssl_version(ca_name, cacert_path=None, ca_filename=None)
-
Revoke a certificate.
New in version 2015.8.0.
- 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.
- 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'
CLI Example:
salt '*' tls.revoke_cert ca_name='koji' ca_filename='ca' crl_file='/etc/openvpn/team1/crl.pem'
salt.modules.tls.revoke_cert(ca_name, CN, cacert_path=None, ca_filename=None, cert_path=None, cert_filename=None, crl_file=None, digest='sha256')
-
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
salt.modules.tls.set_ca_path(cacert_path)
-
New in version 3000.
Validate a certificate against a given CA/CRL.
- cert
-
path to the certifiate PEM file or string
- ca_name
-
name of the CA
- crl_file
-
full path to the CRL file
salt.modules.tls.validate(cert, ca_name, crl_file)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.tls.html