Merge pull request #1188 from pq-code-package/backend_test

Add unit test target

Author: mkannwischer

Makefile

@@ -37,7 +37,7 @@ quickcheck: test
 build: func kat acvp
 	$(Q)echo "  Everything builds fine!"
 
-test: run_kat run_func run_acvp
+test: run_kat run_func run_acvp run_unit
 	$(Q)echo "  Everything checks fine!"
 
 # Detect available SHA256 command
@@ -62,6 +62,14 @@ run_func_1024: func_1024
 	$(W) $(MLKEM1024_DIR)/bin/test_mlkem1024
 run_func: run_func_512 run_func_768 run_func_1024
 
+run_unit_512: unit_512
+	$(W) $(MLKEM512_DIR)/bin/test_unit512
+run_unit_768: unit_768
+	$(W) $(MLKEM768_DIR)/bin/test_unit768
+run_unit_1024: unit_1024
+	$(W) $(MLKEM1024_DIR)/bin/test_unit1024
+run_unit: run_unit_512 run_unit_768 run_unit_1024
+
 run_acvp: acvp
 	python3 ./test/acvp_client.py $(if $(ACVP_VERSION),--version $(ACVP_VERSION))
 
@@ -73,6 +81,14 @@ func_1024: $(MLKEM1024_DIR)/bin/test_mlkem1024
 	$(Q)echo "  FUNC       ML-KEM-1024:  $^"
 func: func_512 func_768 func_1024
 
+unit_512:  $(MLKEM512_DIR)/bin/test_unit512
+	$(Q)echo "  UNIT       ML-KEM-512:   $^"
+unit_768:  $(MLKEM768_DIR)/bin/test_unit768
+	$(Q)echo "  UNIT       ML-KEM-768:   $^"
+unit_1024: $(MLKEM1024_DIR)/bin/test_unit1024
+	$(Q)echo "  UNIT       ML-KEM-1024:  $^"
+unit: unit_512 unit_768 unit_1024
+
 kat_512: $(MLKEM512_DIR)/bin/gen_KAT512
 	$(Q)echo "  KAT        ML-KEM-512:   $^"
 kat_768: $(MLKEM768_DIR)/bin/gen_KAT768

mlkem/mlkem_native.S

@@ -331,6 +331,7 @@
 #undef MLK_INLINE
 #undef MLK_MUST_CHECK_RETURN_VALUE
 #undef MLK_RESTRICT
+#undef MLK_STATIC_TESTABLE
 #undef MLK_SYS_AARCH64
 #undef MLK_SYS_AARCH64_EB
 #undef MLK_SYS_APPLE

mlkem/mlkem_native.c

@@ -318,6 +318,7 @@
 #undef MLK_INLINE
 #undef MLK_MUST_CHECK_RETURN_VALUE
 #undef MLK_RESTRICT
+#undef MLK_STATIC_TESTABLE
 #undef MLK_SYS_AARCH64
 #undef MLK_SYS_AARCH64_EB
 #undef MLK_SYS_APPLE

mlkem/src/compress.c

@@ -34,8 +34,8 @@
  *              unsigned canonical coefficients here.
  *              The reference implementation works with coefficients
  *              in the range (-MLKEM_Q+1,...,MLKEM_Q-1). */
