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.
Example usage
Section titled “Example usage”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.
Arguments
Section titled “Arguments”| 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. |
Read-only attributes
Section titled “Read-only attributes”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.
How it works
Section titled “How it works”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_namesandip_addressesasked for; - has more than
renew_before_daysleft; - 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
digitalSignatureandkeyEnciphermentkey uses; - the
serverAuthandclientAuthextended 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.
Removal
Section titled “Removal”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.
From Ansible
Section titled “From Ansible”This is community.crypto.x509_certificate with provider: selfsigned. conn3x convert ansible doesn’t translate it yet.