Contract: the certificate a program serves beyond its machine

Status: Accepted

How a program lemonfiber builds comes by the certificate it serves to clients on other machines, keeps it current, and keeps its keys. One page, so that every such program, the MCP server’s HTTP mode first and the core’s remote access after it, offers the same four ways, reads the same settings, keeps the same state and fails the same way, while each implements it in its own language.

Satisfies: F13-R8, F13-R12, F13-R13

---

Why this is written down

Who can check a certificate decides which certificate is any use. A client lemonfiber wrote holds the pin of the certificate the stack made itself (ADR-0018, ADR-0025). A desktop client can be told to trust a root the operator installed. An assistant on a phone or in a browser can be told nothing: its provider’s servers make the connection, and they accept a chain to a publicly trusted authority and nothing else.

So there is no one right way, and there must always be a way that depends on no company outside the operator’s house. Four are offered, each said plainly to be checkable by whom. Getting a publicly trusted certificate is a protocol, ACME (RFC 8555), and keeping any certificate is a schedule; two programs that each invented their settings, their state and their renewal would be two things to learn and two ways to fail. So all of it is written here once. The code is not shared: the core is Rust and the MCP server Python, and a library crossing the two would be a third program to keep. What is shared is everything an operator, a volume or a test can see.

The four ways

LEMONFIBER_TLS_MODE chooses one. Setting both of files’ paths chooses files, and where nothing is chosen pinned is served: the one way that trusts nothing beyond a single certificate and depends on nobody. acme and private-ca are served only where LEMONFIBER_TLS_MODE names them, because each extends what has to be trusted: an authority’s word, or a root the operator installs.

private-ca and pinned depend on nobody, and acme against the operator’s own authority depends on nobody but the operator. At start the program writes to its log which mode it serves and who can check it, in those words; where the mode is private-ca or pinned it also says that an assistant on a phone or in a browser reached through its provider cannot connect.

In every mode nothing is answered in plain HTTP but the token of a pending HTTP-01 challenge.

The names a certificate is for are LEMONFIBER_NAMES: one or more host names, or for private-ca and pinned also addresses, separated by commas.

files

Both files are read at start and refused, by name, where either is unreadable, the key does not match the certificate, the certificate has expired, or it does not cover every name in LEMONFIBER_NAMES where that is set. They are read again, with no restart, when either changes, so a certificate renewed by something else is taken. This is also how two programs on one machine share one certificate: a program beside a core that already holds one for the name reads the core’s files and opens no second account.

acme

Choosing acme is agreeing to the authority’s terms. It is the operator accepting the terms of service the directory publishes, as Caddy treats it. The program writes the terms’ address to its log when it first registers an account, and the documentation of every program that implements this page says so where it introduces the mode. Where the directory says an external account is required and no binding is given, the program refuses to start, naming the two settings.

TLS-ALPN-01 (RFC 8737) is answered on the port the program serves on, while it serves. The listener reads each connection’s ClientHello before any handshake; a connection asking for acme-tls/1 and nothing else is answered with the challenge certificate, and every other connection is handed on, still encrypted, to the server that answers it. Renewal costs no downtime and no second port.

HTTP-01 needs port 80, which is plain HTTP. The program opens it when a challenge is pending and closes it once the order is settled; while open it answers GET /.well-known/acme-challenge/<token> for the pending token and 404 to everything else, with no redirect.

DNS-01 is answered through a provider, for a host no inbound connection reaches. A provider does two things, present(name, value) and cleanup(name, value), and declares how long its records take to propagate and how often to look. A _acme-challenge name delegated by CNAME is followed to where it points. Before the authority is told to look, the program asks the zone’s authoritative servers itself and waits until each answers with the value. Providers are named, and their settings spelled, as lego names them, so an operator’s existing configuration carries over:

rfc2136 and exec reach a DNS server the operator runs. A secret is read from the file its _FILE setting names, never from the setting itself, so it never sits in an environment a process listing or a crash report can show.

