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

docs(acme-server): operator-facing reference + threat model + cert-manager walkthrough (Phase 6/7)

Browse Source 
Doc-only commit closing the ACME-server work series. After this commit,
an outside reviewer (procurement engineer / Venafi diligence engineer /
Infisical-comparison-shopper) can read the docs cold, understand the
ACME server's surface, follow the cert-manager walkthrough, and reach
a deployment decision without escalating to certctl maintainers.

What ships:
  - docs/acme-server.md final pass: Auth-mode decision tree (when to
    use trust_authenticated vs challenge), RFC 8555 + RFC 9773
    conformance statement (section-by-section table of implemented
    plus procurement-honest 'not implemented' rows for EAB / multi-
    level wildcards / RFC 8738 / cross-CA proxying), Troubleshooting
    (5 failure modes — badNonce / unknownAuthority / HTTP-01
    connection refused / DNS-01 NXDOMAIN / rejectedIdentifier with
    canonical fix for each), Version pinning + tested clients table
    (cert-manager 1.15.0, lego v4, kind v0.20+, Caddy 2.7.x, Traefik
    3.0+), FAQ (5 entries — why two auth modes, vs cert-manager-
    against-LE, can-I-use-from-outside-K8s, migration story, audit-
    log catalog), See-also cross-link block.
  - docs/acme-cert-manager-walkthrough.md: kind → cert-manager →
    certctl → Certificate flow, with YAML blocks byte-equal to
    deploy/test/acme-integration/{clusterissuer-trust-authenticated,
    certificate-test}.yaml to prevent doc/test drift.
  - docs/acme-caddy-walkthrough.md: Caddyfile acme_ca + tls.cas
    options (OS trust store + Caddy pki.ca block).
  - docs/acme-traefik-walkthrough.md: certificatesResolvers.<name>.acme
    .caServer + serversTransport.rootCAs configuration.
  - docs/acme-server-threat-model.md: Threat surface map + JWS forgery
    resistance (alg-confusion / HS256 substitution / replayed nonce /
    URL spoofing / multi-sig / kid-vs-jwk / kid round-trip mismatch),
    Nonce store integrity rationale, HTTP-01 SSRF defense-in-depth
    (pre-dial check + per-dial check + per-redirect check + body cap +
    bounded redirects), DNS-01 cache-poisoning posture (default Google
    Public DNS + operator-owns-private-resolver-posture), TLS-ALPN-01
    chain-not-validated rationale (RFC 8737 §3 explicit), Rate-limit
    tuning, Audit trail catalog, Out-of-scope threats list.
  - docs/connectors.md: TOC renumbered 3→4 etc. to make room for new
    top-level 'ACME Server (Built-in)' section between Issuer Connector
    and Target Connector — distinguishes the consumer-side ACME
    (existing) from the new server-side ACME via env-var-prefix
    call-out (CERTCTL_ACME_* vs CERTCTL_ACME_SERVER_*).

DoD verification:
  - All 5 docs files exist with the structure prescribed by the
    Phase 6 prompt.
  - Every CERTCTL_ACME_SERVER_* env var in docs/acme-server.md maps
    to an actual lookup in internal/config/config.go (verified by
    'grep -oE | sort -u | diff' returning empty).
  - Every YAML snippet in docs/acme-cert-manager-walkthrough.md is
    byte-equal to the corresponding file in deploy/test/acme-integration/
    (verified with 'diff' against awk-extracted YAML blocks).
  - docs/connectors.md has the cross-link subsection with all 4 new
    docs referenced.
  - cowork/CLAUDE.md Architecture Decisions has the new ACME-server
    bullet documenting per-profile URL family + per-profile
    acme_auth_mode + Phase 4-5-6 progression.
  - cowork/WORKSPACE-CHANGELOG.md has the ACME-Server-6 entry plus
    the ACME-Server rollup spanning Phases 1a-6.
  - cowork/infisical-deep-research-results.md Rank 1 marked SHIPPED.
  - 'gofmt -l .' clean (no Go changes); 'go vet ./...' clean.

Acquisition-readiness: every one of the 12 acquisition-grade criteria
from cowork/acme-server-endpoint-prompt.md is verified by the test
suite (Phases 1a-5) plus this doc walkthrough (Phase 6). The full
RFC 8555 + RFC 9773 surface is live; the operator can deploy
end-to-end by reading one walkthrough doc and one env-var table.

