ci: add CodeQL query to enforce OpenSSL return code handling (#1867)

.github/codeql/openssl-return-check.ql

@@ -0,0 +1,26 @@
+/**
+ * @name Unchecked OpenSSL EVP return value
+ * @description Calls to OpenSSL EVP functions whose return value is not
+ *              checked by the OQS_OPENSSL_GUARD macro may silently ignore
+ *              errors, leading to undefined behaviour.
+ * @kind problem
+ * @problem.severity warning
+ * @precision medium
+ * @id cpp/openssl-unchecked-return
+ * @tags security
+ *       correctness
+ */
+
+import cpp
+
+from FunctionCall call, Function f
+where
+  f = call.getTarget() and
+  f.getName().matches("EVP%") and
+  not f.getType() instanceof PointerType and
+  not f.getType() instanceof VoidType and
+  not exists(MacroAccess m |
+    m.getLocation().subsumes(call.getLocation()) and
+    m.getMacroName() = "OQS_OPENSSL_GUARD"
+  )
+select call, "Return value of " + f.getName() + "() is not checked by OQS_OPENSSL_GUARD."

.github/codeql/test/openssl-return-check-bad.c

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MIT
+/* expect-fail: EVP return value not checked via OQS_OPENSSL_GUARD */
+#include <openssl/evp.h>
+void bad_example(EVP_MD_CTX *ctx, const EVP_MD *md) {
+    EVP_DigestInit_ex(ctx, md, NULL);
+}

.github/workflows/codeql.yml

@@ -0,0 +1,36 @@
+name: CodeQL analysis
+permissions:
+  contents: read
+on:
+  workflow_call:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  codeql:
+    permissions:
+      contents: read
+      security-events: write
+    env:
+      CODEQL_EXTRACTOR_CPP_TRAP_CACHING: false
+    name: CodeQL
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3
+        with:
+          languages: cpp
+          queries: security-and-quality,./.github/codeql/openssl-return-check.ql
+      - name: Build liboqs
+        run: |
+          cmake -S . -B build -DOQS_MINIMAL_BUILD="KEM_ml_kem_768;SIG_ml_dsa_65"
+          cmake --build build --parallel $(nproc)
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@4e828ff8d448a8a6e532957b1811f387a63867e8 # v3
+        with:
+          category: "/language:cpp"
+          upload: false

.github/workflows/pr.yml

@@ -31,3 +31,11 @@ jobs:
       contents: read
       id-token: write
       security-events: write
+
+  codeql:
+    needs: basic-checks
+    uses: ./.github/workflows/codeql.yml
+    secrets: inherit
+    permissions:
+      contents: read
+      security-events: write

CONTRIBUTING.md

@@ -106,3 +106,11 @@ If you feel like contributing but don't know what specific topic to work on,
 please check the [open issues tagged "good first issue" or "help wanted"](https://github.com/open-quantum-safe/liboqs/issues).
 
 You can also take a look at the [contribution wishlist](https://github.com/open-quantum-safe/liboqs/wiki/Contribution-wishlist) for more substantial contributions we are interested in.
+
+## Verifying the CodeQL OpenSSL return-check query
+The query detects EVP_* calls not wrapped in OQS_OPENSSL_GUARD.
+A deliberately bad example lives in
+.github/codeql/test/openssl-return-check-bad.c.
+When CodeQL runs, any match against this file confirms the query
+is scanning correctly. CI will flag new violations automatically
+on every PR.