Intents & Policies
How the security team maps a business intent to a concrete algorithm, posture, key and backend — and proves the migration.
The intent
An intent is what a developer declares. It has three parts:
| Part | Values | Meaning |
|---|---|---|
| Data class | pan, cvv, pii, phi, credential, confidential | What kind of sensitive data this is. |
| Purpose | storage, transport, tokenize, sign | What you are doing with it. |
| Residency | eu, us, ch, global | Optional jurisdiction constraint (defaults to global). |
The intent is identified by the key {data_class}.{purpose} (for example
pan.storage). Developers never state an algorithm, mode or key.
The policy
A policy is a tenant-scoped, versioned rule set the security team owns. Each rule
maps an intent to a decision, and the policy carries a required posture floor
(classical, hybrid, or pqc_only). CAP resolves an intent by matching the most
specific rule and enforcing the floor.
A decision is what CAP resolves an intent to:
| Field | Meaning |
|---|---|
algorithm | The concrete algorithm identifier to run. |
posture | classical · hybrid · pqc_only. |
quantum_resistant | true when the posture is not classical. |
key_ref | A reference to the key — { kind: "vault", vault_id, key_name } or { kind: "derived_tenant", label }. CAP holds no key bytes. |
backend | A backend class: software · fips1403_hsm · pqc_capable · local_tokenizer (the concrete vendor is selected downstream). |
Posture ranking
Posture is ordered classical (0) < hybrid (1) < pqc_only (2). A resolved algorithm
must meet or exceed the policy floor; a stronger algorithm always satisfies a
weaker requirement, never the reverse.
| Posture | Algorithms |
|---|---|
| classical | aes256-gcm, ff1, rsa-oaep2048, ecdsa-p256 |
| hybrid | hybrid-ml-kem768-x25519, hybrid-ml-dsa65-ecdsa-p256 |
| pqc_only | ml-kem768, ml-dsa65, slh-dsa128s |
Start from a compliance template
Instead of authoring rules by hand, bootstrap a policy from a built-in template:
curl -X POST "https://cockpit.example.com/api/cap/policies/from-template" \
-H "Authorization: Bearer $COCKPIT_SESSION_JWT" \
-H "Content-Type: application/json" \
-d '{ "template_key": "pci_dss_4", "name": "PCI baseline" }'| Template | Standard | Posture floor | Highlights |
|---|---|---|---|
pci_dss_4 | PCI DSS 4.0 | classical | PAN tokenized (ff1); PAN/CVV storage aes256-gcm on a FIPS HSM; transport & sign go hybrid. |
finma_ch | FINMA (Switzerland) | hybrid | Hybrid signatures and transport; Swiss residency; FIPS HSM backend. |
enisa_eu | ENISA (EU PQC) | hybrid | Hybrid KEM/DSA; EU residency; pqc_capable backend. |
cnsa_2_0 | NIST CNSA 2.0 | pqc_only | Pure ML-KEM / ML-DSA — no classical or hybrid fallback. |
fips_fedramp | FIPS 140-3 / FedRAMP | classical | aes256-gcm storage on a FIPS HSM; hybrid transport & sign. |
gdpr_pii | GDPR (EU PII) | classical | PII/PHI storage aes256-gcm; hybrid transport & sign; EU residency. |
List the templates and what they contain with GET /api/cap/policy-templates.
Policies are create + soft-delete — there is no in-place update. To change rules
or raise the posture, create a new policy (a higher version). CAP resolves
against the newest enabled policy unless a request pins a specific policy_id.
Simulate a posture flip — Quantum Readiness Score
Before you raise the floor, simulate it. POST /api/cap/simulate shows the
per-intent changes and a Quantum Readiness Score (QRS) uplift (0–100):
curl -X POST "https://cockpit.example.com/api/cap/simulate" \
-H "Authorization: Bearer $COCKPIT_SESSION_JWT" \
-H "Content-Type: application/json" \
-d '{ "target_posture": "pqc_only" }'The response reports qrs.before, qrs.after, qrs.uplift, the quantum-resistant
coverage (n/m intents) before and after, and the exact per-intent from → to
changes. Reuse the DuoKey CBOM and Quantum Readiness Score from the
DuoKey CPM to plan and evidence the migration.
Drift detection — closing the loop
Applications call observe(...) to report the algorithm that actually ran. CAP
resolves the intent against the active policy and compares postures:
Compliant
The observed algorithm meets or exceeds the decision → no finding.
Warning
Weaker than declared but still quantum-resistant (e.g. hybrid where pqc_only was expected) → a warning finding.
Critical
Dropped to a purely classical algorithm → a critical finding.
Findings carry the intent key, declared vs observed algorithm, severity, source and
status (open / resolved). Review them with GET /api/cap/drift.
Policy, template, simulate and drift management are control-plane calls that
use a Cockpit session (JWT) with the Cap.Policies.* / Cap.Drift.*
permissions and require the cap.enabled feature. Applications use the
dke_cap_… API key on the data-plane /api/cap/sdk/resolve and
/api/cap/sdk/observe routes only.
This page covers the intent/policy model and the essential calls. The complete REST contract and the packaged SDK reference are published in the DuoKey Developer Docs.