ACVP: Support FIPS203-tr1 encapDecap (v1.1.0.43)

The FIPS203-tr1 encapDecap revision adds keyFormat 'seed'/'expanded'
groups: the decapsulation key may be supplied as a seed (d||z) to
expand rather than as the expanded dk.

Add a decode_dk() entry point to the ACVP harness accepting either
dk=HEX or seed=HEX (expanding the seed via crypto_kem_keypair_derand),
and route the decapsulation function through it. keyFormat is inspected
per group, so the client copes whether or not a given file carries it.
decode_dk is MLK_NOINLINE so its keyGen scratch stays out of main's
stack frame, which under -fsanitize=undefined would otherwise overflow
AVR RAM. Download and run the ML-KEM-encapDecap-FIPS203-tr1 vectors
when the version ships them (v1.1.0.43+); keep the base FIPS203 dataset.

Two quirks in the v1.1.0.43 sample vectors are worth recording:

- decapsulationKeyCheck cases carry only a tcId with no dk, yet their
  expected results are a non-trivial mix of pass and fail, so they
  cannot be reproduced offline. The client drops decapsulationKeyCheck
  cases that lack a key, from prompt and expected alike; they run
  normally again once a key is present. This is a known upstream sample
  bug (usnistgov/ACVP-Server#459), where the maintainers confirm
  keyFormat there should be 'expanded' with the dk provided.

- The base ML-KEM-encapDecap-FIPS203 file also gained keyFormat at
  v1.1.0.43, whereas for ML-DSA only the -tr1 revision carries it. This
  looks like an unintended regeneration of the base file; the per-group
  handling above keeps the client correct whether or not it is fixed.

Bump the default ACVP version to v1.1.0.43 and roll the CI matrix
forward to the three latest revisions.

Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>

Author: mkannwischer

.github/workflows/base.yml

@@ -67,7 +67,7 @@ jobs:
            name: 'aarch64'
          - runner: ubuntu-latest
            name: 'x86_64'
-        acvp-version: [v1.1.0.40, v1.1.0.41, v1.1.0.42]
+        acvp-version: [v1.1.0.41, v1.1.0.42, v1.1.0.43]
         exclude:
           - {external: true,
              target: {

scripts/tests

@@ -1353,8 +1353,8 @@ def cli():
     )
     acvp_parser.add_argument(
         "--version",
-        default="v1.1.0.41",
-        help="ACVP test vector version (default: v1.1.0.41)",
+        default="v1.1.0.43",
+        help="ACVP test vector version (default: v1.1.0.43)",
     )
 
     # wycheproof arguments

test/acvp/acvp_client.py

@@ -20,6 +20,16 @@
 exec_prefix = exec_prefix.split(" ") if exec_prefix != "" else []
 
 
+def acvp_version_has_tr1(version):
+    """Whether `version` ships the FIPS203-tr1 encapDecap vectors (v1.1.0.43+)."""
+    try:
+        parts = tuple(int(x) for x in version.lstrip("v").split("."))
+    except ValueError:
+        # Non-numeric ref (branch or commit); assume the vectors are present.
+        return True
+    return parts >= (1, 1, 0, 43)
+
+
 def download_acvp_files(version):
     """Download ACVP test files for the specified version if not present."""
     base_url = f"https://raw.githubusercontent.com/usnistgov/ACVP-Server/{version}/gen-val/json-files"
@@ -32,6 +42,13 @@ def download_acvp_files(version):
         "ML-KEM-encapDecap-FIPS203/expectedResults.json",
     ]
 
+    # The FIPS203-tr1 encapDecap vectors add seed/expanded key-format groups.
+    if acvp_version_has_tr1(version):
+        files_to_download += [
+            "ML-KEM-encapDecap-FIPS203-tr1/prompt.json",
+            "ML-KEM-encapDecap-FIPS203-tr1/expectedResults.json",
+        ]
+
     # Create directory structure
     data_dir = Path(f"test/acvp/.acvp-data/{version}/files")
     data_dir.mkdir(parents=True, exist_ok=True)
@@ -63,6 +80,38 @@ def download_acvp_files(version):
     return True
 
 
+def unwrap_acvts(data):
+    # ACVTS files wrap the payload as [{"acvVersion": ...}, {...}].
+    return data[1] if isinstance(data, list) else data
+
+
+def drop_keyless_decap_key_checks(data):
+    """Drop decapsulationKeyCheck cases that provide no key.
+
+    Some ML-KEM sample vectors omit dk for these cases; the check cannot run
+    without a key. Removed from prompt and expected so the comparison stays
+    consistent, and runs normally once a key is present.
+    """
+    dropped = 0
+    for _, promptData, _, expectedData in data:
+        drop = set()
+        for tg in unwrap_acvts(promptData).get("testGroups", []):
+            if tg.get("function") != "decapsulationKeyCheck":
+                continue
+            for tc in tg["tests"]:
+                if "dk" not in tc:
+                    drop.add((tg["tgId"], tc["tcId"]))
+        for d in (promptData, expectedData):
+            if d is None:
+                continue
+            for tg in unwrap_acvts(d).get("testGroups", []):
+                tg["tests"] = [
+                    tc for tc in tg["tests"] if (tg["tgId"], tc["tcId"]) not in drop
+                ]
+        dropped += len(drop)
+    return dropped
+
+
 def loadAcvpData(prompt, expectedResults):
     with open(prompt, "r") as f:
         promptData = json.load(f)
@@ -86,6 +135,17 @@ def loadDefaultAcvpData(version):
             f"{data_dir}/ML-KEM-encapDecap-FIPS203/expectedResults.json",
         ),
     ]
