A ctlplne studio product

Lifecycle & PQC — keeping credentials fresh, and ready for quantum

What it is

A certificate is not a "set it and forget it" object: it's issued, used, nears expiry and must be renewed, sometimes rotated (replaced early) or revoked (canceled), and eventually retired. Lifecycle automation is trstctl doing that work on a schedule. This page also covers two forward-looking concerns: crypto-agility (changing algorithms without rewriting the system) and PQC migration (moving your estate to post-quantum algorithms before quantum computers break today's keys).

The mental model: lifecycle is the superintendent who cuts a new key before the old one wears out; crypto-agility is a master key-cutting machine that can switch blank types instantly; PQC migration is the project to re-cut every key in the building to a new, quantum-resistant blank.

Why it exists

Expiry is the number-one cause of certificate outages, and it's entirely preventable: a machine that renews on schedule never lets a certificate lapse. Rotation limits the damage of a leak, since a short-lived credential is only useful briefly. The quantum transition is a multi-year migration that can't start until your cryptography is agile — able to add and swap algorithms in one place. trstctl was built crypto-agile from the first commit, so this migration is a contained change, not a rewrite.

How it works

Lifecycle automation (F6)

Revoking or retiring an identity stops future issuance and renewal attempts for that identity. Idle queued jobs become cancelled; a running rotation becomes cancelled once its related queued work has stopped. Completed deliveries and revocation publication are preserved. This does not remove a certificate from a listener or undo an external action already performed.

Cancellation derives from the retained identity transition event. Live worker and agent leases keep their result path until completion or expiry. A bounded maintenance sweep, agent claim, or startup reconciliation then cancels remaining idle work, even when scheduled renewal is disabled or a maintenance window is closed. Attempts, errors, issuance bindings, and audit history remain intact; replaying the event log does not re-arm canceled work. Canceling a renewal while keeping its identity active is not yet available.

Open an X.509 identity's detail to see the certificate from its last completed deployment or restore, including validity dates, certificate status, destination, and receipt time. The certificate link opens that exact leaf's revocation view. This is retained evidence, not a fresh connection to the listener: a subsequent replacement or an out-of-band change may serve a different certificate.

GET /api/v1/identities/{id}/deployment-evidence requires certs:read and reads only the caller's tenant. It selects one completed deployment (delivered or verified) or restore (rolled_back), ordered by receipt update time and ID. Queued and failed attempts do not displace that evidence. Certificate metadata is resolved by the receipt's exact fingerprint, including superseded and revoked leaves. An absent receipt means no retained completion; a receipt without a certificate means inventory metadata is unavailable. Neither case substitutes a certificate with a matching name or owner. The response records its read time; it does not represent an atomic history snapshot or proof for every destination.

The same read is available to scripts, including after identity retirement:

trstctl-cli identities deployment-evidence "$identity_id"

Check the returned receipt and certificate before treating a deployment as complete. To prove current application access, also connect to the destination with a native client using its normal authentication and certificate checks.

