QuantaKrypto

Argentina leon@quantakrypto.com

Security crypto-agility post-quantum well-known URI CBOM cryptographic posture This document defines a discoverable, machine-readable JSON document, the crypto-agility manifest, that a website or source repository publishes at the well-known URI "/.well-known/crypto-agility.json" to declare its cryptographic posture: a readiness summary, a compact Cryptography Bill of Materials (CBOM) summary, an optional link to a posture attestation, the migration policy it measures itself against, and an optional self-declared conformance statement with justified exceptions. The manifest lets an automated consumer, such as an AI coding agent, a continuous-integration bot, or an auditor's tool, discover a project's crypto posture the way it already discovers a security contact from "security.txt". The manifest is a public, self-reported claim; it is not a proof. It is intended to complement, not replace, a full CBOM inventory, serving as the CBOM's public-facing discovery counterpart. This document is a proposal. It is not an IETF product and is not a standard of any kind.

Introduction Crypto-agility, the capability to replace and adapt cryptographic algorithms while preserving security and operations, is a mature and well-documented objective. It is treated at the algorithm-agility level by , and at the organizational and lifecycle level by . Mechanism-level guidance for deriving keys when a classical and a post-quantum exchange are combined appears in , and security-evaluation criteria for quantum key distribution in . The migration timelines that give crypto-agility its present urgency are set out in and , and general engineering guidance for the post-quantum transition itself is collected in . The inventory of what cryptography a system actually uses now has a standard representation, the Cryptography Bill of Materials (CBOM) defined in . What is missing is not the concept and not the inventory format. It is a conventional, discoverable place for a project to publish a short, public summary of its posture that a machine can find and read without out-of-band configuration. Automated agents increasingly make dependency and cryptography choices, and continuous-integration systems increasingly gate on them, but there is no standard location from which such a consumer can learn a project's crypto posture, policy, and migration deadlines. Today every such integration is bespoke. This document fills exactly that gap and no more. It borrows its structural model directly from "security.txt" : a small file at a registered well-known location that any party can fetch from an origin alone. Where "security.txt" publishes how to report a vulnerability, the crypto-agility manifest publishes a project's cryptographic posture. A full CBOM answers "what cryptography is in here"; the manifest is its public-facing discovery counterpart, answering "where do I find this project's posture, and what does it summarize to". The manifest is deliberately a summary and not a replacement for a full CBOM or a detailed readiness report. It is small enough to fetch and parse on every CI run, and it answers three questions at a glance: how ready is this project, what quantum-vulnerable cryptography is it still using, and by when has it committed to migrate. A consumer that needs component-level detail follows the CBOM pointer the manifest carries.

Scope and Non-Goals This document specifies the well-known URI, the media type, and the JSON field definitions of the manifest. It does not define a new cryptographic mechanism, a new attestation format, or a new CBOM format; it references the CBOM format of for the summary it carries. It does not specify how a producer computes a readiness score, and it does not define the trust model of the credential an "attestation" link points to. The manifest is a self-reported claim (see ); establishing whether that claim is true is out of scope and is the job of the linked attestation and of the consumer.

Terminology and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The following terms are used in this document:

manifest:

the JSON document defined by this specification.

producer:

the party or tool that generates and publishes a manifest.

consumer:

any party that retrieves and interprets a manifest, for example an agent, a CI system, a scanner, or an auditor's tool.

origin:

as defined in , the scheme, host, and port from which the manifest is retrieved.

CBOM:

a Cryptography Bill of Materials as defined in .

classical public-key cryptography:

public-key algorithms, such as RSA and elliptic-curve Diffie-Hellman, whose security is broken by a cryptographically relevant quantum computer.

Field names, JSON literals, and example values are shown in a monospaced font. JSON types are as defined by the JSON grammar: object, array, string, number, boolean, and null. In this document, "integer" denotes a JSON number with no fractional part.

