35 lines
1.8 KiB
Markdown
35 lines
1.8 KiB
Markdown
# 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.
|