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/2] 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 40d5c0eb84144996c077ed5a80971ea4bcf47bfc 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/2] 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; a value of 0 states that none of the categories are met; consumers must check whether the field is present rather than comparing the value to 0. 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.