The Well-Known URI A producer publishes its manifest at the path "/.well-known/crypto-agility.json" of an origin, that is: This location uses the well-known URI mechanism of , the same mechanism that hosts "security.txt" . Registration of the URI suffix "crypto-agility.json" is requested in . A consumer that knows only an origin MUST be able to locate the manifest by resolving this path against that origin, with no out-of-band configuration. A manifest published for a website or service SHOULD be served from the origin's web root at the path above. A manifest that describes a source repository MAY additionally be committed into the repository at "/.well-known/crypto-agility.json" so that it travels with the source and can be regenerated by continuous integration. A manifest retrieved over HTTP or HTTPS SHOULD be retrieved over HTTPS (see ). A consumer MUST NOT follow a cross-origin redirect to locate a manifest without treating the result as belonging to the redirect target rather than the original origin.

File Format The manifest is a single JSON object encoded in UTF-8. When served over HTTP, it SHOULD be served with a "Content-Type" header field of "application/json". A consumer MUST reject a document that is not a single JSON object. The top-level "version" field is the schema contract. A consumer MUST branch on "version" and MUST reject a value it does not understand. This document defines "version" 1. Additive, backward-compatible fields MAY be introduced under "version" 1; any breaking change bumps "version". A consumer MUST ignore object members it does not recognize, so that additive fields do not break older consumers. The manifest is public by design. It MUST NOT contain secrets, source snippets, file contents, or any data not intended for public disclosure (see ).

Field Definitions The manifest object has the members defined in this section. Unless a member is explicitly marked optional, it is REQUIRED and a conforming producer MUST emit it. A machine-readable JSON Schema for "version" 1 accompanies this specification.

version An integer. The manifest schema version. For this specification the value MUST be 1. A consumer MUST reject a version it does not understand.

manifestType A string. A discriminator that lets a consumer distinguish this document from other JSON served at a well-known path. The value MUST be the string "crypto-agility". A consumer MUST reject a document whose "manifestType" is any other value.

generatedAt A string. The instant the manifest was generated, formatted as an Internet timestamp per (a profile of ISO 8601). A producer MUST set this from its runtime clock at generation time.

generator An object describing what produced the manifest. It has two REQUIRED string members:

name:

the name of the producing tool.

version:

the version of the producing tool.

subject An object identifying what the manifest describes. It has three REQUIRED members:

root:

a string. The scanned root the manifest describes.

repository:

a string or null. The source repository the manifest describes. MUST be null when unknown.

commit:

a string or null. The commit identifier the manifest was derived from. MUST be null when unknown.

posture An object carrying the distilled cryptographic posture. It has four REQUIRED members:

readinessScore:

a number from 0 to 100 inclusive. A producer-defined readiness score. A value of 100 means no classical asymmetric cryptography was found. This document does not define how the score is computed; a consumer MUST NOT assume that scores from different producers are directly comparable.

hybridKexInUse:

a boolean or null. Whether the subject negotiates hybrid post-quantum key exchange. A producer that cannot determine this (for example a static source scan, which cannot observe a negotiated key-exchange group) MUST set null. A consumer MUST treat null as "unknown", distinct from false.

quantumVulnerable:

an object with a REQUIRED integer member "total" (the count of quantum-vulnerable findings) and a REQUIRED object member "bySeverity". "bySeverity" MUST contain all five integer keys "critical", "high", "medium", "low", and "info", each a count that MUST NOT be negative.

hndlExposedCount:

an integer. The number of findings exposed to harvest-now-decrypt-later, that is, data that can be recorded today and decrypted once a cryptographically relevant quantum computer exists.

cbomSummary An object that summarizes, and points to, the full CBOM from which it was derived. The full CBOM is intentionally not inlined, so that the manifest stays small. It has three REQUIRED members:

serialNumber:

a string. The CycloneDX "serialNumber" (a "urn:uuid:" value) of the full CBOM this summary was derived from. This links the manifest to a specific CBOM instance.

assetCount:

an integer. The number of distinct "cryptographic-asset" components in the full CBOM.

algorithmFamilies:

an array of objects, ordered most-referenced first. Each element has a REQUIRED string "family" (the algorithm family name, for example "RSA" or "ECDH"), a REQUIRED integer "count" (the number of references to that family), and a REQUIRED boolean "quantumVulnerable".

attestation (optional) An OPTIONAL object. When present, it has one REQUIRED string member:

url:

