Skip to main content

Module key_rotation

Module key_rotation 

Source
Expand description

JWT signing key rotation — multi-slot drain/active/lead lifecycle.

Keys live in three ordered slots: lead — pre-published (nbf in the future); clients see it in JWKS but no tokens use it yet active — current issuance key drain — old active, still valid for token verification until its exp passes

The background task checks every 6 h:

  1. lead.nbf <= now → promote lead → active, old active → drain
  2. drain exp + drain_days * 86400 < now → remove drain
  3. lead is None and active.exp - now < lead_days * 86400 → generate new lead, persist

Structs§

Es256KeySlot
Es256KeySlots
Es256SigningKeyStore
KeySlot
KeySlots
MlDsaKeySlot
MlDsaKeySlots
MlDsaSigningKeyStore
RotationStores
Additional stores to rotate alongside the primary Ed25519 store.
SigningKeyStore

Functions§

global_ed25519_key_store
Get or initialize the process-wide Ed25519 rotation store.
global_ed25519_verifying_keys
Get or initialize the global published-Ed25519 verifying-key handle.
global_es256_key_store
Get or initialize the global ES256 signing key store.
global_ml_dsa_key_store
Get or initialize the global ML-DSA signing key store.
global_ml_dsa_verifying_keys
Get or initialize the global ML-DSA verifying keys Arc.
initialize_composite_key_set
Restore exact persisted associations and atomically publish the complete signing/verifying/JWKS authority. Component stores are used only to resolve identities recorded in the ledger; they are never cross-paired.
load_or_init_es256_key_store
load_or_init_key_store
Load all three JWT key slots from secrets_dir.
load_or_init_ml_dsa_key_store
load_or_init_root_identity_key_store
Load the root-DID identity rotation set, seeding the first active slot from the already-provisioned node identity key.
refresh_composite_key_set
Publish the post-rotation lifecycle as one atomic exact-pair snapshot.
refresh_ed25519_verifying_keys
Refresh the global published-Ed25519 verifying keys from a signing-key store snapshot (all current drain/active/lead slots).
refresh_ml_dsa_verifying_keys
Refresh the published ML-DSA component-key snapshot.
restore_composite_verifying_key_set
Restore the public exact-pair ledger in verifier-only service processes.
rotate_es256_keys
Returns true if the active key was promoted (lead → active). An installed in-process promotion hook is invoked before the candidate becomes visible.
rotate_jwt_keys
Returns true when every signer slot this cycle touched finished fully restored (or promoted). false means a promotion rollback failed: the durable state is only partially restored, the old active signer stays recoverable in its drain-slot copy, and callers must not treat the cycle as a clean success. A later tick retries the queued lead.
rotate_ml_dsa_keys
Returns true when every signer slot this cycle touched finished fully restored (or promoted). false means a promotion rollback failed: the durable state is only partially restored, the old active signer stays recoverable in its drain-slot copy, and callers must not treat the cycle as a clean success. A later tick retries the queued lead.
rotation_state_dir
Resolve the directory JWT rotation state is persisted to.
spawn_root_identity_rotation_task
Rotate only the root-DID Ed25519 identity set.
spawn_rotation_task

Type Aliases§

PublishedEd25519Keys
Live, shared handle to the node’s published Ed25519 rotation-slot verifying keys (drain/active/lead). This is the SAME Ed25519 key set the /oauth/jwks endpoint publishes — the keys that sign rotation-issued at+JWTs (WIT, S6 grant / token-exchange, and any issuance path using the active slot). It is public-key material only; no signing keys are ever exposed through it.