The lifecycle manager watches the inventory and acts on three signals, tenant-isolated at the database layer:

  • Renew from ARI, with an expiry fallback. For trstctl-issued X.509 identities, the scheduler evaluates the ACME Renewal Information (ARI) window and renews early once it opens, even while the certificate is still outside the fixed renew_before threshold (default 720h = 30 days), a safety fallback for certificates with no usable ARI span. Each renewal re-issues through the one issuance path with an Idempotency-Key, supersedes the old certificate in a single transaction, and emits immutable lifecycle/rotation evidence. Requester-held issuance retains the original authorized CSR through renewal; the requester keeps the private key. The deprecated server-generated path records its separate custody and key-generation event.

    A fallback longer than the certificate's entire lifetime must not cause renewal on every sweep. New endpoint leaves issued by the platform or a selected private CA retain the actual signing constructor's validity timestamp. For a selected external CA, the immutable first issuance receipt proves when trstctl received that leaf; it does not claim to know the CA's signing clock. When renew_before already covers the remaining signed lifetime at that issuance receipt, the scheduler waits for the locally computed last-third window. Thus a newly received 12-minute external leaf with a 30-day lead does not renew again on the next one-minute sweep. The CA may sign a shorter lifetime than the reviewed profile requests; inspect the returned certificate and listener. A 47-day leaf with a 30-day lead still becomes due around day 17; this repair does not shorten the configured lead or postpone that deadline. The automation plan uses the same decision as the scheduler. If a connector attempted deployment but returned a failed receipt, the plan keeps the identity visible with renewal_source: unverified_delivery, due: false, and a repair instruction. The scheduler will not use that issued certificate as a served predecessor. Repair the destination, explicitly retry renewal, and independently verify the served leaf before relying on automatic renewal. A historical deployed identity state alone is not delivery evidence.

  • Revoke with propagation. Revoke(certID, reason) is idempotent, updates the inventory, enqueues a revocation.publish to the outbox in the same transaction so a crash can't drop it, and emits certificate.revoked.

  • Alert before expiry. It finds certificates inside the alert_before window, enriches the alert with the owner and approver recipients, enqueues a notification, stamps alerted_at so it doesn't nag, and emits certificate.expiring.

  • Alert when a renewal attempt fails. A transition into renewal_failed queues one warning for the affected identity and owner. It preserves the standing deployment and points the operator to rotation history, retry status, and the listener's certificate and expiry. The warning does not imply the retry job has ended; an existing retry can still recover automatically. For a host renewal it leads with why, in plain words read from the control plane's own records (never the agent's text): the certificate authority's closed error class for the job's request (domain validation failed, no DNS-01 provider covers the name, the ACME account or finalization failed, an earlier attempt left an unconfirmed result, the attempt was ended, or the authority did not issue), or whether a certificate was signed for the job. It names Retry renewal, the one action from renewal_failed. GET /api/v1/identities/{id} carries the same cause as renewal_failure (cause, job_id, attempt) while the identity is renewal_failed, and the identity view shows it above that action.

  • The CA calendar. CA authorities run on their own clock. A leaf that expires is a page; a root that expires is an outage across every leaf beneath it, and the fix — get a new anchor into every relying party — takes quarters, not an afternoon. So the same sweep also walks ca_authorities.not_after against year-scale bands (36, 24, 12, 6 and 3 months), alerting once per band an authority crosses into, with severity scaled to the runway: a planning signal beyond a year, a warning inside one, critical inside three months. It also flags the failure that hides — an authority with less life left than the validity its leaves are issued with, which silently truncates every new leaf while issuance keeps succeeding. Alerts carry the authority, the band, how many active certificates chain to it, and the date after which leaves stop getting full validity.

The CA calendar's exact contract. Bands are 36/24/12/6/3 months, evaluated against an averaged Gregorian month; an authority sits in the tightest band it has crossed and alerts only when it crosses into a tighter one, so a repeated sweep is silent and each tightening re-fires. The band already notified is recorded on the authority and only ever tightens, so a clock skew cannot re-fire an alert the operator already saw. Authorities beyond 36 months, and authorities with no recorded not_after, raise nothing — an unknown expiry is stated as unknown, not rendered as healthy. Alerts land on the notification.ca_horizon outbox destination as ca.horizon or ca.validity_compression and fan out through the same channels as expiry alerts. The reference leaf validity is lifecycle.leaf_validity (TRSTCTL_LIFECYCLE_LEAF_VALIDITY, default 2160h/90 days); it is a yardstick for horizon reporting and caps nothing. GET /api/v1/ca/authorities carries a horizon object per authority (band, months remaining, severity, renew-by, whether truncation has started, and the leaf validity assumed), and GET /api/v1/certificates/health now resolves beyond 90 days into 180-day, 1-year, 2-year and 3-year bands — the flat "later" bucket is exactly what hid multi-year hierarchy expiry.

Status: served by the running binary. A leader-only background loop scans tenant-scoped deployed X.509 identities, honoring lifecycle.renew_before and lifecycle.alert_before (both parsed and validated at startup), and writes the normal ca.renew and notification.expiry outbox intents rather than acting inline. It's integration-tested against real PostgreSQL, NATS, the signer process, and a signed webhook sink.

Renewal-failure alerts use notification.renewal_failure, kind identity.renewal_failed, and certificate-lifecycle routing with owner/<id> and identity/<id> selectors. The lifecycle event retains the exact alert and receiver identity; its state projection and notification intent commit together. Worker and restart retries reuse that intent. Repeated failed attempts while already in renewal_failed do not create another warning; a new failure after recovery does. Historical failures without a retained notification are not backfilled. Raw CA and agent errors are excluded from the notification. Only failures recorded through this lifecycle transition produce this warning; consult job evidence for failures that have not reached a lifecycle outcome.

POST /api/v1/lifecycle/endpoint-bindings/preview is the effect-free review path. The operator must choose one exact built-in, private, or external CA; the response names that CA, key custody, destination revision, planned records, queued effects, recovery, verification, and the fingerprint that binds execution to the review. POST /api/v1/lifecycle/endpoint-bindings accepts that fingerprint and is the served end-to-end path for automated enrollment, provisioning, renewal, and endpoint binding. It creates the X.509 identity, pins the issuer, binds the route, and queues issue/deploy intents through the outbox. Initial issuance and renewal both use the pinned authority; a missing or unavailable authority fails instead of falling back. The issuer builds the deploy payload while the key is still in memory, so the connector delivers the certificate/key bundle without PEM bytes ever returning from the API response.

See and operate the live renewal plan

The Machine identities → Lifecycle automation panel answers the everyday operator questions in one place:

  • Is automatic renewal running, disabled, or waiting for a maintenance window?
  • How many days before expiry does trstctl renew and alert?
  • Which certificates are watched, due now, already in flight, or failed?
  • Is lifecycle work waiting, processing, or failed in the durable outbox?
  • Which actions are real, and where are the rotation, delivery, and rollback receipts?

The panel reads GET /api/v1/lifecycle/automation-plan; headless operators use the same contract with trstctl lifecycle automation-plan. This is an effect-free preview: it writes no row or event and contacts no CA, connector, or notification service. Its tenant-scoped inventory includes public metadata only. Certificate bytes, private keys, outbox payloads, and idempotency keys are not returned.

When an identity has successful delivery or rollback evidence, the scheduler and plan use the most recently proved certificate's expiry and renewal window. A completed restore moves that deadline back to the predecessor; queued or failed restores do not change it. Issuance history may still call that predecessor superseded; a completed restore proves it is serving again, so its earlier deadline still applies. Revoked certificates are never made renewable by a restore receipt. A later discovery scan can change the inventory source and owner observation for that same fingerprint. The retained issuance key and identity-bound delivery receipt keep its renewal binding; a scan does not erase the original issuance fact. If a later deployment fails verification, the plan shows unverified_delivery and unattended renewal waits until an operator repairs and verifies a retry. Host rollback uses the last certificate that the same agent proved serving on that target before the attempted deploy. The certificate's replaces_id can name a different leaf after an earlier restore. A replacement with the same owner and DNS name cannot inherit its predecessor's longer lifetime. An active endpoint replacement holds the predecessor's automatic renewal; the plan omits that predecessor from its watched and due counts just as the scheduler does. Verify the replacement at the listener before any revocation or retirement of the original. Identities without delivery evidence retain the legacy owner-and-name inventory match; that match alone does not prove which certificate a listener serves.

For a due or failed identity, Review renewal now or Review retry opens the normal version-bound lifecycle transition preview before anything is queued. Execution then appends the lifecycle event and the ca.renew outbox intent through the existing idempotent mutation path. Verification comes from the resulting rotation run and connector receipt, not from a green button state.

A failed agent attempt can leave the identity in renewal_failed while its existing renewal job retries. A host job keeps the subject key it generated on the host, so its next attempt resumes with the same key and request once the certificate authority answers again (a DNS-01 outage heals this way, with nothing to clear on the host). Scheduled sweeps do not start another renewal while that identity has pending or processing ca.renew or endpoint.renew work, and manual renewal previews and execution return HTTP 409 with guidance to follow the existing job while an agent is working on it. Retrying a renewal_failed identity ends a host renewal job that has already failed and that no agent holds right now: its claim, signing and result are refused from then on, and a certificate authority request it left waiting is withdrawn (superseded_by_retry). So a job stuck behind a CA result that can never arrive (an attempt the authority left unconfirmed) does not block the retry. Each new host renewal job tells its agent through which job every renewal of the target has ended, and the agent wipes a key one of those jobs left unsigned; a key an open job holds, or one whose certificate was signed, stays. Once that work is terminal, a still-due identity can be renewed again. Revocation remains available during recovery.

The control limits are intentional and visible:

  • Pause is a maintenance-window configuration action. The current web request does not silently rewrite operator configuration.
  • Resume is automatic when the next configured maintenance window opens.
  • Cancel after enqueue is not offered. A worker may already have leased the command, so claiming it was canceled could allow an unseen issuance or deployment to finish.
  • Rollback is available through Connectors only when a deployed predecessor and a connector-backed rollback procedure exist. The rotation run keeps the public rollback reference used to verify that recovery.

Crypto-agility (F16)

Crypto-agility is an architecture property, and in trstctl it's non-negotiable: all cryptography goes through a single isolated path, or an automated build check fails. An algorithm is a typed identifier; a signer is an opaque handle that signs without revealing its key; a backend (software, HSM, KMS) is one interface. Adding or swapping an algorithm is therefore a one-place change, and every backend must pass a conformance harness (ConformBackend) that signs a probe, verifies it, and confirms a wrong message and a tampered signature both fail.

Profile selection is served for classical RSA, ECDSA, and Ed25519 and, with PQC in the core since 2026-09-20, for the post-quantum and hybrid labels. Operators create profile versions with POST /api/v1/profiles or trstctl-cli profiles create -f profile.json; the API validates every allowed_key_algorithms value through internal/crypto before emitting a profile.created event, and unknown labels fail closed.

All post-quantum algorithms and issuance/signing paths — ML-DSA (FIPS 204), ML-KEM (FIPS 203), SLH-DSA (FIPS 205), hybrid certificate/key types, and PQC signer-held keys — are part of the core (internal/pqc, internal/pqcruntime) and attach in every build through cmd/trstctl/attach_families.go. They plug into the crypto and signer interfaces behind the AN-3 boundary. The core campaign tracker described next records work and evidence; the fleet executor (internal/pqcmigration) attaches beside it.

Core migration campaigns

CBOM sees the problem, so campaign ownership lives beside CBOM in core. A Free-edition operator can create a tenant-scoped campaign over existing quantum-vulnerable or out-of-policy CBOM findings, assign an owner, deadline, wave, and readiness criteria, then record work performed manually or by any external tool. No license is required: POST /api/v1/pqc/campaigns starts the campaign; the corresponding list/detail/update, readiness, finding-disposition, close, and evidence routes serve the complete workflow. The same operations are available under trstctl-cli pqc campaigns and on /posture.

The default UI/API entry point is the graph-bound action route, POST /api/v1/graph/crypto-readiness/actions. It refuses a missing, foreign, unlocated, or unattributed row, and stores the exact current readiness-row digest in the immutable campaign-start event. Existing /api/v1/pqc/campaigns remains the manual campaign API; those legacy/manual campaigns do not claim a graph binding. The console offers an explicit Track manually choice for findings whose graph row has no attributed owner. It uses that manual API and explains that the campaign does not establish dependency coverage or detect topology changes. Graph-bound campaigns refuse further mutation with 409 Conflict when a dependent edge or attributed owner changes. This prevents old coordination evidence from being applied to a newly different blast radius.

Post-quantum pilot waves (A28/A29)

A pilot proves a post-quantum leaf against real clients in stages before a rollout. POST /api/v1/pqc/pilots (trstctl-cli pqc pilots create) records an ordered plan: a name, the issuing authority whose leaf is being proven, and waves of endpoint targets, each bound to the exact leaf it must present (its SHA-256 fingerprint, address and SNI). The first wave is the canary. Each wave is one relay endpoint-verification sweep dispatched through the durable outbox in the same transaction as the immutable event that records it; the network relay performs the real handshakes and reports a signed sweep. The control plane classifies every transcript — negotiated when the client got exactly that leaf, rejected when the endpoint was reached but the handshake was refused or served a different leaf, unreachable when the dial failed — keeping each handshake's size and latency, and takes the compat-lab verdict over everything probed so far. A refusal names the expected leaf's key algorithm as the inventory records it and, where the handshake shows it, the cause (B7-L1): an endpoint that ends the handshake with a handshake_failure alert found no signature algorithm the client offers for its leaf (stock OpenSSL logs "no suitable signature algorithm"), so the result reads "the client does not offer ML-DSA-65 among its signature algorithms, so the endpoint could not sign the handshake with the ML-DSA-65 leaf and ended it"; a client that cannot verify the leaf or its signature says that instead. One refusal halts the pilot; an unreachable canary halts it too, because silence is not compatibility; otherwise the next wave is dispatched, and a pilot whose every wave negotiated completes. Waves after a halt are marked skipped and are never probed. A finished pilot's evidence is signed inside the isolated signer under its pqc-readiness-report key and returned as signed_report, which verifies offline against that key alone; GET /api/v1/pqc/pilots/{id} returns the waves, their results and verdicts. The Posture page's Post-quantum pilot waves panel starts pilots and shows each wave's outcomes, verdicts, skipped waves and the signed report.

Observed traffic (X3-L5). A pilot started with "require_observed_traffic": true (on the Posture page, "Require observed traffic before each wave advances") holds each wave after its probe. The relay's handshake shows trstctl's own client negotiating the leaf; the wave advances only once an observer agent (X1) has also seen real clients connect at every negotiated target after that probe — at its address, or its server name on the same port, or at one of the target's observed_addresses (X3-L2: the backends an observer sees behind NAT or a load balancer, host:port, at most 16; the evidence names the address it was seen at) — presenting the pilot's leaf on TLS 1.2 (TLS 1.3 encrypts the certificate, so there the probe's proof of the leaf stands). Until then the wave is awaiting_traffic and no later wave is dispatched; the leader checks every 30 seconds. Each target's evidence is kept on the wave's results: the observer finding, the TLS version and group the clients negotiated, whether that group is a post-quantum hybrid such as X25519MLKEM768, and when they were last seen. A target nobody was seen using within observed_traffic_window_seconds (default 3600, at most 604800) of the wave's assessment halts the pilot there. The signed readiness report carries the requirement and each target's mark, so its verdict is NOT READY over exactly that evidence and a reader re-derives it from the report alone.

Campaign mutations emit immutable pqc.migration_campaign.* events. PostgreSQL projections carry tenant_id and forced row-level security. Closure is rejected until the readiness gate passes and every selected finding is marked remediated or excepted with a SHA-256 evidence digest. The closure artifact is signed by the persistent audit key and binds the tenant, campaign, frozen finding digests, dispositions, evidence digests, and timestamps; its included public JWKS permits offline verification.

The canonical read and evidence routes are GET /api/v1/graph/crypto-readiness and GET /api/v1/graph/crypto-readiness/export. The latter packages the same ordered rows, owners, actions, evidence references, recommendations, and coverage limitation as CSV and NDJSON, with an audit-key JWS and public JWKS for offline verification.

Automated fleet execution is an optional executor, not a prerequisite for a useful campaign: the tracker records work and evidence on its own, and the executor (internal/pqcmigration, attached in every build) runs re-issuance with rollback when an operator starts a migration.

PQC migration orchestration (F57)

Knowing where your weak crypto is (the CBOM) is the starting point. PQC migration planning and host execution are served in every build (internal/pqcmigration). A certificate-key asset must be bound to an exact enabled host target and a requested identity whose subject key is the run's target_algorithm (ML-DSA-44, ML-DSA-65 or ML-DSA-87) before start. The identity currently serving that asset's certificate on the same target is the replacement's predecessor: it keeps serving until the host installs the successor and does not count as a competing binding, while any unrelated active identity on the target still refuses the plan. The outbox routes the work to that target's enrolled agent.

The migration API attaches POST /api/v1/pqc/migrations and POST /api/v1/pqc/migrations/{run_id}/rollback through the attach seam, so those routes are not part of the static OpenAPI golden; trstctl-cli migration start|rollback drives them, while the pqc campaigns commands record operator work and never call them. For certificate reissues, preview and start check the selected identity, target, issuer and active named profile before queueing work. A refused name returns a conflict and creates no run or outbox intent. The issuer checks the actual host CSR again at execution against the retained profile revision and effective TTL; a profile change between review and execution cannot widen the policy. Run progress comes from retained events. CBOM posture changes only with an independent observation or a verified TLS posture receipt; issuing a certificate alone does not change the algorithm the endpoint is recorded as serving.

Read GET /api/v1/pqc/migrations/{run_id} to distinguish work that was queued, issued, applied, failed, or rolled back. The console's Refresh progress action shows the bound target, certificate fingerprint, and signed listener readback. Run progress is tenant-scoped and rebuilt from retained events, including older issuance-only runs.

For a new host-bound certificate-key finding, applied requires the host's signed readback of the deployed ML-DSA leaf in the requested parameter set. The agent checks and seals the exact installed predecessor before generating a new subject key. That key stays on the host across later renewals. Each renewal updates the finding and CBOM from its own signed served-leaf readback. Host rollback restores the sealed certificate and key on the same target, even after a later renewal; rolled_back requires a signed readback of the original leaf and returns the managed identity to issued because it is no longer deployed. A cold restart finishes that lifecycle event if the process stopped after accepting the host receipt. An issued state alone is not deployment proof. Historical issuance-only certificate runs keep rollback_unverified, counted separately from rolled_back, because they have no recoverable host predecessor. Exhausted issue and rollback attempts report failed and rollback_failed.

A certificate whose current leaf is the hybrid composite can be selected for a pure ML-DSA target: the plan marks that reissue cutover and the console says it waits for acknowledgments. Starting the run queues nothing for it; the finding reads awaiting_acknowledgment and the start response counts it in certificate_cutovers_awaiting_acknowledgment. Record the identity's relying-party roster, threshold and window with trstctl pcas retirement policy set (see PCAS operations); once a quorum of signed acknowledgments for the policy's epoch is recorded inside its window, the leader queues the held host job unchanged within a minute and records pqc.migration.cutover_released with the acknowledging relying parties and the ack-set digest. From there the cutover is an ordinary host reissue: the host generates the ML-DSA key, and applied needs its signed readback. Rollback accepts only findings with an applied, rollback-eligible result in that run. For a known run whose selected finding failed before application, the API returns HTTP 409 with the finding ID and queues no recovery work. A run outside the caller's tenant, or a nonexistent run, returns HTTP 404; duplicate or empty asset IDs return HTTP 400. Correct the selection and retry with a new idempotency key. The host-bound path requires an enabled file-based host connector, an enrolled host, an explicit certificate/key path pair, a listener address and SNI, a compatible active profile and signer, and a native TLS client that can read an ML-DSA leaf. See the operator journey for the exact setup and Current limitations for coverage.

Execution status: Core includes host-bound certificate-key rollout and exact-predecessor rollback for the supported file connectors, and agent-owned Envoy TLS posture rollout and rollback: on the host agent of a co-resident Envoy, or on the network relay a remote Envoy target names (A104). Both require a signed agent readback before the observed CBOM state changes. One run rolls a posture out across several hosts, each change on its own host's agent; two container hosts prove it (A176). The core also exposes CBOM posture, profile selection, campaign tracking and proof, and PQC issuance. See Current limitations for client and connector limits. An expired commercial license does not disable Core migration or rollback; tenant authorization and idempotency requirements still apply.

Offline operator rehearsal

Run the offline rehearsal from the repository root after the pinned Go modules, container images, OpenSSL interop image, and bundled PostgreSQL artifact have been supplied locally:

make pqc-operator-lab

The lab uses a private, disposable Go build cache alongside its temporary signer, token, and database workspace. It removes that workspace after the rehearsal, including when a stage fails.

The command runs the three exact shipped-binary definition-of-done proofs: pure ML-DSA EST enrollment with stock OpenSSL, the classical/PQ SPIFFE SVID pair, and CBOM migration plus rollback. It sets the Go module resolver offline and the pinned interop runner uses --pull=never. The result is dist/pqc-operator-lab-licensed.tar.gz.

PQC is part of the core, so there is no separate edition-unavailable rehearsal. Use the command above for the shipped-binary workflow. The archive's historical licensed filename does not identify a PQC license requirement.

The archive contains a versioned manifest, one machine report and one public transcript per stage, and SHA256SUMS. Archive construction rejects private-key PEM, bearer credentials, trstctl API tokens, and non-empty password/secret/token JSON fields. The command deletes only its own private runtime directory; the receipt archive is the only retained output.

Lifetime-reduction readiness (A178)

The CA/Browser Forum's TLS Baseline Requirements shorten the maximum validity of a publicly trusted TLS server certificate in dated steps. trstctl encodes version 2.3.1 (published 2026-10-04), section 6.3.2, by issuance date:

Issued SHOULD NOT exceed MUST NOT exceed
before 2026-03-15 397 days 398 days
2026-03-15 to 2027-03-14 199 days 200 days
2027-03-15 to 2029-03-14 99 days 100 days
from 2029-03-15 46 days 47 days

The Validity Period runs from notBefore through notAfter inclusive, counted in 86,400-second days, and any part of a day is a day. A certificate whose notAfter is exactly 200 days after its notBefore is therefore 201 days long. A profile ceiling of 4800h asks for 201 days; use 4799h59m59s for 200, and 1127h59m59s for 47.

GET /api/v1/certificates/validity-readiness evaluates every active certificate under each of the three dated reductions, from the scheduler's own view of it:

  • automation: scheduled (the served certificate of a renewable lifecycle identity, or bound to one by its issuance evidence), client (issued over ACME, EST, SCEP, CMP, in-cluster Kubernetes issuance, an attested workload or the agent broker, so its client renews it) or none;
  • deployment of a scheduled certificate: verified (delivered and the served certificate read back), delivered, failed (the latest delivery or verification failed, which holds renewal) or none (no connector delivers a renewal);
  • the renewal lead: a scheduled renewal requests 30 days (less when the profile's max_validity is lower) and starts when one third of the lifetime remains, or lifecycle.renew_before before expiry if that comes first and is shorter than the lifetime.

Each step gets a verdict — renews, at_risk or manual — with reasons: scheduler_disabled, no_automated_renewal, client_renewal_unobserved, renewal_failed, renewal_paused, target_conflict, delivery_failed, deployment_unverified, no_automated_deployment, approval_required, profile_unavailable or renewal_lifetime_exceeds_maximum. Each step's summary counts the verdicts and the hand renewals a year the public TLS certificates nothing renews would need at that step's maximum.

A certificate's scope says whether the maximum binds it: public_tls when it permits TLS server authentication and asserts a CA/Browser Forum reserved policy identifier, else private_tls, not_tls_server, ca_certificate or unknown. A profile says it issues publicly trusted TLS server certificates with public_tls: true (see Authoring certificate profiles); the report flags such a profile under each step whose maximum its max_validity exceeds, or under every step when it has none. A 397-day public profile is flagged for 2026, 2027 and 2029.

GET /api/v1/certificates/validity-readiness/export returns the same report as CSV, one row per certificate or profile and step; the file name and every row name the BR version. trstctl certificates validity-readiness [export] reads both. The rogue-certificate posture applies the same dated maximum to a public TLS certificate's own lifetime, by its issuance date.

Application view for certificates (A244)

GET /api/v1/identities/{id}/application (trstctl identities application <id>, and the Application view section of an identity's detail in the console) reads everything one certificate's application depends on in one answer:

  • owner and profile: the owner, the active profile version, whether issuance needs approval, and the enrollment methods the profile permits;
  • how it was enrolled (A244-L4): the path that issued the identity's first certificate and the one that issued the active certificate — api (issued or renewed through the control plane), agent (its host agent's key and CSR), acme, est, scep or cmp, broker, attested or ephemeral — as each certificate recorded it when it was issued;
  • the exact issuer: the CA the identity is bound to (platform, private or external, by ID) and the issuer name inside the active certificate;
  • where it goes and what was seen: the destination (target, connector, configuration revision), the latest completed delivery and its fingerprint, and whether anything saw an endpoint present that certificate — the delivering connector reading it back, the serving host's agent (local) or a network agent (relay) — with matches_current false when the sighting is of an earlier certificate;
  • approvals, newest first, each naming what changed since it was asked (profile, destination or issuer); a changed one no longer covers the issuance;
  • the next automated action (renew now, renew before expiry, retry, blocked, nothing scheduled) with any failed prerequisite, the latest run, recent alerts, and the recover, revoke and retire actions with whether each applies now. The view lists the newest ten approvals and the newest ten alerts, and approvals_next_cursor and alerts_next_cursor continue them (A244-L3): GET /api/v1/identities/{id}/application/approvals?cursor= pages the identity's approval requests by keyset, and .../application/alerts?cursor= pages its alerts by reading the tenant's notifications newest first, at most 5,000 per call, with a cursor where the read stopped, so no alert is out of reach however many notifications came after it. The console's Show older approvals and Show older alerts continue each list, and say when a stretch of notifications held no alert for the certificate;
  • a value-free review plan — approve, issue from the CA, deploy to the destination, verify from the vantage that saw it last — naming exactly what each step acts on, never a value. Each step carries the effect-free transition preview's result (A244-L2): the step whose transition starts at the identity's state is previewed now, exactly as POST /api/v1/identities/{id}/transitions/preview previews it, with whether execution would go ahead, its refusals apart from its other warnings, the policy execution checks again and how to read the result back; a step the identity is already in reads accepted; a later step reads its transition from the lifecycle registry and waits_on an earlier refused step. Reading the plan writes nothing, enqueues nothing and contacts no signer or external system. The console shows each step's blocker and, on request, what execution checks and how to confirm it;
  • reusable defaults: the owner, profile and CA, which the console carries into the destination form for the next certificate.

The inventory says what each certificate is: requested, issued (no completed delivery carries the active certificate), delivered (a destination accepted it; nothing has seen it in use), served (shown as Seen in use: a readback or a clean endpoint verification observed the active certificate), revoked or retired. GET /api/v1/identities returns it on every item as inventory_state, and a renewal's new certificate starts over at delivered until something sees it.

Operations ledger sources (A245-L1)

The operations ledger (GET /api/v1/operations/ledger, trstctl operations ledger, the Operations page) reads, besides certificate rotations, connector deliveries, secret rotations and approvals:

  • agent jobs (agent_job): a host or relay agent's job, read from its command and its agent's newest signed receipt — executed reads delivered, verified reads verified, a failed or refused report reads failed or uncertain, and a claim that closed without a receipt reads uncertain; a delivery's job stays a delivery;
  • ended access sessions (access_session_revocation): a gateway session reads uncertain until its gateway reports it closed;
  • ended machine sessions (machine_session_revocation);
  • managed-key operations (managed_key_operation): a completed custody check reads verified, another completed action delivered;
  • SSH certificate revocations (ssh_certificate_revocation, certs:read): one row per revocation, named by its serial or as "a key ID" (the key ID itself is never shown), with the operator's reason and who revoked it. It reads queued until the served KRL lists it, delivered once listed (the reason names the KRL version that first listed it), and verified once every host agent that reports its KRL enforces that version or a newer one — served lists only grow, and a host refuses one that drops a revocation. The rows are a read model of the ssh.cert.revoked events, so a rebuild reproduces them, and the listing versions are rebuilt from the same events after a restart.

Each shows only to a caller who may read its domain (agents:read, access:read, secrets:read, keys:read, certs:read) and opens by its own id, such as agent_job:<number>, managed_key_operation:<operation id> or ssh_certificate_revocation:<event id>.

Revocation report: an external CA's own status (A245-L3)

For a certificate an external CA issued, the revocation report's CA facet asks that CA's own OCSP responder, named in the certificate, with the issuer kept in its chain. Only an answer the issuer signed, about that serial and not past its next update, counts: revoked reads confirmed, good reads pending (the CA has not published the revocation yet), and unknown reads failed, each with the answer's time. A certificate naming no responder, a chain without its issuer, or a responder that can't be read reads not observed, saying why. A report asks at most ten responders, five seconds each, through the outbound client that refuses private addresses.

Revocation report: existing sessions (A245-L2)

A session negotiated with a certificate keeps its keys for as long as its connection lives, after the listener serves a replacement. When a Linux host agent deploys or renews a certificate and its own handshake verifies the listener, it also counts the established connections on the listener's port and how many a process started before the deploy holds (a graceful reload keeps old workers draining theirs), read from /proc. The count rides in the deploy's signed receipt — the evidence digest covers it — and the control plane refuses one the receipt does not sign, one on another port, or counts that cannot hold together. The revocation report's existing-sessions facet then reads, on each destination that now serves a replacement, the newest count taken after that replacement's deploy: confirmed when no connection anywhere is held by an older process, pending (naming each destination and how many) while one is, and not observed when a destination was not counted or its holders could not be read. A containment stop still confirms it at once.

What a change would reach is answered before it is made: GET /api/v1/connectors/targets/{id}/impact and GET /api/v1/profiles/impact/{name} (trstctl connector target impact, trstctl profiles impact) list the certificates that use the target or profile and the open approvals the change would supersede. An issuance approval records the destination, its configuration revision and the issuer in its evidence, so editing the target, rebinding the identity or a different issuer supersedes it when it is decided or used, as a changed profile already did.

Cryptographic risk report

GET /api/v1/reports/crypto-risk lists every weak, distrusted or quantum-vulnerable key trstctl holds or has discovered, in the order to act on, with:

  • what depends on it: for a crypto inventory asset, the parties the crypto-readiness graph shows depending on the resources that use it; for a certificate, its blast radius in the credential graph;

  • the deadline that applies, from NIST IR 8547 (Transition to Post-Quantum Cryptography Standards, initial public draft, November 2024, Tables 2 and 4):

    Key Security strength Transition
    RSA, ECDSA, EC and finite-field Diffie-Hellman 112 bits (RSA/DH 2048, P-224) deprecated after 2030, disallowed after 2035
    RSA, ECDSA, EdDSA, EC and finite-field Diffie-Hellman 128 bits or more disallowed after 2035
    any below 112 bits, or rated weak or distrusted replace now

    The status says replace_now, deprecated, upcoming or none (a post-quantum or symmetric algorithm). A key whose size is unknown gets the 112-bit rule and says so;

  • the plan: the crypto-readiness campaign actions bound to the key's asset, or the recommended next step when nothing addresses it yet.

Distrusted keys come first, then weak ones, then by deadline; keys with more dependents come first within each. Every certificate is rated (its bytes when trstctl kept them, else its recorded algorithm and issuer), not one page of them. GET /api/v1/reports/crypto-risk/export returns the same report as CSV, one row per key; trstctl-cli reports crypto-risk [export] reads both.

Schedule it as the crypto_risk report type (see Compliance reporting): each run is signed and archived, and lists what changed since the schedule's previous run (keys added and resolved, priority, deadline and plan changes), after reading that run back from the archive and checking its signature. The on-demand report compares itself with the newest archived one. CNSA 2.0 milestones for national security systems are not encoded; the report says so.

In the console

In the web console, the certificate inventory at /certificates is also a lifecycle command center: expiry bands, the Lifetime-reduction readiness panel (the server's verdicts under each dated step, the public TLS profiles over its maximum, and the CSV export), deployment receipts, and a per-certificate renewal-history timeline. The profile builder's Issues publicly trusted TLS server certificates checkbox sets public_tls. The crypto-agility work surfaces at /posture as CBOM-backed algorithm posture, the complete core campaign/evidence workflow, and the Core migration executor. See The web console.

Use it

Lifecycle thresholds are configuration today:

{
  "lifecycle": {
    "renew_before": "720h",
    "alert_before": "336h"
  }
}

Both are shipped defaults (30 / 14 days). renew_before is the fallback window before expiry when trstctl re-issues absent an earlier ARI window; alert_before is when it warns. See Configuration and Operations for the full set and running behavior. PQC posture is visible in the CBOM via GET /api/v1/cbom/assets; core campaigns are served under /api/v1/pqc/campaigns, and automated fleet execution attaches in every build through internal/pqcmigration.

Pitfalls & limits

  • ARI-driven renewal covers trstctl-issued deployed X.509 identities. Rows discovered from an outside CA stay visible for expiry/risk, but renewing them needs an issuer or connector path that can actually replace that external certificate.
  • External ACME CA timing. For a certificate issued through a configured external ACME authority, a bounded outbox worker fetches that authority's renewalInfo for the exact retained certificate. The scheduler and lifecycle plan use its saved window even when it opens before or after the local estimate. A queued first fetch pauses premature local renewal briefly; a failed refresh retains the last valid CA window. A CA with no ARI advertisement uses the local window, and a near-expiry emergency can override a stale or impossible CA window. Inspect window_source and upstream_status in the ARI posture before attributing a renewal decision to the CA. Discovered certificates without authenticated external issuer provenance do not gain this upstream poll path.
  • Unknown issuance time remains unknown. Inventory discoveries and protocol issuance paths without a constructor timestamp or authenticated issuance receipt still use the fixed fallback alongside ARI. Discovery time and the backdated X.509 notBefore are not substituted for issuance time. An older local leaf can therefore renew once before its new endpoint successor gains this protection. The selected external-CA endpoint path uses its retained first issuance receipt to prevent a repeated immediate renewal; it cannot assert the upstream CA's construction time. This decision covers the served identity scheduler and its plan, not the separate fixed-threshold lifecycle.Manager.RenewExpiring library method.
  • PQC execution is core scope since 2026-09-20: PQC algorithms, automated fleet execution and the standalone pqc campaigns API/CLI/UI all attach in every build.
  • Two PQC client compatibility anchors are served in every build. Stock OpenSSL 3.5 enrolls and verifies a pure ML-DSA-65 subject leaf over EST; the stock SPIFFE Workload API receives a two-entry classical + ML-DSA-65 response. CBOM TLS findings roll out to Envoy through an enrolled host agent or a network relay, with agent-owned rollback. These client proofs do not claim that every legacy client understands ML-DSA. Hybrid-to-pure replacement of an already deployed hybrid leaf is a migration run's cutover: it waits for a quorum of signed relying-party acknowledgments under the identity's PCAS retirement policy, then queues the host reissue; direct pure enrollment is served.
  • SLH-DSA signatures are large — the conservative choice for long-lived roots, not high-volume leaf issuance; pick the algorithm per profile.
  • Lifetime-reduction readiness reads what trstctl can see. A client-renewed certificate's renewal lead is its client's, so it reads at_risk; a public TLS profile over the maximum is flagged, not refused, at issuance; the report covers the 5,000 active certificates that expire first. See Current limitations.

Reference

  • Lifetime-reduction readiness: GET /api/v1/certificates/validity-readiness, GET /api/v1/certificates/validity-readiness/export (certs:read); trstctl certificates validity-readiness [export]; profile field public_tls.
  • Config: lifecycle.renew_before (default 720h), lifecycle.alert_before (default 336h; Go duration strings); TRSTCTL_LIFECYCLE_RENEW_BEFORE, TRSTCTL_LIFECYCLE_ALERT_BEFORE.
  • Lifecycle ops: RenewExpiring, Rotate, Revoke, AlertExpiring.
  • Events: certificate.renewed, certificate.revoked, certificate.expiring; pqc.migration_campaign.started, pqc.migration_campaign.updated, pqc.migration_campaign.finding_dispositioned, pqc.migration_campaign.closed; licensed_crypto.migration.started, licensed_crypto.migration.asset_completed, licensed_crypto.migration.rollback_completed, protocol.issued.
  • CBOM migration feed: POST /api/v1/cbom/scans records cbom.asset.observed and, after a complete observation, cbom.source.reconciled; GET /api/v1/cbom/assets returns current crypto posture, available migration targets, and migration_progress.
  • PQC migration API: Core attaches POST /api/v1/pqc/migrations (CBOM certificate-key assets) and POST /api/v1/pqc/migrations/{run_id}/rollback.
  • Core PQC campaign API: /api/v1/pqc/campaigns plus detail, update, readiness, finding disposition, close, and signed-evidence export routes. The close body is optional; with no closed_by field, the server records the authenticated operator as the closure actor in the signed evidence.
  • PQC algorithms: Core includes ML-DSA (FIPS 204), ML-KEM (FIPS 203), SLH-DSA (FIPS 205), and hybrid algorithms. See the post-quantum section of Current limitations.

See also

Issuance & certificate authorities · Observability & risk (the CBOM source) · Configuration · Operations & resilience · glossary: rotation, revocation, PQC, CBOM

Covers: F6, F16, F57

Rendered live from github.com/ctlplne/trstctl — found a mistake? edit this page.