-static void mlk_poly_compress_d4_c(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D4],
-                                   const mlk_poly *a)
+MLK_STATIC_TESTABLE void mlk_poly_compress_d4_c(
+    uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D4], const mlk_poly *a)
 {
   unsigned i;
   mlk_assert_bound(a, MLKEM_N, 0, MLKEM_Q);
@@ -83,8 +83,8 @@ void mlk_poly_compress_d4(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D4],
  *              unsigned canonical coefficients here.
  *              The reference implementation works with coefficients
  *              in the range (-MLKEM_Q+1,...,MLKEM_Q-1). */
-static void mlk_poly_compress_d10_c(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D10],
-                                    const mlk_poly *a)
+MLK_STATIC_TESTABLE void mlk_poly_compress_d10_c(
+    uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D10], const mlk_poly *a)
 {
   unsigned j;
   mlk_assert_bound(a, MLKEM_N, 0, MLKEM_Q);
@@ -132,7 +132,7 @@ void mlk_poly_compress_d10(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D10],
 
 /* Reference: `poly_decompress()` in the reference implementation @[REF],
  *            for ML-KEM-{512,768}. */
-static void mlk_poly_decompress_d4_c(
+MLK_STATIC_TESTABLE void mlk_poly_decompress_d4_c(
     mlk_poly *r, const uint8_t a[MLKEM_POLYCOMPRESSEDBYTES_D4])
 {
   unsigned i;
@@ -167,7 +167,7 @@ void mlk_poly_decompress_d4(mlk_poly *r,
 
 /* Reference: Embedded into `polyvec_decompress()` in the
  *            reference implementation, for ML-KEM-{512,768}. */
-static void mlk_poly_decompress_d10_c(
+MLK_STATIC_TESTABLE void mlk_poly_decompress_d10_c(
     mlk_poly *r, const uint8_t a[MLKEM_POLYCOMPRESSEDBYTES_D10])
 {
   unsigned j;
@@ -222,8 +222,8 @@ void mlk_poly_decompress_d10(mlk_poly *r,
  *              unsigned canonical coefficients here.
  *              The reference implementation works with coefficients
  *              in the range (-MLKEM_Q+1,...,MLKEM_Q-1). */
-static void mlk_poly_compress_d5_c(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D5],
-                                   const mlk_poly *a)
+MLK_STATIC_TESTABLE void mlk_poly_compress_d5_c(
+    uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D5], const mlk_poly *a)
 {
   unsigned i;
   mlk_assert_bound(a, MLKEM_N, 0, MLKEM_Q);
@@ -277,8 +277,8 @@ void mlk_poly_compress_d5(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D5],
  *              unsigned canonical coefficients here.
  *              The reference implementation works with coefficients
  *              in the range (-MLKEM_Q+1,...,MLKEM_Q-1). */
-static void mlk_poly_compress_d11_c(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D11],
-                                    const mlk_poly *a)
+MLK_STATIC_TESTABLE void mlk_poly_compress_d11_c(
+    uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D11], const mlk_poly *a)
 {
   unsigned j;
   mlk_assert_bound(a, MLKEM_N, 0, MLKEM_Q);
@@ -333,7 +333,7 @@ void mlk_poly_compress_d11(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D11],
 
 /* Reference: `poly_decompress()` in the reference implementation @[REF],
  *            for ML-KEM-1024. */
-static void mlk_poly_decompress_d5_c(
+MLK_STATIC_TESTABLE void mlk_poly_decompress_d5_c(
     mlk_poly *r, const uint8_t a[MLKEM_POLYCOMPRESSEDBYTES_D5])
 {
   unsigned i;
@@ -396,7 +396,7 @@ void mlk_poly_decompress_d5(mlk_poly *r,
 
 /* Reference: Embedded into `polyvec_decompress()` in the
  *            reference implementation, for ML-KEM-1024. */
-static void mlk_poly_decompress_d11_c(
+MLK_STATIC_TESTABLE void mlk_poly_decompress_d11_c(
     mlk_poly *r, const uint8_t a[MLKEM_POLYCOMPRESSEDBYTES_D11])
 {
   unsigned j;
@@ -455,7 +455,8 @@ void mlk_poly_decompress_d11(mlk_poly *r,
  *              unsigned canonical coefficients here.
  *              The reference implementation works with coefficients
  *              in the range (-MLKEM_Q+1,...,MLKEM_Q-1). */
-static void mlk_poly_tobytes_c(uint8_t r[MLKEM_POLYBYTES], const mlk_poly *a)
+MLK_STATIC_TESTABLE void mlk_poly_tobytes_c(uint8_t r[MLKEM_POLYBYTES],
+                                            const mlk_poly *a)
 __contract__(
   requires(memory_no_alias(r, MLKEM_POLYBYTES))
   requires(memory_no_alias(a, sizeof(mlk_poly)))
@@ -509,7 +510,8 @@ void mlk_poly_tobytes(uint8_t r[MLKEM_POLYBYTES], const mlk_poly *a)
 }
 
 /* Reference: `poly_frombytes()` in the reference implementation @[REF]. */
-static void mlk_poly_frombytes_c(mlk_poly *r, const uint8_t a[MLKEM_POLYBYTES])
+MLK_STATIC_TESTABLE void mlk_poly_frombytes_c(mlk_poly *r,
+                                              const uint8_t a[MLKEM_POLYBYTES])
 __contract__(
   requires(memory_no_alias(a, MLKEM_POLYBYTES))
   requires(memory_no_alias(r, sizeof(mlk_poly)))

mlkem/src/poly.c

@@ -114,7 +114,7 @@ __contract__(
 }
 
 /* Reference: `poly_tomont()` in the reference implementation @[REF]. */
-static void mlk_poly_tomont_c(mlk_poly *r)
+MLK_STATIC_TESTABLE void mlk_poly_tomont_c(mlk_poly *r)
 __contract__(
   requires(memory_no_alias(r, sizeof(mlk_poly)))
   assigns(memory_slice(r, sizeof(mlk_poly)))
@@ -188,7 +188,7 @@ __contract__(
  *              here to go from signed to unsigned representatives.
  *              This conditional addition is then dropped from all
  *              polynomial compression functions instead (see `compress.c`). */
-static void mlk_poly_reduce_c(mlk_poly *r)
+MLK_STATIC_TESTABLE void mlk_poly_reduce_c(mlk_poly *r)
 __contract__(
   requires(memory_no_alias(r, sizeof(mlk_poly)))
   assigns(memory_slice(r, sizeof(mlk_poly)))
@@ -267,7 +267,8 @@ void mlk_poly_sub(mlk_poly *r, const mlk_poly *b)
  *            - The reference implementation does not use a
  *              multiplication cache ('mulcache'). This idea originates
  *              from @[NeonNTT] and is used at the C level here. */
-static void mlk_poly_mulcache_compute_c(mlk_poly_mulcache *x, const mlk_poly *a)
+MLK_STATIC_TESTABLE void mlk_poly_mulcache_compute_c(mlk_poly_mulcache *x,
+                                                     const mlk_poly *a)
 __contract__(
   requires(memory_no_alias(x, sizeof(mlk_poly_mulcache)))
   requires(memory_no_alias(a, sizeof(mlk_poly)))
@@ -416,7 +417,7 @@ __contract__(
 /* Reference: `ntt()` in the reference implementation @[REF].
  * - Iterate over `layer` instead of `len` in the outer loop
  *   to simplify computation of zeta index. */
-static void mlk_poly_ntt_c(mlk_poly *p)
+MLK_STATIC_TESTABLE void mlk_poly_ntt_c(mlk_poly *p)
 __contract__(
   requires(memory_no_alias(p, sizeof(mlk_poly)))
   requires(array_abs_bound(p->coeffs, 0, MLKEM_N, MLKEM_Q))
@@ -506,7 +507,7 @@ __contract__(
  *              while the reference implementation normalizes at
  *              the end. This allows us to drop a call to `poly_reduce()`
  *              from the base multiplication. */
-static void mlk_poly_invntt_tomont_c(mlk_poly *p)
+MLK_STATIC_TESTABLE void mlk_poly_invntt_tomont_c(mlk_poly *p)
 __contract__(
   requires(memory_no_alias(p, sizeof(mlk_poly)))
   assigns(memory_slice(p, sizeof(mlk_poly)))

mlkem/src/poly_k.c

@@ -148,7 +148,7 @@ void mlk_polyvec_invntt_tomont(mlk_polyvec r)
  *              at the end. The reference implementation uses 2 * MLKEM_K
  *              more modular reductions since it reduces after every modular
  *              multiplication. */
-static void mlk_polyvec_basemul_acc_montgomery_cached_c(
+MLK_STATIC_TESTABLE void mlk_polyvec_basemul_acc_montgomery_cached_c(
     mlk_poly *r, const mlk_polyvec a, const mlk_polyvec b,
     const mlk_polyvec_mulcache b_cache)
 __contract__(

mlkem/src/sampling.c

@@ -29,8 +29,10 @@
  *              in that it adds the offset and always expects the base of the
  *              target buffer. This avoids shifting the buffer base in the
  *              caller, which appears tricky to reason about. */
-static unsigned mlk_rej_uniform_c(int16_t *r, unsigned target, unsigned offset,
-                                  const uint8_t *buf, unsigned buflen)
+MLK_STATIC_TESTABLE unsigned mlk_rej_uniform_c(int16_t *r, unsigned target,
+                                               unsigned offset,
+                                               const uint8_t *buf,
+                                               unsigned buflen)
 __contract__(
   requires(offset <= target && target <= 4096 && buflen <= 4096 && buflen % 3 == 0)
   requires(memory_no_alias(r, sizeof(int16_t) * target))

mlkem/src/sys.h

@@ -119,6 +119,10 @@
 #endif /* inline */
 #endif /* !MLK_INLINE */
 
+#ifndef MLK_STATIC_TESTABLE
+#define MLK_STATIC_TESTABLE static
+#endif
+
 /*
  * C90 does not have the restrict compiler directive yet.
  * We don't use it in C90 builds.

scripts/tests

@@ -209,6 +209,7 @@ class TEST_TYPES(Enum):
     STACK = 15
     SIZE = 16
     BASIC_DETERMINISTIC = 17
+    UNIT = 18
 
     def is_benchmark(self):
         return self in [TEST_TYPES.BENCH, TEST_TYPES.BENCH_COMPONENTS]
@@ -278,6 +279,8 @@ class TEST_TYPES(Enum):
             return "Example (multilevel build, native)"
         if self == TEST_TYPES.SIZE:
             return "Measurement Code Size"
+        if self == TEST_TYPES.UNIT:
+            return "Unit Test"
 
     def make_dir(self):
         if self == TEST_TYPES.BRING_YOUR_OWN_FIPS202:
@@ -337,6 +340,8 @@ class TEST_TYPES(Enum):
             return ""
         if self == TEST_TYPES.SIZE:
             return "size"
+        if self == TEST_TYPES.UNIT:
+            return "unit"
 
     def make_run_target(self, scheme):
         t = self.make_target()
@@ -618,6 +623,19 @@ class Tests:
 
         self.check_fail()
 
+    def unit(self):
+        def _unit(opt):
+            self._compile_schemes(TEST_TYPES.UNIT, opt)
+            if self.args.run:
+                self._run_schemes(TEST_TYPES.UNIT, opt)
+
+        if self.do_no_opt():
+            _unit(False)
+        if self.do_opt():
+            _unit(True)
+
+        self.check_fail()
+
     def acvp(self):
         def _acvp(opt):
             self._compile_schemes(TEST_TYPES.ACVP, opt)
@@ -751,6 +769,7 @@ class Tests:
         acvp = self.args.acvp
         examples = self.args.examples
         stack = self.args.stack
+        unit = self.args.unit
 
         def _all(opt):
             if func is True:
@@ -761,6 +780,8 @@ class Tests:
                 self._compile_schemes(TEST_TYPES.ACVP, opt)
             if stack is True:
                 self._compile_schemes(TEST_TYPES.STACK, opt)
+            if unit is True:
+                self._compile_schemes(TEST_TYPES.UNIT, opt)
 
             if self.args.run is False:
                 return
@@ -773,6 +794,8 @@ class Tests:
                 self._run_scheme(TEST_TYPES.ACVP, opt, None)
             if stack is True:
                 self._run_schemes(TEST_TYPES.STACK, opt, suppress_output=False)
+            if unit is True:
+                self._run_schemes(TEST_TYPES.UNIT, opt)
 
         if self.do_no_opt():
             _all(False)
@@ -1066,6 +1089,14 @@ def cli():
         "--no-acvp", action="store_false", dest="acvp", help="Do not run acvp test"
     )
 
+    unit_group = all_parser.add_mutually_exclusive_group()
+    unit_group.add_argument(
+        "--unit", action="store_true", dest="unit", help="Run unit test", default=True
+    )
+    unit_group.add_argument(
+        "--no-unit", action="store_false", dest="unit", help="Do not run unit test"
+    )
+
     examples_group = all_parser.add_mutually_exclusive_group()
     examples_group.add_argument(
         "--examples",
@@ -1286,6 +1317,13 @@ def cli():
         "kat", help="Run the kat tests for all parameter sets", parents=[common_parser]
     )
 
+    # unit arguments
+    unit_parser = cmd_subparsers.add_parser(
+        "unit",
+        help="Run the unit tests for all parameter sets",
+        parents=[common_parser],
+    )
+
     # stack arguments
     stack_parser = cmd_subparsers.add_parser(
         "stack",
@@ -1330,6 +1368,8 @@ def cli():
         Tests(args).func()
     elif args.cmd == "kat":
         Tests(args).kat()
+    elif args.cmd == "unit":
+        Tests(args).unit()
     elif args.cmd == "stack":
         Tests(args).stack()
     elif args.cmd == "size":