mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-12 23:58:56 +00:00
docs: Phase 4 follow-on batch 2 — 8 remaining issuer per-pages
Extracts the rest of the issuer per-connector deep-dive pages: - local-ca.md (170 lines) — Local CA self-signed / sub-CA / tree mode, CRL+OCSP endpoints, EKU support, MaxTTL enforcement, L-014 file-on- disk threat model carve-out - acme.md (235 lines) — RFC 8555 v2 client (HTTP-01 / DNS-01 / DNS-PERSIST-01), ARI per RFC 9773, EAB + ZeroSSL auto-EAB, Let's Encrypt profile selection, revoke-by-serial Top-10 fix #7 - step-ca.md (99 lines) — Smallstep JWK-provisioner synchronous issuance with MaxTTL enforcement - openssl.md (157 lines) — script-based shell-out with full threat model (what's accepted, what's not, mitigations, V3-Pro forward path) - sectigo.md (98 lines) — Sectigo SCM REST with bounded async polling - google-cas.md (89 lines) — GCP managed private CA with OAuth2 service-account auth + IAM-role guidance - entrust.md (96 lines) — Entrust CA Gateway mTLS-authenticated with approval-pending support and mTLS keypair caching - globalsign.md (122 lines) — Atlas HVCA dual auth (mTLS + API key/secret), region-aware base URLs, mTLS keypair caching Index forward-list expanded to enumerate all 13 issuer connectors (including the 5 pages from batch 1) in alphabetical order. This is part 2 of 4 for the Phase 4 follow-on (per-connector page extraction) tracked in cowork/docs-overhaul-phase-2-restructure-2026-05-04/log.md. Net add: 8 files, 1,066 lines. No content removed from index.md.
This commit is contained in:
shankar0123
@@ -0,0 +1,99 @@
|
||||
# step-ca (Smallstep) Issuer Connector — Operator Deep-Dive
|
||||
|
||||
> Last reviewed: 2026-05-05
|
||||
>
|
||||
> Operator-grade documentation for the step-ca issuer connector.
|
||||
> For the connector-development context (interface contract,
|
||||
> registry, ports/adapters), see the [connector index](index.md).
|
||||
|
||||
## Overview
|
||||
|
||||
The step-ca connector integrates with Smallstep's step-ca private
|
||||
CA using its native `/sign` API with JWK provisioner
|
||||
authentication. Issuance is synchronous — submit a CSR plus a
|
||||
provisioner-signed token, get back a signed certificate in the
|
||||
same response.
|
||||
|
||||
This is simpler than ACME for internal PKI: no challenge solving,
|
||||
no domain validation, just CSR + auth token → signed certificate.
|
||||
For ACME-based step-ca usage, point the ACME connector at
|
||||
step-ca's ACME directory URL instead.
|
||||
|
||||
Implementation lives at `internal/connector/issuer/stepca/`.
|
||||
|
||||
## When to use this connector
|
||||
|
||||
Use the step-ca connector when:
|
||||
|
||||
- You already run step-ca as your internal CA and want certctl to
|
||||
drive lifecycle automation on top.
|
||||
- You want synchronous issuance against an internal CA without
|
||||
ACME's challenge dance.
|
||||
- You want certctl to enforce profile / MaxTTL policy on step-ca-
|
||||
issued certs.
|
||||
|
||||
Look elsewhere when:
|
||||
|
||||
- You want to use step-ca's ACME directory — that path goes
|
||||
through the [ACME connector](acme.md) instead, which gives you
|
||||
ACME features (ARI, EAB, profile selection) on top.
|
||||
- You don't already run step-ca and want a simpler internal CA —
|
||||
the [Local CA](local-ca.md) issuer is a one-process alternative.
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"ca_url": "https://ca.internal:9000",
|
||||
"provisioner_name": "certctl",
|
||||
"provisioner_key_path": "/etc/certctl/stepca/provisioner.json",
|
||||
"provisioner_password": "...",
|
||||
"root_cert_path": "/etc/certctl/stepca/root_ca.crt",
|
||||
"validity_days": 90
|
||||
}
|
||||
```
|
||||
|
||||
Environment variables:
|
||||
|
||||
- `CERTCTL_STEPCA_URL` — step-ca server URL
|
||||
- `CERTCTL_STEPCA_PROVISIONER` — JWK provisioner name
|
||||
- `CERTCTL_STEPCA_KEY_PATH` — Path to provisioner private key
|
||||
(JWK JSON)
|
||||
- `CERTCTL_STEPCA_PASSWORD` — Provisioner key password
|
||||
|
||||
## Authentication: JWK provisioner
|
||||
|
||||
A JWK provisioner is created in step-ca with a passphrase-encrypted
|
||||
private key (JSON Web Key format). certctl signs short-lived
|
||||
proof-of-authorization tokens with the provisioner key for each
|
||||
issuance request. The provisioner password is needed to decrypt the
|
||||
JWK on disk; it is held in memory by certctl-server.
|
||||
|
||||
Rotation: rotate the JWK provisioner in step-ca, distribute the new
|
||||
JWK + password to certctl, then either restart certctl-server or
|
||||
hot-swap via `PUT /api/v1/issuers/{id}` so the registry's Rebuild
|
||||
path replaces the connector with the new provisioner config.
|
||||
|
||||
## MaxTTL enforcement (M11c)
|
||||
|
||||
When a certificate profile defines a maximum TTL, the step-ca
|
||||
connector caps the `NotAfter` field to ensure the issued
|
||||
certificate does not exceed the profile limit, regardless of the
|
||||
step-ca provisioner's own maximum.
|
||||
|
||||
## Revocation and CRL/OCSP
|
||||
|
||||
step-ca-issued certificates rely on step-ca's own CRL/OCSP
|
||||
infrastructure. certctl's local CRL/OCSP endpoints
|
||||
(`GET /.well-known/pki/crl/{issuer_id}` and
|
||||
`GET /.well-known/pki/ocsp/{issuer_id}/{serial}`, served
|
||||
unauthenticated per RFC 5280 §5 / RFC 6960 / RFC 8615) are
|
||||
populated from step-ca's revocation data if available, but clients
|
||||
should validate against step-ca's endpoints for the authoritative
|
||||
status.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Connector index](index.md) — interface contract, registry, port/adapter wiring
|
||||
- [ACME connector](acme.md) — alternative path to step-ca via its ACME directory URL
|
||||
- [Local CA issuer](local-ca.md) — simpler internal-CA alternative when step-ca isn't already deployed
|
||||
Reference in New Issue
Block a user