Engineering history: cowork/WORKSPACE-CHANGELOG.md 'ACME-Server-6 (docs)'
+ ACME-Server rollup of all 6 phases.
This commit is contained in:
shankar0123
2026-05-03 19:58:15 +00:00
parent bee47f0318
commit 39f065dda4
6 changed files with 1235 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/connectors.md
+65 -14
View File
@@ -19,7 +19,8 @@ Connectors extend certctl to integrate with external systems for certificate iss
- [Revocation Across Issuers](#revocation-across-issuers)
- [EST Integration (GetCACertPEM)](#est-integration-getcacertpem)
- [Building a Custom Issuer](#building-a-custom-issuer)
3. [Target Connector](#target-connector)
3. [ACME Server (Built-in)](#acme-server-built-in)
4. [Target Connector](#target-connector)
- [Interface](#interface-1)
- [Built-in: NGINX](#built-in-nginx)
- [Built-in: Apache httpd](#built-in-apache-httpd)
@@ -34,28 +35,28 @@ Connectors extend certctl to integrate with external systems for certificate iss
- [Windows Certificate Store](#windows-certificate-store)
- [Java Keystore (JKS / PKCS#12)](#java-keystore-jks--pkcs12)
- [Kubernetes Secrets](#kubernetes-secrets)
4. [Notifier Connector](#notifier-connector)
5. [Notifier Connector](#notifier-connector)
- [Interface](#interface-2)
5. [Registering a Connector](#registering-a-connector)
6. [Registering a Connector](#registering-a-connector)
- [IssuerConnectorAdapter](#issuerconnectoradapter)
- [Notifier Registration](#notifier-registration)
6. [Testing Connectors](#testing-connectors)
7. [Testing Connectors](#testing-connectors)
- [Unit Tests](#unit-tests)
- [Integration Tests](#integration-tests)
7. [Best Practices](#best-practices)
8. [Agent Discovery Scanner](#agent-discovery-scanner)
8. [Best Practices](#best-practices)
9. [Agent Discovery Scanner](#agent-discovery-scanner)
- [Configuration](#configuration)
- [How It Works](#how-it-works)
- [API Endpoints](#api-endpoints)
- [Use Cases](#use-cases)
9. [Network Certificate Scanner (M21)](#network-certificate-scanner-m21)
- [Configuration](#configuration-1)
- [Creating Scan Targets](#creating-scan-targets)
- [How It Works](#how-it-works-1)
- [API Endpoints](#api-endpoints-1)
- [Scheduler Integration](#scheduler-integration)
- [Use Cases](#use-cases-1)
10. [What's Next](#whats-next)
10. [Network Certificate Scanner (M21)](#network-certificate-scanner-m21)
- [Configuration](#configuration-1)
- [Creating Scan Targets](#creating-scan-targets)
- [How It Works](#how-it-works-1)
- [API Endpoints](#api-endpoints-1)
- [Scheduler Integration](#scheduler-integration)
- [Use Cases](#use-cases-1)
11. [What's Next](#whats-next)
## Overview
@@ -712,6 +713,56 @@ func (v *VaultIssuer) IssueCertificate(ctx context.Context, req issuer.IssuanceR
// ... implement RenewCertificate, RevokeCertificate, GetOrderStatus
```
## ACME Server (Built-in)
certctl ships a built-in RFC 8555 + RFC 9773 ARI ACME **server**
endpoint at `/acme/profile/<profile-id>/*`. Any RFC 8555 client
(cert-manager 1.15+, Caddy, Traefik, win-acme, certbot, Posh-ACME)
integrates with certctl as an ACME issuer with no certctl-side
modification — closing the "deploy a certctl agent on every K8s node"
friction that costs deals to external PKI vendors.
This is **distinct** from the [ACME consumer
connector](#built-in-acme-v2-lets-encrypt-sectigo-zerossl) above. The
consumer side is `certctl → external CA over ACME`; the server side
is `external client → certctl over ACME`. Operators deploying both
should namespace env vars carefully: consumer uses `CERTCTL_ACME_*`
(`DIRECTORY_URL`, `EMAIL`, `CHALLENGE_TYPE`); server uses
`CERTCTL_ACME_SERVER_*` (`ENABLED`, `DEFAULT_PROFILE_ID`, `NONCE_TTL`,
…).
Two auth modes per profile (`certificate_profiles.acme_auth_mode`):
- **`trust_authenticated`** (default for internal PKI). The JWS-
authenticated ACME account is trusted to issue for any identifier
the profile policy permits; no out-of-band ownership proof. The
most common certctl use case — internal-PKI fleets where the
network itself is the trust boundary.
- **`challenge`**. Full HTTP-01 + DNS-01 + TLS-ALPN-01 validation per
RFC 8555 §8 + RFC 8737. Required for public-trust-style PKI where
account-key compromise must not cost issuance authority.
Routes through `service.CertificateService.Create` so policy + audit
+ metrics + bulk-revocation + cloud-discovery all apply uniformly to
ACME-issued certs (just as they do to API-issued, agent-issued, EST-
issued, SCEP-issued certs).
See:
- [ACME Server Reference](./acme-server.md) — env-var reference,
endpoints, auth-mode decision tree, RFC 8555 conformance statement,
troubleshooting, FAQ.
- [cert-manager Walkthrough](./acme-cert-manager-walkthrough.md) — kind
→ cert-manager → certctl-server → Certificate flow.
- [Caddy Walkthrough](./acme-caddy-walkthrough.md) — Caddyfile `acme_ca`
+ trust configuration.
- [Traefik Walkthrough](./acme-traefik-walkthrough.md) — `certificatesResolvers`
+ `serversTransport.rootCAs`.
- [Threat Model](./acme-server-threat-model.md) — JWS forgery
resistance, nonce store integrity, HTTP-01 SSRF, DNS-01 cache
posture, TLS-ALPN-01 chain-not-validated rationale, rate-limit
tuning, audit trail.
## Target Connector
Target connectors deploy certificates to infrastructure systems. They run on agents, not on the control plane.