Key management#

Every key that can sign an identity, a checkpoint or a licence, or decrypt stored data, is customer-held. MAQPNA never holds, escrows or phones home with a key. Keys are referenced either by a file path mounted from a Kubernetes Secret, or by a key URI resolved by pkg/keys.

Key URIs#

Azure Key Vault authentication, first that applies: AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET (client credentials); AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_FEDERATED_TOKEN_FILE (workload identity); then az account get-access-token. For a sovereign cloud, give the vault's full host name.

Key IDs are RFC 7638 JWK thumbprints everywhere, so a kid in a token, checkpoint or card names exactly one public key.

Sealers encrypt data at rest. keys.ParseSealerURI accepts file:/// (a 32-byte AES-256 key) and, when registered, pkcs11: or kms://. AESGCMSealer uses AES-256-GCM with a random 96-bit nonce and key ID aes256gcm:<16 hex>; a Keyring holds one primary key and any retired keys, so data sealed under an old key still opens after rotation.

Which component holds which key#

flowchart LR
    subgraph IDN["maqpna-identity"]
      K1["identity signing key<br/>Ed25519, -key file"]
      K2["tenant signing keys<br/>Secret maqpna-tenant-keys"]
    end
    subgraph GWN["maqpna-gateway"]
      K3["audit checkpoint key<br/>auditCheckpointKey URI"]
      K4["HMAC checkpoint key<br/>MAQPNA_AUDIT_HMAC_KEY"]
      K5["token vault key<br/>tokenVault.keyURI sealer"]
      K6["capture key<br/>captureArgs key sealer"]
      K7["Txn-Token key<br/>txnTokens.signingKey"]
      K8["A2A card key<br/>a2a.cardSigningKey"]
    end
    subgraph ATN["maqpna-attest"]
      K9["response signing key<br/>-response-signing-key file"]
    end
    subgraph CLI["maqpna CLI, offline"]
      K10["licence signing key<br/>file or azurekv URI"]
      K11["usage report key<br/>file URI"]
    end
    K1 -- "JWKS /.well-known/jwks.json" --> V1["gateway, broker verify tokens"]
    K3 -- "JWKS /v1/audit/jwks" --> V2["auditors verify checkpoints<br/>and erasure certificates"]
    K8 -- "JWKS /a2a/jwks.json" --> V3["remote A2A peers"]
    K9 -- "public key to the operator" --> V4["attest agents in the VM"]

Rotation#

maqpna keys rotate rotates a key without downtime. Every key lives in a Secret mounted as a directory, and the servers also load sibling files next to the active key, so a rotation edits the Secret and restarts the Deployment that reads it:

1. maqpna keys rotate identity generates a new key and keeps the old one as previous-<kid>.pem.
2. It restarts the broker, then waits for gateways to pick up the new JWKS (--jwks-wait, default 5m30s) or restarts them (--restart-gateway).
3. After the grace period (--grace, default 1 hour, longer than the maximum token TTL), --finish removes the old key.
4. Progress is recorded in the Secret annotation maqpna.com/key-rotation (kind, phase prepared/swapped/done, oldKid, newKid), so an interrupted rotation can be resumed.

What you see#

$ maqpna keys rotate identity -n maqpna-system --dry-run

prints the plan without changing anything. The usage lines (from cmd/maqpna/keys.go):

maqpna keys rotate identity         [-n NS] [--grace 1h] [--jwks-wait 5m30s | --restart-gateway] [--no-finish | --finish [--force]]
maqpna keys rotate audit-checkpoint [-n NS] [--secret NAME]
maqpna keys rotate vault            [-n NS] [--secret NAME] [--drop-old]
maqpna keys rotate attest           [-n NS] --secret NAME [--grace 24h] [--no-finish | --finish [--force]]

See maqpna keys rotate, maqpna keygen and maqpna license issue.

Related#

• What "sovereign" means
• Identity broker flow
• Ledger record format
• Licensing and entitlements