Read this first
Cryptographic posture is not machine-discoverable: nothing lets an agent, a CI bot, or an auditor read what cryptography a project runs and how far its post-quantum migration has gone, without asking a human. We are proposing `crypto-agility.json`, a small file served at `/.well-known/crypto-agility.json` that publishes a readiness score, a CBOM summary, a link to any independent attestation, and the migration deadlines the project holds itself to. It is a proposal, not an existing standard, and it deliberately composes conventions that already exist (RFC 8615 well-known URIs, the security.txt model, the CycloneDX cryptography bill of materials). An emitter and validator for it are landing in qScan.
The migration off quantum-vulnerable cryptography is a coordination problem across millions of independent parties, and the parties reading each other's posture are increasingly software: an AI coding agent proposing dependency updates, a build gate deciding whether to ship, an auditor or regulator or journalist wanting to know where a sector stands. Every one of them, today, has to reverse-engineer the answer or take a human's word for it, because there is no conventional place to look. The web solved this class of problem before, one small well-known file at a time.
What it publishes
- Posture: a readiness score, a hybrid-key-exchange flag (operator-assertable, since a static scan cannot observe a negotiated TLS group), and quantum-vulnerable finding counts by severity.
- CBOM summary: the algorithm families in use and a link to the full cryptographic bill of materials, so the manifest stays small while the detail is one hop away.
- Attestation: an optional link to an independently verifiable credential, recorded verbatim and never fetched by the emitter.
- Policy: the deadlines the project commits to, defaulting to the named ones (deprecate classical public-key algorithms after 2030, disallow after 2035), with a citation.
How a machine would use it
- An agent updating your code reads a dependency's manifest and declines to pull one still on a deprecated curve.
- A CI gate fails a build whose own manifest slipped below the bar the project set.
- A researcher reads the manifests across a sector and publishes the distribution without commissioning a single audit, which is what the PQC Observatory does by hand today, made cheap and continuous.
A claim, not a proof
It is worth being honest about what a self-published file is. Anyone can serve any JSON at a well-known address, so a self-reported readiness score is worth exactly the reader's trust in the reporter, which on its own is little. That is why one field is a link to an attestation a third party has verified and anyone can check. The manifest is the front door; the attestation is the thing behind it that does not depend on believing the owner. security.txt gives you a contact; this gives you a contact and a checkable record.
It is a proposal, and it reuses what exists
To be clear: `crypto-agility.json` is not a ratified standard, it is a convention we are proposing. It invents as little as possible, borrowing the well-known-URI mechanism (RFC 8615), the model of security.txt (RFC 9116), and the CycloneDX cryptography bill of materials, and pointing them at the one question none of them answers. A convention is worth only the number of parties who adopt it, so the specification is small, public, and deliberately boring. If the idea has merit, it is worth other people's edits.
Written up as an Internet-Draft
To make it something people can argue with precisely rather than in the abstract, we wrote the convention up as a formal Internet-Draft, modeled closely on RFC 9116, the security.txt specification: the same shape of document, a registered well-known suffix, an IANA Considerations section requesting `crypto-agility.json` in the Well-Known URIs registry, and candid Security and Operational Considerations about the fact that a self-published file is a claim and not a proof. It has been submitted to the IETF as an Internet-Draft, where anyone can review it. The draft, the JSON Schema, and worked examples live in a dedicated repository, quantakrypto/crypto-agility, and the prior work it builds on is cited there. Review, disagreement, and pull requests are exactly why it is public.
Publishing one
The spec lives with our open-source tooling, and qScan is gaining a command to produce the file from a scan you are probably already running: `qscan crypto-agility emit ./ -o public/.well-known/crypto-agility.json`, with `qscan crypto-agility validate <file>` to check a manifest against the schema, offline. A network fetch-and-validate and an MCP reader (so an agent can query a project's posture over the existing transport) are the next steps, noted as follow-ups in the spec.
References
- RFC 8615 - Well-Known Uniform Resource Identifiers - the `/.well-known/` mechanism.
- RFC 9116 - A File Format to Aid in Security Vulnerability Disclosure (security.txt) - the model this echoes.
- CycloneDX Cryptography Bill of Materials (CBOM) - the machine-readable crypto inventory the manifest summarizes.
- NIST IR 8547 - Transition to Post-Quantum Cryptography Standards - the source of the default policy deadlines.
- IETF datatracker - draft-acosta-crypto-agility-manifest - the submitted Internet-Draft.
- quantakrypto/crypto-agility - the Internet-Draft source, JSON Schema, and examples.