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

docs(scep): document multi-profile env vars (CERTCTL_SCEP_PROFILES + per-profile prefix)

Browse Source 
Phase 1.5 added two new env-var literals to internal/config/config.go
that the G-3 docs-drift CI guard picked up but I forgot to document
when shipping commit fdd424b:

  * CERTCTL_SCEP_PROFILES — comma-list of profile names enabling
    multi-endpoint dispatch (e.g. 'corp,iot' produces /scep/corp +
    /scep/iot).
  * CERTCTL_SCEP_PROFILE_ — the prefix string used in
    loadSCEPProfilesFromEnv's getEnv calls (e.g.
    getEnv('CERTCTL_SCEP_PROFILE_'+envName+'_ISSUER_ID', ...)). The
    G-3 regex extracts string literals between double quotes; the
    prefix is a literal even though the suffix is concatenated at
    runtime, so the scanner correctly flags it as 'defined in Go but
    not documented'.

Added 7 rows to the SCEP env-vars table in docs/features.md:
  * CERTCTL_SCEP_PROFILES (the explicit list var)
  * CERTCTL_SCEP_PROFILE_<NAME>_ISSUER_ID (per-profile issuer)
  * CERTCTL_SCEP_PROFILE_<NAME>_PROFILE_ID (per-profile cert profile)
  * CERTCTL_SCEP_PROFILE_<NAME>_CHALLENGE_PASSWORD (per-profile secret)
  * CERTCTL_SCEP_PROFILE_<NAME>_RA_CERT_PATH (per-profile RA cert)
  * CERTCTL_SCEP_PROFILE_<NAME>_RA_KEY_PATH (per-profile RA key)

Each row notes the per-profile validation contract (required for every
profile in the list, file modes, fail-loud-with-PathID semantics).

Verification: local G-3 set difference (Go-defined ∖ docs-mentioned)
empty. The literal prefix CERTCTL_SCEP_PROFILE_ now appears in
docs/features.md as the documented env-var prefix, satisfying the
scanner's substring match.
This commit is contained in:
shankar0123
2026-04-29 03:50:37 +00:00
parent fdd424bf5f
commit 294f6cff52
1 changed files with 6 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features.md
+6
View File
@@ -648,6 +648,12 @@ SCEP uses a single URL (`/scep?operation=...`). The handler extracts PKCS#10 CSR
| `CERTCTL_SCEP_CHALLENGE_PASSWORD` | (none) | Shared secret for enrollment authentication |
| `CERTCTL_SCEP_RA_CERT_PATH` | (none) | Path to PEM-encoded RA (Registration Authority) certificate. **Required when `CERTCTL_SCEP_ENABLED=true`** for the RFC 8894 PKIMessage path: SCEP clients encrypt their PKCS#10 CSR to this cert's public key (EnvelopedData wrapper, RFC 8894 §3.2.2) and the server signs the outbound CertRep PKIMessage signerInfo with the matching key (RFC 8894 §3.3.2). Generation: a self-signed cert with `CN=<your-ca-id>-RA` and the `id-kp-emailProtection` / `id-kp-cmcRA` EKU is sufficient — see [`legacy-est-scep.md`](legacy-est-scep.md) for the openssl recipe. The preflight gate at startup also enforces a cert/key match, non-expired NotAfter, and an RSA-or-ECDSA public-key algorithm. |
| `CERTCTL_SCEP_RA_KEY_PATH` | (none) | Path to PEM-encoded private key matching `CERTCTL_SCEP_RA_CERT_PATH`. **Required when `CERTCTL_SCEP_ENABLED=true`.** File MUST be mode `0600` (owner read/write only); preflight refuses to load a world- or group-readable RA key as defense-in-depth against credential leak. The server reads this file once at startup; rotation requires a restart. |
| `CERTCTL_SCEP_PROFILES` | (none, single-profile mode) | Comma-separated list of SCEP profile names enabling **multi-endpoint dispatch** (Phase 1.5). When set, certctl exposes one `/scep/<pathID>` endpoint per name (e.g. `CERTCTL_SCEP_PROFILES=corp,iot,server` produces `/scep/corp`, `/scep/iot`, `/scep/server`). Each name also drives the env-var prefix for the per-profile config below. When unset, certctl runs in legacy single-profile mode using the flat `CERTCTL_SCEP_*` env vars above (which synthesise a single-element profile bound to the legacy `/scep` 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. |
| `CERTCTL_SCEP_PROFILE_<NAME>_ISSUER_ID` | (none) | Per-profile issuer binding when `CERTCTL_SCEP_PROFILES` is set. `<NAME>` is the upper-cased profile name from the list (e.g. `CERTCTL_SCEP_PROFILE_CORP_ISSUER_ID=iss-corp-laptop`). Same per-profile env-var prefix `CERTCTL_SCEP_PROFILE_` is also used for `_PROFILE_ID`, `_CHALLENGE_PASSWORD`, `_RA_CERT_PATH`, `_RA_KEY_PATH` — see the four rows below. Required for every profile listed in `CERTCTL_SCEP_PROFILES`. Each profile is independently validated at startup; per-profile failures log the offending PathID. |
| `CERTCTL_SCEP_PROFILE_<NAME>_PROFILE_ID` | (none) | Per-profile optional `CertificateProfile` constraint, mirroring the legacy `CERTCTL_SCEP_PROFILE_ID`. Leave unset to allow the issuer's defaults. |
| `CERTCTL_SCEP_PROFILE_<NAME>_CHALLENGE_PASSWORD` | (none) | Per-profile shared secret. **Required for every profile** in `CERTCTL_SCEP_PROFILES` (CWE-306: per-profile auth boundary). Empty value at startup fails the boot with the offending PathID in the structured log. |
| `CERTCTL_SCEP_PROFILE_<NAME>_RA_CERT_PATH` | (none) | Per-profile RA certificate PEM path. Same semantics as `CERTCTL_SCEP_RA_CERT_PATH` but scoped to one profile. **Required for every profile.** |
| `CERTCTL_SCEP_PROFILE_<NAME>_RA_KEY_PATH` | (none) | Per-profile RA private key PEM path (mode `0600`). Same semantics as `CERTCTL_SCEP_RA_KEY_PATH` but scoped to one profile. **Required for every profile.** |
---