gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 13:51:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(est): document CERTCTL_EST_PROFILES + per-profile env-var family (G-3 fix)

Browse Source 
The Phase 1 commit (a808948) introduced 11 new CERTCTL_EST_PROFILE_*
env vars + the CERTCTL_EST_PROFILES list-trigger but did not document
them in docs/features.md. CI's G-3 docs-drift guard correctly flagged
the gap.

This commit adds 11 rows to docs/features.md::EST Server (RFC 7030)
covering every new env var with its phase reference, default, and
cross-check semantics. Each row includes a forward pointer to the
phase that wires the corresponding behavior:

  - CERTCTL_EST_PROFILES (Phase 1 dispatch)
  - CERTCTL_EST_PROFILE_<NAME>_ISSUER_ID (Phase 1)
  - CERTCTL_EST_PROFILE_<NAME>_PROFILE_ID (Phase 1)
  - CERTCTL_EST_PROFILE_<NAME>_ENROLLMENT_PASSWORD (Phase 3)
  - CERTCTL_EST_PROFILE_<NAME>_MTLS_ENABLED (Phase 2)
  - CERTCTL_EST_PROFILE_<NAME>_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH (Phase 2)
  - CERTCTL_EST_PROFILE_<NAME>_CHANNEL_BINDING_REQUIRED (Phase 2 / RFC 9266)
  - CERTCTL_EST_PROFILE_<NAME>_ALLOWED_AUTH_MODES (Phases 2+3)
  - CERTCTL_EST_PROFILE_<NAME>_RATE_LIMIT_PER_PRINCIPAL_24H (Phase 4)
  - CERTCTL_EST_PROFILE_<NAME>_SERVERKEYGEN_ENABLED (Phase 5)

Verified locally: G-3 guard's defined-vs-documented diff for
CERTCTL_EST_* is now empty.

