as4-411/docs/security/key-reference-model.md

Key Reference Model and Rotation

Overview

as4-411 does not store private keys or raw secrets. It stores references to key material held in a vault or KMS. This document describes the reference model and rotation procedure.

Key Reference Model

Stored Data

• credentials table (per participant):

  • credential_type: tls | sign | encrypt
  • vault_ref: URI or identifier for the key in the vault/KMS (e.g. vault://secret/tenant1/cert-id, or KMS key ARN).
  • fingerprint: Optional certificate or public key fingerprint for verification.
  • valid_from / valid_to: Validity window for the referenced material.

• No private key material, no PEM bodies, and no long-lived secrets are stored in the directory database.

Resolution Output

• RouteDirective.security.keyRefs can carry the same vault/KMS references (or short-lived tokens) so that gateways resolve “which key” and then fetch material from the vault within their trust boundary.

Rotation Procedure

1. Stage new cert/key in vault/KMS; obtain new vault_ref and optional fingerprint.
2. Add or update credential record with new vault_ref, valid_from set to now (or overlap start).
3. Dual-valid overlap: Keep previous credential valid until cutover. Configure overlap window so gateways can refresh to the new key.
4. Cutover: Set old credential’s valid_to to end of overlap (or mark inactive). Prefer new credential via higher priority or by updating endpoint/participant metadata.
5. Revoke/archive old key in vault per policy; remove or expire old credential record.

Compliance Notes

• Audit log records changes to credential refs (who/what/when).
• Per-rail requirements (e.g. card networks, DTC) may impose additional constraints on key lifecycle and storage; see protocol docs where applicable.