Contract common to every operation
Every operation is authenticated, authorized, policy-pinned, provider-bounded and evidence-producing. Unknown operations return UNKNOWN_OPERATION; registered but unavailable operations return OPERATION_NOT_IMPLEMENTED or CAPABILITY_MISMATCH. This distinction lets clients separate a spelling/version error from a deployment gap.
Signature operations
| Operation | Required input | Output | v2 emphasis |
|---|---|---|---|
CreateKey |
usage, intent, constraints | opaque key reference and public metadata | RSA, ECDSA P-256, ML-DSA profiles |
Sign |
key reference, message | signature and evidence | no algorithm fallback |
Verify |
key/public reference, message, signature | valid boolean and evidence | verifier profile must be explicit |
The current reference slice runs Ed25519 for a small vertical test. The v2 contract and examples concentrate on RSA-PSS, ECDSA P-256 and ML-DSA-65 migration because those profiles demonstrate classical and post-quantum transition behavior.
Encryption and authenticated encryption
Encrypt and Decrypt carry plaintext or ciphertext, associated data, nonce/IV requirements and algorithm-profile constraints. A profile must define whether nonce generation belongs to the provider and how reuse is prevented. Decryption failures must not expose oracle-quality distinctions unless the profile explicitly permits them.
MAC operations
GenerateMac and VerifyMac define key usage, input, tag, truncation rules and constant-time verification expectations. A signature policy cannot silently satisfy a MAC intent or vice versa.
Key establishment and KEM
AgreeKeycovers classical or approved hybrid key agreement where both parties contribute key material.Encapsulatereturns a shared secret reference plus ciphertext for a KEM recipient.Decapsulateconsumes the recipient key reference and ciphertext, returning an opaque derived-secret reference.DeriveKeyapplies an approved KDF with explicit context, salt, output usage and length.
Shared secrets should remain opaque whenever the downstream provider can consume them directly.
Key protection and lifecycle
WrapKey, UnwrapKey, RotateKey, TransformKey, MigrateKey and DestroyKey are independent operations. Providers may reject an operation when custody or non-exportability prevents it. CALI surfaces that limitation rather than weakening protection.
Policy and discovery
ResolvePolicy is an internal or privileged diagnostic contract, not a consumer shortcut around authorization. GetCapabilities returns scoped, expiring information. GetOperation and registry retrieval allow tooling to understand maturity and schemas without assuming runtime support.
Idempotency
State-changing operations require an idempotency key scoped to the authenticated caller and operation. Reusing the same key with different input returns IDEMPOTENCY_CONFLICT. A retry must not create a second key generation or repeat a migration silently.