Cryptographic Agility for Applications: An Assessment Framework and Principled API Design

The impending post-quantum cryptographic transition requires replacing algorithms across entire software portfolios, yet no systematic method exists for decomposing cryptographic agility into assessable dimensions. The term conflates distinct capabilities, including algorithm replacement, policy-driven selection, and implementation substitution, and the absence of a structured decomposition impedes both assessment and principled API design. We make four contributions. First, we introduce a component-based assessment framework that characterizes application-level cryptographic agility along seven orthogonal dimensions, capturing non-hierarchical profiles that linear maturity models cannot represent. Second, we derive thirteen API design principles from five foundational architectural properties. Third, we demonstrate their realization through concrete Protocol Buffers API patterns. Fourth, we evaluate six representative systems (PKCS#11, OpenSSL~3.0, JCA, Google Tink, AWS KMS, and HashiCorp Vault Transit), revealing three pervasive gaps: most achieve only partial operation decoupling (uniform signatures, but algorithm-specific parameters still leak through) and none reaches intent-based key creation, making algorithm migration a per-site code-change problem; none provides policy-driven algorithm selection, so organizations govern who may use cryptography but not which algorithms; and most lack the ability to transform existing keys to new algorithms. These gaps are independent and individually sufficient to prevent agile migration, explaining why post-quantum transition remains a code-change problem despite decades of API progress.