From e7a95fff0a262b7471500781942fa7e168df8d2f Mon Sep 17 00:00:00 2001 From: John Coffey Date: Mon, 12 Oct 2026 15:05:25 -0700 Subject: [PATCH] inbuxa certs: read the mail server's certificate, and with an API key renew it Reports what the mail ports present (issuer, expiry, names, whether it verifies) and where the mail host resolves, which needs nothing. With an API key made in the console, as join takes one, it starts a new ACME order -- the server doesn't start another by itself once an order has failed -- or turns ACME on where the managed Caddy or the operator's web server passes the challenges, and waits for the mail ports to present the result. A certificate is a problem when it is self-signed, expired, for other names, doesn't verify, or has less than a sixth of its lifetime left: a fraction, since lifetimes differ (Let's Encrypt's are getting shorter). Install now records the mail host and --local in install.json; older installs fall back to the deployment and the server's environment. e2e/cases/certs.sh: a failed order at install, reported, a wrong key refused, a key while DNS is wrong, then fixed. --- README.md | 15 +- cmd/inbuxa/main.go | 131 ++++++++++++++++ e2e/cases/certs.sh | 175 +++++++++++++++++++++ internal/apply/apply.go | 4 +- internal/apply/certs.go | 295 +++++++++++++++++++++++++++++++++++ internal/apply/certs_test.go | 171 ++++++++++++++++++++ internal/jmap/setup.go | 30 ++-- internal/state/state.go | 2 + 8 files changed, 810 insertions(+), 13 deletions(-) create mode 100755 e2e/cases/certs.sh create mode 100644 internal/apply/certs.go create mode 100644 internal/apply/certs_test.go diff --git a/README.md b/README.md index 64f4d61..ff49a64 100644 --- a/README.md +++ b/README.md @@ -132,13 +132,25 @@ This is early. What is built: delete. Docker, and the configuration your own web server loads, are left alone. To take one component off, run `install` again with it skipped. +- **`certs [--key KEY]`** -- the mail server's own certificate, the one its + mail ports present: who issued it, until when, for which names, whether + it verifies, and where the mail host resolves. Reading it needs nothing. + Fixing it needs an API key made in the console, as `join` does (`--key -` + or `INBUXA_API_KEY`; never written down): a new ACME order, which the + server doesn't start again by itself once one has failed -- typically + because DNS wasn't in place during the install -- or, on a domain not yet + on ACME, ACME turned on where the managed Caddy or your own web server + passes the challenges. It waits for the mail ports to present the new + certificate. The console's and the webmail's certificates are the + proxy's, which renews them itself. + - **`status`** -- what is installed, what is running, and where those two disagree: a container stopped by hand, or a deployment nothing recorded installing. It exits non-zero when they disagree, so a machine can be asked in a script whether it still matches itself. Not built yet: `join` in the interface (it is a command for now) and of -front ends on the host, `certs`, and moving the server between a container +front ends on the host, and moving the server between a container and the host. The design is in the inbuxa specification (ยง6.1 and the installer draft); the phases are there too. @@ -194,6 +206,7 @@ is tested on a throwaway virtual machine rather than on anybody's desk: install run again: restarted when it must be, only then e2e/vm/run.sh e2e/cases/uninstall-containers.sh uninstalled, installed again on the data, purged e2e/vm/run.sh e2e/cases/uninstall-host.sh the same with the server and the webmail on the host + e2e/vm/run.sh e2e/cases/certs.sh a failed order, reported, then fixed with a key e2e/vm/run.sh e2e/cases/topology.sh growing and shrinking from a file e2e/vm/run.sh e2e/cases/status-export.sh intent against reality, and the file OLD_REF= e2e/vm/run.sh e2e/cases/upgrade-volumes.sh diff --git a/cmd/inbuxa/main.go b/cmd/inbuxa/main.go index ce1f089..222e02a 100644 --- a/cmd/inbuxa/main.go +++ b/cmd/inbuxa/main.go @@ -12,6 +12,7 @@ import ( "bufio" "context" "encoding/json" + "errors" "flag" "fmt" "io" @@ -20,6 +21,7 @@ import ( "path/filepath" "runtime" "strings" + "time" "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/apply" "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/deps" @@ -52,6 +54,9 @@ const usage = `inbuxa -- install the inbuxa suite on this machine --no-backup inbuxa uninstall take the programs away, keep the data: --dry-run, --yes, --purge (the data too) + inbuxa certs [--key KEY] the mail server's certificate: what its mail + ports present, and with an API key a new + order when it needs one inbuxa export [-o FILE] write a topology file from what is here inbuxa version this program's version @@ -90,6 +95,16 @@ join flags: --exempt-address IP the address the server sees the webmail at, when it is not what the webmail's name resolves to +certs flags: + --key KEY an API key made in the console by a server + administrator, needed only to change anything; + "-" reads it from standard input, and + INBUXA_API_KEY works too + --mail-host NAME the server's name, if the install didn't record it + --email ADDRESS the ACME contact, if ACME is turned on here; + default: postmaster@DOMAIN + --dry-run report, and say what it would do + deps flags: --server/--console/--webmail SHAPE the shapes to work out the needs for --install do it, rather than only saying what it would do @@ -134,6 +149,8 @@ func main() { os.Exit(upgradeCmd(os.Args[2:])) case "uninstall": os.Exit(uninstallCmd(os.Args[2:])) + case "certs": + os.Exit(certsCmd(os.Args[2:])) case "version": fmt.Println(version) case "-h", "--help", "help": @@ -819,6 +836,120 @@ func uninstallCmd(args []string) int { return 0 } +func certsCmd(args []string) int { + fs := flag.NewFlagSet("certs", flag.ContinueOnError) + fs.Usage = func() { fmt.Print(usage) } + var ( + key = fs.String("key", os.Getenv("INBUXA_API_KEY"), "") + mailHost = fs.String("mail-host", "", "") + email = fs.String("email", "", "") + acmeDir = fs.String("acme-directory", "", "") + dryRun = fs.Bool("dry-run", false, "") + ) + if err := fs.Parse(args); err != nil { + return 2 + } + ctx := context.Background() + st, err := state.Load() + if err != nil { + fmt.Fprintln(os.Stderr, err.Error()) + return 1 + } + if _, ok := st.Shapes["server"]; !ok || st.Removed() { + fmt.Println("The mail server isn't installed on this machine, so its certificate is looked after where it runs.") + if st.ServerURL != "" { + fmt.Println("The console's and the webmail's certificates here are Caddy's, which renews them itself.") + } + return 0 + } + if apply.LocalInstall(st) { + fmt.Println("This is a --local install: the mail ports are on loopback and have the server's own") + fmt.Println("self-signed certificate, which is all a local evaluation needs. A real certificate comes") + fmt.Println("with installing for a domain that points here.") + return 0 + } + f := host.Survey(ctx) + found := discover.Run(ctx, f, st.Dir) + o := apply.CertsOptions{ + MailHost: apply.CertsMailHost(*mailHost, st, found.MailHost), + Email: *email, ACMEDirectory: *acmeDir, + } + switch { + case found.Proxy: + o.Proxy = "caddy" + case fileExists(filepath.Join(st.Dir, "proxy", "nginx-inbuxa.conf")): + o.Proxy = "snippets" + } + + roots := apply.CertRoots(st.Dir) + s, err := apply.ReadServed(ctx, o.MailHost, roots) + problem := "" + if err != nil { + problem = err.Error() + } else { + fmt.Printf("The mail server's certificate for %s, as port %s presents it:\n", o.MailHost, s.Port) + issuer := s.Issuer + if s.SelfSigned { + issuer = "itself (self-signed)" + } + until := s.NotAfter.Format("2006-01-02") + // A self-signed certificate is often dated to the end of time, where + // a count of days says nothing. + if days := int(time.Until(s.NotAfter).Hours() / 24); days < 3650 { + until += fmt.Sprintf(" (%d days)", days) + } + fmt.Printf(" issued by %s\n valid until %s\n names %s\n", + issuer, until, strings.Join(s.Names, ", ")) + problem = s.Problem(o.MailHost, time.Now()) + } + if addrs, err := net.DefaultResolver.LookupHost(ctx, o.MailHost); err == nil && len(addrs) > 0 { + fmt.Printf("\n%s resolves to %s.\n", o.MailHost, strings.Join(addrs, ", ")) + } else { + fmt.Printf("\n%s doesn't resolve. A certificate can't be issued until it points here: the records\n"+ + "are in %s.\n", o.MailHost, filepath.Join(st.Dir, "dns.zone")) + } + if problem == "" { + fmt.Println("\nNothing to do: the server renews it itself, well before it expires.") + return 0 + } + fmt.Printf("\nThe problem: %s.\n", problem) + if *dryRun { + fmt.Println("\nWith an API key, this would start a new certificate order for " + o.MailHost + " and wait for it.") + return 0 + } + if *key == "-" { + line, err := bufio.NewReader(os.Stdin).ReadString('\n') + if err != nil && line == "" { + fmt.Fprintln(os.Stderr, "reading the key from standard input: "+err.Error()) + return 2 + } + *key = strings.TrimSpace(line) + } + if *key == "" { + fmt.Println("\nA new order needs an API key: make one in the console (your account, API keys), then") + fmt.Println(" sudo inbuxa certs --key -") + fmt.Println("and paste it, or set INBUXA_API_KEY. It isn't kept.") + return 1 + } + fmt.Println() + o.Key = *key + if _, err := apply.Renew(ctx, st, o, &printer{}); err != nil { + fmt.Fprintln(os.Stderr, "\nstopped: "+err.Error()) + if !errors.Is(err, apply.ErrKeyRefused) { + fmt.Fprintln(os.Stderr, " the server's log says why: "+apply.CertsLogHint(st)) + } + return 1 + } + s, _ = apply.ReadServed(ctx, o.MailHost, roots) + if s != nil { + fmt.Printf("\nDone: port %s now presents a certificate for %s from %s, valid until %s.\n", + s.Port, o.MailHost, s.Issuer, s.NotAfter.Format("2006-01-02")) + } + return 0 +} + +func fileExists(p string) bool { _, err := os.Stat(p); return err == nil } + func shapeComponent(s string) (string, error) { switch strings.ToLower(s) { case "server", "console", "webmail": diff --git a/e2e/cases/certs.sh b/e2e/cases/certs.sh new file mode 100755 index 0000000..9151736 --- /dev/null +++ b/e2e/cases/certs.sh @@ -0,0 +1,175 @@ +#!/bin/bash +# SPDX-FileCopyrightText: 2026 Coffey Labs LLC +# SPDX-License-Identifier: AGPL-3.0-or-later +# +# inbuxa certs: the install's order fails because the mail host points +# somewhere else, as it does when DNS isn't in place yet; certs reports that +# without a key, refuses a wrong one, fails while DNS is still wrong, and +# gets the certificate once it is fixed. The same lab as install-public.sh +# (Pebble for Let's Encrypt, a DNS stub), with the server on the host. +# +# Run from the host with: e2e/vm/run.sh e2e/cases/certs.sh +set -uo pipefail + +pass=0; fail=0 +ok() { echo " ok $*"; pass=$((pass+1)); } +bad() { echo " FAIL $*"; fail=$((fail+1)); } + +DOMAIN=lab.test +MAIL=mx.lab.test # not "mail": proves the names follow --mail-host +CONSOLE=console.lab.test +WEBMAIL=webmail.lab.test +DIR=/var/lib/inbuxa + +# Whichever runtime this machine has. The installer picks docker where there +# is one and podman on the Red Hat family; a case that says "docker" only +# tests half the distributions it is run on. +# +# Asked at each call, not once at the top: these cases start on a machine +# with no runtime at all and install one along the way, so anything decided +# up here is decided before the answer exists. +rt() { command -v docker >/dev/null 2>&1 && echo docker || echo podman; } +compose() { + if [ "$(rt)" = docker ]; then + docker compose -f "$DIR/compose.yaml" "$@" + else + DOCKER_HOST=unix:///run/podman/podman.sock \ + /usr/local/lib/docker/cli-plugins/docker-compose -f "$DIR/compose.yaml" "$@" + fi +} +WORK=/tmp/lab +LABNET=inbuxa-e2e +LABSUBNET=172.31.254.0/24 +HOSTIP=172.31.254.1 # this machine, as the lab network sees it + +rm -rf "$WORK"; mkdir -p "$WORK" + +echo "==> what the installer needs, before the lab" +/tmp/inbuxa deps --console container --webmail container --install >/dev/null 2>&1 || true +{ docker version >/dev/null 2>&1 || podman version >/dev/null 2>&1; } && ok "a container runtime is usable" || { bad "no docker"; exit 1; } + +echo +echo "==> standing up a private CA and a DNS stub" +docker network create --subnet "$LABSUBNET" "$LABNET" >/dev/null 2>&1 +# Pebble's own certificate names localhost and "pebble"; the server and Caddy +# reach it at this machine's address from another network, so it gets one for +# that address, signed by the test root that ships with it. +docker create --name inbuxa-e2e-extract ghcr.io/letsencrypt/pebble:latest >/dev/null 2>&1 +docker cp inbuxa-e2e-extract:/test/certs "$WORK/pebble-certs" >/dev/null +docker cp inbuxa-e2e-extract:/test/config/pebble-config.json "$WORK/pebble-config.json" >/dev/null +docker rm inbuxa-e2e-extract >/dev/null +openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -subj "/CN=pebble" \ + -keyout "$WORK/pebble-key.pem" -out "$WORK/pebble.csr" 2>/dev/null +openssl x509 -req -in "$WORK/pebble.csr" -days 2 -CA "$WORK/pebble-certs/pebble.minica.pem" \ + -CAkey "$WORK/pebble-certs/pebble.minica.key.pem" -CAcreateserial \ + -extfile <(printf 'subjectAltName=IP:%s\nextendedKeyUsage=serverAuth\n' "$HOSTIP") \ + -out "$WORK/pebble-cert.pem" 2>/dev/null +python3 - "$WORK/pebble-config.json" <<'PY' +import json, sys +c = json.load(open(sys.argv[1])) +c["pebble"].update(httpPort=80, tlsPort=443, + certificate="/work/pebble-cert.pem", privateKey="/work/pebble-key.pem") +json.dump(c, open(sys.argv[1], "w")) +PY +chmod -R a+r "$WORK" +docker run -d --name inbuxa-e2e-dns --network "$LABNET" --ip 172.31.254.3 \ + ghcr.io/letsencrypt/pebble-challtestsrv:latest \ + -defaultIPv4 "$HOSTIP" -defaultIPv6 "" -http01 "" -https01 "" -tlsalpn01 "" -doh "" >/dev/null +# Nonce rejection off: Pebble refuses 5% of nonces on purpose, and the server +# gives up an order on the first one rather than retrying. +docker run -d --name inbuxa-e2e-pebble --network "$LABNET" --ip 172.31.254.2 \ + -p 14000:14000 -p 15000:15000 -v "$WORK:/work:ro" \ + -e PEBBLE_VA_NOSLEEP=1 -e PEBBLE_WFE_NONCEREJECT=0 \ + ghcr.io/letsencrypt/pebble:latest -config /work/pebble-config.json -dnsserver 172.31.254.3:8053 >/dev/null +for _ in $(seq 1 30); do + curl -sf --cacert "$WORK/pebble-certs/pebble.minica.pem" "https://$HOSTIP:14000/dir" >/dev/null && break + sleep 1 +done +curl -sf --cacert "$WORK/pebble-certs/pebble.minica.pem" "https://$HOSTIP:14000/dir" >/dev/null \ + && ok "Pebble answers at https://$HOSTIP:14000/dir" || { bad "Pebble did not come up"; exit 1; } + +# The mail host points nowhere useful, so the server's HTTP-01 challenge +# can't reach it. The console's and the webmail's names point here, so +# Caddy's own certificates are not what fails. +BOGUS=172.31.254.99 +curl -s -X POST -d "{\"host\":\"$MAIL\",\"addresses\":[\"$BOGUS\"]}" http://172.31.254.3:8055/add-a >/dev/null \ + && ok "the DNS stub sends $MAIL to $BOGUS" || bad "the DNS stub's management API" +# The CA resolves names through the stub; this machine, as an operator's +# would, through its own resolver, which is told the same. +echo "$BOGUS $MAIL" >> /etc/hosts + +CA="$WORK/pebble-certs/pebble.minica.pem" +curl -sf --cacert "$CA" "https://$HOSTIP:15000/roots/0" > "$WORK/root.pem" +curl -sf --cacert "$CA" "https://$HOSTIP:15000/intermediates/0" > "$WORK/int.pem" +cat "$WORK/int.pem" "$WORK/root.pem" > "$WORK/chain.pem" +# The machine trusts the CA, as a real one trusts Let's Encrypt. +cp "$WORK/root.pem" /usr/local/share/ca-certificates/inbuxa-e2e-pebble.crt && update-ca-certificates >/dev/null 2>&1 + +echo +echo "==> installing, with the mail host pointing elsewhere" +OUT="$(/tmp/inbuxa install --domain "$DOMAIN" --mail-host "$MAIL" --console-host "$CONSOLE" \ + --webmail-host "$WEBMAIL" --server host --acme-directory "https://$HOSTIP:14000/dir" \ + --acme-ca-root "$CA" --install-deps --yes 2>&1)"; rc=$? +echo "$OUT" | grep -v '^ |' | tail -6 | sed 's/^/ /' +[ $rc -eq 0 ] && ok "installed (exit 0)" || bad "exit $rc" +grep -q "no certificate yet for $MAIL" <<<"$OUT" && ok "it said there was no certificate yet" || bad "it did not say so" +grep -q "\"mailHost\": \"$MAIL\"" /etc/inbuxa/install.json && ok "the install recorded the mail host" || bad "no mailHost in install.json" + +echo +echo "==> certs, with no key" +OUT="$(/tmp/inbuxa certs 2>&1)"; rc=$? +echo "$OUT" | sed 's/^/ /' +[ $rc -eq 1 ] && ok "exit 1: there is a problem" || bad "exit $rc" +grep -q "self-signed" <<<"$OUT" && ok "it names the self-signed certificate" || bad "no mention of self-signed" +grep -q "$MAIL resolves to $BOGUS" <<<"$OUT" && ok "it shows where $MAIL points" || bad "no resolution shown" +grep -q "needs an API key" <<<"$OUT" && ok "it says a key is needed" || bad "no word about a key" +OUT="$(/tmp/inbuxa certs --dry-run 2>&1)"; rc=$? +[ $rc -eq 0 ] && grep -q "would start a new certificate order" <<<"$OUT" && ok "--dry-run says what it would do" || bad "dry run exit $rc" + +echo +echo "==> an API key, as an administrator makes one in the console" +SERVER=http://127.0.0.1:8081 +wait_server() { for _ in $(seq 1 60); do [ "$(curl -s -o /dev/null -w '%{http_code}' $SERVER/.well-known/jmap)" != 000 ] && return 0; sleep 2; done; return 1; } +AUSER=$(awk '/^administrator/ {print $2}' "$DIR/credentials.txt") +APASS=$(awk '/^administrator/{getline; print $2}' "$DIR/credentials.txt") +echo "INBUXA_HTTP_BASIC_AUTH=all" >> "$DIR/server.env" +systemctl restart inbuxa-server; wait_server +EXPIRES=$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ) +ANSWER=$(curl -s -u "$AUSER:$APASS" -H 'Content-Type: application/json' \ + -d "{\"using\":[\"urn:ietf:params:jmap:core\",\"urn:inbuxa:jmap:registry\"],\"methodCalls\":[[\"x:ApiKey/set\",{\"create\":{\"k\":{\"description\":\"certs test\",\"expiresAt\":\"$EXPIRES\",\"permissions\":{\"@type\":\"Inherit\"}}}},\"0\"]]}" $SERVER/jmap/) +KEY=$(sed -n 's/.*"secret":"\([^"]*\)".*/\1/p' <<<"$ANSWER") +sed -i '/^INBUXA_HTTP_BASIC_AUTH=/d' "$DIR/server.env" +systemctl restart inbuxa-server; wait_server +[ -n "$KEY" ] && ok "an API key for the administrator" || { bad "no API key"; head -c 300 <<<"$ANSWER" | sed 's/^/ /'; } + +OUT="$(INBUXA_API_KEY=wrong-key /tmp/inbuxa certs 2>&1)"; rc=$? +[ $rc -eq 1 ] && grep -q "refused the API key" <<<"$OUT" && ok "a wrong key is refused, and says so" || { bad "wrong key: exit $rc"; echo "$OUT" | tail -4 | sed 's/^/ /'; } + +echo +echo "==> with a key, while DNS is still wrong" +OUT="$(echo "$KEY" | /tmp/inbuxa certs --key - 2>&1)"; rc=$? +echo "$OUT" | tail -5 | sed 's/^/ /' +[ $rc -eq 1 ] && grep -q "no certificate for $MAIL after three minutes" <<<"$OUT" && ok "it gives up, and says why" || bad "exit $rc" +grep -q "journalctl -u inbuxa-server" <<<"$OUT" && ok "and where the server's log is" || bad "no log hint" + +echo +echo "==> DNS fixed, with a key" +curl -s -X POST -d "{\"host\":\"$MAIL\"}" http://172.31.254.3:8055/clear-a >/dev/null +sed -i "s/^$BOGUS $MAIL\$/$HOSTIP $MAIL/" /etc/hosts +OUT="$(echo "$KEY" | /tmp/inbuxa certs --key - 2>&1)"; rc=$? +echo "$OUT" | sed 's/^/ /' +[ $rc -eq 0 ] && ok "exit 0" || bad "exit $rc" +grep -q "starting a new certificate order" <<<"$OUT" && ok "it started a new order" || bad "no new order" +grep -q "Done: port 993 now presents a certificate for $MAIL" <<<"$OUT" && ok "it reports the new certificate" || bad "no Done line" +out=$(echo | timeout 20 openssl s_client -connect "127.0.0.1:993" -servername "$MAIL" -verify_hostname "$MAIL" -CAfile "$WORK/chain.pem" 2>&1) +grep -q "Verify return code: 0 (ok)" <<<"$out" && ok "993 verifies for $MAIL" || bad "993 does not verify" +grep -rqF "$KEY" "$DIR" /etc/inbuxa 2>/dev/null && bad "the API key was written down" || ok "the API key was not kept" + +echo +echo "==> certs again, nothing to do" +OUT="$(/tmp/inbuxa certs 2>&1)"; rc=$? +[ $rc -eq 0 ] && grep -q "Nothing to do" <<<"$OUT" && ok "nothing to do, without a key" || { bad "exit $rc"; echo "$OUT" | sed 's/^/ /'; } + +echo +echo "==> $pass passed, $fail failed" +[ "$fail" -eq 0 ] diff --git a/internal/apply/apply.go b/internal/apply/apply.go index 77fcd34..4d77da6 100644 --- a/internal/apply/apply.go +++ b/internal/apply/apply.go @@ -575,7 +575,7 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro // intent rather than guessing from what happens to be up. st, err := state.Load() if err == nil { - st.Machine, st.Dir, st.Domain = o.Machine, dir, o.Domain + st.Machine, st.Dir, st.Domain, st.MailHost, st.Local = o.Machine, dir, o.Domain, o.MailHost, o.Local st.Runtime, st.Topology = f.Runtime.Kind, o.TopologyPath st.Shapes = map[string]string{} for _, c := range []plan.Component{plan.Server, plan.Console, plan.Webmail} { @@ -746,7 +746,7 @@ func convergeHost(ctx context.Context, o plan.Options, stack compose.Stack, cmp } func saveState(st *state.State, o plan.Options, f host.Facts, log Log) { - st.Machine, st.Dir, st.Domain = o.Machine, o.Dir, o.Domain + st.Machine, st.Dir, st.Domain, st.MailHost, st.Local = o.Machine, o.Dir, o.Domain, o.MailHost, o.Local st.Runtime, st.Topology = f.Runtime.Kind, o.TopologyPath st.Installer = "server " + release.ServerVersion st.RemovedAt = nil // installed again, on what was kept diff --git a/internal/apply/certs.go b/internal/apply/certs.go new file mode 100644 index 0000000..c45a17b --- /dev/null +++ b/internal/apply/certs.go @@ -0,0 +1,295 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package apply + +// Certs is the mail server's own certificate: the one its mail ports present +// to clients, which the proxy in front never sees. The console's and the +// webmail's are the proxy's, and it renews those itself. +// +// Looking needs nothing: the certificate is read off port 993 the way a mail +// client reads it. Doing something about it needs an API key made in the +// console, as join does. The server takes no password on its API once it is +// set up, and switching that back on for a moment, as the install's setup +// does, is not something to do to a server that is already live. +// +// What it does about it: a domain whose certificates are on ACME gets a new +// order, which is the one thing the server does not do by itself once an +// order has failed -- the usual story is that DNS was not in place during +// the install. A domain not on ACME is put on it, if something here answers +// the server's challenges on port 80: the managed Caddy, or the operator's +// own web server loading the configuration written for it. + +import ( + "bytes" + "context" + "crypto/tls" + "crypto/x509" + "errors" + "fmt" + "net" + "os" + "path/filepath" + "strings" + "time" + + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/jmap" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state" +) + +// Served is a certificate as a mail client is given it. +type Served struct { + Port string + Issuer string + NotBefore time.Time + NotAfter time.Time + Names []string + SelfSigned bool + Trust error // why it doesn't verify for the mail host; nil when it does +} + +// stuckBelow is how little of its lifetime a certificate may have left +// before that is reported as a problem. The server renews with a third left +// (ACME's renewBefore is two thirds of the way through), so a certificate +// down to a sixth has missed its renewal. A fraction rather than a number of +// days, because lifetimes differ: Let's Encrypt's are moving from 90 days +// towards six, and a test CA's are shorter still. +const stuckBelow = 6 + +// Problem is what is wrong with it for host, in a phrase; "" when nothing is. +func (s *Served) Problem(host string, now time.Time) string { + switch { + case s.SelfSigned: + return "it is the server's own self-signed certificate, which mail clients refuse" + case now.After(s.NotAfter): + return "it expired on " + s.NotAfter.Format("2006-01-02") + case !covers(s.Names, host): + return "it does not name " + host + case s.Trust != nil: + return "it does not verify: " + s.Trust.Error() + case s.NotAfter.Sub(now) < s.NotAfter.Sub(s.NotBefore)/stuckBelow: + return "it expires " + inWords(s.NotAfter.Sub(now)) + " and has not been renewed" + } + return "" +} + +func inWords(d time.Duration) string { + if d >= 48*time.Hour { + return fmt.Sprintf("in %d days", int(d.Hours()/24)) + } + return fmt.Sprintf("in %d hours", int(d.Hours())) +} + +func covers(names []string, host string) bool { + for _, n := range names { + if strings.EqualFold(n, host) { + return true + } + if rest, ok := strings.CutPrefix(n, "*."); ok { + if _, parent, ok := strings.Cut(host, "."); ok && strings.EqualFold(parent, rest) { + return true + } + } + } + return false +} + +// ServedCertificate reads the certificate the server presents for host at +// addr (host:port), as a client would, and checks it against roots: the +// system's when nil. +func ServedCertificate(ctx context.Context, addr, host string, roots *x509.CertPool) (*Served, error) { + d := tls.Dialer{Config: &tls.Config{ServerName: host, InsecureSkipVerify: true}} + d.NetDialer = &net.Dialer{Timeout: 10 * time.Second} + ctx, cancel := context.WithTimeout(ctx, 15*time.Second) + defer cancel() + conn, err := d.DialContext(ctx, "tcp", addr) + if err != nil { + return nil, err + } + defer conn.Close() + chain := conn.(*tls.Conn).ConnectionState().PeerCertificates + if len(chain) == 0 { + return nil, errors.New("no certificate was presented") + } + leaf := chain[0] + _, port, _ := net.SplitHostPort(addr) + s := &Served{ + Port: port, + Issuer: issuerName(leaf), + NotBefore: leaf.NotBefore, + NotAfter: leaf.NotAfter, + Names: leaf.DNSNames, + SelfSigned: bytes.Equal(leaf.RawIssuer, leaf.RawSubject), + } + inter := x509.NewCertPool() + for _, c := range chain[1:] { + inter.AddCert(c) + } + _, s.Trust = leaf.Verify(x509.VerifyOptions{DNSName: host, Roots: roots, Intermediates: inter}) + return s, nil +} + +func issuerName(c *x509.Certificate) string { + name := c.Issuer.CommonName + if len(c.Issuer.Organization) > 0 && !strings.Contains(name, c.Issuer.Organization[0]) { + if name == "" { + return c.Issuer.Organization[0] + } + name += " (" + c.Issuer.Organization[0] + ")" + } + if name == "" { + name = c.Issuer.String() + } + return name +} + +// CertRoots are the roots this machine trusts, plus the private CA's root an +// install with --acme-ca-root was given, which the server was told to trust +// and so should this. +func CertRoots(dir string) *x509.CertPool { + pool, err := x509.SystemCertPool() + if err != nil { + pool = x509.NewCertPool() + } + if b, err := os.ReadFile(filepath.Join(dir, "ca-bundle.crt")); err == nil { + pool.AppendCertsFromPEM(b) + } + return pool +} + +// MailPorts are where the certificate is read: IMAP over TLS, then +// submission over TLS, whichever answers first. +var MailPorts = []string{"993", "465"} + +// ReadServed reads the certificate off the first mail port that answers. +func ReadServed(ctx context.Context, host string, roots *x509.CertPool) (*Served, error) { + var errs []string + for _, p := range MailPorts { + s, err := ServedCertificate(ctx, net.JoinHostPort("127.0.0.1", p), host, roots) + if err == nil { + return s, nil + } + errs = append(errs, p+": "+err.Error()) + } + return nil, fmt.Errorf("the mail ports don't answer with TLS (%s)", strings.Join(errs, "; ")) +} + +// CertsMailHost is the server's name: as given, as recorded, as the +// deployment says, or the default. +func CertsMailHost(given string, st *state.State, found string) string { + for _, h := range []string{given, st.MailHost, found} { + if h != "" { + return h + } + } + return "mail." + st.Domain +} + +// LocalInstall is whether the install here was --local: recorded since +// 2026.10.13, and before that read off the address the server was given for +// itself, which only a local install sets. +func LocalInstall(st *state.State) bool { + if st.Local { + return true + } + for _, f := range []string{"compose.yaml", "server.env"} { + if b, err := os.ReadFile(filepath.Join(st.Dir, f)); err == nil && strings.Contains(string(b), "INBUXA_PUBLIC_URL") { + return true + } + } + return false +} + +// ErrKeyRefused is an API key the server doesn't take. +var ErrKeyRefused = errors.New("the server refused the API key: make one in the console (your account, API keys) as an administrator") + +// CertsOptions are what Renew needs beyond the install record. +type CertsOptions struct { + MailHost string + Key string + Proxy string // "caddy", "snippets" or "" for none: what answers on port 80 + Email string // the ACME contact when ACME is turned on here + ACMEDirectory string +} + +// Renew gets the server a certificate: a new order on ACME, or ACME turned +// on first where something here can pass its challenges. It returns what the +// mail ports present afterwards. +func Renew(ctx context.Context, st *state.State, o CertsOptions, log Log) (*Served, error) { + srv := &jmap.Client{BaseURL: "http://" + hostFinalBind, Token: o.Key} + domainID, err := srv.DomainID(ctx, st.Domain) + if err != nil { + var he *jmap.HTTPError + if errors.As(err, &he) && (he.Status == 401 || he.Status == 403) { + return nil, ErrKeyRefused + } + return nil, fmt.Errorf("finding %s on the server: %w", st.Domain, err) + } + kind, _, err := srv.CertificateManagement(ctx, domainID) + if err != nil { + return nil, err + } + if kind == "Automatic" { + log.Step("starting a new certificate order for %s", o.MailHost) + if err := srv.RetryCertificates(ctx, domainID); err != nil { + return nil, err + } + } else { + if o.Proxy == "" { + return nil, fmt.Errorf("the domain's certificates are %s, and nothing here passes the server's ACME challenges on port 80 "+ + "(the install has no proxy): its certificate is yours to arrange", strings.ToLower(kind)) + } + email := o.Email + if email == "" { + email = "postmaster@" + st.Domain + } + log.Step("turning on certificates for %s, from ACME (contact %s)", o.MailHost, email) + if o.Proxy == "snippets" { + log.Info("the challenges reach the server through your web server, so it must be loading %s first", + filepath.Join(st.Dir, "proxy")) + } + if _, err := srv.EnableACME(ctx, domainID, o.ACMEDirectory, email); err != nil { + return nil, fmt.Errorf("enabling ACME: %w", err) + } + } + // Waited for as the mail ports present it, not as the server lists it: + // a certificate about to expire is listed too, and is what is being + // replaced. A new order is asked for again every so often, as the + // install does, since one that fails is not retried. + log.Info("waiting for the certificate (up to three minutes)") + roots := CertRoots(st.Dir) + deadline := time.Now().Add(3 * time.Minute) + nextRetry := time.Now().Add(45 * time.Second) + var last string + for { + s, err := ReadServed(ctx, o.MailHost, roots) + if err == nil { + if last = s.Problem(o.MailHost, time.Now()); last == "" { + return s, nil + } + } else { + last = err.Error() + } + if time.Now().After(deadline) { + return s, fmt.Errorf("no certificate for %s after three minutes (%s): check that it resolves to this machine and that port 80 reaches it", o.MailHost, last) + } + if time.Now().After(nextRetry) { + log.Info("asking again") + _ = srv.RetryCertificates(ctx, domainID) + nextRetry = time.Now().Add(45 * time.Second) + } + select { + case <-ctx.Done(): + return s, ctx.Err() + case <-time.After(3 * time.Second): + } + } +} + +// CertsLogHint is where the server says why an order failed. +func CertsLogHint(st *state.State) string { + if st.Shapes["server"] == "host" { + return "journalctl -u " + HostServerUnit + " | grep -i acme" + } + return "docker compose --project-directory " + st.Dir + " logs server | grep -i acme" +} diff --git a/internal/apply/certs_test.go b/internal/apply/certs_test.go new file mode 100644 index 0000000..fdc36cc --- /dev/null +++ b/internal/apply/certs_test.go @@ -0,0 +1,171 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package apply + +import ( + "context" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/tls" + "crypto/x509" + "crypto/x509/pkix" + "math/big" + "net" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state" +) + +type issued struct { + cert *x509.Certificate + key *ecdsa.PrivateKey + der []byte +} + +// mint makes a certificate for names, signed by parent, or by itself when +// parent is nil. +func mint(t *testing.T, cn string, names []string, notAfter time.Time, ca bool, parent *issued) *issued { + t.Helper() + key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatal(err) + } + tmpl := &x509.Certificate{ + SerialNumber: big.NewInt(time.Now().UnixNano()), + Subject: pkix.Name{CommonName: cn, Organization: []string{"Lab"}}, + NotBefore: time.Now().Add(-time.Hour), + NotAfter: notAfter, + DNSNames: names, + KeyUsage: x509.KeyUsageDigitalSignature | x509.KeyUsageCertSign, + ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}, + IsCA: ca, BasicConstraintsValid: true, + } + signer, signerKey := tmpl, key + if parent != nil { + signer, signerKey = parent.cert, parent.key + } + der, err := x509.CreateCertificate(rand.Reader, tmpl, signer, &key.PublicKey, signerKey) + if err != nil { + t.Fatal(err) + } + c, _ := x509.ParseCertificate(der) + return &issued{c, key, der} +} + +// serve presents leaf (and its chain) on a loopback port and returns the +// address. +func serve(t *testing.T, chain ...*issued) string { + t.Helper() + cert := tls.Certificate{PrivateKey: chain[0].key} + for _, c := range chain { + cert.Certificate = append(cert.Certificate, c.der) + } + ln, err := tls.Listen("tcp", "127.0.0.1:0", &tls.Config{Certificates: []tls.Certificate{cert}}) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { ln.Close() }) + go func() { + for { + c, err := ln.Accept() + if err != nil { + return + } + go func(c net.Conn) { c.(*tls.Conn).Handshake(); c.Close() }(c) + } + }() + return ln.Addr().String() +} + +func TestTheCertificateOnTheMailPortsIsReadAsAClientSeesIt(t *testing.T) { + ctx := context.Background() + in := time.Now().Add(60 * 24 * time.Hour) + root := mint(t, "Lab Root", nil, in.Add(time.Hour), true, nil) + leaf := mint(t, "mx.lab.test", []string{"mx.lab.test", "autoconfig.lab.test"}, in, false, root) + roots := x509.NewCertPool() + roots.AddCert(root.cert) + + s, err := ServedCertificate(ctx, serve(t, leaf), "mx.lab.test", roots) + if err != nil { + t.Fatal(err) + } + if p := s.Problem("mx.lab.test", time.Now()); p != "" { + t.Errorf("a trusted certificate for the name, two months out, is a problem: %s", p) + } + if s.SelfSigned || s.Issuer != "Lab Root" || len(s.Names) != 2 { + t.Errorf("read back as %+v", s) + } + + // The same certificate without its root trusted. + s, _ = ServedCertificate(ctx, serve(t, leaf), "mx.lab.test", x509.NewCertPool()) + if p := s.Problem("mx.lab.test", time.Now()); !strings.Contains(p, "does not verify") { + t.Errorf("an untrusted issuer reads %q", p) + } + + // The server's own, before any order succeeded. + self := mint(t, "mx.lab.test", []string{"mx.lab.test"}, in, false, nil) + s, _ = ServedCertificate(ctx, serve(t, self), "mx.lab.test", roots) + if p := s.Problem("mx.lab.test", time.Now()); !strings.Contains(p, "self-signed") { + t.Errorf("a self-signed certificate reads %q", p) + } +} + +func TestWhatIsWrongWithACertificateIsSaidInOnePhrase(t *testing.T) { + now := time.Now() + for _, c := range []struct { + name string + s Served + want string + }{ + {"fine", Served{NotBefore: now.Add(-24 * time.Hour), NotAfter: now.Add(60 * 24 * time.Hour), Names: []string{"mx.lab.test"}}, ""}, + {"wildcard", Served{NotBefore: now.Add(-24 * time.Hour), NotAfter: now.Add(60 * 24 * time.Hour), Names: []string{"*.lab.test"}}, ""}, + {"expired", Served{NotAfter: now.Add(-time.Hour), Names: []string{"mx.lab.test"}}, "expired"}, + {"other name", Served{NotBefore: now.Add(-24 * time.Hour), NotAfter: now.Add(60 * 24 * time.Hour), Names: []string{"mail.lab.test"}}, "does not name mx.lab.test"}, + {"renewal stuck", Served{NotBefore: now.Add(-85 * 24 * time.Hour), NotAfter: now.Add(5 * 24 * time.Hour), Names: []string{"mx.lab.test"}}, "in 5 days and has not been renewed"}, + {"short-lived, new", Served{NotBefore: now.Add(-time.Hour), NotAfter: now.Add(5 * 24 * time.Hour), Names: []string{"mx.lab.test"}}, ""}, + {"short-lived, stuck", Served{NotBefore: now.Add(-110 * time.Hour), NotAfter: now.Add(10 * time.Hour), Names: []string{"mx.lab.test"}}, "in 10 hours"}, + } { + got := c.s.Problem("mx.lab.test", now) + if (c.want == "") != (got == "") || !strings.Contains(got, c.want) { + t.Errorf("%s: %q, wanted %q", c.name, got, c.want) + } + } +} + +func TestTheMailHostComesFromWhatIsKnownBeforeTheDefault(t *testing.T) { + st := &state.State{Domain: "lab.test"} + if h := CertsMailHost("", st, ""); h != "mail.lab.test" { + t.Errorf("nothing known: %s", h) + } + if h := CertsMailHost("", st, "mx.lab.test"); h != "mx.lab.test" { + t.Errorf("from the deployment: %s", h) + } + st.MailHost = "smtp.lab.test" + if h := CertsMailHost("", st, "mx.lab.test"); h != "smtp.lab.test" { + t.Errorf("recorded: %s", h) + } + if h := CertsMailHost("given.lab.test", st, "mx.lab.test"); h != "given.lab.test" { + t.Errorf("given: %s", h) + } +} + +func TestALocalInstallIsKnownEvenIfItWasNotRecorded(t *testing.T) { + dir := t.TempDir() + st := &state.State{Dir: dir} + if LocalInstall(st) { + t.Fatal("an empty directory is local") + } + os.WriteFile(filepath.Join(dir, "server.env"), []byte("INBUXA_PUBLIC_URL=http://localhost:8081\n"), 0o600) + if !LocalInstall(st) { + t.Error("a server told its own loopback address is not local") + } + if !LocalInstall(&state.State{Dir: t.TempDir(), Local: true}) { + t.Error("a recorded --local is not local") + } +} diff --git a/internal/jmap/setup.go b/internal/jmap/setup.go index a440b98..7ea3649 100644 --- a/internal/jmap/setup.go +++ b/internal/jmap/setup.go @@ -184,10 +184,9 @@ func (c *Client) EnableACME(ctx context.Context, domainID, directory, contact st return id, nil } -// RetryCertificates starts a fresh ACME order for the domain. A failed order -// is not retried on a restart; moving the domain to manual and straight back -// is what starts a new one. -func (c *Client) RetryCertificates(ctx context.Context, domainID string) error { +// CertificateManagement says how the domain's certificates are managed: +// "Automatic" with the ACME provider's id, or "Manual" with none. +func (c *Client) CertificateManagement(ctx context.Context, domainID string) (kind, providerID string, err error) { var got struct { List []struct { CertificateManagement struct { @@ -198,18 +197,29 @@ func (c *Client) RetryCertificates(ctx context.Context, domainID string) error { } rs, err := c.Do(ctx, Call{"x:Domain/get", map[string]any{"ids": []string{domainID}, "properties": []string{"certificateManagement"}}, "0"}) if err != nil { - return err + return "", "", err } if err := json.Unmarshal(rs[0].Args, &got); err != nil || len(got.List) != 1 { - return errors.New("x:Domain/get did not return the domain") + return "", "", errors.New("x:Domain/get did not return the domain") } cm := got.List[0].CertificateManagement - if cm.Type != "Automatic" || cm.AcmeProviderID == "" { - return fmt.Errorf("the domain's certificates are %q, not managed by ACME", cm.Type) + return cm.Type, cm.AcmeProviderID, nil +} + +// RetryCertificates starts a fresh ACME order for the domain. A failed order +// is not retried on a restart; moving the domain to manual and straight back +// is what starts a new one. +func (c *Client) RetryCertificates(ctx context.Context, domainID string) error { + kind, providerID, err := c.CertificateManagement(ctx, domainID) + if err != nil { + return err } - rs, err = c.Do(ctx, + if kind != "Automatic" || providerID == "" { + return fmt.Errorf("the domain's certificates are %q, not managed by ACME", kind) + } + rs, err := c.Do(ctx, Call{"x:Domain/set", map[string]any{"update": map[string]any{domainID: map[string]any{"certificateManagement": map[string]any{"@type": "Manual"}}}}, "0"}, - Call{"x:Domain/set", map[string]any{"update": map[string]any{domainID: automaticCertificates(cm.AcmeProviderID)}}, "1"}, + Call{"x:Domain/set", map[string]any{"update": map[string]any{domainID: automaticCertificates(providerID)}}, "1"}, ) if err != nil { return err diff --git a/internal/state/state.go b/internal/state/state.go index 657cf21..0388264 100644 --- a/internal/state/state.go +++ b/internal/state/state.go @@ -30,6 +30,8 @@ type State struct { Dir string `json:"dir"` // the deployment directory Runtime string `json:"runtime,omitempty"` // docker or podman Domain string `json:"domain,omitempty"` // + MailHost string `json:"mailHost,omitempty"` // the server's name; installs before 2026.10.13 did not record it + Local bool `json:"local,omitempty"` // --local: loopback only, no certificates Shapes map[string]string `json:"shapes"` // component -> container|host Topology string `json:"topology,omitempty"` // the file this came from, if any ServerURL string `json:"serverUrl,omitempty"` // the server on another machine these front ends were joined to -- 2.54.0