Crypto-Agility: Design Patterns for Swappable Cryptography

Crypto-agility is the ability to change cryptographic algorithms, key sizes or providers without redesigning the system. Cryptography has always needed this (MD5, SHA-1, DES and RC4 all had to be retired), but the post-quantum transition makes it urgent because new algorithms come with larger keys, different APIs and, for some years, hybrid modes. The patterns below make that change routine.

Pattern 1: One crypto interface

Do not scatter direct library calls across the codebase. Put cryptographic operations behind a small internal interface:

// crypto-service.js: the only module allowed to import crypto libraries
export async function encrypt(plaintext, context) { /* ... */ }
export async function decrypt(envelope, context) { /* ... */ }
export async function sign(message, keyId) { /* ... */ }
export async function verify(message, signature, keyId) { /* ... */ }

Application code asks for "encrypt this under context user-pii," not "AES-GCM with a 12-byte IV." When the algorithm changes, one module changes. Enforce it with a lint rule that forbids importing crypto libraries elsewhere.

Pattern 2: Self-describing ciphertext

Store the algorithm identifier with the data it protects. A versioned envelope makes old and new data coexist:

{
  "v": 2,
  "alg": "AES-256-GCM",
  "kid": "kms-key-2026-09",
  "iv": "base64...",
  "ct": "base64..."
}

At decryption time, read alg and kid from the envelope to pick the right routine and key. Without this, you cannot tell which records are encrypted with what, and migrations require guesswork.

Pattern 3: Policy as configuration

Which algorithms are allowed should be data, not code:

crypto-policy:
  key-exchange: [X25519MLKEM768, X25519]
  signature:   [ECDSA-P256]
  hash:        [SHA-256, SHA-384]
  deny:        [MD5, SHA-1, RSA-1024]

Changing policy is then a reviewed configuration change that can be rolled out gradually and rolled back, instead of a code release. Keep the policy in version control and alert when a service deviates from it.

Pattern 4: Dual operation during transition

Migrations need an overlap period:

• Encryption: new writes use the new algorithm; reads accept both. A background job re-encrypts old records, tracking progress by counting envelopes per v.
• Signatures: sign with both classical and post-quantum algorithms (composite or dual signatures) while verifiers upgrade.
• Key exchange: negotiate hybrid groups, fall back to classical until telemetry says it is safe.

Define in advance how you will know the old path is unused, such as zero decrypts of v:1 for 30 days, before you delete it.

Pattern 5: Abstract key management

Refer to keys by identifier and purpose (kid), never by raw bytes in application code. Let a KMS or HSM hold the keys. This lets you change key type behind the identifier, and it supports rotation without redeploying services. See also Secrets Management.

Pattern 6: Plan for size changes

Post-quantum algorithms have larger keys, ciphertexts and signatures. Check for hidden limits:

• Database columns sized for 256-byte RSA signatures
• HTTP headers or cookies with size caps
• Certificate or token fields in fixed-size protocols
• Embedded devices with small flash or RAM

ML-DSA-65 signatures, for example, are 3,309 bytes (see Post-Quantum Digital Signatures). Test with realistic sizes early.

Pattern 7: Test the swap

Agility that has never been exercised usually does not work. Add a test that runs your encryption and signing paths with two different algorithm configurations, and run a periodic game day in staging where you flip the policy and confirm that everything still works.

Antipatterns

• Hardcoding algorithm names in more than one place
• Storing ciphertext with no version or algorithm field
• Rolling your own "flexible" cipher framework instead of using vetted libraries
• Treating agility as a one-off project rather than a standing design rule

Agility has a cost, mainly some indirection and test effort. For systems expected to live beyond a few years, that is a small price compared with a forced emergency migration.