Crypto Agility Api

---
name: crypto-agility-api
description: "Intent-Based Cryptographic API Design for Cryptographic Agility — designing APIs that support transparent post-quantum algorithm migration without code rewrites. Use when building cryptographic systems, migrating to post-quantum cryptography, designing intent-based crypto APIs, or implementing policy-driven algorithm selection. Activation: cryptographic agility, post-quantum migration, intent-based API, policy-driven selection, key rotation, cryptographic governance"
metadata:
  arxiv_id: "2606.13445"
  published: "2026-06-11"
  authors: "Navaneeth Rameshan, Gregoire Messmer"
  tags: ["cryptography", "post-quantum", "api-design", "software-engineering", "information-science", "security"]
---

# Intent-Based Cryptographic API Design for Cryptographic Agility

Design cryptographic APIs that enable transparent migration to post-quantum algorithms without rewriting application code.

## Problem

Current crypto APIs (PKCS#11, OpenSSL 3.0, JCA, Google Tink, AWS KMS, HashiVault) tie applications to specific algorithms. Post-quantum transition requires rewriting code because APIs lack:
- Intent-based key creation (decoupled from algorithm identity)
- Policy-driven algorithm selection (distinct from access control)
- First-class key evolution operations (rotation, transformation, migration)

## Five Design Principles

1. **Abstraction**: Decouple key creation from algorithm identities via intent vocabulary
2. **Stability**: Stable key identifiers that persist across algorithm changes
3. **Temporal Flexibility**: Support transparent algorithm substitution within scoped contexts
4. **Separation**: Separate governance policy from implementation
5. **Extensibility**: Enable future algorithm additions without API changes

## Implementation Patterns

### Intent-Based Key Creation
- Keys created with intent (scope, purpose) not algorithm name
- Policy layer maps intent to current algorithm
- Enable transparent substitution by updating policy, not code

### Key Evolution Operations
- **Rotation**: Generate new key material under same identifier
- **Transformation**: Convert existing key to different algorithm
- **Migration**: Move keys between providers while tracking evolution history

### Governance via Abstract Policy API
- Policy format not prescribed by the API
- Scope-based intent vocabulary enables decoupled algorithm selection
- Track original key identity + full evolution history

## Seven Assessment Dimensions

When evaluating cryptographic agility, measure along these dimensions:

1. **Creation Decoupling**: What application code knows about algorithm at key creation
2. **Operation Decoupling**: What code knows during cryptographic operations
3. **Storage Decoupling**: What code knows about stored key format
4. **Cross-Cutting Decoupling**: Central mechanism enabling decoupling across system
5. **Governance Authority**: Who/what controls algorithm selection policy
6. **Algorithm Substitution Enabler**: Actual capability to swap algorithms
7. **Key Migration Enabler**: Actual capability to migrate existing keys

## Pitfalls

- No existing major crypto API supports all three gaps identified in assessment
- Algorithm selection ≠ access control — they address different concerns
- Key transformation is distinct from key rotation (transformation changes algorithm)

## Verification

- After API design, evaluate against all 7 dimensions independently
- Ensure policy updates do not require application code changes
- Verify key evolution history tracks both original identity and transformations