x509 – Keystone Core

x509

Manages a TLS certificate and its private key on disk (the declaration name is the certificate path) using crypto/x509 — no shelling out. Idempotent: a key and certificate that already match the declaration (right subject, validity, and signer) report no change; anything stale or expiring is regenerated.

Category: Certificates

States

State	Meaning
`present`	A private key and a matching certificate exist, the certificate is currently valid with at least `renew_days` left, and it is self-signed or signed by the declared `ca_cert`. Stale or expiring material is regenerated.
`absent`	The certificate file and the key file are removed.

Parameters

Parameter	Type	Required	Description
`key_path`	string	yes	Private-key path; must differ from the certificate path (combined cert+key PEM is not supported).
`common_name`	string		Subject common name (CN). For state `present`, one of `common_name` or `subject_alt_names` is required.
`subject_alt_names`	list		Subject alternative names; a single string or a list of strings. IP vs DNS is auto-detected. One of `common_name` or `subject_alt_names` is required for `present`.
`organization`	string		Subject organization (O).
`days`	int		Validity window in days for a newly generated certificate. Default: `365`.
`renew_days`	int		Regenerate when fewer than this many days of validity remain; 0 disables expiry-proximity renewal. Default: `30`.
`key_type`	string		Private-key algorithm: `rsa`, `ecdsa`, or `ed25519`. Default: `rsa`.
`rsa_bits`	int		RSA key size (minimum 2048); applies when `key_type` is `rsa`. Default: `2048`.
`ecdsa_curve`	string		ECDSA curve: `p256`, `p384`, or `p521`; applies when `key_type` is `ecdsa`. Default: `p256`.
`is_ca`	bool		Mark the certificate as a CA (sets the basic-constraints CA flag). Default: `false`.
`ca_cert`	string		Signing CA certificate path; set together with `ca_key`. Omit both for a self-signed certificate.
`ca_key`	string		Signing CA private-key path; set together with `ca_cert`.

Examples

Self-signed leaf certificate

x509:
  /etc/ssl/myapp/server.crt:
    state: present
    key_path: /etc/ssl/myapp/server.key
    common_name: host.example.com
    subject_alt_names:
      - host.example.com
      - 10.1.2.3
    organization: Keystone
    days: 365
    renew_days: 30

A CA, then a leaf signed by it

The require requisite orders the leaf after its signing CA.

x509:
  /etc/pki/ca.crt:
    state: present
    key_path: /etc/pki/ca.key
    common_name: Keystone Root CA
    is_ca: true
    key_type: ecdsa
    ecdsa_curve: p384
  /etc/pki/server.crt:
    state: present
    key_path: /etc/pki/server.key
    common_name: host.example.com
    ca_cert: /etc/pki/ca.crt
    ca_key: /etc/pki/ca.key
    require:
      - x509: /etc/pki/ca.crt

Remove a certificate and its key

x509:
  /etc/ssl/old/server.crt:
    state: absent
    key_path: /etc/ssl/old/server.key

Notes

OS-agnostic: certificate and key material is generated in-process with crypto/x509 — no openssl binary required.
ca_cert and ca_key must be set together; omit both for a self-signed certificate.
days only affects newly generated certificates; on regeneration a still-valid key is reused.
New keys are written 0600 and new certificates 0644; rewrites preserve the existing mode.
Out of scope (v0.x candidates, #110): combined cert+key PEM in one file, encrypted (passphrase-protected) keys, OpenSSL-style SAN prefixes and email/URI SANs, additional Subject fields, explicit mode/owner params, and CRL/OCSP/PKCS#12/ACME issuance.

langpkg