+
+    # FIPS203-tr1 encapDecap vectors (seed/expanded key formats) exist from
+    # v1.1.0.43.
+    if acvp_version_has_tr1(version):
+        acvp_jsons_for_version.append(
+            (
+                f"{data_dir}/ML-KEM-encapDecap-FIPS203-tr1/prompt.json",
+                f"{data_dir}/ML-KEM-encapDecap-FIPS203-tr1/expectedResults.json",
+            )
+        )
+
     acvp_data = []
     for prompt, expectedResults in acvp_jsons_for_version:
         acvp_data.append(loadAcvpData(prompt, expectedResults))
@@ -139,12 +199,18 @@ def run_encapDecap_test(tg, tc):
             results[k] = v
     elif tg["function"] == "decapsulation":
         acvp_bin = get_acvp_binary(tg)
+        # keyFormat 'seed' provides d and z to expand into the key; 'expanded'
+        # (or absent) provides the expanded dk directly.
+        if tg.get("keyFormat") == "seed":
+            key_arg = f"seed={tc['d'] + tc['z']}"
+        else:
+            key_arg = f"dk={tc['dk']}"
         acvp_call = exec_prefix + [
             acvp_bin,
             "encapDecap",
             "VAL",
             "decapsulation",
-            f"dk={tc['dk']}",
+            key_arg,
             f"c={tc['c']}",
         ]
         result = subprocess.run(acvp_call, encoding="utf-8", capture_output=True)
@@ -319,6 +385,10 @@ def test(prompt, expected, output, version):
         # load data from downloaded files
         data = loadDefaultAcvpData(version)
 
+    dropped = drop_keyless_decap_key_checks(data)
+    if dropped:
+        info(f"Skipping {dropped} decapsulationKeyCheck case(s) with no key")
+
     runTest(data, output)
 
 
@@ -338,8 +408,8 @@ def test(prompt, expected, output, version):
 parser.add_argument(
     "--version",
     "-v",
-    default="v1.1.0.41",
-    help="ACVP test vector version (default: v1.1.0.41)",
+    default="v1.1.0.43",
+    help="ACVP test vector version (default: v1.1.0.43)",
 )
 args = parser.parse_args()
 

test/acvp/acvp_mlkem.c

@@ -119,6 +119,38 @@ static int decode_hex(const char *prefix, unsigned char *out, size_t out_len,
   return 1;
 }
 
+/*
+ * Decode the decapsulation-key argument into dk. It is either the expanded
+ * key ("dk=HEX", keyFormat 'expanded') or a seed d||z to expand via keyGen
+ * ("seed=HEX", keyFormat 'seed'). Returns 0 on success, 1 on failure.
+ * MLK_NOINLINE keeps the keyGen scratch (ek) out of the caller's (main's)
+ * stack frame; under -fsanitize=undefined it would not share slots and would
+ * overflow AVR RAM.
+ */
+static MLK_NOINLINE int decode_dk(const char *arg,
+                                  unsigned char dk[CRYPTO_SECRETKEYBYTES])
+{
+  size_t seed_len = strlen("seed=");
+
+  /* Prefix check via memcmp; strncmp is unavailable on baremetal builds. */
+  if (strlen(arg) >= seed_len && memcmp(arg, "seed=", seed_len) == 0)
+  {
+    unsigned char ek[CRYPTO_PUBLICKEYBYTES];
+    unsigned char coins[2 * MLKEM_SYMBYTES];
+    if (decode_hex("seed", coins, sizeof(coins), arg) != 0)
+    {
+      return 1;
+    }
+    if (crypto_kem_keypair_derand(ek, dk, coins) != 0)
+    {
+      fprintf(stderr, "Failed to expand seed into decapsulation key\n");
+      return 1;
+    }
+    return 0;
+  }
+  return decode_hex("dk", dk, CRYPTO_SECRETKEYBYTES, arg);
+}
+
 static void print_hex(const char *name, const unsigned char *raw, size_t len)
 {
   if (name != NULL)
@@ -321,8 +353,8 @@ int main(int argc, char *argv[])
             goto decaps_usage;
           }
 
-          /* Parse dk */
-          if (argc == 0 || decode_hex("dk", dk, sizeof(dk), *argv) != 0)
+          /* Parse dk (expanded key, or a seed to expand) */
+          if (argc == 0 || decode_dk(*argv, dk) != 0)
           {
             goto decaps_usage;
           }