Spec preserved at cowork/est-rfc7030-hardening-prompt.md.
This commit is contained in:
shankar0123
2026-04-29 22:28:48 +00:00
parent a808948397
commit 827b9cb6c8
1 changed files with 12 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features.md
+12 -2
View File
@@ -623,8 +623,18 @@ Accepts both base64-encoded DER (EST standard) and PEM-encoded PKCS#10 CSR input
| Env Var | Default | Description |
|---|---|---|
| `CERTCTL_EST_ENABLED` | `false` | Enable EST endpoints |
| `CERTCTL_EST_ISSUER_ID` | `iss-local` | Issuer for EST enrollments |
| `CERTCTL_EST_PROFILE_ID` | (none) | Optional profile constraint |
| `CERTCTL_EST_ISSUER_ID` | `iss-local` | Issuer for EST enrollments. Legacy single-issuer mode; merged into `Profiles[0]` (PathID="") by the Phase 1 back-compat shim when `CERTCTL_EST_PROFILES` is unset. |
| `CERTCTL_EST_PROFILE_ID` | (none) | Optional profile constraint. Legacy single-issuer mode (same back-compat shim as above). |
| `CERTCTL_EST_PROFILES` | (none, single-issuer mode) | **EST RFC 7030 hardening Phase 1.** Comma-separated list of EST profile names enabling **multi-endpoint dispatch**. When set, certctl exposes one `/.well-known/est/<pathID>/` endpoint group per name (e.g. `CERTCTL_EST_PROFILES=corp,iot,wifi` produces `/.well-known/est/corp/{cacerts,simpleenroll,simplereenroll,csrattrs}` etc.). Each name also drives the env-var prefix for the per-profile config below. When unset, certctl runs in legacy single-issuer mode using the flat `CERTCTL_EST_*` env vars above (which synthesise a single-element profile bound to the legacy `/.well-known/est/` root path). PathID must be a path-safe slug (`[a-z0-9-]`, no leading/trailing hyphen); names get lowercased for the URL path and uppercased for the env-var prefix. Mirrors the SCEP `CERTCTL_SCEP_PROFILES` family from the SCEP RFC 8894 master bundle (commit `6d30493`). |
| `CERTCTL_EST_PROFILE_<NAME>_ISSUER_ID` | (none) | Per-profile issuer binding when `CERTCTL_EST_PROFILES` is set. `<NAME>` is the upper-cased profile name from the list (so a `CERTCTL_EST_PROFILES` entry of `corp` resolves the issuer-id env var key with `<NAME>` replaced by `CORP`, the `_ISSUER_ID` suffix unchanged). The same per-profile env-var prefix `CERTCTL_EST_PROFILE_` is also used for `_PROFILE_ID`, `_ENROLLMENT_PASSWORD`, `_MTLS_ENABLED`, `_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH`, `_CHANNEL_BINDING_REQUIRED`, `_ALLOWED_AUTH_MODES`, `_RATE_LIMIT_PER_PRINCIPAL_24H`, `_SERVERKEYGEN_ENABLED` — see the rows below. **Required for every profile** listed in `CERTCTL_EST_PROFILES`. Each profile is independently validated at startup; per-profile failures log the offending PathID. |
| `CERTCTL_EST_PROFILE_<NAME>_PROFILE_ID` | (none) | Per-profile optional `CertificateProfile` constraint, mirroring the legacy `CERTCTL_EST_PROFILE_ID`. Leave unset to allow the issuer's defaults. **Required when `_SERVERKEYGEN_ENABLED=true`** because the Phase 5 server-keygen path needs a profile to pin `AllowedKeyAlgorithms` (the server has to decide what key to generate). |
| `CERTCTL_EST_PROFILE_<NAME>_ENROLLMENT_PASSWORD` | (none) | **EST RFC 7030 §3.2.3 alternative.** Per-profile shared secret for HTTP Basic auth on the standard `/.well-known/est/<pathID>/` route. Empty value means HTTP Basic auth is NOT required for this profile (mTLS-only or anonymous, depending on `_ALLOWED_AUTH_MODES`). Stored only in process memory; never logged. Constant-time comparison via `crypto/subtle.ConstantTimeCompare` in the handler. **Required when `_ALLOWED_AUTH_MODES` lists `basic`** (Phase 1 cross-check refuses the boot otherwise). The Phase 3 handler dispatches HTTP Basic auth using this value. |
| `CERTCTL_EST_PROFILE_<NAME>_MTLS_ENABLED` | `false` | **EST RFC 7030 hardening Phase 2 (opt-in).** When true, certctl exposes a sibling `/.well-known/est-mtls/<pathID>/` route alongside the standard `/.well-known/est/<pathID>/` route. The sibling route requires the EST client to present an mTLS client cert that chains to `_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH`. The standard route continues to honour `_ENROLLMENT_PASSWORD` (HTTP Basic) — operators can run BOTH routes simultaneously for migration / heterogeneous client fleets. mTLS is additive, not a replacement. Mirrors the SCEP `_MTLS_ENABLED` from commit `e7a3075`. |
| `CERTCTL_EST_PROFILE_<NAME>_MTLS_CLIENT_CA_TRUST_BUNDLE_PATH` | (none) | PEM bundle of CA certs that sign the client (device-bootstrap) certs the operator allows to enroll on this profile's `/.well-known/est-mtls/<pathID>/` route. **Required when `_MTLS_ENABLED=true`** (Phase 1 Validate refuses the boot otherwise). The Phase 2 startup preflight (`cmd/server/main.go::preflightESTMTLSClientCATrustBundle`, lands in Phase 2) will validate: file exists, parses as PEM, contains ≥1 cert, none expired. Reloaded on `SIGHUP` via the same `TrustAnchorHolder` primitive the SCEP/Intune trust bundle uses. |
| `CERTCTL_EST_PROFILE_<NAME>_CHANNEL_BINDING_REQUIRED` | `false` | **EST RFC 7030 hardening Phase 2 — RFC 9266 `tls-exporter` channel binding.** When true, the Phase 2 EST mTLS handler requires the CSR to carry a `id-aa-channelBindings` attribute matching the server-side `r.TLS.ConnectionState().ExportKeyingMaterial("EXPORTER-Channel-Binding", nil, 32)` output. Without this binding an attacker that bridges two TLS connections could submit a CSR over a TLS handshake authenticated by a different cert. **Refused at boot when `_MTLS_ENABLED=false`** (Phase 1 cross-check) — channel binding is meaningful only when mTLS is in use. Operators running clients that don't support RFC 9266 (older libest, etc.) can opt out per-profile by leaving this `false`. |
| `CERTCTL_EST_PROFILE_<NAME>_ALLOWED_AUTH_MODES` | (empty, no auth required) | **EST RFC 7030 hardening Phases 2 + 3.** Comma-separated list of accepted auth modes for this profile. Valid entries: `mtls`, `basic`. Empty (default) preserves the pre-Phase-1 unauthenticated behavior for back-compat (Phase 12 docs nudge operators to set this explicitly; a future bundle may flip the default to require explicit opt-in). Cross-checks at boot: `mtls` in the list requires `_MTLS_ENABLED=true`; `basic` requires `_ENROLLMENT_PASSWORD` non-empty. Unknown modes refused at boot with the offending token in the error message. |
| `CERTCTL_EST_PROFILE_<NAME>_RATE_LIMIT_PER_PRINCIPAL_24H` | `0` (disabled) | **EST RFC 7030 hardening Phase 4.** Sliding-window rate-limit cap on enrollments per `(CSR.Subject.CN, sourceIP)` pair in any rolling 24-hour window. Default `0` preserves the pre-Phase-1 unlimited behavior for back-compat; operators on production deploys set `3` (mirrors the SCEP/Intune per-device limit). Negative values refused at boot as a config typo. The Phase 4 handler dispatches via the extracted `internal/ratelimit/SlidingWindowLimiter`. |
| `CERTCTL_EST_PROFILE_<NAME>_SERVERKEYGEN_ENABLED` | `false` | **EST RFC 7030 hardening Phase 5 (opt-in).** When true, certctl exposes the `/.well-known/est/<pathID>/serverkeygen` endpoint per RFC 7030 §4.4. The server generates the keypair on behalf of the client and returns both cert + private key (the latter wrapped in CMS EnvelopedData encrypted to the client's CSR pubkey per RFC 7030 §4.4.2). Used for resource-constrained IoT devices that lack a hardware RNG. **Refused at boot when `_PROFILE_ID` is empty** (Phase 1 cross-check) — server-keygen needs a `CertificateProfile` to pin `AllowedKeyAlgorithms`. The Phase 5 handler implements the CMS EnvelopedData wire format + key zeroization discipline. |
### SCEP Server (RFC 8894)