Comments and reorg.

Author: bdrodes

cpp/ql/src/experimental/campaigns/nccoe-pqc-migration/QuantumVulnerableDiscovery/WinCng/WindowsCng.qll

@@ -6,29 +6,47 @@ abstract class BCryptOpenAlgorithmProviderSink extends DataFlow::Node { }
 
 abstract class BCryptOpenAlgorithmProviderSource extends DataFlow::Node { }
 
+// ------------------ Helper Predicates ----------------------
+/**
+ * Holds if there is a call with global name`funcGlobalName` with argument `arg` of that call
+ * at argument index `index`.
+ */
 predicate isCallArgument(string funcGlobalName, Expr arg, int index) {
   exists(Call c | c.getArgument(index) = arg and c.getTarget().hasGlobalName(funcGlobalName))
 }
 
+/**
+ * Holdes if StringLiteral `lit` has a string value indicative of a post quantum crypto
+ * vulnerable algorithm identifier.
+ */
+predicate vulnProviderLiteral(StringLiteral lit) {
+  exists(string s | s = lit.getValue() |
+    s in ["DH", "DSA", "ECDSA", "ECDH"] or
+    s.matches("ECDH%") or
+    s.matches("RSA%")
+  )
+}
+
 //TODO: Verify NCrypt calls (parameters) & find all other APIs that should be included (i.e. decrypt, etc.)
-// ------------------ SINKS ----------------------
+// ------------------ Default SINKS ----------------------
+/**
+ * Argument at index 0 of call to BCryptSignHash
+ */
 class BCryptSignHashArgumentSink extends BCryptOpenAlgorithmProviderSink {
   BCryptSignHashArgumentSink() { isCallArgument("BCryptSignHash", this.asExpr(), 0) }
 }
 
+/**
+ * Argument at index 0 of call to BCryptEncrypt
+ */
 class BCryptEncryptArgumentSink extends BCryptOpenAlgorithmProviderSink {
   BCryptEncryptArgumentSink() { isCallArgument("BCryptEncrypt", this.asExpr(), 0) }
 }
 
-// ----------------- SOURCES -----------------------
-predicate vulnProviderLiteral(StringLiteral lit) {
-  exists(string s | s = lit.getValue() |
-    s in ["DH", "DSA", "ECDSA", "ECDH"] or
-    s.matches("ECDH%") or
-    s.matches("RSA%")
-  )
-}
-
+// ----------------- Default SOURCES -----------------------
+/**
+ * A string identifier of known PQC vulnerable algorithms.
+ */
 class BCryptOpenAlgorithmProviderPqcVulnerableAlgorithmsSource extends BCryptOpenAlgorithmProviderSource {
   BCryptOpenAlgorithmProviderPqcVulnerableAlgorithmsSource() { vulnProviderLiteral(this.asExpr()) }
 }

cpp/ql/src/experimental/campaigns/nccoe-pqc-migration/QuantumVulnerableDiscovery/WinCng/WindowsCngPQCVulnerableUsage.ql

@@ -16,7 +16,6 @@ import DataFlow::PathGraph
 import WindowsCng
 import WindowsCngPQCVulnerableUsage
 
-
 from BCryptConfiguration config, DataFlow::PathNode source, DataFlow::PathNode sink
 where config.hasFlowPath(source, sink)
 select sink.getNode(), source, sink, "PQC vulnerable algorithm $@ in use has been detected.",

cpp/ql/src/experimental/campaigns/nccoe-pqc-migration/QuantumVulnerableDiscovery/WinCng/WindowsCngPQCVulnerableUsage.qll

@@ -1,6 +1,12 @@
 import cpp
 import WindowsCng
 
+/**
+ * Steps from input variable (argument 1) to output variable (argument 0)
+ * for CNG API BCryptOpenAlgorithmProvider.
+ * Argument 1 represents LPCWSTR (a string algorithm ID)
+ * Argument 0 represents BCRYPT_ALG_HANDLE
+ */
 predicate stepOpenAlgorithmProvider(DataFlow::Node node1, DataFlow::Node node2) {
   exists(FunctionCall call |
     // BCryptOpenAlgorithmProvider 2nd argument specifies the algorithm to be used
@@ -10,6 +16,12 @@ predicate stepOpenAlgorithmProvider(DataFlow::Node node1, DataFlow::Node node2)
   )
 }
 
+/**
+ * Steps from input variable (argument 0) to output variable (argument 1)
+ * for CNG APIs BCryptImportKeyPair and BCryptGenerateKeyPair.
+ * Argument 0 represents a BCRYPT_ALG_HANDLE.
+ * Argument 1 represents a BCRYPT_KEY_HANDLE.
+ */
 predicate stepImportGenerateKeyPair(DataFlow::Node node1, DataFlow::Node node2) {
   exists(FunctionCall call |
     node1.asExpr() = call.getArgument(0) and
@@ -21,14 +33,18 @@ predicate stepImportGenerateKeyPair(DataFlow::Node node1, DataFlow::Node node2)
   )
 }
 
+/**
+ * Additional DataFlow steps from input variables to output handle variables on CNG apis.
+ */
 predicate isWindowsCngAdditionalTaintStep(DataFlow::Node node1, DataFlow::Node node2) {
   stepOpenAlgorithmProvider(node1, node2)
   or
   stepImportGenerateKeyPair(node1, node2)
 }
 
-
-// CNG-specific DataFlow configuration
+/**
+ * CNG-specific DataFlow configuration
+ */
 class BCryptConfiguration extends DataFlow::Configuration {
   BCryptConfiguration() { this = "BCryptConfiguration" }