Port and exercise MLD_CHECK_APIS

- This commit port and exercise the `MLD_CHECK_APIS` to mldsa-native,
  referencing from mlkem-native

- add the API consistency between internal sign.h and external
  mldsa_native.h for forllowing:
  - CRYPTO_SECRETKEYBYTES != \
    MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)
  - CRYPTO_PUBLICKEYBYTES != \
    MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)
  - CRYPTO_BYTES != \
    MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)
- This commit add consistency checking for API and conduct sanity checks
  on the bakcend in common.h

Signed-off-by: willieyz <[email protected]>

Author: willieyz

.github/workflows/ci.yml

@@ -471,6 +471,37 @@ jobs:
           kat: true
           acvp: true
           nix-shell: ${{ matrix.compiler.shell }}
+  # ensure that sign.h and mldsa_native.h; api.h and native backends are compatible
+  check-apis:
+    strategy:
+      fail-fast: false
+      matrix:
+        external:
+         - ${{ github.repository_owner != 'pq-code-package' }}
+        target:
+         - runner: pqcp-arm64
+           name: 'aarch64'
+         - runner: ubuntu-latest
+           name: 'x86_64'
+        exclude:
+          - {external: true,
+             target: {
+               runner: pqcp-arm64,
+               name: 'aarch64'
+             }}
+    name: Check API consistency
+    runs-on: ${{ matrix.target.runner }}
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - name: make quickcheck
+        run: |
+          OPT=0 CFLAGS="-Imldsa -DMLD_CHECK_APIS -Wno-redundant-decls" make quickcheck
+          make clean >/dev/null
+          OPT=1 CFLAGS="-Imldsa -DMLD_CHECK_APIS -Wno-redundant-decls" make quickcheck
+      - uses: ./.github/actions/setup-apt
+      - name: tests func
+        run: |
+          ./scripts/tests func --cflags="-Imldsa -DMLD_CHECK_APIS -Wno-redundant-decls"
   ec2_functests:
     strategy:
       fail-fast: false

mldsa/mldsa_native.c

@@ -187,6 +187,8 @@
 #undef MLD_COMMON_H
 #undef MLD_CONCAT
 #undef MLD_CONCAT_
+#undef MLD_CONFIG_API_NAMESPACE_PREFIX
+#undef MLD_CONFIG_API_PARAMETER_SET
 #undef MLD_EMPTY_CU
 #undef MLD_EXTERNAL_API
 #undef MLD_FIPS202X4_HEADER_FILE
@@ -295,6 +297,7 @@
 #undef mld_power2round
 #undef mld_use_hint
 /* mldsa/src/sign.h */
+#undef MLD_CONFIG_API_NO_SUPERCOP
 #undef MLD_PREHASH_SHA2_224
 #undef MLD_PREHASH_SHA2_256
 #undef MLD_PREHASH_SHA2_384

mldsa/src/common.h

@@ -72,7 +72,15 @@
 
 #if defined(MLD_CONFIG_USE_NATIVE_BACKEND_ARITH)
 #include MLD_CONFIG_ARITH_BACKEND_FILE
+/* Include to enforce consistency of API and implementation,
+ * and conduct sanity checks on the backend.
+ *
+ * Keep this _after_ the inclusion of the backend; otherwise,
+ * the sanity checks won't have an effect. */
+#if defined(MLD_CHECK_APIS) && !defined(__ASSEMBLER__)
+#include "native/api.h"
 #endif
+#endif /* MLD_CONFIG_USE_NATIVE_BACKEND_ARITH */
 
 /* On Apple platforms, we need to emit leading underscore
  * in front of assembly symbols. We thus introducee a separate
@@ -102,7 +110,15 @@
 
 #if defined(MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202)
 #include MLD_CONFIG_FIPS202_BACKEND_FILE
+/* Include to enforce consistency of API and implementation,
+ * and conduct sanity checks on the backend.
+ *
+ * Keep this _after_ the inclusion of the backend; otherwise,
+ * the sanity checks won't have an effect. */
+#if defined(MLD_CHECK_APIS) && !defined(__ASSEMBLER__)
+#include "fips202/native/api.h"
 #endif
+#endif /* MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 */
 
 #if !defined(MLD_CONFIG_FIPS202_CUSTOM_HEADER)
 #define MLD_FIPS202_HEADER_FILE "fips202/fips202.h"
@@ -129,6 +145,20 @@
 #endif
 #endif /* !__ASSEMBLER__ */
 
-
+/* Just in case we want to include mldsa_native.h, set the configuration
+ * for that header in accordance with the configuration used here. */
+
+/* Double-check that this is not conflicting with pre-existing definitions. */
+#if defined(MLD_CONFIG_API_PARAMETER_SET) ||    \
+    defined(MLD_CONFIG_API_NAMESPACE_PREFIX) || \
+    defined(MLD_CONFIG_API_NO_SUPERCOP) ||      \
+    defined(MLD_CONFIG_API_CONSTANTS_ONLY)
+#error Pre-existing MLD_CONFIG_API_XXX configuration is neither useful nor allowed during an mldsa-native build
+#endif /* MLD_CONFIG_API_PARAMETER_SET || MLD_CONFIG_API_NAMESPACE_PREFIX || \
+          MLD_CONFIG_API_NO_SUPERCOP || MLD_CONFIG_API_CONSTANTS_ONLY */
+
+#define MLD_CONFIG_API_PARAMETER_SET MLD_CONFIG_PARAMETER_SET
+#define MLD_CONFIG_API_NAMESPACE_PREFIX \
+  MLD_ADD_PARAM_SET(MLD_CONFIG_NAMESPACE_PREFIX)
 
 #endif /* !MLD_COMMON_H */

mldsa/src/sign.h

@@ -23,6 +23,27 @@
 #include "polyvec.h"
 #include "sys.h"
 
+#if defined(MLD_CHECK_APIS)
+/* Include to ensure consistency between internal sign.h
+ * and external mldsa_native.h. */
+#define MLD_CONFIG_API_NO_SUPERCOP
+#include "mldsa_native.h"
+#undef MLD_CONFIG_API_NO_SUPERCOP
+
+#if CRYPTO_SECRETKEYBYTES != MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)
+#error Mismatch for SECRETKEYBYTES between sign.h and mldsa_native.h
+#endif
+
+#if CRYPTO_PUBLICKEYBYTES != MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)
+#error Mismatch for PUBLICKEYBYTES between sign.h and mldsa_native.h
+#endif
+
+#if CRYPTO_BYTES != MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)
+#error Mismatch for CRYPTO_BYTES between sign.h and mldsa_native.h
+#endif
+
+#endif /* MLD_CHECK_APIS */
+
 #define crypto_sign_keypair_internal MLD_NAMESPACE_KL(keypair_internal)
 #define crypto_sign_keypair MLD_NAMESPACE_KL(keypair)
 #define crypto_sign_signature_internal MLD_NAMESPACE_KL(signature_internal)