Skip to content
local-cert
Browse the documentation

ACME server

local-cert exposes an ACME endpoint (RFC 8555) at /acme/directory. Any tool that can request a certificate from Let's Encrypt can request it from local-cert instead, for hosts that Let's Encrypt could never reach.

This instance's directory
https://certs.example.com/acme/directory

What it is, and what it isn't

It is not a certificate authority. local-cert signs nothing: it acts as an intermediary between your ACME client and Let's Encrypt, and the certificate you receive is a real Let's Encrypt certificate, trusted everywhere.

The problem it solves: a regular ACME client proves it controls a name by answering on port 80 (HTTP-01), which requires Let's Encrypt to be able to reach the machine. On a LAN that is impossible. Proving control through DNS (DNS-01) works, but means handing DNS credentials to every machine. local-cert keeps those credentials to itself and does the DNS proof on the client's behalf.

How a certificate is issued

  1. Registration. The client creates its ACME account by presenting an EAB credential. This happens once; after that it signs with its own account key.
  2. Order. The client requests a certificate for one or more names. local-cert checks that they belong to a managed domain, and that the EAB credential is allowed on it. Otherwise the order is rejected immediately.
  3. Challenge. local-cert offers an HTTP-01 challenge, like an ordinary CA. The client prepares its response and signals that it is ready.
  4. Actual validation. local-cert never fetches the HTTP response. Instead, it opens an order with Let's Encrypt, writes the _acme-challenge TXT record in your zone, waits for it to propagate, has it validated, then deletes the record. The client's challenge turns valid when this is done.
  5. Finalization. The client sends its CSR. local-cert forwards it to Let's Encrypt and returns the certificate chain. The private key never left the client.

EAB credentials

EAB stands for External Account Binding. It is the mechanism ACME provides so that a CA only accepts clients it already knows: when creating its account, the client proves it holds a secret handed to it in advance. Here, it replaces the API key.

An EAB credential consists of two values, plus the server URL:

ValueWhere to find itIn this guide
ACME directoryfixed for each instancehttps://certs.example.com/acme/directory
Key ID (kid)Keys & access → EAB credentialseab_XXXXXXXXXXXXXXXX
HMAC keyshown only once, at creationCLE_HMAC

It is created in Keys & access → EAB credentials → + New credential, with:

  • a name, so you know which client it was handed to;
  • an optional expiry;
  • the allowed domains: the client can only request certificates under those.

Good to know

  • The HMAC key is displayed only once. If you lose it, you must create a new credential.
  • The client only uses it at registration, but local-cert re-reads the credential on every request: revoking it or letting it expire also cuts off clients that are already registered.
  • One credential can serve several clients. One credential per client lets you cut them off separately and see who issued what.
  • The key is base64url-encoded, the format all clients expect (hmacEncoded, --eab-hmac-key, mac_key…).

What the client must be able to do

Three things, which nearly all modern ACME clients support:

  1. use a custom directory URL;
  2. register with an External Account Binding;
  3. solve an HTTP-01 challenge.
ToolSupportGuide
Traefiknativeopen
Caddynativeopen
Apache httpdnative (mod_md)open
Nginxvia certbot or acme.shopen
HAProxyvia acme.shopen
Nginx Proxy Managermanual importopen
Kubernetesnative (cert-manager)open
Dokploynative (Traefik)open
Coolifynative (Traefik)open
Synology DSMvia acme.shopen
Proxmox VEnative (pvenode)open
certbot, acme.sh, legonativeopen

For everything else, see Other systems.

Rules and limits

  • A name outside the managed domains is rejected (rejectedIdentifier); so is a domain the credential isn't authorized for (unauthorized).
  • All names in a single order must belong to the same managed domain.
  • Wildcards (*.home.example.com) are accepted: since the actual validation is done with DNS-01, the usual HTTP-01 restriction doesn't apply. Some clients nevertheless refuse a wildcard over HTTP-01 on their own.
  • These certificates show up in Certificates with the external key type, with no private key and no automatic renewal: the client does the renewing.
  • An ACME account can revoke the certificates it obtained. Account key rollover (keyChange) is not implemented.

Troubleshooting

SymptomCause
JWS "url" is … but this endpoint is …local-cert is behind a proxy that doesn't forward X-Forwarded-Proto / X-Forwarded-Host. Forward them, or set the PUBLIC_URL variable.
externalAccountRequiredThe client is registering without EAB. Check its configuration.
unauthorized at registrationUnknown, revoked or expired credential, or wrong HMAC key.
rejectedIdentifierThe requested name is not under any managed domain.
The client gives up after ~1 minuteIts timeout is shorter than the DNS validation. Run it again: the order in progress is resumed.
TLS error when connecting to local-certlocal-cert is served with a certificate the client doesn't trust. Serve it with a public certificate, or add its CA to the client's trust store.