mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 19:01:34 +00:00
feat: add EST server (RFC 7030) for device certificate enrollment (M23)
Implement Enrollment over Secure Transport protocol with 4 endpoints under /.well-known/est/ — cacerts (CA chain distribution), simpleenroll (initial enrollment), simplereenroll (certificate renewal), and csrattrs (CSR attributes). PKCS#7 certs-only wire format with hand-rolled ASN.1, accepts both PEM and base64-encoded DER CSRs, configurable issuer and profile binding, full audit trail. 28 new tests (18 handler + 10 service). Also includes: - GetCACertPEM added to issuer connector interface (all 4 issuers updated) - EST integration tests wired into e2e test suite (13 test cases) - QA testing guide Part 26 (15 manual EST test cases) - All docs updated: README, features, architecture, concepts, connectors, quickstart, demo-advanced (endpoint counts, MCP wording, agent IDs, issuer interface, resource lists, OpenSSL status) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shankar0123
+45
-3
@@ -521,10 +521,13 @@ type Connector interface {
|
||||
RenewCertificate(ctx context.Context, request RenewalRequest) (*IssuanceResult, error)
|
||||
RevokeCertificate(ctx context.Context, request RevocationRequest) error
|
||||
GetOrderStatus(ctx context.Context, orderID string) (*OrderStatus, error)
|
||||
GenerateCRL(ctx context.Context, revokedCerts []RevokedCertEntry) ([]byte, error)
|
||||
SignOCSPResponse(ctx context.Context, req OCSPSignRequest) ([]byte, error)
|
||||
GetCACertPEM(ctx context.Context) (string, error)
|
||||
}
|
||||
```
|
||||
|
||||
Built-in issuers: **Local CA** (self-signed or sub-CA mode using `crypto/x509`), **ACME v2** (HTTP-01 and DNS-01 challenges, compatible with Let's Encrypt, Sectigo, and any ACME-compliant CA), and **step-ca** (Smallstep private CA via native /sign API with JWK provisioner auth). The ACME connector uses `golang.org/x/crypto/acme`, generates an ECDSA P-256 account key, handles account registration with ToS acceptance, order creation, challenge solving (HTTP-01 via built-in server, DNS-01 via script-based hooks), order finalization, and DER-to-PEM chain conversion.
|
||||
Built-in issuers: **Local CA** (self-signed or sub-CA mode using `crypto/x509`), **ACME v2** (HTTP-01 and DNS-01 challenges, compatible with Let's Encrypt, Sectigo, and any ACME-compliant CA), **step-ca** (Smallstep private CA via native /sign API with JWK provisioner auth), and **OpenSSL/Custom CA** (script-based signing delegating to user-provided shell scripts). The ACME connector uses `golang.org/x/crypto/acme`, generates an ECDSA P-256 account key, handles account registration with ToS acceptance, order creation, challenge solving (HTTP-01 via built-in server, DNS-01 via script-based hooks), order finalization, and DER-to-PEM chain conversion. The interface also includes `GetCACertPEM(ctx)` for CA chain distribution (used by the EST server's `/cacerts` endpoint).
|
||||
|
||||
### Target Connector
|
||||
|
||||
@@ -560,6 +563,45 @@ Built-in notifiers: **Email** (SMTP), **Webhook** (HTTP POST), **Slack** (incomi
|
||||
|
||||
See the [Connector Development Guide](connectors.md) for details on building custom connectors.
|
||||
|
||||
### EST Server (RFC 7030)
|
||||
|
||||
The EST (Enrollment over Secure Transport) server provides an industry-standard enrollment interface for devices that need certificates without using the REST API. It runs under `/.well-known/est/` per RFC 7030 and supports four operations: CA certificate distribution (`/cacerts`), initial enrollment (`/simpleenroll`), re-enrollment (`/simplereenroll`), and CSR attributes (`/csrattrs`).
|
||||
|
||||
**Architecture:** EST is a handler-level protocol that delegates certificate issuance to an existing `IssuerConnector`. This means EST is not a new issuer — it's a new *interface* to the existing issuance infrastructure. The `ESTService` bridges the `ESTHandler` to whichever issuer connector is configured via `CERTCTL_EST_ISSUER_ID`.
|
||||
|
||||
```
|
||||
Client (WiFi AP, MDM, IoT)
|
||||
│
|
||||
▼
|
||||
ESTHandler (handler layer)
|
||||
│ CSR parsing, PKCS#7 response encoding
|
||||
▼
|
||||
ESTService (service layer)
|
||||
│ CSR validation, CN/SAN extraction, audit recording
|
||||
▼
|
||||
IssuerConnector (connector layer via IssuerConnectorAdapter)
|
||||
│ Certificate signing (Local CA, step-ca, etc.)
|
||||
▼
|
||||
Signed certificate returned as PKCS#7 certs-only
|
||||
```
|
||||
|
||||
**Wire format:** EST uses PKCS#7 (RFC 2315) certs-only degenerate SignedData for certificate responses and base64-encoded DER for CSR requests. The handler includes a hand-rolled ASN.1 PKCS#7 builder — no external PKCS#7 dependency. The CSR reader accepts both base64-encoded DER (standard EST wire format) and PEM-encoded PKCS#10 (convenience for debugging).
|
||||
|
||||
**Interface:** The `ESTHandler` defines an `ESTService` interface (dependency inversion, same pattern as all other handlers):
|
||||
|
||||
```go
|
||||
type ESTService interface {
|
||||
GetCACerts(ctx context.Context) (string, error)
|
||||
SimpleEnroll(ctx context.Context, csrPEM string) (*domain.ESTEnrollResult, error)
|
||||
SimpleReEnroll(ctx context.Context, csrPEM string) (*domain.ESTEnrollResult, error)
|
||||
GetCSRAttrs(ctx context.Context) ([]byte, error)
|
||||
}
|
||||
```
|
||||
|
||||
**Issuer connector extension:** EST required adding `GetCACertPEM(ctx) (string, error)` to the issuer connector interface so the `/cacerts` endpoint can serve the CA chain. The Local CA connector returns its CA certificate PEM; ACME, step-ca, and OpenSSL connectors return errors (they don't expose a static CA chain — their chains are per-issuance).
|
||||
|
||||
**Audit:** Every EST enrollment is recorded in the audit trail with `protocol: "EST"`, the CN, SANs, issuer ID, serial number, and optional profile ID.
|
||||
|
||||
## Security Model
|
||||
|
||||
### Private Key Management
|
||||
@@ -646,9 +688,9 @@ All endpoints are under `/api/v1/` and follow consistent patterns:
|
||||
- **Delete**: `DELETE /api/v1/{resources}/{id}` — returns `204` (soft delete/archive)
|
||||
- **Actions**: `POST /api/v1/{resources}/{id}/{action}` — returns `202` for async operations
|
||||
|
||||
Resources: certificates, issuers, targets, agents, jobs, policies, profiles, teams, owners, agent-groups, audit, notifications.
|
||||
Resources: certificates, issuers, targets, agents, jobs, policies, profiles, teams, owners, agent-groups, audit, notifications, discovered-certificates, discovery-scans, network-scan-targets, stats, metrics.
|
||||
|
||||
The full API is documented in an OpenAPI 3.1 specification at `api/openapi.yaml` with 93 endpoints across 19 resource domains (91 under `/api/v1/` plus `/health` and `/ready`; includes auth, 7 discovery endpoints from M18b, 6 network scan endpoints from M21, and Prometheus metrics from M22), all request/response schemas, and pagination conventions. See the [OpenAPI Guide](openapi.md) for usage with Swagger UI and SDK generation.
|
||||
The full API is documented in an OpenAPI 3.1 specification at `api/openapi.yaml` with 97 endpoints across 20 resource domains (95 under `/api/v1/` + `/.well-known/est/` plus `/health` and `/ready`; includes auth, 7 discovery endpoints from M18b, 6 network scan endpoints from M21, Prometheus metrics from M22, and 4 EST enrollment endpoints from M23), all request/response schemas, and pagination conventions. See the [OpenAPI Guide](openapi.md) for usage with Swagger UI and SDK generation.
|
||||
|
||||
Jobs support additional action endpoints: `POST /api/v1/jobs/{id}/cancel`, `POST /api/v1/jobs/{id}/approve`, `POST /api/v1/jobs/{id}/reject`.
|
||||
|
||||
|
||||
+15
-1
@@ -38,6 +38,14 @@ ACME (Automatic Certificate Management Environment) is the protocol Let's Encryp
|
||||
|
||||
certctl speaks ACME natively with both HTTP-01 and DNS-01 challenges, so it can request certificates — including wildcard certificates — from Let's Encrypt or any ACME-compatible CA without manual intervention. HTTP-01 uses a built-in temporary HTTP server for domain validation; DNS-01 uses pluggable script-based hooks to create TXT records with any DNS provider (Cloudflare, Route53, Azure DNS, etc.).
|
||||
|
||||
### EST Protocol (Enrollment over Secure Transport)
|
||||
|
||||
EST (RFC 7030) is a standard protocol for devices to request certificates from a CA. While ACME was designed for web servers proving domain ownership, EST was designed for devices that need certificates without domain validation — think WiFi access points, corporate laptops connecting to 802.1X networks, IoT devices, and mobile devices managed by MDM platforms.
|
||||
|
||||
The workflow is straightforward: a device generates a key pair and a Certificate Signing Request (CSR), sends the CSR to the EST server, and gets back a signed certificate. The EST server also distributes its CA certificate chain so devices can build a complete trust path.
|
||||
|
||||
certctl includes a built-in EST server at `/.well-known/est/` with four operations: distributing the CA certificate chain (`/cacerts`), enrolling new devices (`/simpleenroll`), renewing existing certificates (`/simplereenroll`), and advertising CSR requirements (`/csrattrs`). EST enrollment uses the same issuer connectors as the REST API — so a certificate issued via EST and a certificate issued via the dashboard go through the same CA, appear in the same inventory, and follow the same policies.
|
||||
|
||||
### Private Key
|
||||
|
||||
Every certificate has a corresponding private key. The certificate is public — anyone can see it. The private key is secret — it's what allows your server to decrypt traffic. If someone gets your private key, they can impersonate your server.
|
||||
@@ -186,10 +194,16 @@ The CLI supports both table and JSON output formats (`--format table` or `--form
|
||||
|
||||
### MCP Server (AI Integration)
|
||||
|
||||
certctl includes an MCP (Model Context Protocol) server that exposes all 78 API endpoints as MCP tools. This enables AI assistants like Claude, Cursor, and other MCP-compatible tools to interact with your certificate infrastructure using natural language — "show me all expiring certificates," "revoke the VPN cert," or "what agents are offline?"
|
||||
certctl includes an MCP (Model Context Protocol) server that exposes 78 MCP tools covering the REST API. This enables AI assistants like Claude, Cursor, and other MCP-compatible tools to interact with your certificate infrastructure using natural language — "show me all expiring certificates," "revoke the VPN cert," or "what agents are offline?"
|
||||
|
||||
The MCP server is a separate binary (`cmd/mcp-server/`) that communicates via stdio transport and acts as a stateless HTTP proxy to the certctl REST API. It requires no additional infrastructure — just point it at your certctl server URL and API key.
|
||||
|
||||
### EST Enrollment (Device Certificates)
|
||||
|
||||
certctl's EST server enables device certificate enrollment for use cases that don't fit the traditional "ops team requests a cert via API" model. When a RADIUS server is configured to use certctl for 802.1X WiFi authentication, or an MDM platform enrolls corporate devices, they use the EST protocol at `/.well-known/est/`. The EST server validates the CSR, issues a certificate via the configured issuer connector, and returns it in PKCS#7 format — the standard wire format that every EST client understands. Each enrollment is recorded in the audit trail with the protocol, common name, SANs, issuer, and serial number.
|
||||
|
||||
Enable it with `CERTCTL_EST_ENABLED=true`. Optionally bind enrollments to a specific issuer (`CERTCTL_EST_ISSUER_ID`) or certificate profile (`CERTCTL_EST_PROFILE_ID`) to constrain what EST clients can request.
|
||||
|
||||
### Certificate Discovery
|
||||
|
||||
Certificate discovery is the process of automatically finding existing certificates in your infrastructure — certificates you didn't issue through certctl, possibly issued by other CAs or tools. This is essential for building a complete inventory before you can manage everything.
|
||||
|
||||
@@ -45,6 +45,11 @@ type Connector interface {
|
||||
// SignOCSPResponse signs an OCSP response for the given certificate serial.
|
||||
// Returns nil if the issuer does not support OCSP (e.g., ACME).
|
||||
SignOCSPResponse(ctx context.Context, req OCSPSignRequest) ([]byte, error)
|
||||
|
||||
// GetCACertPEM returns the PEM-encoded CA certificate chain for this issuer.
|
||||
// Used by the EST server's /cacerts endpoint (RFC 7030).
|
||||
// Returns error if the issuer doesn't provide a static CA chain (e.g., ACME, step-ca).
|
||||
GetCACertPEM(ctx context.Context) (string, error)
|
||||
}
|
||||
|
||||
type IssuanceRequest struct {
|
||||
@@ -206,6 +211,17 @@ Each issuer handles revocation differently:
|
||||
- **step-ca**: Calls step-ca's `/revoke` API endpoint. Clients should check step-ca's own CRL/OCSP for authoritative status.
|
||||
- **OpenSSL/Custom CA**: Invokes the configured revoke script (`CERTCTL_OPENSSL_REVOKE_SCRIPT`) with the serial number as an argument.
|
||||
|
||||
### EST Integration (GetCACertPEM)
|
||||
|
||||
The `GetCACertPEM()` method returns the PEM-encoded CA certificate chain, used by the EST server's `/.well-known/est/cacerts` endpoint (RFC 7030) to distribute the CA chain to enrolling devices. Each issuer handles this differently:
|
||||
|
||||
- **Local CA**: Returns the CA certificate PEM (self-signed or sub-CA cert). This is the primary EST issuer.
|
||||
- **ACME**: Returns error — ACME CAs provide chains per-issuance, not statically.
|
||||
- **step-ca**: Returns error — step-ca serves its own `/root` endpoint for CA distribution.
|
||||
- **OpenSSL/Custom CA**: Returns error — custom script-based CAs have no CA cert access through certctl.
|
||||
|
||||
Note: EST (Enrollment over Secure Transport) is not a connector — it's a protocol handler (`internal/api/handler/est.go`) that delegates certificate issuance to whichever issuer connector is configured via `CERTCTL_EST_ISSUER_ID`. See the [Architecture Guide](architecture.md#est-server-rfc-7030) for details.
|
||||
|
||||
### Planned Issuers
|
||||
|
||||
The following issuer connectors are planned for future milestones:
|
||||
|
||||
@@ -221,7 +221,7 @@ You should see:
|
||||
|
||||
The result is a structurally valid X.509 certificate — browsers won't trust it (no root CA in their trust store), but it exercises the exact same code paths that a production ACME or Vault issuer would.
|
||||
|
||||
**Why pluggable issuers:** Different organizations use different CAs. Some use Let's Encrypt (ACME protocol), some use step-ca or internal PKI (Vault), some use commercial CAs (DigiCert, Entrust, GlobalSign), and some have custom OpenSSL-based workflows. For enterprises with ADCS, certctl can operate as a sub-CA — all issued certs chain to the enterprise root. The connector interface means certctl doesn't care — it calls `IssueCertificate()` and gets back a signed cert regardless of the backend. V1 ships with Local CA (self-signed or sub-CA), ACME (HTTP-01 + DNS-01 for wildcards), and step-ca (Smallstep private CA via native /sign API). OpenSSL/Custom CA is planned for V2; DigiCert, Vault PKI, Entrust, GlobalSign, Google CAS, and EJBCA are planned for V3.
|
||||
**Why pluggable issuers:** Different organizations use different CAs. Some use Let's Encrypt (ACME protocol), some use step-ca or internal PKI (Vault), some use commercial CAs (DigiCert, Entrust, GlobalSign), and some have custom OpenSSL-based workflows. For enterprises with ADCS, certctl can operate as a sub-CA — all issued certs chain to the enterprise root. The connector interface means certctl doesn't care — it calls `IssueCertificate()` and gets back a signed cert regardless of the backend. V1 ships with Local CA (self-signed or sub-CA), ACME (HTTP-01 + DNS-01 for wildcards), and step-ca (Smallstep private CA via native /sign API). V2 adds the OpenSSL/Custom CA connector (script-based signing). DigiCert, Vault PKI, Entrust, GlobalSign, Google CAS, and EJBCA are planned for V3+.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
@@ -472,14 +472,14 @@ In production, agents poll for work and report results. You can simulate this ma
|
||||
|
||||
```bash
|
||||
# Poll for pending deployment work (as an agent)
|
||||
curl -s "$API/api/v1/agents/agent-nginx-prod/work" | jq .
|
||||
curl -s "$API/api/v1/agents/ag-web-prod/work" | jq .
|
||||
```
|
||||
|
||||
This returns pending deployment jobs assigned to the agent. The agent would then fetch the certificate, deploy it, and report back:
|
||||
|
||||
```bash
|
||||
# Report job completion (replace JOB_ID with an actual job ID from the work response)
|
||||
curl -s -X POST "$API/api/v1/agents/agent-nginx-prod/jobs/JOB_ID/status" \
|
||||
curl -s -X POST "$API/api/v1/agents/ag-web-prod/jobs/JOB_ID/status" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"status": "Completed",
|
||||
@@ -908,7 +908,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
|
||||
## Part 15: MCP Server for AI Integration (M18a)
|
||||
|
||||
certctl exposes all 78 API endpoints as tools via the Model Context Protocol (MCP), enabling seamless integration with Claude, Cursor, and other AI assistants:
|
||||
certctl exposes 78 MCP tools covering the REST API via the Model Context Protocol (MCP), enabling seamless integration with Claude, Cursor, and other AI assistants:
|
||||
|
||||
```bash
|
||||
# Build the MCP server
|
||||
@@ -922,7 +922,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
./mcp-server
|
||||
```
|
||||
|
||||
**How it works:** The MCP server uses the official Model Context Protocol Go SDK to expose stateless HTTP proxies to all 78 API endpoints. Each MCP tool corresponds to one or more REST endpoints and includes:
|
||||
**How it works:** The MCP server uses the official Model Context Protocol Go SDK to expose 78 stateless HTTP proxy tools covering the REST API. Each MCP tool corresponds to one or more REST endpoints and includes:
|
||||
|
||||
- **Input schema** — typed arguments with JSON schema hints for LLM-friendly introspection
|
||||
- **Binary support** — handles DER-encoded CRL and OCSP responses without mangling
|
||||
|
||||
+34
-3
@@ -7,7 +7,7 @@ Complete reference of all features shipped in the V2 release (as of March 2026).
|
||||
## API Surface
|
||||
|
||||
### Overview
|
||||
- **91 endpoints** across 19 resource domains under `/api/v1/`
|
||||
- **95 endpoints** across 20 resource domains under `/api/v1/` + `/.well-known/est/`
|
||||
- REST API with HTTP semantics (GET, POST, PUT, DELETE)
|
||||
- All endpoints require authentication by default (configurable)
|
||||
- OpenAPI 3.1 spec with full schema documentation
|
||||
@@ -94,6 +94,7 @@ curl -H "$AUTH" "$SERVER/api/v1/certificates?expires_before=2026-04-24T00:00:00Z
|
||||
| **Notifications** | 3 | List, get, mark as read |
|
||||
| **Stats** | 5 | Dashboard summary, certificates by status, expiration timeline, job trends, issuance rate |
|
||||
| **Metrics** | 2 | JSON metrics (gauges, counters, uptime), Prometheus exposition format |
|
||||
| **EST (RFC 7030)** | 4 | CA certs (PKCS#7), simple enrollment, re-enrollment, CSR attributes |
|
||||
| **Health** | 4 | Health check, readiness check, auth info, auth check |
|
||||
|
||||
---
|
||||
@@ -924,9 +925,39 @@ The web dashboard is the primary operational interface for certctl. Built with *
|
||||
- CLI flags: `--server`, `--api-key`, `--format` (json/table)
|
||||
- Tested with httptest mock server; all commands covered
|
||||
|
||||
### EST Server (RFC 7030, M23)
|
||||
**Enrollment over Secure Transport** — industry-standard protocol for device certificate enrollment. Enables WiFi/802.1X, MDM, IoT, and BYOD use cases where devices need certificates without direct API access.
|
||||
|
||||
**Endpoints** (under `/.well-known/est/` per RFC 7030):
|
||||
|
||||
| Endpoint | Method | Description | Wire Format |
|
||||
|----------|--------|-------------|-------------|
|
||||
| `/cacerts` | GET | CA certificate chain distribution | Base64 PKCS#7 certs-only (application/pkcs7-mime) |
|
||||
| `/simpleenroll` | POST | Initial certificate enrollment | Request: PEM or base64-DER PKCS#10; Response: PKCS#7 |
|
||||
| `/simplereenroll` | POST | Certificate re-enrollment (renewal) | Same as simpleenroll |
|
||||
| `/csrattrs` | GET | CSR attributes the server requires | ASN.1 DER (application/csrattrs) |
|
||||
|
||||
**Architecture:**
|
||||
- **ESTService** bridges handler to existing `IssuerConnector` — no new issuance logic, reuses existing CA connectors
|
||||
- **CSR input handling** — accepts both base64-encoded DER (EST wire standard) and PEM-encoded PKCS#10 (convenience)
|
||||
- **PKCS#7 output** — hand-rolled ASN.1 degenerate SignedData builder (no external PKCS#7 dependency)
|
||||
- **CSR validation** — signature verification, Common Name extraction, SAN extraction (DNS, IP, email, URI)
|
||||
- **Configurable issuer binding** — `CERTCTL_EST_ISSUER_ID` selects which issuer connector processes enrollment
|
||||
- **Optional profile binding** — `CERTCTL_EST_PROFILE_ID` constrains enrollments to a specific certificate profile
|
||||
- **Audit trail** — all EST enrollments recorded with protocol=EST, CN, SANs, issuer ID, serial, profile ID
|
||||
|
||||
**Configuration:**
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `CERTCTL_EST_ENABLED` | `false` | Enable EST enrollment endpoints |
|
||||
| `CERTCTL_EST_ISSUER_ID` | `iss-local` | Issuer connector for EST enrollments |
|
||||
| `CERTCTL_EST_PROFILE_ID` | — | Optional profile ID to constrain enrollments |
|
||||
|
||||
**Note:** EST endpoints currently use the same middleware stack as the REST API (API key auth). TLS client certificate authentication for EST is planned for V3.
|
||||
|
||||
### OpenAPI 3.1 Specification
|
||||
- **File** — `api/openapi.yaml`
|
||||
- **Scope** — 93 operations (91 API + /health + /ready), all request/response schemas, enums, pagination
|
||||
- **Scope** — 97 operations (95 API + /health + /ready), all request/response schemas, enums, pagination
|
||||
- **Schemas** — Complete domain models with examples
|
||||
- **Enums** — Job types, states, policy rule types, notification types
|
||||
- **Pagination** — Standard envelope (data, total, page, per_page)
|
||||
@@ -1199,7 +1230,7 @@ Each guide includes an evidence summary table mapping specific criteria to certc
|
||||
|
||||
| Category | Count |
|
||||
|----------|-------|
|
||||
| **API Endpoints** | 91 (under /api/v1/) |
|
||||
| **API Endpoints** | 95 (under /api/v1/ + /.well-known/est/) |
|
||||
| **Dashboard** | Full web GUI |
|
||||
| **Issuer Connectors** | 4 (Local CA, ACME, step-ca, OpenSSL) |
|
||||
| **Target Connectors** | 5 (3 impl: NGINX, Apache, HAProxy; 2 stubs: F5, IIS) |
|
||||
|
||||
+3
-3
@@ -111,7 +111,7 @@ curl -s http://localhost:8443/api/v1/certificates/mc-api-prod/deployments | jq .
|
||||
curl -s http://localhost:8443/api/v1/agents | jq .
|
||||
|
||||
# Check agent pending work
|
||||
curl -s http://localhost:8443/api/v1/agents/agent-nginx-prod/work | jq .
|
||||
curl -s http://localhost:8443/api/v1/agents/ag-web-prod/work | jq .
|
||||
|
||||
# View audit trail
|
||||
curl -s http://localhost:8443/api/v1/audit | jq .
|
||||
@@ -322,7 +322,7 @@ export CERTCTL_API_KEY="test-key-123"
|
||||
./mcp-server
|
||||
```
|
||||
|
||||
Exposes all 78 API endpoints as MCP tools via stdio transport. Ask Claude: "What certificates are expiring in the next 30 days?", "Revoke the payments cert due to key compromise", "Show me the audit trail."
|
||||
Exposes 78 MCP tools covering the REST API via stdio transport. Ask Claude: "What certificates are expiring in the next 30 days?", "Revoke the payments cert due to key compromise", "Show me the audit trail."
|
||||
|
||||
## Demo Data Reference
|
||||
|
||||
@@ -331,7 +331,7 @@ Exposes all 78 API endpoints as MCP tools via stdio transport. Ask Claude: "What
|
||||
| Teams | 5 | Platform, Security, Payments, Frontend, Data |
|
||||
| Owners | 5 | Alice, Bob, Carol, Dave, Eve |
|
||||
| Issuers | 4 | Local Dev CA, Let's Encrypt Staging, step-ca Internal, DigiCert (disabled) |
|
||||
| Agents | 5 | nginx-prod, nginx-staging, f5-prod, iis-prod, data-agent |
|
||||
| Agents | 5 | ag-web-prod, ag-web-staging, ag-lb-prod, ag-iis-prod, ag-data-prod |
|
||||
| Targets | 5 | NGINX (prod/staging/data), F5 LB, IIS |
|
||||
| Certificates | 15 | Various statuses: Active, Expiring, Expired, Failed, Wildcard |
|
||||
| Policies | 4 | Required owner, allowed environments, max lifetime, min renewal window |
|
||||
|
||||
+241
-1
@@ -3832,9 +3832,248 @@ grep -rn "errors.Is.*errors.New\|errors.Is(.*err.*errors.New" internal/service/*
|
||||
|
||||
---
|
||||
|
||||
## Part 26: EST Server (RFC 7030)
|
||||
|
||||
**Scope:** Enrollment over Secure Transport — 4 endpoints under `/.well-known/est/` for device certificate enrollment. Tests cover CA cert distribution, certificate enrollment (PEM and base64-DER CSR formats), re-enrollment, CSR attributes, wire format compliance, and error handling.
|
||||
|
||||
**Prerequisites:** Server running with `CERTCTL_EST_ENABLED=true`, `CERTCTL_EST_ISSUER_ID=iss-local` (or a valid issuer). An ECDSA P-256 key pair and CSR for enrollment tests.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.1 — GET /.well-known/est/cacerts returns PKCS#7 CA chain**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $API_KEY" \
|
||||
http://localhost:8443/.well-known/est/cacerts
|
||||
```
|
||||
|
||||
**Expected:** HTTP 200, `Content-Type: application/pkcs7-mime`, `Content-Transfer-Encoding: base64`. Body is base64-encoded degenerate PKCS#7 SignedData containing the CA certificate chain.
|
||||
**PASS if** status = 200, correct content type, non-empty body.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.2 — GET /cacerts method enforcement**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" -X POST \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
http://localhost:8443/.well-known/est/cacerts
|
||||
```
|
||||
|
||||
**Expected:** HTTP 405 Method Not Allowed.
|
||||
**PASS if** status = 405.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.3 — POST /.well-known/est/simpleenroll with PEM CSR**
|
||||
|
||||
Generate a test CSR and submit as PEM:
|
||||
|
||||
```bash
|
||||
# Generate ECDSA P-256 key and CSR
|
||||
openssl ecparam -name prime256v1 -genkey -noout -out /tmp/est-test.key
|
||||
openssl req -new -key /tmp/est-test.key -out /tmp/est-test.csr \
|
||||
-subj "/CN=est-test.example.com" \
|
||||
-addext "subjectAltName=DNS:est-test.example.com"
|
||||
|
||||
# Submit PEM CSR
|
||||
curl -s -w "\n%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/pkcs10" \
|
||||
--data-binary @/tmp/est-test.csr \
|
||||
http://localhost:8443/.well-known/est/simpleenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 200, `Content-Type: application/pkcs7-mime`, `Content-Transfer-Encoding: base64`. Body contains base64-encoded PKCS#7 with the signed certificate.
|
||||
**PASS if** status = 200, response decodes to valid PKCS#7.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.4 — POST /simpleenroll with base64-encoded DER CSR**
|
||||
|
||||
```bash
|
||||
# Convert PEM CSR to base64-encoded DER (EST wire format)
|
||||
openssl req -in /tmp/est-test.csr -outform DER | base64 > /tmp/est-test-b64der.csr
|
||||
|
||||
curl -s -w "\n%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/pkcs10" \
|
||||
--data-binary @/tmp/est-test-b64der.csr \
|
||||
http://localhost:8443/.well-known/est/simpleenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 200. Server auto-detects base64-encoded DER and converts to PEM internally.
|
||||
**PASS if** status = 200.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.5 — POST /simpleenroll with empty body**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/pkcs10" \
|
||||
-X POST -d "" \
|
||||
http://localhost:8443/.well-known/est/simpleenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 400 Bad Request.
|
||||
**PASS if** status = 400.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.6 — POST /simpleenroll with invalid CSR**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/pkcs10" \
|
||||
-X POST -d "not-a-valid-csr-at-all" \
|
||||
http://localhost:8443/.well-known/est/simpleenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 400 Bad Request.
|
||||
**PASS if** status = 400.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.7 — POST /simpleenroll with CSR missing Common Name**
|
||||
|
||||
```bash
|
||||
openssl ecparam -name prime256v1 -genkey -noout -out /tmp/est-nocn.key
|
||||
openssl req -new -key /tmp/est-nocn.key -out /tmp/est-nocn.csr -subj "/"
|
||||
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/pkcs10" \
|
||||
--data-binary @/tmp/est-nocn.csr \
|
||||
http://localhost:8443/.well-known/est/simpleenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 500 (service returns error for missing CN). Error message should reference "Common Name".
|
||||
**PASS if** status != 200.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.8 — POST /simpleenroll method enforcement (GET not allowed)**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
http://localhost:8443/.well-known/est/simpleenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 405 Method Not Allowed.
|
||||
**PASS if** status = 405.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.9 — POST /.well-known/est/simplereenroll (re-enrollment)**
|
||||
|
||||
```bash
|
||||
openssl ecparam -name prime256v1 -genkey -noout -out /tmp/est-renew.key
|
||||
openssl req -new -key /tmp/est-renew.key -out /tmp/est-renew.csr \
|
||||
-subj "/CN=renew-est.example.com" \
|
||||
-addext "subjectAltName=DNS:renew-est.example.com"
|
||||
|
||||
curl -s -w "\n%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H "Content-Type: application/pkcs10" \
|
||||
--data-binary @/tmp/est-renew.csr \
|
||||
http://localhost:8443/.well-known/est/simplereenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 200. Functionally identical to simpleenroll per RFC 7030 Section 4.2.2.
|
||||
**PASS if** status = 200, valid PKCS#7 response.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.10 — GET /simplereenroll method enforcement**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
http://localhost:8443/.well-known/est/simplereenroll
|
||||
```
|
||||
|
||||
**Expected:** HTTP 405 Method Not Allowed.
|
||||
**PASS if** status = 405.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.11 — GET /.well-known/est/csrattrs returns 204 (no required attrs)**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
http://localhost:8443/.well-known/est/csrattrs
|
||||
```
|
||||
|
||||
**Expected:** HTTP 204 No Content (default implementation requires no specific CSR attributes).
|
||||
**PASS if** status = 204.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.12 — POST /csrattrs method enforcement**
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-X POST http://localhost:8443/.well-known/est/csrattrs
|
||||
```
|
||||
|
||||
**Expected:** HTTP 405 Method Not Allowed.
|
||||
**PASS if** status = 405.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.13 — EST enrollment creates audit event**
|
||||
|
||||
After a successful simpleenroll request (Test 26.3), query the audit trail:
|
||||
|
||||
```bash
|
||||
curl -s -H "Authorization: Bearer $API_KEY" \
|
||||
"http://localhost:8443/api/v1/audit?page=1&per_page=10" | \
|
||||
jq '.data[] | select(.action == "est_simple_enroll")'
|
||||
```
|
||||
|
||||
**Expected:** At least one audit event with `action: "est_simple_enroll"`, `protocol: "EST"` in details, and the enrolled CN in the details.
|
||||
**PASS if** audit event found with correct action and details.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.14 — EST disabled returns 404**
|
||||
|
||||
With `CERTCTL_EST_ENABLED=false` (default), EST endpoints should not be registered:
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" http://localhost:8443/.well-known/est/cacerts
|
||||
```
|
||||
|
||||
**Expected:** HTTP 404 Not Found (endpoints not registered when EST is disabled).
|
||||
**PASS if** status = 404.
|
||||
|
||||
---
|
||||
|
||||
**Test 26.15 — EST with profile binding**
|
||||
|
||||
With `CERTCTL_EST_PROFILE_ID=profile-wifi-client`, verify that audit events include the profile_id in their details:
|
||||
|
||||
```bash
|
||||
# After enrollment with profile binding, check audit
|
||||
curl -s -H "Authorization: Bearer $API_KEY" \
|
||||
"http://localhost:8443/api/v1/audit?page=1&per_page=5" | \
|
||||
jq '.data[0].details.profile_id'
|
||||
```
|
||||
|
||||
**Expected:** Profile ID appears in audit event details when configured.
|
||||
**PASS if** `profile_id` present in audit details.
|
||||
|
||||
---
|
||||
|
||||
## Release Sign-Off
|
||||
|
||||
All 25 parts must pass before tagging v2.0.0.
|
||||
All 26 parts must pass before tagging v2.0.1.
|
||||
|
||||
| Section | Pass? | Tester | Date | Notes |
|
||||
|---------|-------|--------|------|-------|
|
||||
@@ -3863,6 +4102,7 @@ All 25 parts must pass before tagging v2.0.0.
|
||||
| Part 23: Structured Logging | ☐ | | | |
|
||||
| Part 24: Documentation Verification | ☐ | | | |
|
||||
| Part 25: Regression Tests | ☐ | | | |
|
||||
| Part 26: EST Server (RFC 7030) | ☐ | | | |
|
||||
|
||||
**Automated tests (900+) must also be green.** CI passing is necessary but not sufficient — this manual QA catches integration issues that isolated unit tests miss.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user