From d2a1f2bc83f3c52c1e1f3f972805137e0921864f Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 6 Feb 2025 16:54:20 +0000 Subject: [PATCH] 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 --- examples/bring_your_own_fips202/Makefile | 6 ++-- .../{fips202 => custom_fips202}/README.md | 0 .../{fips202 => custom_fips202}/fips202.h | 0 .../{fips202 => custom_fips202}/fips202x4.h | 0 .../tiny_sha3/LICENSE | 0 .../tiny_sha3/README.md | 0 .../tiny_sha3/sha3.c | 0 .../tiny_sha3/sha3.h | 0 mlkem/common.h | 12 +++++++ mlkem/config.h | 32 +++++++++++++++++++ mlkem/indcpa.c | 2 -- mlkem/poly.c | 1 - mlkem/sampling.c | 2 -- mlkem/symmetric.h | 4 +-- 14 files changed, 49 insertions(+), 10 deletions(-) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/README.md (100%) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/fips202.h (100%) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/fips202x4.h (100%) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/tiny_sha3/LICENSE (100%) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/tiny_sha3/README.md (100%) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/tiny_sha3/sha3.c (100%) rename examples/bring_your_own_fips202/{fips202 => custom_fips202}/tiny_sha3/sha3.h (100%) diff --git a/examples/bring_your_own_fips202/Makefile b/examples/bring_your_own_fips202/Makefile index 2a197de7a..c5b1d680e 100644 --- a/examples/bring_your_own_fips202/Makefile +++ b/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) diff --git a/examples/bring_your_own_fips202/fips202/README.md b/examples/bring_your_own_fips202/custom_fips202/README.md similarity index 100% rename from examples/bring_your_own_fips202/fips202/README.md rename to examples/bring_your_own_fips202/custom_fips202/README.md diff --git a/examples/bring_your_own_fips202/fips202/fips202.h b/examples/bring_your_own_fips202/custom_fips202/fips202.h similarity index 100% rename from examples/bring_your_own_fips202/fips202/fips202.h rename to examples/bring_your_own_fips202/custom_fips202/fips202.h diff --git a/examples/bring_your_own_fips202/fips202/fips202x4.h b/examples/bring_your_own_fips202/custom_fips202/fips202x4.h similarity index 100% rename from examples/bring_your_own_fips202/fips202/fips202x4.h rename to examples/bring_your_own_fips202/custom_fips202/fips202x4.h diff --git a/examples/bring_your_own_fips202/fips202/tiny_sha3/LICENSE b/examples/bring_your_own_fips202/custom_fips202/tiny_sha3/LICENSE similarity index 100% rename from examples/bring_your_own_fips202/fips202/tiny_sha3/LICENSE rename to examples/bring_your_own_fips202/custom_fips202/tiny_sha3/LICENSE diff --git a/examples/bring_your_own_fips202/fips202/tiny_sha3/README.md b/examples/bring_your_own_fips202/custom_fips202/tiny_sha3/README.md similarity index 100% rename from examples/bring_your_own_fips202/fips202/tiny_sha3/README.md rename to examples/bring_your_own_fips202/custom_fips202/tiny_sha3/README.md diff --git a/examples/bring_your_own_fips202/fips202/tiny_sha3/sha3.c b/examples/bring_your_own_fips202/custom_fips202/tiny_sha3/sha3.c similarity index 100% rename from examples/bring_your_own_fips202/fips202/tiny_sha3/sha3.c rename to examples/bring_your_own_fips202/custom_fips202/tiny_sha3/sha3.c diff --git a/examples/bring_your_own_fips202/fips202/tiny_sha3/sha3.h b/examples/bring_your_own_fips202/custom_fips202/tiny_sha3/sha3.h similarity index 100% rename from examples/bring_your_own_fips202/fips202/tiny_sha3/sha3.h rename to examples/bring_your_own_fips202/custom_fips202/tiny_sha3/sha3.h diff --git a/mlkem/common.h b/mlkem/common.h index a92e6c42e..cc8ad13fb 100644 --- a/mlkem/common.h +++ b/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 */ diff --git a/mlkem/config.h b/mlkem/config.h index 3e92722a0..26c91d0d0 100644 --- a/mlkem/config.h +++ b/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 diff --git a/mlkem/indcpa.c b/mlkem/indcpa.c index ee2431787..a1ab08753 100644 --- a/mlkem/indcpa.c +++ b/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" diff --git a/mlkem/poly.c b/mlkem/poly.c index 202433ec1..9ee0690e6 100644 --- a/mlkem/poly.c +++ b/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" diff --git a/mlkem/sampling.c b/mlkem/sampling.c index dcc1cb7f5..e4208b634 100644 --- a/mlkem/sampling.c +++ b/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" diff --git a/mlkem/symmetric.h b/mlkem/symmetric.h index faaa9bc57..0d248a46b 100644 --- a/mlkem/symmetric.h +++ b/mlkem/symmetric.h @@ -9,8 +9,8 @@ #include #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 */