mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 22:31:36 +00:00
shankar0123
de06141ce5
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.
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# 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
|