A salt module for SSL/TLS. Can create a Certificate Authority (CA) or use Self-Signed certificates.
depends: |
|
---|---|
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 emailAddress=pleasedontemail@thisisnot.coms
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
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.
cert_info
(cert_path, digest='sha256')¶Return information for a particular certificate
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)
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.
cert_type
.
type_ext
will be completely overridden.Replace this certificate even if it exists
New in version 2015.5.1.
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()
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)
valid subjectAltNames in full form, e.g. to add DNS entry you would call this function with this value:
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.
Specify the general certificate type. Can be either server or client. Indicates the set of common extensions added to the CSR.
}
}
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 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.
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)
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)
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
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
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
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.
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.
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.
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