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_beforethreshold (default720h= 30 days), a safety fallback for certificates with no usable ARI span. Each renewal re-issues through the one issuance path with anIdempotency-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_beforealready 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 withrenewal_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 historicaldeployedidentity state alone is not delivery evidence.Revoke with propagation.
Revoke(certID, reason)is idempotent, updates the inventory, enqueues arevocation.publishto the outbox in the same transaction so a crash can't drop it, and emitscertificate.revoked.Alert before expiry. It finds certificates inside the
alert_beforewindow, enriches the alert with the owner and approver recipients, enqueues a notification, stampsalerted_atso it doesn't nag, and emitscertificate.expiring.Alert when a renewal attempt fails. A transition into
renewal_failedqueues 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 fromrenewal_failed.GET /api/v1/identities/{id}carries the same cause asrenewal_failure(cause,job_id,attempt) while the identity isrenewal_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_afteragainst 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) ornone; - deployment of a scheduled certificate:
verified(delivered and the served certificate read back),delivered,failed(the latest delivery or verification failed, which holds renewal) ornone(no connector delivers a renewal); - the renewal lead: a scheduled renewal requests 30 days (less when the
profile's
max_validityis lower) and starts when one third of the lifetime remains, orlifecycle.renew_beforebefore 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,sceporcmp,broker,attestedorephemeral— 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) — withmatches_currentfalse 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_cursorandalerts_next_cursorcontinue 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/previewpreviews 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 readsaccepted; a later step reads its transition from the lifecycle registry andwaits_onan 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 thessh.cert.revokedevents, 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,upcomingornone(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
renewalInfofor 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. Inspectwindow_sourceandupstream_statusin 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
notBeforeare 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-thresholdlifecycle.Manager.RenewExpiringlibrary method. - PQC execution is core scope since 2026-09-20: PQC algorithms, automated fleet
execution and the standalone
pqc campaignsAPI/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 fieldpublic_tls. - Config:
lifecycle.renew_before(default720h),lifecycle.alert_before(default336h; 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/scansrecordscbom.asset.observedand, after a complete observation,cbom.source.reconciled;GET /api/v1/cbom/assetsreturns current crypto posture, available migration targets, andmigration_progress. - PQC migration API: Core attaches
POST /api/v1/pqc/migrations(CBOM certificate-key assets) andPOST /api/v1/pqc/migrations/{run_id}/rollback. - Core PQC campaign API:
/api/v1/pqc/campaignsplus detail, update, readiness, finding disposition, close, and signed-evidence export routes. The close body is optional; with noclosed_byfield, 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