# salt.states.x509

Manage X509 Certificates

New in version 2015.8.0.

depends:

  M2Crypto

This module can enable managing a complete PKI infrastructure including creating private keys, CAs, 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

    /etc/salt/minion.d/x509.conf:
      file.managed:
        - source: salt://x509.conf

    restart-salt-minion:
      cmd.run:
        - name: 'salt-call service.restart salt-minion'
        - bg: True
        - onchanges:
          - file: /etc/salt/minion.d/x509.conf

    /etc/pki:
      file.directory

    /etc/pki/issued_certs:
      file.directory

    /etc/pki/ca.key:
      x509.private_key_managed:
        - bits: 4096
        - backup: True

    /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:
          - file: /etc/pki

The signing policy defines properties that override any property requested or included in a CRL. It also can define a restricted list of minions which are allowed to remotely invoke this signing policy.

/srv/salt/x509.conf

    mine_functions:
      x509.get_pem_entries: [/etc/pki/ca.crt]

    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.private_key_managed:
        - name: /etc/pki/www.key
        - bits: 4096
        - backup: True

    /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

This other state creates a private key then requests a certificate signed by ca according to the www policy but adds a strict date range for the certificate to be considered valid.

/srv/salt/www-time-limited.sls

    /etc/pki/www-time-limited.crt:
      x509.certificate_managed:
        - ca_server: ca
        - signing_policy: www
        - public_key: /etc/pki/www-time-limited.key
        - CN: www.example.com
        - not_before: 2019-05-05 00:00:00
        - not_after: 2020-05-05 14:30:00
        - backup: True

salt.states.x509.certificate_managed(name, days_remaining=90, append_certs=None, **kwargs)

  Manage a Certificate

  name

    Path to the certificate

  days_remaining90

    Recreate the certificate if the number of days remaining on it are less than this number. The value should be less than `days_valid`, otherwise the certificate will be recreated every time the state is run. A value of 0 disables automatic renewal.

  append_certs:

    A list of certificates to be appended to the managed file. They must be valid PEM files, otherwise an error will be thrown.

  kwargs:

    Any arguments supported by `x509.create_certificate` or `file.managed` are supported.

  not_before:

    Initial validity date for the certificate. This date must be specified in the format '%Y-%m-%d %H:%M:%S'.

    New in version 3001.

  not_after:

    Final validity date for the certificate. This date must be specified in the format '%Y-%m-%d %H:%M:%S'.

    New in version 3001.

  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

  name

    Path to the certificate

  signing_private_key

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

  signing_private_key_passphrase

    Passphrase to decrypt the private key.

  signing_cert

    The certificate of the authority that will be used to sign the 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_valid100

    The number of days the certificate should be valid for.

  digest

    The digest to use for signing the CRL. This has no effect on versions of pyOpenSSL less than 0.14.

  days_remaining30

    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.

  include_expiredFalse

    If `True`, include expired certificates in the CRL.

  kwargs

    Any arguments supported by `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

  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.

  kwargs:

    Any arguments supported by `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.

  name:

    The path to the file to manage

  text:

    The PEM formatted text to write.

  kwargs:

    Any arguments supported by `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.

  name:

    Path to the private key

  bits:

    Key length in bits. Default 2048.

  passphrase:

    Passphrase for encrypting the private key.

  cipher:

    Cipher for encrypting the private key.

  new:

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

  overwrite:

    Overwrite an existing private key if the provided passphrase cannot decrypt it.

  verbose:

    Provide visual feedback on stdout, dots while key is generated. Default is True.

    New in version 2016.11.0.

  kwargs:

    Any kwargs supported by file.managed are supported.

  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/www.key') -%}
          - prereq:
            - x509: /etc/pki/www.crt
          {%- endif %}