Manage X509 Certificates
New in version 2015.8.0.
depends: | M2Crypto |
---|
This module can enable managing a complete PKI infrastructure including creating private keys, CA's, certificates and CRLs. It includes the ability to generate a private key on a server, and have the corresponding public key sent to a remote CA to create a CA signed certificate. This can be done in a secure manner, where private keys are always generated locally and never moved across the network.
Here is a simple example scenario. In this example ca
is the ca server,
and www
is a web server that needs a certificate signed by ca
.
For remote signing, peers must be permitted to remotely call the
sign_remote_certificate
function.
/etc/salt/master.d/peer.conf
peer:
.*:
- x509.sign_remote_certificate
/srv/salt/top.sls
base:
'*':
- cert
'ca':
- ca
'www':
- www
This state creates the CA key, certificate and signing policy. It also publishes the certificate to the mine where it can be easily retrieved by other minions.
/srv/salt/ca.sls
salt-minion:
service.running:
- enable: True
- listen:
- file: /etc/salt/minion.d/signing_policies.conf
/etc/salt/minion.d/signing_policies.conf:
file.managed:
- source: salt://signing_policies.conf
/etc/pki:
file.directory
/etc/pki/issued_certs:
file.directory
/etc/pki/ca.crt:
x509.certificate_managed:
- signing_private_key: /etc/pki/ca.key
- CN: ca.example.com
- C: US
- ST: Utah
- L: Salt Lake City
- basicConstraints: "critical CA:true"
- keyUsage: "critical cRLSign, keyCertSign"
- subjectKeyIdentifier: hash
- authorityKeyIdentifier: keyid,issuer:always
- days_valid: 3650
- days_remaining: 0
- backup: True
- managed_private_key:
name: /etc/pki/ca.key
bits: 4096
backup: True
- require:
- file: /etc/pki
mine.send:
module.run:
- func: x509.get_pem_entries
- kwargs:
glob_path: /etc/pki/ca.crt
- onchanges:
- x509: /etc/pki/ca.crt
The signing policy defines properties that override any property requested or included in a CRL. It also can define a restricted list of minons which are allowed to remotely invoke this signing policy.
/srv/salt/signing_policies.conf
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 keyEncipherment"
- subjectKeyIdentifier: hash
- authorityKeyIdentifier: keyid,issuer:always
- days_valid: 90
- copypath: /etc/pki/issued_certs/
This state will instruct all minions to trust certificates signed by our new CA.
Using jinja to strip newlines from the text avoids dealing with newlines in the rendered yaml,
and the sign_remote_certificate
state will
handle properly formatting the text before writing the output.
/srv/salt/cert.sls
/usr/local/share/ca-certificates:
file.directory
/usr/local/share/ca-certificates/intca.crt:
x509.pem_managed:
- text: {{ salt['mine.get']('ca', 'x509.get_pem_entries')['ca']['/etc/pki/ca.crt']|replace('\n', '') }}
This state creates a private key then requests a certificate signed by ca according to the www policy.
/srv/salt/www.sls
/etc/pki/www.crt:
x509.certificate_managed:
- ca_server: ca
- signing_policy: www
- public_key: /etc/pki/www.key
- CN: www.example.com
- days_remaining: 30
- backup: True
- managed_private_key:
name: /etc/pki/www.key
bits: 4096
backup: True
salt.states.x509.
certificate_managed
(name, days_remaining=90, managed_private_key=None, append_certs=None, **kwargs)¶Manage a Certificate
x509.private_key_managed
are supported. If name is not
speicified or is the same as the name of the certificate, the private
key and certificate will be written together in the same file.x509.create_certificate
or file.managed
are supported.Examples:
/etc/pki/ca.crt:
x509.certificate_managed:
- signing_private_key: /etc/pki/ca.key
- CN: ca.example.com
- C: US
- ST: Utah
- L: Salt Lake City
- basicConstraints: "critical CA:true"
- keyUsage: "critical cRLSign, keyCertSign"
- subjectKeyIdentifier: hash
- authorityKeyIdentifier: keyid,issuer:always
- days_valid: 3650
- days_remaining: 0
- backup: True
/etc/ssl/www.crt:
x509.certificate_managed:
- ca_server: pki
- signing_policy: www
- public_key: /etc/ssl/www.key
- CN: www.example.com
- days_valid: 90
- days_remaining: 30
- backup: True
salt.states.x509.
crl_managed
(name, signing_private_key, signing_private_key_passphrase=None, signing_cert=None, revoked=None, days_valid=100, digest='', days_remaining=30, include_expired=False, **kwargs)¶Manage a Certificate Revocation List
days_remaining
days until the crl expires. Set to 0 to disable
automatic renewal.True
, include expired certificates in the CRL.file.managed
are supported.Example:
/etc/pki/ca.crl:
x509.crl_managed:
- signing_private_key: /etc/pki/myca.key
- signing_cert: /etc/pki/myca.crt
- revoked:
- compromized_Web_key:
- certificate: /etc/pki/certs/badweb.crt
- revocation_date: 2015-03-01 00:00:00
- reason: keyCompromise
- terminated_vpn_user:
- serial_number: D6:D2:DC:D8:4D:5C:C0:F4
- not_after: 2016-01-01 00:00:00
- revocation_date: 2015-02-25 00:00:00
- reason: cessationOfOperation
salt.states.x509.
csr_managed
(name, **kwargs)¶Manage a Certificate Signing Request
file.managed
are supported.Example:
/etc/pki/mycert.csr:
x509.csr_managed:
- private_key: /etc/pki/mycert.key
- CN: www.example.com
- C: US
- ST: Utah
- L: Salt Lake City
- keyUsage: 'critical dataEncipherment'
salt.states.x509.
pem_managed
(name, text, backup=False, **kwargs)¶Manage the contents of a PEM file directly with the content in text, ensuring correct formatting.
file.managed
are supported.salt.states.x509.
private_key_managed
(name, bits=2048, passphrase=None, cipher='aes_128_cbc', new=False, overwrite=False, verbose=True, **kwargs)¶Manage a private key's existence.
prereq
, or when used as part of a managed_private_key can allow key rotation whenever a new certificiate is generated.Provide visual feedback on stdout, dots while key is generated. Default is True.
New in version 2016.11.0.
Example:
The jinja templating in this example ensures a private key is generated if the file doesn't exist and that a new private key is generated whenever the certificate that uses it is to be renewed.
/etc/pki/www.key:
x509.private_key_managed:
- bits: 4096
- new: True
{% if salt['file.file_exists']('/etc/pki/ca.key') -%}
- prereq:
- x509: /etc/pki/www.crt
{%- endif %}