Skip to content

tls_self_signed_cert

A self-signed certificate for a key already on the host, such as one from tls_private_key, made with the host’s openssl and renewed before it expires.

Use tls_self_signed_cert for a certificate an internal service can start with, before or instead of a CA. Conn3x signs it on the host with the host’s openssl, for a key that’s already there, and makes a new one when it gets close to expiring.

A key and a certificate for a web server, valid for a year and renewed a month before it runs out:

step "web_key" {
tls_private_key {
path = "/etc/pki/tls/private/web.key"
}
}
step "web_cert" {
tls_self_signed_cert {
path = "/etc/pki/tls/certs/web.crt"
key_path = "/etc/pki/tls/private/web.key"
common_name = "web1.internal.example"
dns_names = ["web1.internal.example", "web.internal.example"]
}
}

A short-lived certificate for an address, renewed when a week is left:

step "metrics_cert" {
tls_self_signed_cert {
path = "/etc/metrics/tls.crt"
key_path = "/etc/metrics/tls.key"
common_name = "metrics"
ip_addresses = ["10.0.0.20"]
days = 30
renew_before_days = 7
}
}

cert_pem holds the certificate, so another resource can hand it to the clients that should trust it.

Name Type Required Description
common_name string Yes Subject common name, such as the host’s name.
days number No How long it’s valid, from 1 to 3650 days. Defaults to 365.
dns_names list of string No Host names in the subject alternative names. Clients check these, not the common name.
group string No Group. Unset keeps the file’s.
ip_addresses list of string No IP addresses in the subject alternative names.
key_path string Yes Absolute path of the private key it’s for.
mode string No Octal permissions. Defaults to “0644”.
on_remove string No “forget” (default) leaves the file, “delete” removes it.
owner string No Owner. Unset keeps the file’s.
path string Yes Absolute path of the certificate file.
renew_before_days number No Refresh plans a new certificate when fewer days than this are left. Defaults to 30.

Conn3x sets these; reference them as conn3x_tls_self_signed_cert.<circuit>__<step>["<host>"].<name>.

Name Type Description
cert_pem string The certificate, PEM-encoded, for clients to trust.
in_sync bool Whether the file holds a certificate for the key with these names and enough days left.
not_after string When it expires, in RFC 3339.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.

A step lowers to the conn3x_tls_self_signed_cert resource, one instance per host, and connects with its circuit’s ssh block.

Reading. On every plan, Conn3x reads the certificate and the public half of the key at key_path. in_sync is true when the certificate:

  • is signed by that key, for that key;
  • has the common_name, dns_names and ip_addresses asked for;
  • has more than renew_before_days left;
  • has the file mode, owner and group asked for.

When it gets within renew_before_days of expiring, the next plan shows an update, and the apply makes a new certificate, which also notifies any handlers.

Applying. Conn3x writes an openssl req config of its own, so the distribution’s defaults can’t make the certificate a CA. The certificate gets:

  • CA:FALSE;
  • the digitalSignature and keyEncipherment key uses;
  • the serverAuth and clientAuth extended uses;
  • your names as subject alternative names.

It’s written to a temporary file and moved into place. When the key changes, such as a tls_private_key step with a new type, the certificate was planned before it, so the next plan finds it’s for the old key and makes a new one. If only the mode, owner or group is wrong, the certificate is kept and only those change. The key must already exist, so put the tls_private_key step first.

The host needs openssl 1.1.1 or newer.

When you delete a tls_self_signed_cert step, on_remove decides what happens on the host. The default, "forget", leaves the certificate. "delete" removes the file.

This is community.crypto.x509_certificate with provider: selfsigned. conn3x convert ansible doesn’t translate it yet.