# 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](../protocols/) where applicable.