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-06-12 18:48:51 +00:00 · 2026-05-05 03:53:52 +00:00
parent b452013dd9
commit fd94205cfa
6 changed files with 643 additions and 6 deletions
@@ -0,0 +1,165 @@
+# AWS ACM Private CA Issuer Connector — Operator Deep-Dive
+
+> Last reviewed: 2026-05-05
+>
+> Operator-grade documentation for the AWS Certificate Manager
+> Private Certificate Authority (ACM PCA) issuer connector. For the
+> connector-development context (interface contract, registry,
+> ports/adapters), see the [connector index](index.md).
+
+## Overview
+
+AWS ACM Private CA is a managed private CA on AWS. The connector
+calls `IssueCertificate` (which is asynchronous at the ACM PCA API
+level), then runs the SDK's `NewCertificateIssuedWaiter` until the
+cert reaches `CERTIFICATE_ISSUED` state, then `GetCertificate` to
+retrieve the PEM. Default waiter timeout is 5 minutes; tune by
+editing `defaultWaiterTimeout` in
+`internal/connector/issuer/awsacmpca/awsacmpca.go`.
+
+Implementation lives at `internal/connector/issuer/awsacmpca/`.
+
+## When to use this connector
+
+Use the AWS ACM PCA connector when:
+
+- Your workloads are AWS-native and you want the CA to live inside
+  your AWS account (for blast-radius, IAM, and audit reasons).
+- You need ACM PCA's CRL distribution and OCSP responder to serve
+  status to relying parties without certctl being in the OCSP path.
+- You want IAM-based access control (no API keys to rotate) for
+  certctl's signing path.
+
+Look elsewhere when:
+
+- You're not on AWS — Google CAS or Azure Key Vault are the cloud-
+  native equivalents on those platforms.
+- You need public-trust certificates — ACM PCA is private only.
+- You don't already pay for ACM PCA (it has a non-trivial monthly
+  cost). Vault, step-ca, or the Local CA issuer are free
+  self-hosted alternatives.
+
+## Configuration
+
+| Setting | Required | Default | Description |
+|---|---|---|---|
+| `CERTCTL_AWS_PCA_REGION` | Yes | — | AWS region (e.g. `us-east-1`) |
+| `CERTCTL_AWS_PCA_CA_ARN` | Yes | — | ARN of the ACM Private CA |
+| `CERTCTL_AWS_PCA_SIGNING_ALGORITHM` | No | `SHA256WITHRSA` | Signing algorithm |
+| `CERTCTL_AWS_PCA_VALIDITY_DAYS` | No | `365` | Certificate validity in days |
+| `CERTCTL_AWS_PCA_TEMPLATE_ARN` | No | — | Optional certificate template ARN |
+
+Supported signing algorithms: `SHA256WITHRSA`, `SHA384WITHRSA`,
+`SHA512WITHRSA`, `SHA256WITHECDSA`, `SHA384WITHECDSA`,
+`SHA512WITHECDSA`.
+
+## Authentication
+
+Standard AWS credential chain via
+`aws-sdk-go-v2/config.LoadDefaultConfig()`. Resolves credentials in
+this order:
+
+1. Environment variables (`AWS_ACCESS_KEY_ID`,
+   `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`).
+2. Shared config files (`~/.aws/config`, `~/.aws/credentials`,
+   profile via `AWS_PROFILE`).
+3. IAM Roles for Service Accounts (IRSA) on EKS.
+4. EC2 instance profiles.
+5. ECS task roles.
+6. SSO.
+
+certctl never stores AWS credentials directly — set them in the
+certctl process's environment or via the IAM role attached to the
+host.
+
+## Minimal IAM policy
+
+The IAM principal that certctl authenticates as needs the following
+actions against the CA's ARN:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "acm-pca:IssueCertificate",
+        "acm-pca:GetCertificate",
+        "acm-pca:RevokeCertificate",
+        "acm-pca:GetCertificateAuthorityCertificate"
+      ],
+      "Resource": "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012"
+    }
+  ]
+}
+```
+
+Replace the `Resource` ARN with your own CA ARN. If you use a
+`TemplateArn` (subordinate-CA template), the policy needs no
+additional permissions — `IssueCertificate` covers it.
+
+## Worked example: add the issuer via API
+
+```bash
+curl -k -X POST https://localhost:8443/api/v1/issuers \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "id": "iss-aws-prod",
+    "name": "AWS ACM PCA (prod)",
+    "type": "AWSACMPCA",
+    "config": {
+      "region": "us-east-1",
+      "ca_arn": "arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012",
+      "signing_algorithm": "SHA256WITHRSA",
+      "validity_days": 90
+    }
+  }'
+```
+
+The certctl server process must have AWS credentials available
+before the issuer is created (or before any subsequent issuance
+call). For a local dev run with shared-config creds:
+`export AWS_PROFILE=my-profile` before `docker compose up`. For an
+EKS deployment: attach an IRSA-bound IAM role to the certctl pod's
+service account.
+
+## Troubleshooting
+
+### `AccessDeniedException: User ... is not authorized to perform: acm-pca:IssueCertificate`
+
+The IAM principal certctl is using lacks the required actions.
+Apply the IAM policy above (scoped to your CA ARN) to the
+role/user. The principal can be inspected with
+`aws sts get-caller-identity` from the certctl host.
+
+### `ResourceNotFoundException: Could not find Certificate Authority`
+
+The `CAArn` doesn't match any CA in the configured region. Common
+causes: region mismatch (CA is in `us-west-2`, certctl region is
+set to `us-east-1`), CA was deleted, ARN typo. Verify with
+`aws acm-pca describe-certificate-authority --certificate-authority-arn <arn> --region <region>`.
+
+### `acmpca waiter (waiting for issuance): exceeded max wait time`
+
+The cert was submitted but didn't reach `CERTIFICATE_ISSUED` state
+within 5 minutes. Check the CA's CloudWatch metrics for backlog;
+check the CA's audit reports for any policy violations on the
+request. If the wait is consistently slow, edit
+`defaultWaiterTimeout` in
+`internal/connector/issuer/awsacmpca/awsacmpca.go` and rebuild.
+
+## Revocation
+
+CRL and OCSP are managed by AWS ACM PCA directly. certctl records
+revocations locally and notifies AWS via the `RevokeCertificate`
+API with RFC 5280 reason mapping (e.g. `keyCompromise` →
+`KEY_COMPROMISE`). AWS ACM PCA's CRL distribution point and OCSP
+responder serve the resulting status to verifying clients —
+certctl is **not** in the OCSP path for this connector.
+
+## Related docs
+
+- [Connector index](index.md) — interface contract, registry, port/adapter wiring
+- [Async CA polling](../protocols/async-ca-polling.md) — bounded-polling primitive (ACM PCA uses the SDK waiter, not certctl's polling, but the same operator concerns apply)
+- [Disaster recovery runbook](../../operator/runbooks/disaster-recovery.md) — what happens to ACM PCA-issued certs if the CA is deleted