certctl/docs/reference/profiles.md

Certificate profiles

Last reviewed: 2026-05-09

A CertificateProfile is the policy object that groups every cert with the same shape: which issuer mints it, which key algorithm + size are allowed, what EKUs and SANs the issuer should emit, what renewal window the scheduler uses, what targets get the cert deployed to. Every managed certificate references exactly one profile; changing a profile's policy retroactively affects renewal of every cert pointing at it.

This file documents the profile lifecycle as it stands after Bundle 1. For the schema, see migrations/000003_certificate_profiles.up.sql + migrations/000027_approval_workflow.up.sql + migrations/000033_approval_kinds.up.sql. For the API surface, see api/openapi.yaml under /api/v1/profiles.

Anatomy

Field	Default	Purpose
id	autogenerated prof-<slug>	Stable opaque identifier; used by every other resource.
name	required	Human-readable label; rendered in the GUI's profile picker.
issuer_id	required	Which issuer (Local / Vault / EJBCA / ACME / SCEP / EST / ADCS / etc.) mints certs against this profile.
default_validity_days	90	Rendered into the issuer call as the requested NotAfter delta.
renewal_window_days	30	Scheduler enqueues a renewal Job when cert.NotAfter - now < renewal_window_days.
allowed_key_algorithms	RSA 2048+, ECDSA P-256+	Validates incoming CSRs at issuance time.
allowed_ekus	server, client	RFC 5280 §4.2.1.12 EKU set.
must_staple	false	Per-profile RFC 7633 id-pe-tlsfeature extension toggle (Phase 5.6 of the SCEP master bundle).
requires_approval	false	Bundle 1 Phase 9 — gates issuance + renewal AND profile edits behind a four-eyes approval workflow. See below.

RequiresApproval and the approval workflow

Setting requires_approval=true on a profile does two things:

1. Issuance + renewal of every cert pointing at the profile gates on a non-requester admin's approval. The scheduler enqueues a Job at status AwaitingApproval; the linked issuance_approval_requests row stays at pending until either approved (job → Pending, scheduler dispatches) or rejected (job → Cancelled). Same actor cannot self-approve.
2. Edits to the profile itself gate on a non-requester admin's approval. This is the Bundle 1 Phase 9 closure for the flip-flop loophole — without it an admin could set requires_approval=false, mutate any other field, set requires_approval=true, and the approval workflow would only have been bypassed during the "off" window. The Phase 9 gate fires under three conditions:
   • The live profile has requires_approval=true AND the operator submits any edit (regardless of whether the edit changes the flag).
   • The live profile has requires_approval=false AND the operator submits an edit that would set it to true (the flag-flip direction is gated too because otherwise the gate could be enabled by anyone and have no review).
   • Both arms route through ApprovalService.RequestProfileEditApproval which writes a row to issuance_approval_requests with approval_kind=profile_edit. The pending profile diff is serialized to payload (JSONB).

Edit response shape. When the gate fires, PUT /api/v1/profiles/{id} returns HTTP 202 Accepted with body {"status":"pending_approval","pending_approval_id":"ar-…"}. The operator copies the approval ID, hands it to a peer admin, and the peer POSTs /api/v1/approvals/{id}/approve with their own credentials. On approve, the server deserializes payload, applies the diff against the live profile, and emits a profile.edit_applied audit row with event_category=auth. On reject, the pending row is dropped; the live profile is unchanged.

Same-actor self-approve is rejected with HTTP 403 and the existing ErrApproveBySameActor sentinel. This is the load-bearing two-person-integrity invariant that satisfies SOC 2 CC6.3 + NIST SSDF PO.5.2.

Bypass mode. CERTCTL_APPROVAL_BYPASS=true short-circuits both issuance approvals and profile-edit approvals; every request auto-approves with actor=system-bypass. Used by dev / CI for fast iteration; production deploys MUST leave it unset. A single SQL query (SELECT FROM audit_events WHERE actor='system-bypass') confirms zero rows.

Operator workflows

Enable approval for an existing profile. Edit the profile, set requires_approval=true. The first time you do this, the edit itself is gated (the live profile is non-approval but the proposed state is approval-tier, so the flip-on direction still routes through the workflow). Hand the approval ID to a peer; once approved, every subsequent edit and every renewal of every cert pointing at the profile gates on the workflow.

Disable approval. Edit the profile, set requires_approval=false. This edit is gated because the live profile is currently approval-tier. A peer must approve the disable. Once disabled, subsequent edits flow through the direct-apply path again.

Audit who approved what. The audit trail records every approval request + decision under event_category=auth. Filter via GET /api/v1/audit?category=auth or the auditor role's audit-only view. Each row carries the approval ID + the requester

• the decider; the WORM trigger prevents tampering.

Related

• migrations/000027_approval_workflow.up.sql (initial approval schema, Rank 7 of the 2026-05-03 deep-research deliverable)
• migrations/000033_approval_kinds.up.sql (Phase 9 — adds approval_kind + payload + nullable cert/job FKs)
• internal/service/approval.go::RequestProfileEditApproval
• internal/service/profile.go::UpdateProfile (gate)
• internal/api/handler/profiles.go::UpdateProfile (202 mapping)
• cowork/auth-bundle-1-prompt.md (Phase 9 spec)