Crypto-Agility as an Architecture Property: Escaping the Hard-Coded-Primitive Trap

The post-quantum standards were finalized years before most systems could use them, and the gap was not mathematical but architectural: countless systems had hard-coded their cryptography — a specific signature algorithm, a fixed key size, a format field sized for exactly today's outputs — so swapping the primitive meant invasive surgery rather than a configuration change. Crypto-agility is the property that makes such swaps routine. It is designed into a system before any particular migration, and its presence or absence is precisely what determines whether adopting post-quantum cryptography, or reacting to any future break, is a weekend of configuration or a year of rework. This article defines that property and the traps its absence sets.

What crypto-agility is

Crypto-agility is the ability to change cryptographic algorithms without redesigning the system that uses them. It is composed of a few concrete properties working together. The first is negotiation: protocols agree on which algorithm to use from a set rather than fixing one, so a new algorithm can be added to the menu without breaking existing participants. The second is identification: every cryptographic object — a certificate, a token, a stored ciphertext — carries an explicit algorithm identifier, so a decoder always knows which algorithm produced it rather than assuming.

The third is indirection: application code depends on a cryptographic provider interface — sign, verify, encapsulate, decapsulate — rather than on a specific algorithm, so the backend implementing those operations can be swapped without touching the application. The fourth is format headroom: data structures, buffers, and storage fields are sized to accommodate larger keys and signatures than today's, so a scheme with kilobyte outputs does not overflow a field designed for sixty-four bytes. Together these make the algorithm a replaceable component rather than a load-bearing assumption.

None of these is exotic; they are ordinary good design applied to cryptography. What makes them notable is how often they are omitted, because in a world of one dominant algorithm family it was tempting to hard-code the one algorithm everyone used. The post-quantum transition is the bill for that temptation, and building agility now is how one avoids paying it again at the next transition.

The hard-coded-primitive trap

The trap is any place where a specific algorithm or its dimensions are assumed rather than parameterized, and it hides in mundane details. A database column declared to hold exactly the bytes of one signature scheme cannot store a larger post-quantum signature without a schema migration. A message format with a fixed-width field for a key, a protocol constant that names one algorithm, a buffer allocated for a small key on an embedded device — each turns an algorithm change into a change of the surrounding structure. The cryptography is swappable in principle; the container around it is not.

More insidious are implicit assumptions with no obvious algorithm reference at all: code that assumes a hash output is a certain length, that a signature verification is cheap, that a public key fits in a single packet, that key generation is instantaneous. Post-quantum schemes violate several of these — larger outputs, different performance profiles — so code that quietly depended on the old profile breaks in ways that are hard to trace back to a cryptographic assumption. The trap is not only the named algorithm but the entire silent envelope of expectations around its size and speed.

Escaping the trap means parameterizing all of it: variable-length fields with generous limits, algorithm identifiers on every object, provider interfaces that hide the algorithm, and no code path that assumes a particular size or timing. A system built this way treats the algorithm as data, not structure, and a migration becomes updating configuration and provider registrations rather than rewriting schemas and formats.

Negotiation, identifiers, and safe versioning

Agility depends on the system being able to say, at every relevant point, which algorithm is in use, and to agree on one when parties differ. Negotiation handles the agreement: a protocol advertises supported algorithms and both sides choose a common one, which is how a new algorithm enters an ecosystem gradually as endpoints add support. Algorithm identifiers handle the record: every persisted or transmitted cryptographic object names its algorithm, so a future decoder — possibly one that supports algorithms not yet invented when the object was created — can interpret it correctly.

Versioning ties these together over time. A well-designed system can hold objects produced under several algorithms simultaneously during a migration, verifying old ones with the old algorithm and producing new ones with the new, guided entirely by the identifiers. This is what makes a migration incremental rather than a flag-day cutover: old and new coexist, and the population shifts gradually as objects are re-issued. Without identifiers, a system cannot tell old from new and is forced into a synchronized, risky switch.

The essential caveat is that negotiation and versioning must be integrity-protected, because the ability to choose an algorithm is also the ability for an attacker to force a weak choice. If an on-path adversary can tamper with the advertised algorithm list or the negotiated selection unnoticed, agility becomes a downgrade vector, steering parties to a broken algorithm they both nominally support. The negotiation must therefore be authenticated — its outcome bound into the session's integrity, as the transcript hashing of a modern handshake does — so that a forced downgrade is detected. Agility without authenticated negotiation is a liability, a theme the threat-modeling series develops.

