Skip to content

Key reuse and pinning

By default, every renewal generates a fresh private key on the endpoint. That is the right default: keys age like certificates do, and rotating both together costs nothing extra. But some endpoints must keep their key across renewals, and for them a renewal profile offers Reuse private key across renewals (for pins/DANE) — "keep private key" for short.

Why an endpoint would pin its key

  • Published pins. HPKP headers, DANE/TLSA records, mobile apps or embedded clients that ship with the endpoint's public key baked in — rotate the key and every pinned client breaks until its pin updates.
  • External CSR workflows. A paid CA account that expects renewals against the same key (the CSR on file), or hardware that holds the key somewhere regeneration can't reach.
  • Change-control boundaries. A key that was ceremonially generated and approved once, where a silent rotation would violate the paperwork even if nothing technical broke.

With the option enabled, the renewal produces a new certificate over the same public key — the certificate changes, its validity window changes, the key does not. You can prove it yourself: the key's modulus digest before and after the renewal is identical (openssl rsa -noout -modulus | openssl sha256).

How the key gets under management: Adopt key

The reused key is loaded from exactly one place: the Scout's managed delivery directory for that domain. An endpoint that has been serving for years keeps its key wherever the web server was configured — /etc/nginx/ssl/, a home directory, a certbot layout. Before the first key-reuse renewal, that key must be brought under management, and that is the one-time Adopt key action:

  1. When you renew a key-reuse profile whose key is not yet managed, the renewal refuses before any order is created and names the key file it found serving the endpoint. This refusal is a feature: the alternative would be silently generating a fresh key on a profile whose whole point was not to.
  2. The endpoint drawer then offers Adopt key. The Scout copies the served private key into its managed directory (owner-only permissions), after verifying it actually matches the certificate the endpoint serves. The key is copied on the endpoint, by the endpoint's own Scout — it never crosses the network and the Hub never sees it.
  3. Renew again: the pre-flight now finds the managed key, checks its type and size against the profile (an rsa_2048 profile reuses only a 2048-bit RSA key), and the order proceeds with a CSR signed by the adopted key.

What happens to the old file paths

After a key-reuse renewal, delivery works entirely in the managed directory — and any external certificate path the endpoint serves from is re-pointed as a symlink into the managed files. The web server's configuration keeps naming the path it always named; the path now follows every future renewal automatically. The original files are quarantined, not destroyed, and the whole replacement is transactional — a failure mid-way restores the original pair rather than leaving a mismatched cert/key on disk.

For the Scout to be allowed to touch those external paths at all, the directory must be one it is configured to watch — path containment is fail-closed, and a directory the operator never listed is a directory the Scout will refuse to write. See Scout → Certificate discovery for how directories are configured and Scout → Commands → Safety mechanisms for the containment rules.

The key-type rule on Hub-driven lanes

On the Hub-driven DNS-01 lanes and the internal CA, the Scout never generates a fresh RSA key — fresh keys on those lanes are always ECDSA. An RSA-typed profile is therefore meaningful there only with key reuse enabled: the RSA type nominates the existing key (matching its modulus size) rather than requesting RSA generation. If you need a brand-new RSA key on those lanes, that is not currently a supported combination — adopt the existing RSA key, or accept ECDSA for fresh generation. (Scout-local HTTP-01 is the exception: it generates whatever key type the profile names, RSA included.)

The full walkthrough of adopting a key, with expected outputs at each step, is How-to → Adopt a private key.