0
Fork 0
mirror of https://github.com/oblien/openship.git synced 2026-11-18 06:55:56 +00:00
openship/docs/acme.md
Tristan Rhodes 3b7752a122 fix(acme): survive CA switches on renewal and harden EAB secret handling
Review follow-ups on the alternate-CA/EAB foundation:

- renewCert: a lineage issued by a different directory than the one now
  configured cannot be renewed against the new CA (renew neither registers
  the account nor carries EAB). Compare the renewal conf's recorded server
  with the effective directory and force-reissue on mismatch — a one-time,
  self-healing switch. Drop the now-redundant --server from plain renew.
- Write the ephemeral EAB config with mode 0600 from the start (_writeFile
  gained an optional mode applied to the temp file before the rename), so
  the HMAC key is never on disk world-readable, however briefly.
- Redact the EAB HMAC inside _execCertbot's error paths (buffered throw and
  full accumulated stream output), so no caller can leak it by omitting a
  redacting catch; per-chunk redaction alone missed chunk-boundary splits.
- Validate the OPENSHIP_ACME_* contract at API boot (EAB pair, base64url
  HMAC, printable kid, absolute CA bundle) so misconfiguration names the
  variable at startup instead of failing at the first deploy.
- Docs: note that --config bypasses an operator cli.ini during EAB runs and
  document the reissue-on-CA-switch behavior.
- Tests: renew mismatch/match paths, renew-error redaction, tightened 0600
  ordering assertions, and complete the preserved-ACME-env assertions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-01 12:47:29 -06:00

3.6 KiB

Custom ACME certificate authorities

OpenShip uses Certbot on the managed OpenResty edge. With no ACME configuration, certificate issuance and renewal continue to use Let's Encrypt production.

Set the following variables in the environment used to start OpenShip, then restart the API/control plane:

OPENSHIP_ACME_EMAIL=ops@example.com
OPENSHIP_ACME_DIRECTORY_URL=https://acme.example.com/directory
OPENSHIP_ACME_EAB_KID=example-key-id
OPENSHIP_ACME_EAB_HMAC_KEY=base64url-encoded-hmac-key
OPENSHIP_ACME_KEY_TYPE=ec256
OPENSHIP_ACME_TOS_AGREED=true

OPENSHIP_ACME_EAB_KID and OPENSHIP_ACME_EAB_HMAC_KEY are optional, but they must be supplied together. OpenShip never places the HMAC key in Certbot's command line or streamed logs. It writes the pair to a unique mode-0600 Certbot configuration file for the issuance process and deletes that file when the process exits. Keep the source value in a protected environment/secret store.

Because that file is passed with Certbot's --config flag, an operator-managed /etc/letsencrypt/cli.ini is ignored for EAB issuance runs. If you rely on custom cli.ini settings, express them through the OPENSHIP_ACME_* variables instead.

Supported certificate key choices are ec256, ec384, rsa2048, and rsa4096. When omitted, Certbot's installed-version default is preserved.

Let's Encrypt

No custom settings are required. For staging tests, add:

OPENSHIP_ACME_DIRECTORY_URL=https://acme-staging-v02.api.letsencrypt.org/directory

ZeroSSL

Create EAB credentials in ZeroSSL, then configure its production directory:

OPENSHIP_ACME_EMAIL=ops@example.com
OPENSHIP_ACME_DIRECTORY_URL=https://acme.zerossl.com/v2/DV90
OPENSHIP_ACME_EAB_KID=your-zerossl-kid
OPENSHIP_ACME_EAB_HMAC_KEY=your-zerossl-hmac-key
OPENSHIP_ACME_TOS_AGREED=true

The HMAC value must remain in the base64url form supplied by the CA; do not decode it before configuring OpenShip.

Private CA and custom trust root

For a private ACME server such as step-ca, point OpenShip at the directory and make its root certificate visible in the environment where Certbot runs:

OPENSHIP_ACME_DIRECTORY_URL=https://ca.internal.example/acme/provisioner/directory
OPENSHIP_ACME_EAB_KID=provisioned-key-id
OPENSHIP_ACME_EAB_HMAC_KEY=provisioned-base64url-key
OPENSHIP_ACME_CA_BUNDLE=/etc/ssl/private/acme-root.pem

On a bare Linux edge, the bundle path is a normal absolute host path. When the edge runs in a container, the same absolute path must be mounted read-only into the edge container. For the repository Compose stack, use an override:

services:
  edge:
    volumes:
      - /secure/acme-root.pem:/etc/ssl/private/acme-root.pem:ro

Certbot uses REQUESTS_CA_BUNDLE for issuance and renewal. The bundle therefore needs to contain the private root plus any public roots needed by the ACME endpoint's chain.

Switching certificate authorities

Certbot records the issuing directory per certificate, and a certificate issued by one CA cannot be renewed against another (the new CA requires its own account, and usually its own EAB credentials). When the configured directory differs from the one that issued a certificate, OpenShip reissues that certificate under the newly configured CA at its next renewal instead of renewing it — a one-time reissue per domain, after which normal renewal resumes. Existing certificates keep serving traffic until that happens.

Current scope

These settings define one instance-wide CA. Persistent named CA profiles and per-project/per-domain overrides require a database and API design and are not yet exposed by the dashboard or CLI.