ADR-0022: record what the Dovecot GSSAPI work actually cost, and the keytab invariant #297

New issue

Closed

opened 2026-08-08 02:31:14 +02:00 by dominik.polakovics · 0 comments

dominik.polakovics commented

2026-08-08 02:31:14 +02:00

Owner

docs/adr/0022-keycloak-and-scoped-kerberos.md describes the GSSAPI bonuses as needing only "a keytab and one more entry in auth_mechanisms". Building it (#290, #291) showed that was too cheap by one item, and surfaced an invariant that a future change would plausibly violate.

Amend the ADR to record:

nixpkgs does not build Dovecot with GSSAPI — no kerberos in buildInputs, no --with-gssapi, no withGSSAPI argument — so a package override was required. It must replace the dovecot_2_3 attribute rather than services.dovecot2.package, or pigeonhole is built against a different dovecot; krb5 also has to be in nativeBuildInputs because of strictDeps.
Two SPNs, because IMAP and submission are reached under different hostnames, which forces auth_gssapi_hostname = "$ALL". Aligning the names is not available: the two services carry different ACME certificates.
The keytab invariant. $ALL moves the trust boundary from a hostname to the keytab's contents. It is safe only while that keytab stays Dovecot's own — and GSSAPI SSH will put host/<fqdn> into /etc/krb5.keytab, making "just use the machine keytab" the obvious-looking change that must not be made. A comment in dovecot.nix will not be read by whoever writes the SSH module; this belongs in the ADR.
Postfix needed no change, and its risk is reject_authenticated_sender_login_mismatch — rejected mail rather than failed login.
What it actually delivers: one account of five, VPN-only, no Thunderbird auth-method fallback.

Documentation only; no configuration change.

`docs/adr/0022-keycloak-and-scoped-kerberos.md` describes the GSSAPI bonuses as needing only "a keytab and one more entry in `auth_mechanisms`". Building it (#290, #291) showed that was too cheap by one item, and surfaced an invariant that a future change would plausibly violate. Amend the ADR to record: - **nixpkgs does not build Dovecot with GSSAPI** — no kerberos in `buildInputs`, no `--with-gssapi`, no `withGSSAPI` argument — so a package override was required. It must replace the `dovecot_2_3` attribute rather than `services.dovecot2.package`, or pigeonhole is built against a different dovecot; `krb5` also has to be in `nativeBuildInputs` because of `strictDeps`. - **Two SPNs, because IMAP and submission are reached under different hostnames**, which forces `auth_gssapi_hostname = "$ALL"`. Aligning the names is not available: the two services carry different ACME certificates. - **The keytab invariant.** `$ALL` moves the trust boundary from a hostname to the keytab's contents. It is safe only while that keytab stays Dovecot's own — and **GSSAPI SSH will put `host/<fqdn>` into `/etc/krb5.keytab`**, making "just use the machine keytab" the obvious-looking change that must not be made. A comment in `dovecot.nix` will not be read by whoever writes the SSH module; this belongs in the ADR. - **Postfix needed no change**, and its risk is `reject_authenticated_sender_login_mismatch` — rejected mail rather than failed login. - **What it actually delivers**: one account of five, VPN-only, no Thunderbird auth-method fallback. Documentation only; no configuration change.

dominik.polakovics added the

ready-for-human

label

2026-08-08 02:31:14 +02:00

dominik.polakovics referenced this issue from a pull request that will close it,

2026-08-08 02:31:42 +02:00

docs(adr-0022): record the Dovecot GSSAPI cost and the keytab invariant #298

dominik.polakovics closed this issue

2026-08-08 14:28:32 +02:00