From f84e0f75a4fb719387803678b9fb5cbbab4c56a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=A4=A9=E8=B5=AB?= Date: Mon, 26 Oct 2026 10:21:08 +0800 Subject: [PATCH 1/3] docs(1.7): clarify that an omitted nistQuantumSecurityLevel is not 0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 1.7 description only stated "A value of 0 indicates that none of the categories are met." It said nothing about the omitted case, which leaves two readings open: that omission means 0, or that omission means "not evaluated". Both readings are wrong. 0 is an assertion that none of the categories are met; an omitted property makes no category assertion at all, and says nothing about whether an assessment was performed. Encoding "unknown" as 0 turns a non-claim into a claim. Description-only change, applied to the three 1.7 artifacts so they stay in sync: bom-1.7.schema.json (description), bom-1.7.xsd (documentation) and bom-1.7.proto (comment). No structure, type, bound or required list is touched. Verified: the edited schema still compiles under ajv; valid-bom-1.7.json still validates, and two invalid 1.7 fixtures are still rejected, so the check is not vacuous; the XSD still parses as XML. No BOM, no CRLF, no U+FFFD introduced. 1.6.2 keeps its current wording here: it is released and superseded by 1.7, and changing a released artifact is a separate decision. 2.0-dev needs the same wording once this one is settled. Signed-off-by: 刘天赫 --- schema/bom-1.7.proto | 2 +- schema/bom-1.7.schema.json | 2 +- schema/bom-1.7.xsd | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/schema/bom-1.7.proto b/schema/bom-1.7.proto index 5a1dc6c84..d8a69087b 100644 --- a/schema/bom-1.7.proto +++ b/schema/bom-1.7.proto @@ -2321,7 +2321,7 @@ message CryptoProperties { repeated CryptoAlgorithmFunction cryptoFunctions = 9; // The classical security level that a cryptographic algorithm provides (in bits). optional int32 classicalSecurityLevel = 10; - // The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). A value of 0 indicates that none of the categories are met. + // The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional and has no default: omitting it is not an implicit 0, and does not establish whether an assessment was performed. A value of 0 indicates that none of the categories are met. Consumers should not interpret an omitted value as 0, nor treat it as evidence that the asset is quantum-safe. optional int32 nistQuantumSecurityLevel = 11; } // end of AlgorithmProperties diff --git a/schema/bom-1.7.schema.json b/schema/bom-1.7.schema.json index 1ca17a2e3..0a699fe6d 100644 --- a/schema/bom-1.7.schema.json +++ b/schema/bom-1.7.schema.json @@ -5495,7 +5495,7 @@ "nistQuantumSecurityLevel": { "type": "integer", "title": "NIST security strength category", - "description": "The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). A value of 0 indicates that none of the categories are met.", + "description": "The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional and has no default: omitting it is not an implicit 0, and does not establish whether an assessment was performed. A value of 0 indicates that none of the categories are met. Consumers should not interpret an omitted value as 0, nor treat it as evidence that the asset is quantum-safe.", "minimum": 0, "maximum": 6 } diff --git a/schema/bom-1.7.xsd b/schema/bom-1.7.xsd index c8687c766..84b4e64dc 100644 --- a/schema/bom-1.7.xsd +++ b/schema/bom-1.7.xsd @@ -7289,7 +7289,11 @@ limitations under the License. The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). + This property is optional and has no default: omitting it is not an + implicit 0, and does not establish whether an assessment was performed. A value of 0 indicates that none of the categories are met. + Consumers should not interpret an omitted value as 0, nor treat it as + evidence that the asset is quantum-safe. From 356280aaaa40ff3db2c7b3ea4819a4de83c61cb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=A4=A9=E8=B5=AB?= Date: Mon, 26 Oct 2026 19:51:01 +0800 Subject: [PATCH 2/3] docs(1.7): describe field presence instead of "has no default" for nistQuantumSecurityLevel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Protobuf comment said the property "has no default", which is the wrong model for `optional int32`: an unset field's numeric accessor returns 0, so the value alone cannot be told apart from an explicitly supplied zero. That is exactly the confusion this clarification exists to prevent. Replace the phrase in all three 1.7 artifacts and state the consequence instead: an omitted value makes no category assertion and does not establish whether an assessment was performed; an explicit value of 0 indicates that none of the NIST-defined quantum security categories apply; consumers must check whether the field is present rather than comparing the value to 0. The zero case is now stated in its own sentence. It is worth saying plainly because 0 is not one of the NIST categories -- it is a value in the permitted range that asserts the absence of all of them -- and a reader who sees only "0..6" should not have to infer that. Language-neutral on purpose. No per-binding accessor names, so the wording does not need revising when bindings change. Description and documentation text only. No field number, type, optionality, bound or required list is touched: the JSON structure is unchanged apart from description strings, and the XSD still parses as XML. Signed-off-by: 刘天赫 --- schema/bom-1.7.proto | 2 +- schema/bom-1.7.schema.json | 2 +- schema/bom-1.7.xsd | 10 ++++++---- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/schema/bom-1.7.proto b/schema/bom-1.7.proto index d8a69087b..8c90872c9 100644 --- a/schema/bom-1.7.proto +++ b/schema/bom-1.7.proto @@ -2321,7 +2321,7 @@ message CryptoProperties { repeated CryptoAlgorithmFunction cryptoFunctions = 9; // The classical security level that a cryptographic algorithm provides (in bits). optional int32 classicalSecurityLevel = 10; - // The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional and has no default: omitting it is not an implicit 0, and does not establish whether an assessment was performed. A value of 0 indicates that none of the categories are met. Consumers should not interpret an omitted value as 0, nor treat it as evidence that the asset is quantum-safe. + // The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional. Omitting it makes no NIST security category assertion and does not establish whether an assessment was performed; a value of 0 states that none of the categories are met. An unset integer field may read back as 0, so the raw value cannot distinguish absence from an explicit zero: consumers must check whether the field is present rather than comparing the value to 0. An omitted value is not 0, and is not evidence that the asset is quantum-safe. optional int32 nistQuantumSecurityLevel = 11; } // end of AlgorithmProperties diff --git a/schema/bom-1.7.schema.json b/schema/bom-1.7.schema.json index 0a699fe6d..2d9a68d12 100644 --- a/schema/bom-1.7.schema.json +++ b/schema/bom-1.7.schema.json @@ -5495,7 +5495,7 @@ "nistQuantumSecurityLevel": { "type": "integer", "title": "NIST security strength category", - "description": "The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional and has no default: omitting it is not an implicit 0, and does not establish whether an assessment was performed. A value of 0 indicates that none of the categories are met. Consumers should not interpret an omitted value as 0, nor treat it as evidence that the asset is quantum-safe.", + "description": "The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional. Omitting it makes no NIST security category assertion and does not establish whether an assessment was performed; a value of 0 states that none of the categories are met. An unset integer field may read back as 0, so the raw value cannot distinguish absence from an explicit zero: consumers must check whether the field is present rather than comparing the value to 0. An omitted value is not 0, and is not evidence that the asset is quantum-safe.", "minimum": 0, "maximum": 6 } diff --git a/schema/bom-1.7.xsd b/schema/bom-1.7.xsd index 84b4e64dc..9636c5823 100644 --- a/schema/bom-1.7.xsd +++ b/schema/bom-1.7.xsd @@ -7289,10 +7289,12 @@ limitations under the License. The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). - This property is optional and has no default: omitting it is not an - implicit 0, and does not establish whether an assessment was performed. - A value of 0 indicates that none of the categories are met. - Consumers should not interpret an omitted value as 0, nor treat it as + This property is optional. Omitting it makes no NIST security category + assertion and does not establish whether an assessment was performed; + a value of 0 states that none of the categories are met. An unset integer + field may read back as 0, so the raw value cannot distinguish absence from + an explicit zero: consumers must check whether the field is present rather + than comparing the value to 0. An omitted value is not 0, and is not evidence that the asset is quantum-safe. From d549b4be3f518752fa242660ca58a7b46ae8b84e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E5=A4=A9=E8=B5=AB?= Date: Fri, 30 Oct 2026 11:21:20 +0800 Subject: [PATCH 3/3] docs(1.7): state the explicit-zero case in its own sentence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the sentence requested in review, verbatim and as a standalone sentence: An explicit value of 0 indicates that none of the NIST-defined quantum security categories apply. The case is worth its own sentence rather than the previous clause: 0 is not one of the NIST categories, and a reader who only sees the 0..6 range should not have to infer that 0 asserts the absence of all of them. Also drops "This property is optional.", which duplicated what the schema already expresses, and leaves the accessor-level presence check to the guides as raised in the same thread. The omission semantics stay in the description: omitting the field makes no category assertion and is not evidence that the asset is quantum-safe. Applied to all three 1.7 artifacts: schema/bom-1.7.schema.json (description), schema/bom-1.7.xsd (xs:documentation) and schema/bom-1.7.proto (field comment). Description text only: no field number, type, bound, optionality or required list is touched. Verified locally: the JSON parses and the new text is at definitions.cryptoProperties.properties.algorithmProperties.properties .nistQuantumSecurityLevel.description; the XSD parses as well-formed XML. No protoc available here, so no descriptor-set comparison is claimed for this commit. Signed-off-by: 刘天赫 --- schema/bom-1.7.proto | 2 +- schema/bom-1.7.schema.json | 2 +- schema/bom-1.7.xsd | 11 ++++------- 3 files changed, 6 insertions(+), 9 deletions(-) diff --git a/schema/bom-1.7.proto b/schema/bom-1.7.proto index 8c90872c9..e4226d4cf 100644 --- a/schema/bom-1.7.proto +++ b/schema/bom-1.7.proto @@ -2321,7 +2321,7 @@ message CryptoProperties { repeated CryptoAlgorithmFunction cryptoFunctions = 9; // The classical security level that a cryptographic algorithm provides (in bits). optional int32 classicalSecurityLevel = 10; - // The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional. Omitting it makes no NIST security category assertion and does not establish whether an assessment was performed; a value of 0 states that none of the categories are met. An unset integer field may read back as 0, so the raw value cannot distinguish absence from an explicit zero: consumers must check whether the field is present rather than comparing the value to 0. An omitted value is not 0, and is not evidence that the asset is quantum-safe. + // The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). Omitting this property makes no NIST security category assertion and does not establish whether an assessment was performed; it is not evidence that the asset is quantum-safe. An explicit value of 0 indicates that none of the NIST-defined quantum security categories apply. optional int32 nistQuantumSecurityLevel = 11; } // end of AlgorithmProperties diff --git a/schema/bom-1.7.schema.json b/schema/bom-1.7.schema.json index 2d9a68d12..f8fe1cb56 100644 --- a/schema/bom-1.7.schema.json +++ b/schema/bom-1.7.schema.json @@ -5495,7 +5495,7 @@ "nistQuantumSecurityLevel": { "type": "integer", "title": "NIST security strength category", - "description": "The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). This property is optional. Omitting it makes no NIST security category assertion and does not establish whether an assessment was performed; a value of 0 states that none of the categories are met. An unset integer field may read back as 0, so the raw value cannot distinguish absence from an explicit zero: consumers must check whether the field is present rather than comparing the value to 0. An omitted value is not 0, and is not evidence that the asset is quantum-safe.", + "description": "The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). Omitting this property makes no NIST security category assertion and does not establish whether an assessment was performed; it is not evidence that the asset is quantum-safe. An explicit value of 0 indicates that none of the NIST-defined quantum security categories apply.", "minimum": 0, "maximum": 6 } diff --git a/schema/bom-1.7.xsd b/schema/bom-1.7.xsd index 9636c5823..e177c827c 100644 --- a/schema/bom-1.7.xsd +++ b/schema/bom-1.7.xsd @@ -7289,13 +7289,10 @@ limitations under the License. The NIST security strength category as defined in https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/evaluation-criteria/security-(evaluation-criteria). - This property is optional. Omitting it makes no NIST security category - assertion and does not establish whether an assessment was performed; - a value of 0 states that none of the categories are met. An unset integer - field may read back as 0, so the raw value cannot distinguish absence from - an explicit zero: consumers must check whether the field is present rather - than comparing the value to 0. An omitted value is not 0, and is not - evidence that the asset is quantum-safe. + Omitting this property makes no NIST security category assertion and does + not establish whether an assessment was performed; it is not evidence that + the asset is quantum-safe. An explicit value of 0 indicates that none of the + NIST-defined quantum security categories apply.