Module local 

A certificate authority for a zone no public authority can issue for.

A server always serves TLS, including on a developer’s machine. A .localhost zone has no public DNS, so ACME cannot complete a challenge for it; this module is where its certificate comes from instead.

The authority lives in a directory of its own, one per machine rather than one per server: a developer trusts its certificate once, and every local server on that machine then presents leaves it signed. It signs a <zone> + *.<zone> leaf for each configured zone, cached in the data directory when there is one and signed afresh at every start when there is not.

What makes this safe to put in a trust store

A developer installs this certificate into their own trust store, so it can vouch for names on their machine the way a public authority vouches for names on the internet. Two things bound what it can vouch for:

• The certificate carries a name constraint permitting localhost and everything under it, and nothing else. A verifier that honours name constraints — rustls, and the browsers — refuses a leaf from this authority for any other name, so a key that leaks cannot be used to impersonate a real site.
• crate::source refuses this mode for any zone that is not under .localhost, so the authority is never asked to issue outside that constraint in the first place.

The key still belongs to whoever can read the data directory, which is why it is written 0600 and why the directory is 0700.

Structs

LocalAuthority

This machine’s own certificate authority, loaded from the data directory or generated into it.

LocalFleet

Every zone served from LocalAuthority, behind the one SNI-dispatching resolver a multi-zone deployment uses for ACME certificates.

Enums

LocalError

Why a local certificate could not be generated, loaded or served.

Constants

CA_COMMON_NAME

The subject of the authority’s own certificate, and what a developer sees in their trust store’s list.

CA_VALIDITY

How long the authority’s own certificate is good for.

CLOCK_SKEW 🔒

Backdating on both the authority and the leaves, so a machine whose clock is a little behind the one that signed still accepts them.

LEAF_REISSUE_BEFORE

How close to a leaf’s expiry a start signs a fresh one rather than serving what is on disk. There is no renewal loop here: signing costs a few milliseconds and needs nothing off this machine, so a start does it whenever the answer is in doubt.

LEAF_VALIDITY

How long a zone’s leaf is good for. Under the 398 days browsers accept, and short enough that a leaf outlives neither the machine it was minted on nor anyone’s memory of minting it.

LOCAL_SOURCE

What CertMeta::directory_url records for a leaf this module signed, where an ACME leaf records the directory that issued it. No ACME directory URL can collide with it: they are absolute https:// URLs.

PERMITTED_SUBTREE 🔒

The one name this authority may vouch for, plus everything under it. Written into the certificate as an RFC 5280 name constraint, so a verifier enforces it rather than taking this module’s word for it.

Functions

ca_params 🔒

The authority certificate’s parameters, fixed so that a later start rebuilds the same issuer from the saved key alone.