docs: add post-quantum migration CBOM example

CBOM/Post-Quantum-Migration/README.md

@@ -0,0 +1,23 @@
+# Post-Quantum Migration CBOM Example
+
+This example models an application during a staged migration from classical public-key cryptography to post-quantum cryptography. The inventory contains ML-KEM-768 and ML-DSA-65 alongside ECDH P-256 and ECDSA P-256, reflecting a period in which compatibility or migration constraints require both algorithm families to remain present.
+
+The application depends on an illustrative cryptographic library, and the library provides the four algorithm assets. This separation allows consumers to distinguish the application that uses a cryptographic implementation from the implementation boundary and the algorithms it provides.
+
+## Interpreting the inventory
+
+`nistQuantumSecurityLevel` records the NIST security category associated with the parameter set. A value of `0` on the classical ECDH and ECDSA assets means that they do not provide security against a cryptographically relevant quantum computer. It does not mean that they provide no classical security.
+
+The presence of an algorithm in a CBOM does not establish that:
+
+- the implementation is correct or side-channel resistant;
+- the application negotiates or combines algorithms securely;
+- keys and other cryptographic material are managed securely;
+- every runtime-selected algorithm was discovered; or
+- migration to post-quantum cryptography is complete.
+
+Inventory consumers should retain unresolved or dynamically selected algorithms as explicit unknowns rather than classifying them as quantum-safe. Migration decisions also require deployment context, protected-data lifetime, protocol behavior, interoperability testing, and implementation validation.
+
+## Source fixture
+
+[`fixture/app.py`](fixture/app.py) is a deliberately small, non-executable discovery fixture. It identifies the algorithm selections and operations represented by the CBOM without including keys, ciphertexts, signatures, or generated cryptographic material. It was reduced from the open-source [`AAH_PostQuantum_Cryptography`](https://github.com/AAH20/AAH_PostQuantum_Cryptography) implementation for use as a stable inventory example.

CBOM/Post-Quantum-Migration/bom.json

@@ -0,0 +1,155 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:57d81338-2f4c-5b91-9f46-d92b1efb1328",
+  "version": 1,
+  "metadata": {
+    "timestamp": "2026-08-17T00:00:00Z",
+    "component": {
+      "type": "application",
+      "bom-ref": "application:pqc-migration-example@1.0.0",
+      "name": "PQC Migration Example",
+      "version": "1.0.0",
+      "description": "An illustrative application in a transition state where classical and post-quantum cryptographic algorithms coexist."
+    }
+  },
+  "components": [
+    {
+      "type": "library",
+      "bom-ref": "library:python-oqs-binding",
+      "name": "Python OQS binding",
+      "description": "Illustrative implementation boundary for the algorithms used by the source fixture."
+    },
+    {
+      "type": "cryptographic-asset",
+      "bom-ref": "algorithm:ml-kem-768",
+      "name": "ML-KEM-768",
+      "cryptoProperties": {
+        "assetType": "algorithm",
+        "algorithmProperties": {
+          "algorithmFamily": "ML-KEM",
+          "primitive": "kem",
+          "parameterSetIdentifier": "ML-KEM-768",
+          "executionEnvironment": "software-plain-ram",
+          "implementationPlatform": "x86_64",
+          "certificationLevel": [
+            "none"
+          ],
+          "cryptoFunctions": [
+            "keygen",
+            "keyderive"
+          ],
+          "nistQuantumSecurityLevel": 3
+        },
+        "oid": "2.16.840.1.101.3.4.4.2"
+      }
+    },
+    {
+      "type": "cryptographic-asset",
+      "bom-ref": "algorithm:ml-dsa-65",
+      "name": "ML-DSA-65",
+      "cryptoProperties": {
+        "assetType": "algorithm",
+        "algorithmProperties": {
+          "algorithmFamily": "ML-DSA",
+          "primitive": "signature",
+          "parameterSetIdentifier": "ML-DSA-65",
+          "executionEnvironment": "software-plain-ram",
+          "implementationPlatform": "x86_64",
+          "certificationLevel": [
+            "none"
+          ],
+          "cryptoFunctions": [
+            "keygen",
+            "sign",
+            "verify"
+          ],
+          "nistQuantumSecurityLevel": 3
+        },
+        "oid": "2.16.840.1.101.3.4.3.18"
+      }
+    },
+    {
+      "type": "cryptographic-asset",
+      "bom-ref": "algorithm:ecdh-p-256",
+      "name": "ECDH-P-256",
+      "cryptoProperties": {
+        "assetType": "algorithm",
+        "algorithmProperties": {
+          "algorithmFamily": "ECDH",
+          "primitive": "key-agree",
+          "parameterSetIdentifier": "P-256",
+          "ellipticCurve": "nist/P-256",
+          "executionEnvironment": "software-plain-ram",
+          "implementationPlatform": "x86_64",
+          "certificationLevel": [
+            "none"
+          ],
+          "cryptoFunctions": [
+            "keygen",
+            "keyderive"
+          ],
+          "classicalSecurityLevel": 128,
+          "nistQuantumSecurityLevel": 0
+        },
+        "oid": "1.2.840.10045.3.1.7"
+      }
+    },
+    {
+      "type": "cryptographic-asset",
+      "bom-ref": "algorithm:ecdsa-p-256-sha-256",
+      "name": "ECDSA-P-256-SHA-256",
+      "cryptoProperties": {
+        "assetType": "algorithm",
+        "algorithmProperties": {
+          "algorithmFamily": "ECDSA",
+          "primitive": "signature",
+          "parameterSetIdentifier": "P-256/SHA-256",
+          "ellipticCurve": "nist/P-256",
+          "executionEnvironment": "software-plain-ram",
+          "implementationPlatform": "x86_64",
+          "certificationLevel": [
+            "none"
+          ],
+          "cryptoFunctions": [
+            "keygen",
+            "sign",
+            "verify"
+          ],
+          "classicalSecurityLevel": 128,
+          "nistQuantumSecurityLevel": 0
+        },
+        "oid": "1.2.840.10045.4.3.2"
+      }
+    }
+  ],
+  "dependencies": [
+    {
+      "ref": "application:pqc-migration-example@1.0.0",
+      "dependsOn": [
+        "library:python-oqs-binding"
+      ]
+    },
+    {
+      "ref": "library:python-oqs-binding",
+      "provides": [
+        "algorithm:ml-kem-768",
+        "algorithm:ml-dsa-65",
+        "algorithm:ecdh-p-256",
+        "algorithm:ecdsa-p-256-sha-256"
+      ]
+    },
+    {
+      "ref": "algorithm:ml-kem-768"
+    },
+    {
+      "ref": "algorithm:ml-dsa-65"
+    },
+    {
+      "ref": "algorithm:ecdh-p-256"
+    },
+    {
+      "ref": "algorithm:ecdsa-p-256-sha-256"
+    }
+  ]
+}

CBOM/Post-Quantum-Migration/fixture/app.py

@@ -0,0 +1,15 @@
+"""Static discovery fixture for a staged post-quantum migration inventory."""
+
+POST_QUANTUM_KEY_ESTABLISHMENT = "ML-KEM-768"
+POST_QUANTUM_SIGNATURE = "ML-DSA-65"
+
+# Classical algorithms remain visible during the transition period.
+CLASSICAL_KEY_ESTABLISHMENT = "ECDH-P-256"
+CLASSICAL_SIGNATURE = "ECDSA-P-256-SHA-256"
+
+CRYPTOGRAPHIC_OPERATIONS = {
+    POST_QUANTUM_KEY_ESTABLISHMENT: ("keygen", "keyderive"),
+    POST_QUANTUM_SIGNATURE: ("keygen", "sign", "verify"),
+    CLASSICAL_KEY_ESTABLISHMENT: ("keygen", "keyderive"),
+    CLASSICAL_SIGNATURE: ("keygen", "sign", "verify"),
+}