dohertj2/mxaccessgw
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: implementation plan for gateway TLS auto-cert and lenient client trust

Browse Source
This commit is contained in:
Joseph Doherty
2026-06-01 07:01:58 -04:00
parent 6bfa4fe884
commit c4e7ddea70
3 changed files with 1231 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2026-06-01-gateway-cert-autogen-design.md
+11 -5
View File
@@ -50,9 +50,12 @@ New type `SelfSignedCertificateProvider` in
day` (clock-skew slack), `notAfter = now + ValidityYears`. SANs: `DNS=localhost`,
`DNS=<MachineName>`, `DNS=<MachineName.FQDN>` when resolvable, plus
`IP=127.0.0.1` and `IP=::1`. Server-auth EKU.
4. **Persist securely.** Write the PFX with a random in-memory-only export password;
restrictive ACL (SYSTEM + Administrators + service account) on the `certs`
directory and file; atomic write (temp + rename).
4. **Persist securely.** Write the PFX with an **empty** export password (a random
in-memory password cannot be reused across restarts, which the persist-and-reuse
decision requires); protect the private key with a restrictive ACL (SYSTEM +
Administrators + service account) on the `certs` directory and file on Windows,
and `0600` on non-Windows; atomic write (temp + rename). After generating, the
cert is reloaded from the persisted PFX so Kestrel always serves the on-disk key.
5. **Wire into Kestrel.** In `GatewayApplication.CreateBuilder`, add
`builder.WebHost.ConfigureKestrel(o => o.ConfigureHttpsDefaults(h =>
h.ServerCertificate = cert))`. `ConfigureHttpsDefaults` supplies the cert only
@@ -71,8 +74,11 @@ All optional; the zero-config path needs none of them.
| `Tls:AdditionalDnsNames` | `[]` | Extra SANs (e.g. a load-balancer name) |
| `Tls:RegenerateIfExpired` | `true` | Auto-replace an expired persisted cert |
Validated by `GatewayOptionsValidator`: path non-empty when TLS is active,
`ValidityYears` in 1–100.
Validated by `GatewayOptionsValidator`: `ValidityYears` in 1–100,
`SelfSignedCertPath` is a valid path shape when non-blank, and
`AdditionalDnsNames` entries are non-blank. (The "https endpoint exists but cert
path is blank" fail-fast lives in the bootstrap/provider, not the validator,
because the validator only sees the `MxGateway` section, not `Kestrel:Endpoints`.)
**Logging:** on generate/load, log thumbprint + SAN list + `notAfter` at
Information. Never log the PFX password or private key.