Renewal. A certificate is renewed when the authority’s ACME Renewal Information (RFC 9773) says to, where it offers it, and otherwise once a third of its lifetime is left, which holds for a certificate of six days as for one of ninety. A failed attempt is tried again after a minute, doubling to six hours, with jitter, and never sooner than a Retry-After or a rate-limit problem from the authority says.

private-ca

The program makes a root of its own the first time it starts in this mode, and issues the certificate it serves from that root.

The operator installs the root once on each device that is to connect. From then on every client that trusts it checks the chain as it checks any other, and renewal is the program’s.

A root is replaced when the operator asks (ca replace), when LEMONFIBER_NAMES gains a name the root’s constraints do not cover, and when a year of the root’s life is left. Replacement makes a new root beside the old one, writes it to ca/next-root.pem and prints its fingerprint and, at every start until the switch, that it is waiting to be installed. The program keeps serving from the old root until the operator switches (ca switch), or, where the old root would expire first, until 30 days before it does. A name the old root does not cover is not served until the switch; the program says so rather than serving a certificate that would be refused. After the switch the old root’s key is deleted.

pinned

The program makes a certificate of its own, self-signed, for the names in LEMONFIBER_NAMES, ECDSA P-256 by default, valid for ten years, and prints its fingerprint at every start in the form the companion’s pairing material carries: SHA-256 over the DER encoding, lower-case hex (ADR-0025). A client given the fingerprint pins it and checks it in the handshake. The certificate is not renewed, since a new one would break every pin; it is replaced only when the operator asks (pinned replace), or when LEMONFIBER_NAMES changes, and the program says at start, with the new fingerprint, that every client must be given it again.

Keys

Every key is generated by the program itself. No two roles share a key: an ACME account key, a private root’s key and a certificate’s key are three keys.

A renewed or replaced certificate is taken by new handshakes as soon as it lands; no connection is dropped for it.

When it fails

A program that holds a stack credential, as the core does, also raises its own alert. One that holds none, as the MCP server does not, has the log and the health answer.

The state

$LEMONFIBER_STATE/
  account/<sha256 of the directory URL>/key.pem      acme: the account key, one per authority
  account/<sha256 of the directory URL>/account.json acme: its URL and contact
  ca/root.pem, ca/root-key.pem                       private-ca: the root and its key
  ca/next-root.pem, ca/next-root-key.pem             private-ca: a replacement waiting for the switch
  certificates/<first name>/key.pem                  the served certificate's key
  certificates/<first name>/chain.pem                its chain, leaf first
  certificates/<first name>/renewal.json             the mode, when it was issued, when renewal is due, the last attempt and its outcome

The directory is 0700 and every file in it 0600, owned by the user the program runs as; a program refuses to start on a state directory others can read or that another user owns. A file is written beside its final name, flushed and renamed into place, so a crash leaves the old file or the new one and never half of either.

No private key, account key, root key, External Account Binding key or DNS credential is written to a log, an error, the health answer or a value’s printed form, and none is passed to another process except the one exec provider, which is given only the name and the record’s value.

Conformance

Each implementation runs, in its own CI, the same scenarios. Against Pebble, the authority Let’s Encrypt publishes for testing, with its challenge test server answering DNS: first issuance by each challenge, renewal by Renewal Information and by lifetime, an authority requiring a binding with and without one, a rate-limit answer, and an order that fails. Against itself: a private root’s constraints, checked by a real validator for a root given only host names, only addresses and both, accepting each name it was given and refusing a host name, an IPv4 address and an IPv6 address outside them, its replacement and switch, a pinned certificate’s fingerprint matching what a client computes, a renewal swapped without dropping a connection, and a key or a state directory with the wrong permissions. A DNS provider that talks to a remote API is tested against a stand-in of that API.

Requirements

Related

• F13 An assistant’s way in — the first program it binds
• ADR-0025 — the fingerprint’s form, which pinned prints
• web-api — the surface the core serves