Make custom FIPS-202 headers configurable

While consumers of mlkem-native can bring their own FIPS-202 implementation
(as demonstrated by libOQS and the example/bring_your_own_fips202) it is
slightly rigid in that the FIPS-202 headers have to be reachable through a
path "fips202/fips202.h" and "fips202/fips202x4.h". In the case of libOQS,
this is the reason why a patch is needed.

This commit makes the installation of a custom FIPS-202 implementation more
convenient, by adding the configuration options
- MLK_FIPS202_CUSTOM_HEADER
- MLK_FIPS202X4_CUSTOM_HEADER
If set, those must be the names of files replacing fips202/fips202.h and
fips202/fips202x4.h If they are not set (default), mlkem-native's own
FIPS-202 implementation will be used.

This is demonstrated in the case of example/bring_your_own_fips202, where
we can now freely rename the directory holding the tiny_sha3 implementation.

Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>

examples/bring_your_own_fips202/Makefile

@@ -28,9 +28,7 @@ INC=-Imlkem_native/
 #
 # At present, this must be located in a directory named "fips202".
 # This limitation will be lifted in the future.
-FIPS202_SOURCE=fips202/tiny_sha3/sha3.c
-
-INC+=-I./
+FIPS202_SOURCE=custom_fips202/tiny_sha3/sha3.c
 
 # Part C:
 #
@@ -71,6 +69,8 @@ CFLAGS := \
 	-MMD \
 	-O3 \
 	$(CFLAGS)
+CFLAGS += -DMLK_FIPS202_CUSTOM_HEADER="\"../custom_fips202/fips202.h\""
+CFLAGS += -DMLK_FIPS202X4_CUSTOM_HEADER="\"../custom_fips202/fips202x4.h\""
 
 BINARY_NAME_FULL=$(BUILD_DIR)/$(BIN)
 

examples/monolithic_build/mlkem_native_monobuild.c

@@ -57,7 +57,9 @@
 #undef MLK_ASM_NAMESPACE
 #undef MLK_COMMON_H
 #undef MLK_EMPTY_CU
+#undef MLK_FIPS202X4_HEADER_FILE
 #undef MLK_FIPS202_BACKEND_NAME
+#undef MLK_FIPS202_HEADER_FILE
 #undef MLK_INTERNAL_API
 #undef MLK_MAKE_NAMESPACE
 #undef MLK_MAKE_NAMESPACE_

mlkem/common.h

@@ -78,4 +78,16 @@
  * The following is to avoid compilers complaining about this. */
 #define MLK_EMPTY_CU(s) extern int MLK_NAMESPACE_K(empty_cu_##s);
 
+#if !defined(MLK_FIPS202_CUSTOM_HEADER)
+#define MLK_FIPS202_HEADER_FILE "fips202/fips202.h"
+#else
+#define MLK_FIPS202_HEADER_FILE MLK_FIPS202_CUSTOM_HEADER
+#endif
+
+#if !defined(MLK_FIPS202X4_CUSTOM_HEADER)
+#define MLK_FIPS202X4_HEADER_FILE "fips202/fips202x4.h"
+#else
+#define MLK_FIPS202X4_HEADER_FILE MLK_FIPS202X4_CUSTOM_HEADER
+#endif
+
 #endif /* MLK_COMMON_H */

mlkem/config.h

@@ -203,6 +203,38 @@
 #define MLK_FIPS202_BACKEND_FILE "fips202/native/meta.h"
 #endif
 
+/******************************************************************************
+ * Name:        MLK_FIPS202_CUSTOM_HEADER
+ *
+ * Description: Custom header to use for FIPS-202
+ *
+ *              This should only be set if you intend to use a custom
+ *              FIPS-202 implementation, different from the one shipped
+ *              with mlkem-native.
+ *
+ *              If set, it must be the name of a file serving as the
+ *              replacement for mlkem/fips202/fips202.h, and exposing
+ *              the same API (see FIPS202.md).
+ *
+ *****************************************************************************/
+/* #define MLK_FIPS202_CUSTOM_HEADER "SOME_FILE.h" */
+
+/******************************************************************************
+ * Name:        MLK_FIPS202X4_CUSTOM_HEADER
+ *
+ * Description: Custom header to use for FIPS-202-X4
+ *
+ *              This should only be set if you intend to use a custom
+ *              FIPS-202 implementation, different from the one shipped
+ *              with mlkem-native.
+ *
+ *              If set, it must be the name of a file serving as the
+ *              replacement for mlkem/fips202/fips202x4.h, and exposing
+ *              the same API (see FIPS202.md).
+ *
+ *****************************************************************************/
+/* #define MLK_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */
+
 /*************************  Config internals  ********************************/
 
 /* Default namespace

mlkem/indcpa.c

@@ -9,8 +9,6 @@
 #include "arith_backend.h"
 #include "cbmc.h"
 #include "debug.h"
-#include "fips202/fips202.h"
-#include "fips202/fips202x4.h"
 #include "indcpa.h"
 #include "poly.h"
 #include "poly_k.h"

mlkem/poly.c

@@ -10,7 +10,6 @@
 #include "arith_backend.h"
 #include "cbmc.h"
 #include "debug.h"
-#include "fips202/fips202x4.h"
 #include "poly.h"
 #include "sampling.h"
 #include "symmetric.h"

mlkem/sampling.c

@@ -7,8 +7,6 @@
 
 #include "arith_backend.h"
 #include "debug.h"
-#include "fips202/fips202.h"
-#include "fips202/fips202x4.h"
 #include "sampling.h"
 #include "symmetric.h"
 

mlkem/symmetric.h

@@ -9,8 +9,8 @@
 #include <stdint.h>
 #include "cbmc.h"
 #include "common.h"
-#include "fips202/fips202.h"
-#include "fips202/fips202x4.h"
+#include MLK_FIPS202_HEADER_FILE
+#include MLK_FIPS202X4_HEADER_FILE
 
 /* Macros denoting FIPS-203 specific Hash functions */