salt.states.x509¶

Manage X509 Certificates

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.key:
  x509.private_key_managed:
    - bits: 4096
    - backup: True
    - require:
      - file: /etc/pki

/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
    - require:
      - x509: /etc/pki/ca.key

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 cRLSign, keyCertSign"
    - 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.key:
  x509.private_key_managed:
    - bits: 4096

/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

salt.states.x509.certificate_managed(name, days_remaining=90, backup=False, **kwargs)¶

Manage a Certificate

name:

Path to the certificate

days_remaining:

The minimum number of days remaining when the certificate should be recreated. Default is 90. A value of 0 disables automatic renewal.

backup:

When replacing an existing file, backup the old file on the minion. Default is False.

kwargs:

Any arguments supported by x509.create_certificate 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_cert=None, revoked=None, days_valid=100, days_remaining=30, include_expired=False, backup=False)¶

Manage a Certificate Revocation List

name:

Path to the certificate

signing_private_key:

The private key that will be used to sign this crl. This is usually your CA's private key.

signing_cert:

The certificate of the authority that will be used to sign this crl. This is usually your CA's certificate.

revoked:

A list of certificates to revoke. Must include either a serial number or a the certificate itself. Can optionally include the revocation date and notAfter date from the certificate. See example below for details.

days_valid:

The number of days the certificate should be valid for. Default is 100.

days_remaining:

The crl should be automatically recreated if there are less than days_remaining days until the crl expires. Set to 0 to disable automatic renewal. Default is 30.

include_expired:

Include expired certificates in the CRL. Default is False.

backup:

When replacing an existing file, backup the old file onthe minion. Default is False.

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, backup=False, **kwargs)¶

Manage a Certificate Signing Request

name:

Path to the CSR

properties:

The properties to be added to the certificate request, including items like subject, extensions and public key. See above for valid properties.

Example:

/etc/pki/mycert.csr:
  x509.csr_managed:
     - public_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)¶

Manage the contents of a PEM file directly with the content in text, ensuring correct formatting.

name:

The path to the file to manage

text:

The PEM formatted text to write.

backup:

When replacing an existing file, backup the old file on the minion. Default is False.

salt.states.x509.private_key_managed(name, bits=2048, new=False, backup=False)¶

Manage a private key's existence.

name:

Path to the private key

bits:

Key length in bits. Default 2048.

new:

Always create a new key. Defaults to False. Combining new with prereq can allow key rotation whenever a new certificiate is generated.

backup:

When replacing an existing file, backup the old file onthe minion. Default is False.

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 %}