a URI locating a machine-verifiable posture credential. A producer MUST record the URI verbatim and MUST NOT be required to fetch it when generating the manifest. A producer MUST omit the "attestation" member entirely when no credential is declared, rather than emitting an empty or null value.

The presence of an "attestation" link does not by itself make the manifest verifiable; it points a consumer to where verification can be performed. See .

policy An object stating the migration policy the subject declares it is measured against. It has five REQUIRED members:

source:

a string. A label for the policy source: a published standard's name, or the literal "operator-declared" when the deadlines are set by the operator rather than adopted from a standard.

deprecateClassicalAfter:

an integer year after which classical public-key cryptography is considered deprecated under the declared policy.

disallowClassicalAfter:

an integer year after which classical public-key cryptography is considered disallowed under the declared policy.

transitionDeadline:

a string or null. An operator-declared migration deadline (an date or a year), or null when none is declared.

citation:

a string. A human-readable citation for the declared deadlines.

The values of "deprecateClassicalAfter" and "disallowClassicalAfter" are the policy the subject holds itself to; they are a declaration, not a verification. A producer that adopts a published timeline SHOULD name it in "source" and "citation", for example the 2030 and 2035 milestones of and . National-security profiles such as the milestones of are a valid "operator-declared" choice.

conformance (optional) An OPTIONAL object stating the subject's self-declared conformance to the policy in , together with any residual quantum-vulnerable findings it accepts. It lets a subject that is not at a readiness score of 100 declare that its remaining classical cryptography is known and accepted under the policy, not an oversight. When present, it has two REQUIRED members and two OPTIONAL members:

policy:

a string naming the policy the conformance is asserted against. It SHOULD match the "source" member of the "policy" object.

status:

a string, one of "conformant", "conditional", or "nonconformant". "conformant" means the subject meets the declared policy outright. "conditional" means the subject does not meet the numeric bar, but every residual quantum-vulnerable finding is enumerated in "exceptions" with a justification. "nonconformant" means residual findings exist without accepted exceptions.

statement:

an OPTIONAL string carrying a human-readable rationale for the status.

exceptions:

an OPTIONAL array of the residual findings the subject accepts. Each element is an object with a REQUIRED "family" string (the algorithm family or finding the exception covers, for example "RSA" or "X25519"), a REQUIRED "justification" string, and an OPTIONAL "acceptedUntil" integer year (typically aligned with a policy deadline) or null.

A self-published "conformance" status is a claim of the same kind as every other value in this document, not a proof (). A consumer MUST NOT treat a "conformant" or "conditional" status as assurance unless the manifest also carries an "attestation" () that covers the asserted conformance and that the consumer has verified. A producer that emits a "conformant" or "conditional" status SHOULD also provide an "attestation".

Examples The following is a complete, conforming manifest for a repository that has migrated most, but not all, of its key exchange to hybrid post-quantum key exchange, still uses RSA and ECDH in two places, and adopts the transition timeline. The "conformance" object above is optional. Because its "status" is "conditional", the "attestation" link is what lets a consumer treat it as more than a claim (). A producer that cannot observe live key exchange (a static source scan) sets "hybridKexInUse" to null and omits both "attestation" and "conformance" when neither is declared.

Operational Considerations The manifest is a self-reported claim. Every value in it is asserted by the producer about itself. On its own the manifest establishes what a project says about its posture, not what is true of it. This is the same trust posture as "security.txt": publishing a file does not prove the statements in it. The "attestation" link is the bridge from claim to evidence. It points a consumer to a machine-verifiable posture credential that a third party can check independently of the manifest. A consumer that needs assurance rather than a claim SHOULD follow "attestation.url" and verify the credential there; the manifest itself SHOULD NOT be treated as proof of the posture it reports. A manifest without an "attestation" member is an unverified self-declaration and SHOULD be consumed as such. The manifest and its CBOM summary SHOULD be derived from the same underlying scan and CBOM, so that the summary can never contradict the full CBOM referenced by "cbomSummary.serialNumber". A consumer that needs component-level detail follows that pointer to the full CBOM rather than relying on the summary. Producers SHOULD regenerate the manifest as posture changes, for example on each CI run, so that a stale manifest does not misrepresent a project that has since migrated or regressed. "generatedAt" lets a consumer judge freshness and reject a manifest that is older than a policy it enforces. Relationship to security.txt. An origin that already publishes a "security.txt" file SHOULD co-locate this manifest beside it under "/.well-known/", so that an operator who maintains one maintains the other and the two describe a consistent security posture. RFC 9116 does not define a field for pointing at an arbitrary well-known resource, and its "Encryption" field is reserved for a key or a certificate used to encrypt a report to the operator, not for a posture document; a producer MUST NOT repurpose "Encryption" to reference this manifest. Where an operator wishes to make the link explicit, they MAY add a comment line to "security.txt" naming the manifest's well-known location. A consumer that has discovered a "security.txt" file SHOULD attempt to resolve this manifest at its own well-known path independently, rather than relying on any such reference.

