CALI v2.0 specification | Ganesh Mallaya

Scope

The Cryptographic Abstraction Layer Interface defines a stable operation contract between consumers and cryptographic implementations. CALI accepts a typed operation and an intent, resolves a pinned policy, matches it against scoped capabilities and key state, dispatches to one provider adapter and emits evidence.

CALI does not define new cryptographic algorithms. It does not replace provider APIs, key-management protocols, certificate issuance, relying-party validation or application protocols. Those systems retain their own semantics and trust boundaries.

Actors and trust boundaries

Actor	Responsibility	Must not assume
Consumer	Authenticate and submit operation, intent, constraints, context and typed input	That discovery authorizes an operation
Policy authority	Issue versioned, expiring, authenticated decisions	That provider availability permits downgrade
Broker	Authorize, pin one decision, validate state, dispatch once and emit evidence	That two matching rules can be resolved by ordering
Provider adapter	Translate resolved operations without changing meaning	That a native success proves CALI policy compliance
Key provider	Preserve custody, usage, lifecycle and non-exportability	That opaque references are portable across tenants
Certificate authority	Own issuance and certificate-policy decisions	That CALI replaces enrollment or revocation protocols

Request envelope

Every operation request contains:

{
  "apiVersion": "2.0.0",
  "requestId": "req-8f2a",
  "operation": "Sign",
  "intent": "application-authentication",
  "expectedPolicy": {
    "profileId": "workload-signing",
    "profileVersion": "2026-08-pqc"
  },
  "minimumConstraints": {
    "profile": "mldsa-65",
    "providerClasses": ["hsm", "software"]
  },
  "input": {
    "keyRef": "key_opaque_reference",
    "message": "base64url-without-padding"
  }
}

The consumer does not send private key material. Algorithm identifiers appear only when the contract explicitly requires a pinned algorithm or profile; they are not an invitation to bypass policy.

Resolution invariants

The broker must:

authenticate the consumer and establish tenant and workload context;
authorize the requested operation and intent;
reject missing, expired, ambiguous or mismatched policy;
bind exactly one policy version to the request;
validate algorithm, provider, key state, usage and protection constraints;
dispatch exactly once; and
return typed output or a stable error category with non-secret evidence.

There is no silent fallback. If ML-DSA is required and unavailable, CALI returns CAPABILITY_MISMATCH; it does not fall back to ECDSA or RSA.

Key lifecycle and evolution

CALI separates lifecycle operations that are often collapsed into “rotation”:

RotateKey creates a new generation with the same approved algorithm and provider class.
TransformKey moves a logical use from one algorithm profile to another, such as ECDSA P-256 to ML-DSA-65.
MigrateKey changes provider or custody boundary without pretending private key material can always be exported.
WrapKey and UnwrapKey are explicit operations governed by export and wrapping constraints.

Transformation normally creates new key material. CALI does not mathematically convert an ECC private key into an ML-DSA private key.

Discovery

GetCapabilities returns a tenant- and identity-scoped, freshness-bounded view of operations, profiles, algorithms, provider classes and limits. A capability record is informational. The caller must still submit an authorized operation that resolves against current policy and state.

Evidence and errors

Successful and rejected requests produce evidence suitable for authorized audit consumers. Evidence can include request ID, operation, policy ID and version, algorithm profile, provider class, key-reference fingerprint, outcome and timestamps. It must exclude secret keys, raw bearer tokens and sensitive payloads.

Stable error categories include authentication failure, authorization failure, policy not found, policy expired, policy ambiguous, capability mismatch, key-state mismatch, validation failure, unsupported operation, provider failure and idempotency conflict.

Deployment modes

CALI supports three intended topologies:

local library with embedded enforcement;
remote service with centralized enforcement; and
hybrid deployment with local execution and a centralized policy/control plane.

All modes must preserve the same request, resolution, failure and evidence semantics.

Binding and conformance direction

The OpenAPI document is the experimental HTTP binding. A later gRPC binding may express the same semantics. Conformance remains undefined until test vectors, a black-box runner, profile requirements and versioning rules are published. Implementing one endpoint does not imply CALI conformance.