mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 13:41:30 +00:00

Files

T

shankar0123 de06141ce5 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.

2026-05-05 03:59:35 +00:00

3.6 KiB

Raw Blame History

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.

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 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 issuer is a one-process alternative.

Configuration

{
  "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.

Connector index — interface contract, registry, port/adapter wiring
ACME connector — alternative path to step-ca via its ACME directory URL
Local CA issuer — simpler internal-CA alternative when step-ca isn't already deployed

3.6 KiB Raw Blame History