69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
# Authority Crypto Provider and JWKS Contract
|
|
|
|
This document defines the minimum contract Authority must satisfy to support sovereign crypto providers (FIPS, GOST, SM, PQ-ready modes where enabled) while keeping exports deterministic and offline-verifiable.
|
|
|
|
## 1) Scope
|
|
- Provider registry binding for Authority signing keys.
|
|
- JWKS export rules (which keys are exposed and how `kid` is computed).
|
|
- Signing profile selection rules (how Authority chooses keys/algorithms for different operations).
|
|
- Determinism requirements for JWKS JSON and key identifiers.
|
|
|
|
This contract is written so downstream consumers (Gateway, services, CLI, Offline Kit tooling) can validate tokens and rotate trust roots without depending on Authority's internal database schema.
|
|
|
|
## 2) Terms
|
|
- Provider: a crypto implementation or backend (software, HSM, KMS) identified by `provider_id`.
|
|
- Key: a signing key (or key handle) identified by `key_id` within a provider.
|
|
- Profile: a named signing policy that constrains algorithm choices and key selection.
|
|
- `kid`: the key identifier exposed in JWT headers and JWKS entries.
|
|
|
|
## 3) Provider registry (required fields)
|
|
|
|
Each registered Authority signing key MUST have, at minimum:
|
|
- `provider_id`: stable provider identifier (string).
|
|
- `key_id`: stable key identifier within the provider (string).
|
|
- `alg`: signing algorithm identifier as used by JWT/JWS (string).
|
|
- `usage`: at least `sig` (signing). If other usages are supported, they must be explicit.
|
|
- `tenant_scope` (optional): when set, the key is only valid for the specified tenant(s); when absent, it is platform-wide.
|
|
|
|
## 4) JWKS export rules
|
|
|
|
### 4.1 Which keys are exported
|
|
- JWKS MUST include only keys usable for token verification by downstream services.
|
|
- Exported keys MUST be filtered by:
|
|
- profile rules (do not export keys that cannot be selected by any active profile), and
|
|
- tenant scope (do not export tenant-scoped keys into other tenants' JWKS views if per-tenant JWKS is supported).
|
|
|
|
### 4.2 `kid` composition (deterministic)
|
|
`kid` MUST be stable across restarts and across equivalent deployments.
|
|
|
|
Recommended minimum rule:
|
|
- Compute `kid` from the public key material plus the profile discriminator:
|
|
- `kid = sha256(public_key_spki_bytes || ":" || profile_id)`
|
|
|
|
If Authority exposes both an all-profiles JWKS and a per-profile JWKS, the `kid` value must remain stable in both views.
|
|
|
|
### 4.3 Canonical JWKS JSON (deterministic)
|
|
- JWKS JSON MUST be canonicalized for reproducible hashing and offline verification:
|
|
- stable key ordering (sort by `kid` ascending),
|
|
- stable field ordering within a key object,
|
|
- no incidental whitespace dependence for hashing or signatures.
|
|
|
|
## 5) Signing profiles
|
|
|
|
Authority SHOULD define named profiles (examples: `default`, `ru-gost`, `pq-experimental`) that map:
|
|
- allowed algorithms (`alg` allowlist),
|
|
- allowed providers (provider allowlist),
|
|
- selection precedence when multiple keys match.
|
|
|
|
Profile selection MUST be deterministic given the same registry and request context.
|
|
|
|
## 6) Rotation and revocation expectations
|
|
- Rotation MUST preserve the ability to verify previously issued (unexpired) tokens.
|
|
- Revocation exports and JWKS exports MUST be consumable offline (cacheable and distributable in Offline Kit bundles).
|
|
|
|
## 7) Related docs
|
|
- Authority module dossier: `docs/modules/authority/architecture.md`
|
|
- Authority operations (key rotation, backup/restore): `docs/modules/authority/operations/`
|
|
- Gateway tenant/auth header contract: `docs/api/gateway/tenant-auth.md`
|
|
|