Crypto Agility in Code: Patterns, Size Budgets, Hybrid Signatures and Testing
What agility means for a programmer
NIST defines crypto agility as the ability to swap and adapt cryptographic algorithms across protocols, applications, software, hardware, firmware and infrastructure while preserving security and ongoing operations. NIST's white paper on the subject (CSWP 39) covers cryptographic APIs, risk management and transition planning. The original was published December 19, 2025. NIST withdrew it on June 29, 2026 and replaced it with CSWP 39upd1 (final), so cite the updated edition. For the concept in plain English see crypto agility explained. This guide is about the code.
Pattern 1: one interface, many algorithms
Wrap each primitive behind a small interface: a key agreement interface with generate, encapsulate and decapsulate, and a signature interface with generate, sign and verify. Application code never mentions "ECDSA" or "ML-DSA" directly. This is the same shape as the KEM and signature APIs that ML-KEM and ML-DSA use, so adapters are thin.
Pattern 2: algorithm identifiers everywhere
Every stored key, signature and ciphertext should carry an identifier saying how it was made. Protocols already do this: TLS names the hybrid group X25519MLKEM768 with codepoint 4588 (0x11EC), and the Java JEP 527 spec uses the same IANA names. In your own formats, prefer a registered identifier, such as an OID or a standard name, over a private enum, and include a version field. A verifier should reject unknown identifiers instead of guessing. Never infer the algorithm from the length of a blob.
Pattern 3: policy in config, not code
Keep a policy object that lists allowed algorithms in preference order, plus a deprecation date for each. Rolling out a new algorithm then becomes a config change, and retiring one is a flag day you can schedule. Include a kill switch: Go, for example, documents a GODEBUG setting to turn off its default hybrid group when buggy servers choke on large records.
Size and bandwidth budget
Post-quantum objects are bigger, and the budget is the part that surprises teams. Figures below are reported sizes from the IETF hybrid document and a technical analysis of signature sizes.
| Object | Public key or share | Signature |
|---|---|---|
| X25519 (key agreement) | 32 bytes | none |
| X25519MLKEM768 client share | 1,216 bytes | none |
| ECDSA | 33 bytes | 64 to 72 bytes |
| FN-DSA-512 (Falcon) | 897 bytes | 666 bytes |
| ML-DSA-44 | 1,312 bytes | 2,420 bytes |
| ML-DSA-65 | 1,952 bytes | 3,309 bytes |
| SLH-DSA-SHA2-128s | 32 to 64 bytes | 7,856 bytes |
| SLH-DSA-SHA2-128f | 32 to 64 bytes | 17,088 bytes |
Check each against your limits: database column widths, QR codes, JWT or cookie size caps, MTU and TLS record behavior, mobile data costs, log volume, and any on-chain space. Cloudflare estimated that switching all TLS signatures to ML-DSA-44 would add about 15 kB to a handshake, and about 7 kB for FN-DSA-512. Blockchains feel this hardest, as explained in signature sizes and block space.
Hybrid signatures
For key exchange the hybrid is well settled. For signatures there is no single dominant format, and standards work is still ongoing, so keep your design flexible. A common approach is a composite: sign the message with both a classical and a post-quantum key and require both to verify, with both signatures and an identifier for the pair stored together. The cost is the sum of both sizes. Another approach is a dual-signature field where verifiers that do not understand the new algorithm can ignore it. Either way, write down what happens when only one signature verifies (the safe answer is reject) and avoid designs where an attacker can strip the post-quantum part. This is my design advice, not a standard, so review it with a cryptographer.
Testing agility
- Round-trip tests for every registered algorithm: generate, sign, verify, and also tampered-message failures.
- Known-answer tests from the NIST vectors in your CI.
- Cross-library interop: sign with one library, verify with another.
- Downgrade tests: confirm a peer cannot force the weakest allowed algorithm if a stronger one is mutually supported.
- Chaos drills: flip the policy to the new algorithm in staging and watch size-related failures.
- Inventory: keep a machine-readable list of where each algorithm is used. See the migration checklist.
Sources and further reading
- NIST CSWP 39upd1: considerations for achieving crypto agility (replaces the withdrawn December 2025 edition)
- RFC 10024: Post-Quantum Traditional (PQ/T) Hybrid Key Agreement Mechanisms for TLS 1.3
- OpenJDK JEP 527: post-quantum hybrid key exchange for TLS 1.3
- Go 1.24 release notes (crypto/mlkem, X25519MLKEM768)
- PostQuantum.com: fixing Bitcoin, signature sizes and throughput
- Cloudflare blog: state of the post-quantum Internet in 2025
Reported as of 2026-10-09. Library versions, defaults and standards status change often, so check the primary documents and test on your own stack before relying on anything here. Nothing here is financial advice or a security audit. The QNT memecoin is independent of Quantinuum Ltd, the real company, and of every project, library, lab and chain named on this page.
Frequently asked questions
What is the single most useful crypto agility habit?
Never hard-code an algorithm. Put it behind an interface and name it with a standard identifier stored next to every key and signature.
How much bigger is a hybrid TLS key share?
The IETF document lists 1,216 bytes for X25519MLKEM768, versus 32 bytes for plain X25519.
Should I sign with two algorithms at once?
Hybrid signatures are a reasonable transition idea, but formats are still settling. Require both to verify, make stripping impossible, and have a cryptographer review the design.
Which standard names should I use as identifiers?
Use the registered names such as ML-KEM-768, ML-DSA-44 and SLH-DSA-SHA2-128s, or registered OIDs, not private labels.
Keep reading
- Crypto Agility Explained: Preparing for Algorithm Change
Crypto agility is the ability to swap cryptographic algorithms without rebuilding a system. Learn why it matters for the post-quantum shift and for blockchains. - Post-Quantum Signature Sizes and Block Space: Why Blockchains Feel the Squeeze
Post-quantum signatures are many times bigger than today's. Here is what that means for block space, fees and throughput, in plain English. - Hybrid Key Exchange in TLS Explained: How Your Browser Is Already Quantum Ready
A plain English guide to X25519MLKEM768, the hybrid handshake that now protects a large share of web traffic against harvest now, decrypt later attacks. - Falcon vs ML-DSA vs SLH-DSA vs Winternitz: Picking a Quantum-Safe Signature
A readable comparison of the main post-quantum signature families that blockchains are considering, with their trade-offs. - A Plain English Post-Quantum Migration Checklist for Companies
A step by step checklist any company can follow to get ready for post-quantum cryptography, including how banks and financial firms are prioritizing.
All Quantum computing guides | Back to top | Search the site
Main pages: Quantum computing explained | Quantum and crypto | Companies | Quantum news | Glossary