Security Considerations A manifest is a claim, not a proof. Nothing about serving a manifest establishes that its contents are accurate. A consumer MUST NOT treat a manifest as an authenticated statement of posture; a consumer that requires assurance MUST obtain it from a verifiable credential (see ), not from the manifest alone. A hostile or careless producer can overstate readiness, understate vulnerable findings, or advertise deadlines it does not meet. A consumer that gates a decision on an unverified manifest inherits that risk. Self-declared conformance is not a pass. The optional "conformance" object () lets a producer assert a "conformant" or "conditional" status and enumerate accepted exceptions. This is a producer's own assertion and carries no more weight than the readiness score itself. A consumer MUST NOT treat a self-published status as a pass, an approval, or evidence of accepted risk unless the manifest also carries an "attestation" () that covers the asserted conformance and that the consumer has independently verified. Absent a verified attestation, the "status" and "exceptions" are informative context for a human reviewer, not an authorization to proceed. Do not leak internal detail. The manifest is public. A producer MUST NOT place secrets, key material, source snippets, file paths, internal hostnames, or any non-public detail in it. The fields defined here are deliberately coarse summaries for this reason. A precise public inventory of which quantum-vulnerable algorithms a system still uses, and where it is exposed to harvest-now-decrypt-later, is also a roadmap for an attacker; a producer SHOULD weigh the transparency benefit of a detailed posture against the reconnaissance value it hands an adversary, and MAY publish only the coarse summary this document defines. Retrieve over TLS. A manifest retrieved over the network SHOULD be retrieved over HTTPS, so that a network attacker cannot substitute or tamper with it in transit. A consumer SHOULD reject, or clearly mark as untrusted, a manifest retrieved over an unauthenticated channel. As with "security.txt" , a cross-origin redirect encountered while retrieving a manifest MUST NOT be treated as authoritative for the original origin. Freshness and denial of service. A stale manifest can misrepresent current posture; consumers SHOULD use "generatedAt" to bound acceptable age. Because the manifest is fetched automatically and potentially often, producers SHOULD serve it as a static resource, and consumers SHOULD bound the size they will read and cache results, so that manifest retrieval is not turned into a denial-of-service vector against either party.

IANA Considerations IANA is requested to register the following well-known URI in the "Well-Known URIs" registry defined by .

URI suffix:

crypto-agility.json

Change controller:

IETF

Specification document(s):

This document.

Status:

permanent

Related information:

The resource is a JSON document with media type "application/json". See .

This document registers no new media type; the manifest uses the existing "application/json" media type.

Normative References OWASP CycloneDX / Ecma International TC54 Cryptographic assets in the CycloneDX Bill of Materials specification (integrated in CycloneDX 1.6, extended in 1.7; published as Ecma International standard ECMA-424) Informative References National Institute of Standards and Technology National Institute of Standards and Technology Initial Public Draft; deprecation of quantum-vulnerable public-key algorithms after 2030 and disallowance after 2035 The White House National Security Memorandum 10; goal of mitigating quantum risk to the maximum extent feasible by 2035 International Organization for Standardization / International Electrotechnical Commission

Status of This Proposal This document is an individual Internet-Draft, the first step of the IETF process, published to solicit review. It is not the product of an IETF working group and does not represent IETF consensus, and it is not yet a standard: it is a proposal put forward to be reviewed and, if it has merit, advanced. The reference implementation, a schema, and examples are maintained in the open at the repository from which this draft originates.