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

Files

T

shankar0123 fd94205cfa 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).

2026-05-05 03:53:52 +00:00

4.2 KiB

Raw Blame History

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.

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

Connector index — interface contract, registry, port/adapter wiring
Async CA polling — the bounded-polling primitive
ACME server — alternative issuer for DV-only workflows

4.2 KiB Raw Blame History