docs: Phase 4 follow-on batch 1 — 5 issuer per-pages

Extract the first 5 issuer per-connector deep-dive pages:

- vault.md (128 lines) — Vault PKI synchronous issuance, token TTL +
  auto-renewal loop, MaxTTL enforcement, rotation playbook
- digicert.md (106 lines) — CertCentral DV/OV/EV with bounded async
  polling for vetting workflows
- aws-acm-pca.md (165 lines) — managed private CA on AWS with full
  IAM policy, IRSA wiring, troubleshooting matrix
- ejbca.md (116 lines) — open-source / Keyfactor EJBCA with mTLS or
  OAuth2 auth, mTLS keypair caching, approval-pending guidance
- adcs.md (111 lines) — Active Directory Certificate Services as
  enterprise root via Local CA sub-CA mode, sub-CA rotation playbook

Index updated with forward-list entries and the index-purpose blurb
revised so the index now positions itself as 'navigate from here;
deeper material lives in siblings' rather than 'docs to be extracted
later'.

Each per-page follows the WHAT/HOW/WHY pattern: what the connector is,
how authentication and issuance work, and when to choose this vs an
alternative. Cross-links to the connector index, async-ca-polling
primitive, and adjacent operator runbooks.

This is part 1 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: 5 files, 626 lines. No content removed from index.md (the
index keeps its inline reference; per-pages add operator depth on
top, matching the pattern set by apache/f5/iis/k8s/nginx in Phase 4
structural).
This commit is contained in:
shankar0123
2026-05-05 03:53:52 +00:00
parent b452013dd9
commit fd94205cfa
6 changed files with 643 additions and 6 deletions
+106
View File
@@ -0,0 +1,106 @@
# DigiCert CertCentral Issuer Connector — Operator Deep-Dive
> Last reviewed: 2026-05-05
>
> Operator-grade documentation for the DigiCert CertCentral issuer
> connector. For the connector-development context (interface
> contract, registry, ports/adapters), see the
> [connector index](index.md).
## Overview
The DigiCert connector integrates with DigiCert's CertCentral REST
API for ordering and managing certificates from DigiCert's commercial
public CA. It supports Domain Validated (DV), Organization Validated
(OV), and Extended Validated (EV) certificates, with async order
processing for OV/EV.
Implementation lives at `internal/connector/issuer/digicert/`.
## When to use this connector
Use the DigiCert connector when:
- You're already a DigiCert CertCentral customer and want certctl to
drive issuance, renewal, and deployment from the same platform that
manages your internal PKI.
- You need OV or EV certificates that require DigiCert to validate
organization details before issuance.
- You want one tool that covers both internal CAs (Vault, Local,
step-ca) and a public-trust commercial CA.
Look elsewhere when:
- You only need DV certificates and Let's Encrypt / ZeroSSL is an
acceptable issuer — use the ACME connector instead.
- You need self-hosted PKI with no commercial CA dependency — use
Vault PKI, step-ca, or the Local CA issuer.
## Configuration
| Variable | Default | Description |
|---|---|---|
| `CERTCTL_DIGICERT_API_KEY` | — | DigiCert API key (sent in `X-DC-DEVKEY` header) |
| `CERTCTL_DIGICERT_ORG_ID` | — | DigiCert organization ID |
| `CERTCTL_DIGICERT_PRODUCT_TYPE` | `ssl_basic` | Certificate product (e.g. `ssl_basic`, `ssl_plus`, `ssl_ev`) |
| `CERTCTL_DIGICERT_BASE_URL` | `https://www.digicert.com/services/v2` | DigiCert API base URL |
| `CERTCTL_DIGICERT_POLL_MAX_WAIT_SECONDS` | `600` | Bounded-polling deadline for `GetOrderStatus` |
## Authentication
API key passed via `X-DC-DEVKEY` header. The organization ID is sent
in the request body (not the header). No mTLS or OAuth2 required.
## Issuance model
- **DV certificates** — typically issue immediately; the
`/order/certificate/create` API may return the PEM in the same
response.
- **OV / EV certificates** — require DigiCert-side validation
(vetting org documents, checking domain ownership). The API
returns 201 with an order ID; certctl's `GetOrderStatus` polls
until the certificate is retrievable.
`GetOrderStatus` runs bounded internal polling (5s/15s/45s/2m/5m
capped, ±20% jitter, default 10-minute deadline). For OV/EV orders
where humans approve enrollments, bump
`CERTCTL_DIGICERT_POLL_MAX_WAIT_SECONDS` to a value that comfortably
covers the approval window — see
[async-ca-polling.md](../protocols/async-ca-polling.md) for the
schedule shape and tuning guidance.
## Revocation
CRL and OCSP are managed by DigiCert. Clients should validate
certificate status against DigiCert's infrastructure. certctl
records the revocation locally (audit row + cert state) but does
**not** call DigiCert's revoke endpoint — operators revoke through
DigiCert's dashboard or the CertCentral REST API directly. This
keeps the certctl revocation flow simple at the cost of one extra
manual step on revocation.
## Operator playbook
### API key rotation
Rotate the API key in DigiCert's dashboard, then either restart
certctl-server with the new value in `CERTCTL_DIGICERT_API_KEY` or
hot-swap via `PUT /api/v1/issuers/{id}` so the registry's Rebuild
path replaces the connector with the new key. No certificate
state is invalidated by the rotation — the new key just signs
future API calls.
### Diagnosing slow OV/EV issuance
DigiCert's OV/EV vetting is a human process and can take hours to
days. Bumping `CERTCTL_DIGICERT_POLL_MAX_WAIT_SECONDS` lets a
single tick wait through the full approval window, but the better
operational pattern is to issue OV/EV certs well ahead of expiry
so the bounded poll deadline is short. The renewal scheduler's
"alert at T-30 days" default exists for exactly this reason.
## Related docs
- [Connector index](index.md) — interface contract, registry, port/adapter wiring
- [Async CA polling](../protocols/async-ca-polling.md) — the bounded-polling primitive
- [ACME server](../protocols/acme-server.md) — alternative issuer for DV-only workflows