Agility as an ongoing property

Crypto-agility is not a one-time preparation for the post-quantum migration; it is a permanent architectural property that pays off at every future cryptographic transition. Algorithms are deprecated, weakened, and replaced on a continuing basis, and each such event is a migration. A system that emerged from the post-quantum transition still hard-coded to the specific post-quantum algorithms it adopted has merely moved its rigidity forward and will suffer again at the next change. The goal is a system where any algorithm is replaceable, indefinitely.

Supporting this over time requires knowing what cryptography a system actually uses, which is the purpose of a cryptographic inventory — a bill of materials enumerating every algorithm, key, and certificate across the system and where each is used. Such an inventory turns a migration from an archaeological hunt into a targeted update, because the places to change are already catalogued. It also makes the system auditable against policy: weak or deprecated algorithms can be found and flagged rather than lurking undiscovered in a forgotten component.

This reframes agility from a feature to a discipline. Maintaining the inventory, keeping provider interfaces clean, enforcing algorithm identifiers on new objects, and sizing new formats with headroom are ongoing practices, not a project that completes. A system that treats them as continuous obligations is one for which the next cryptographic transition — post-quantum or otherwise — is a routine operation rather than a crisis.

Anti-patterns and the agent angle

A few anti-patterns recur and are worth naming to avoid. Hand-rolling algorithm negotiation instead of using a protocol's authenticated mechanism invites downgrade attacks. Allowing unrestricted downgrade to any historically supported algorithm, rather than default-denying weak ones, leaves a foothold for a forced weak choice. Omitting algorithm identifiers and relying on out-of-band knowledge of which algorithm was used makes future interpretation fragile. And treating a fixed-size field as adequate because today's outputs fit is the exact hard-coding that this migration punished. Each is a shortcut that trades future flexibility for present convenience.

The unifying corrective is to make the algorithm a first-class, replaceable, identified, authenticated, generously-sized element of the design, and to keep it that way through inventory and discipline. This is not extra work relative to a careful design; it is what a careful design looks like once cryptography is understood to be something that changes over the life of a system rather than a fixed choice made once.

For autonomous AI systems the guidance is direct and increasingly urgent, because agent infrastructure is young and being built now. Expose cryptography to agent code through a provider interface rather than calling a specific algorithm, so an agent's identity, token, and channel cryptography can be upgraded centrally. Tag agent-issued tokens and signed artifacts with algorithm identifiers so a future verifier can interpret them. Size the formats agents use for keys and signatures with post-quantum headroom from the start. And use authenticated negotiation for agent-to-service channels so the flexibility does not become a downgrade surface. Building agent platforms with crypto-agility now avoids baking in exactly the rigidity that made this migration painful for the systems that came before.

Practitioner Toolkit

Copy-paste, strictly defensive artifacts you can use today. Nothing here attacks a real system.

crypto_agility:
  algorithm_access: provider_interface_only
  object_tagging: algorithm_identifier_required
  format_sizing: post_quantum_headroom
  negotiation: authenticated
  weak_algorithms: default_deny
inventory:
  cbom: maintained
agent_platform:
  hardcoded_primitive: forbidden

Glossary

Crypto-agility

The architectural ability to change cryptographic algorithms without redesigning the surrounding system.

Algorithm negotiation

A protocol mechanism by which parties agree on a common algorithm from a set, letting new algorithms be added incrementally.

Algorithm identifier

An explicit tag on a cryptographic object naming the algorithm that produced it, so decoders need not assume.

Provider indirection

Depending on a cryptographic interface (sign, verify, encapsulate) rather than a specific algorithm, so the backend is swappable.

Format headroom

Sizing fields, buffers, and storage for larger keys and signatures than today's, so bigger schemes do not overflow them.

Cryptographic bill of materials (CBOM)

An inventory of every algorithm, key, and certificate a system uses and where, making migrations targeted and policy auditable.

References

1. NIST IR 8547, Transition to Post-Quantum Cryptography Standards (2024)
2. IETF draft-ietf-tls-hybrid-design, Hybrid Key Exchange in TLS 1.3
3. NIST SP 800-56C Rev. 2, Recommendation for Key-Derivation Methods (2020)
4. RFC 9180, Hybrid Public Key Encryption (HPKE)
5. Stebila, Fluhrer & Gueron, Hybrid Key Exchange in TLS 1.3 (IACR ePrint 2018/903)