certctl/docs/reference/connectors/local-ca.md

Local CA Issuer Connector — Operator Deep-Dive

Last reviewed: 2026-05-05

Operator-grade documentation for the Local CA issuer. For the connector-development context (interface contract, registry, ports/adapters), see the connector index.

Overview

The Local CA issuer signs certificates using Go's crypto/x509 library directly inside certctl-server. There is no external CA service involved — certctl owns the signing key and emits certificates synchronously.

Implementation lives at internal/connector/issuer/local/.

When to use this connector

Use the Local CA when:

• You're standing up an internal-only PKI and don't want to operate a separate CA service (Vault, step-ca, EJBCA).
• You want certctl to be the single point of administration: signing key, profile policy, CRL and OCSP responder, and lifecycle automation all live in one process.
• You want sub-CA mode to chain into an enterprise root (ADCS, HSM-backed root, or another upstream CA) so existing trust stores validate certctl-issued leaves automatically.

Look elsewhere when:

• You need a public-trust certificate — the Local CA is internal only. Use ACME or DigiCert / Sectigo for public trust.
• You want signing material backed by an HSM or cloud KMS — that is on the roadmap (the internal/crypto/signer/ driver abstraction exists; HSM, cloud KMS, and SSH-CA drivers don't yet ship). Until those drivers ship, sub-CA mode pointing at a hardware-protected root is the closest production posture.

Modes

Self-signed mode (default)

Creates a CA on first use (in memory), issues certificates with proper serial numbers, validity periods, SANs, and key usage extensions. Designed for development and demos — certificates are self-signed and not trusted by browsers without operator-side trust-store work.

Sub-CA mode (production)

Loads a CA certificate and private key from disk (CERTCTL_CA_CERT_PATH + CERTCTL_CA_KEY_PATH). The CA cert was signed by an upstream CA (e.g. ADCS), so all issued certificates chain to the enterprise root trust hierarchy. Clients that already trust the enterprise root automatically trust certctl-issued certs.

Supports RSA, ECDSA, and PKCS#8 key formats. If the paths are not set, the connector falls back to self-signed mode. The loaded certificate must have IsCA=true and KeyUsageCertSign.

Tree mode (Rank 8 — multi-level CA hierarchy)

When Issuer.HierarchyMode = "tree" is set on the issuer row, the connector reads the active CA hierarchy from the intermediate_cas table and assembles IssuanceResult.ChainPEM by walking the parent_ca_id ancestry from the issuing leaf CA up to the root.

Tree mode is operator-managed via the admin-gated /api/v1/issuers/{id}/intermediates and /api/v1/intermediates/{id} endpoints (POST to create / sign children, GET to list / inspect, POST .../retire to two-phase retire). The signing path is shared with single-mode (cert is signed via c.caCert + c.caSigner from the on-disk issuing CA cert+key); only the chain bytes differ.

RFC 5280 §3.2 (self-signed root validation), §4.2.1.9 (path-length tightening), and §4.2.1.10 (NameConstraints subset semantics) are enforced at the service layer fail-closed. The default is single, byte-identical to the pre-Rank-8 historical flow.

See intermediate-ca-hierarchy.md for the operator runbook covering 4-level FedRAMP boundary CA, 3-level financial-services policy CA, 2-level internal-PKI patterns, and the migration runbook for flipping a single-mode issuer to tree.

Configuration

{
  "ca_common_name": "CertCtl Local CA",
  "validity_days": 90,
  "ca_cert_path": "/etc/certctl/ca/ca.pem",
  "ca_key_path": "/etc/certctl/ca/ca-key.pem"
}

CRL and OCSP (M15b)

The Local CA serves DER-encoded X.509 CRLs unauthenticated at GET /.well-known/pki/crl/{issuer_id} (RFC 5280 §5, RFC 8615, Content-Type: application/pkix-crl) with 24-hour validity.

An embedded OCSP responder at GET /.well-known/pki/ocsp/{issuer_id}/{serial} (RFC 6960, Content-Type: application/ocsp-response) returns signed OCSP responses for issued certificates (good / revoked / unknown status).

Both endpoints are reachable by relying parties with no certctl API credentials, which is how standard TLS clients, browsers, and hardware appliances consume these resources.

Certificates with profile TTL < 1 hour automatically skip CRL/OCSP — expiry is treated as sufficient revocation for short-lived credentials.

Extended Key Usage support (M27)

The Local CA respects EKU constraints from certificate profiles and adjusts key usage flags accordingly:

• S/MIME (emailProtection EKU) → DigitalSignature | ContentCommitment.
• TLS (serverAuth / clientAuth EKU) → DigitalSignature | KeyEncipherment.

This enables a single CA to issue TLS, S/MIME, code signing, and timestamping certificates from one issuer row.

MaxTTL enforcement (M11c)

When a certificate profile defines a maximum TTL, the Local CA caps the NotAfter field to min(validity_days, maxTTL). This ensures certificates never exceed the profile's configured lifetime regardless of the issuer's validity_days setting.

L-014 file-on-disk threat-model carve-out

In file-driver mode (the default), the CA private key sits on the certctl-server filesystem as a PEM at CERTCTL_CA_KEY_PATH. This is a standard internal-PKI posture but means filesystem compromise of the certctl host equals signing-key compromise. Mitigations:

• Filesystem permissions. Mode 0600, owned by the certctl service user. The connector preflight refuses to load a key whose mode is wider than 0600.
• Sub-CA rotation. Rotate the certctl sub-CA cert+key periodically (yearly is a sensible default) so a captured key has a bounded blast-radius window.
• Filesystem audit. Add an auditctl watch on the key path; any read/write attempt outside certctl-server's process is logged.
• Move to alternate signer drivers when they ship. The internal/crypto/signer/ interface is the integration seam; HSM (PKCS#11), cloud KMS, and SSH-CA drivers will close the filesystem-residency leg without changing the rest of the signing path.

Related docs

• Connector index — interface contract, registry, port/adapter wiring
• ADCS integration — sub-CA mode rooted at ADCS
• Intermediate CA hierarchy — tree mode operator runbook
• CRL and OCSP — RFC 5280 / RFC 6960 endpoint reference