Remove FIPS202_NAMESPACE_PREFIX configuration option

Previously, the namespace for FIPS202 symbols could be separately defined from the namespace for MLKEM-specific symbols. This was primarily to allow for a multi-level build where FIPS202 code is shared. Now that multi-level builds are possible even with sharing of all level-independent code (not merely FIPS202), there is no longer a use of a separate FIPS202 namespace. Note also that when a custom FIPS202 implementation is used, the user is in full control of namespacing since they can are expected to replace the FIPS202 headers. In light of the above, this commit merges the FIPS202_NAMESPACE_PREFIX configuration option into MLKEM_NAMESPACE_PREFIX. The latter now controls prefixing of _all_ global symbols in an mlkem-native build. If users want to share common code in a multilevel build, this should be done by setting MLKEM_NAMESPACE_PREFIX_ADD_LEVEL, and dropping the level from the MLKEM_NAMESPACE_PREFIX; all this is already demonstrated in the example `example/multilevel_build`. It is therefore no longer necessary to demonstrate a shared-FIPS202 build in the `Makefile`, which was done so far. Instead, the default build can be simplified to three independent builds of libmlkem{512,768,1024}, each with their own FIPS202. Again, usage examples are now provided in `examples/*`, while the user should not need to inspect the test Makefiles. Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>
pq-code-package · Jan 20, 2025 · 119fc71 · 119fc71
1 parent 412ff2d
commit 119fc71
Show file tree

Hide file tree

Showing 31 changed files with 97 additions and 342 deletions.
diff --git a/Makefile b/Makefile
@@ -91,7 +91,7 @@ acvp_1024: $(MLKEM1024_DIR)/bin/acvp_mlkem1024
 	$(Q)echo "  ACVP       ML-MEM-1024:  $^"
 acvp: acvp_512 acvp_768 acvp_1024
 
-lib: $(BUILD_DIR)/libmlkem.a
+lib: $(BUILD_DIR)/libmlkem.a $(BUILD_DIR)/libmlkem512.a $(BUILD_DIR)/libmlkem768.a $(BUILD_DIR)/libmlkem1024.a
 
 # Enforce setting CYCLES make variable when
 # building benchmarking binaries

diff --git a/examples/bring_your_own_fips202/fips202/fips202.h b/examples/bring_your_own_fips202/fips202/fips202.h
@@ -29,7 +29,7 @@ typedef sha3_ctx_t shake128ctx;
  * This function does not support being called multiple times
  * with the same state.
  */
-#define shake128_absorb_once FIPS202_NAMESPACE(shake128_absorb_once)
+#define shake128_absorb_once MLKEM_NAMESPACE(shake128_absorb_once)
 /*************************************************
  * Name:        shake128_absorb_once
  *
@@ -56,7 +56,7 @@ static INLINE void shake128_absorb_once(shake128ctx *state,
  *
  * Supports being called multiple times
  */
-#define shake128_squeezeblocks FIPS202_NAMESPACE(shake128_squeezeblocks)
+#define shake128_squeezeblocks MLKEM_NAMESPACE(shake128_squeezeblocks)
 /*************************************************
  * Name:        shake128_squeezeblocks
  *
@@ -76,12 +76,12 @@ static INLINE void shake128_squeezeblocks(uint8_t *output, size_t nblocks,
 }
 
 /* Free the state */
-#define shake128_release FIPS202_NAMESPACE(shake128_release)
+#define shake128_release MLKEM_NAMESPACE(shake128_release)
 static INLINE void shake128_release(shake128ctx *state) { ((void)state); }
 
 /* One-stop SHAKE256 call. Aliasing between input and
  * output is not permitted */
-#define shake256 FIPS202_NAMESPACE(shake256)
+#define shake256 MLKEM_NAMESPACE(shake256)
 /*************************************************
  * Name:        shake256
  *
@@ -105,7 +105,7 @@ static INLINE void shake256(uint8_t *output, size_t outlen,
 /* One-stop SHA3_256 call. Aliasing between input and
  * output is not permitted */
 #define SHA3_256_HASHBYTES 32
-#define sha3_256 FIPS202_NAMESPACE(sha3_256)
+#define sha3_256 MLKEM_NAMESPACE(sha3_256)
 /*************************************************
  * Name:        sha3_256
  *
@@ -123,7 +123,7 @@ static INLINE void sha3_256(uint8_t *output, const uint8_t *input, size_t inlen)
 /* One-stop SHA3_512 call. Aliasing between input and
  * output is not permitted */
 #define SHA3_512_HASHBYTES 64
-#define sha3_512 FIPS202_NAMESPACE(sha3_512)
+#define sha3_512 MLKEM_NAMESPACE(sha3_512)
 /*************************************************
  * Name:        sha3_512
  *

diff --git a/examples/bring_your_own_fips202/fips202/fips202x4.h b/examples/bring_your_own_fips202/fips202/fips202x4.h
@@ -21,7 +21,7 @@
 
 typedef shake128ctx shake128x4ctx[4];
 
-#define shake128x4_absorb_once FIPS202_NAMESPACE(shake128x4_absorb_once)
+#define shake128x4_absorb_once MLKEM_NAMESPACE(shake128x4_absorb_once)
 static INLINE void shake128x4_absorb_once(shake128x4ctx *state,
                                           const uint8_t *in0,
                                           const uint8_t *in1,
@@ -42,7 +42,7 @@ __contract__(
   shake128_absorb_once(&(*state)[3], in3, inlen);
 }
 
-#define shake128x4_squeezeblocks FIPS202_NAMESPACE(shake128x4_squeezeblocks)
+#define shake128x4_squeezeblocks MLKEM_NAMESPACE(shake128x4_squeezeblocks)
 static INLINE void shake128x4_squeezeblocks(uint8_t *out0, uint8_t *out1,
                                             uint8_t *out2, uint8_t *out3,
                                             size_t nblocks,
@@ -66,7 +66,7 @@ __contract__(
   shake128_squeezeblocks(out3, nblocks, &(*state)[3]);
 }
 
-#define shake128x4_release FIPS202_NAMESPACE(shake128x4_release)
+#define shake128x4_release MLKEM_NAMESPACE(shake128x4_release)
 static INLINE void shake128x4_release(shake128x4ctx *state)
 {
   shake128_release(&(*state)[0]);
@@ -75,7 +75,7 @@ static INLINE void shake128x4_release(shake128x4ctx *state)
   shake128_release(&(*state)[3]);
 }
 
-#define shake256x4 FIPS202_NAMESPACE(shake256x4)
+#define shake256x4 MLKEM_NAMESPACE(shake256x4)
 static INLINE void shake256x4(uint8_t *out0, uint8_t *out1, uint8_t *out2,
                               uint8_t *out3, size_t outlen, uint8_t *in0,
                               uint8_t *in1, uint8_t *in2, uint8_t *in3,

diff --git a/examples/custom_backend/mlkem_native/custom_config.h b/examples/custom_backend/mlkem_native/custom_config.h
@@ -41,14 +41,6 @@
  *****************************************************************************/
 #define MLKEM_NAMESPACE_PREFIX CUSTOM_TINY_SHA3
 
-/******************************************************************************
- * Name:        FIPS202_NAMESPACE_PREFIX
- *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/fips202/.
- *****************************************************************************/
-#define FIPS202_NAMESPACE_PREFIX CUSTOM_TINY_SHA3
-
 /******************************************************************************
  * Name:        MLKEM_USE_NATIVE
  *

diff --git a/examples/monolithic_build/config_512.h b/examples/monolithic_build/config_512.h
@@ -48,17 +48,6 @@
  *****************************************************************************/
 #define MLKEM_NAMESPACE_PREFIX mlkem512
 
-/******************************************************************************
- * Name:        FIPS202_NAMESPACE_PREFIX
- *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/fips202/.
- *
- *              This can also be set using CFLAGS.
- *
- *****************************************************************************/
-#define FIPS202_NAMESPACE_PREFIX fips202
-
 /******************************************************************************
  * Name:        MLKEM_USE_NATIVE
  *

diff --git a/examples/monolithic_build/mlkem_native_monobuild.c b/examples/monolithic_build/mlkem_native_monobuild.c
@@ -32,16 +32,6 @@
  * Undo all #define directives from *.c or *.h files
  */
 
-/* mlkem/common.h */
-#if defined(FIPS202_ASM_NAMESPACE)
-#undef FIPS202_ASM_NAMESPACE
-#endif
-
-/* mlkem/common.h */
-#if defined(FIPS202_NAMESPACE)
-#undef FIPS202_NAMESPACE
-#endif
-
 /* mlkem/common.h */
 #if defined(MLKEM_ASM_NAMESPACE)
 #undef MLKEM_ASM_NAMESPACE
@@ -112,16 +102,6 @@
 #undef PREFIX_UNDERSCORE_
 #endif
 
-/* mlkem/config.h */
-#if defined(FIPS202_DEFAULT_NAMESPACE_PREFIX)
-#undef FIPS202_DEFAULT_NAMESPACE_PREFIX
-#endif
-
-/* mlkem/config.h */
-#if defined(FIPS202_NAMESPACE_PREFIX)
-#undef FIPS202_NAMESPACE_PREFIX
-#endif
-
 /* mlkem/config.h */
 #if defined(MLKEM_DEFAULT_NAMESPACE_PREFIX)
 #undef MLKEM_DEFAULT_NAMESPACE_PREFIX

diff --git a/examples/monolithic_build_multilevel/config_1024.h b/examples/monolithic_build_multilevel/config_1024.h
@@ -49,17 +49,6 @@
 #define MLKEM_NAMESPACE_PREFIX mlkem
 #define MLKEM_NAMESPACE_PREFIX_ADD_LEVEL
 
-/******************************************************************************
- * Name:        FIPS202_NAMESPACE_PREFIX
- *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/fips202/.
- *
- *              This can also be set using CFLAGS.
- *
- *****************************************************************************/
-#define FIPS202_NAMESPACE_PREFIX fips202
-
 /******************************************************************************
  * Name:        MLKEM_USE_NATIVE
  *

diff --git a/examples/monolithic_build_multilevel/config_512.h b/examples/monolithic_build_multilevel/config_512.h
@@ -49,17 +49,6 @@
 #define MLKEM_NAMESPACE_PREFIX mlkem
 #define MLKEM_NAMESPACE_PREFIX_ADD_LEVEL
 
-/******************************************************************************
- * Name:        FIPS202_NAMESPACE_PREFIX
- *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/fips202/.
- *
- *              This can also be set using CFLAGS.
- *
- *****************************************************************************/
-#define FIPS202_NAMESPACE_PREFIX fips202
-
 /******************************************************************************
  * Name:        MLKEM_USE_NATIVE
  *

diff --git a/examples/monolithic_build_multilevel/config_768.h b/examples/monolithic_build_multilevel/config_768.h
@@ -49,17 +49,6 @@
 #define MLKEM_NAMESPACE_PREFIX mlkem
 #define MLKEM_NAMESPACE_PREFIX_ADD_LEVEL
 
-/******************************************************************************
- * Name:        FIPS202_NAMESPACE_PREFIX
- *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/fips202/.
- *
- *              This can also be set using CFLAGS.
- *
- *****************************************************************************/
-#define FIPS202_NAMESPACE_PREFIX fips202
-
 /******************************************************************************
  * Name:        MLKEM_USE_NATIVE
  *

diff --git a/mlkem/common.h b/mlkem/common.h
@@ -43,9 +43,6 @@
 #define MLKEM_NATIVE_MAKE_NAMESPACE_(x1, x2) x1##_##x2
 #define MLKEM_NATIVE_MAKE_NAMESPACE(x1, x2) MLKEM_NATIVE_MAKE_NAMESPACE_(x1, x2)
 
-#define FIPS202_NAMESPACE(s) \
-  MLKEM_NATIVE_MAKE_NAMESPACE(FIPS202_NAMESPACE_PREFIX, s)
-
 #define MLKEM_NAMESPACE(s) \
   MLKEM_NATIVE_MAKE_NAMESPACE(MLKEM_NAMESPACE_PREFIX, s)
 
@@ -65,13 +62,11 @@
 #if !defined(__APPLE__)
 #define MLKEM_ASM_NAMESPACE(sym) MLKEM_NAMESPACE(sym)
 #define MLKEM_ASM_NAMESPACE_K(sym) MLKEM_NAMESPACE_K(sym)
-#define FIPS202_ASM_NAMESPACE(sym) FIPS202_NAMESPACE(sym)
 #else
 #define PREFIX_UNDERSCORE_(sym) _##sym
 #define PREFIX_UNDERSCORE(sym) PREFIX_UNDERSCORE_(sym)
 #define MLKEM_ASM_NAMESPACE(sym) PREFIX_UNDERSCORE(MLKEM_NAMESPACE(sym))
 #define MLKEM_ASM_NAMESPACE_K(sym) PREFIX_UNDERSCORE(MLKEM_NAMESPACE_K(sym))
-#define FIPS202_ASM_NAMESPACE(sym) PREFIX_UNDERSCORE(FIPS202_NAMESPACE(sym))
 #endif
 
 #endif /* MLKEM_NATIVE_COMMON_H */
diff --git a/mlkem/config.h b/mlkem/config.h
@@ -42,8 +42,10 @@
 /******************************************************************************
  * Name:        MLKEM_NAMESPACE_PREFIX
  *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/.
+ * Description: The prefix to use to namespace global symbols from mlkem/.
+ *
+ *              Level-dependent symbols will additionally be prefixed with the
+ *              security level if MLKEM_NAMESPACE_PREFIX_ADD_LEVEL is set.
  *
  *              This can also be set using CFLAGS.
  *
@@ -68,19 +70,6 @@
  *****************************************************************************/
 /* #define MLKEM_NAMESPACE_PREFIX_ADD_LEVEL */
 
-/******************************************************************************
- * Name:        FIPS202_NAMESPACE_PREFIX
- *
- * Description: The prefix to use to namespace global symbols
- *              from mlkem/fips202/.
- *
- *              This can also be set using CFLAGS.
- *
- *****************************************************************************/
-#if !defined(FIPS202_NAMESPACE_PREFIX)
-#define FIPS202_NAMESPACE_PREFIX FIPS202_DEFAULT_NAMESPACE_PREFIX
-#endif
-
 /******************************************************************************
  * Name:        MLKEM_NATIVE_MULTILEVEL_BUILD_WITH_SHARED
  *
@@ -179,25 +168,13 @@
 /* Default namespace
  *
  * Don't change this. If you need a different namespace, re-define
- * MLKEM_NAMESPACE above instead, and remove the following.
- */
-
-/*
- * The default FIPS202 namespace is
- *
- *   PQCP_MLKEM_NATIVE_FIPS202_<BACKEND>_
+ * MLKEM_NAMESPACE_PREFIX above instead, and remove the following.
  *
- * e.g., PQCP_MLKEM_NATIVE_FIPS202_C_
- */
-
-#define FIPS202_DEFAULT_NAMESPACE_PREFIX PQCP_MLKEM_NATIVE_FIPS202
-
-/*
  * The default MLKEM namespace is
  *
- *   PQCP_MLKEM_NATIVE_MLKEM<LEVEL>_<BACKEND>_
+ *   PQCP_MLKEM_NATIVE_MLKEM<LEVEL>_
  *
- * e.g., PQCP_MLKEM_NATIVE_MLKEM512_AARCH64_OPT_
+ * e.g., PQCP_MLKEM_NATIVE_MLKEM512_
  */
 
 #if MLKEM_K == 2

diff --git a/mlkem/fips202/fips202.c b/mlkem/fips202/fips202.c
@@ -24,9 +24,9 @@
  * This is to facilitate building multiple instances
  * of mlkem-native (e.g. with varying security levels)
  * within a single compilation unit. */
-#define keccak_absorb_once FIPS202_NAMESPACE(keccak_absorb_once)
-#define keccak_squeeze_once FIPS202_NAMESPACE(keccak_squeeze_once)
-#define keccak_squeezeblocks FIPS202_NAMESPACE(keccak_squeezeblocks)
+#define keccak_absorb_once MLKEM_NAMESPACE(keccak_absorb_once)
+#define keccak_squeeze_once MLKEM_NAMESPACE(keccak_squeeze_once)
+#define keccak_squeezeblocks MLKEM_NAMESPACE(keccak_squeezeblocks)
 /* End of static namespacing */
 
 /*************************************************
@@ -185,7 +185,7 @@ void shake128_squeezeblocks(uint8_t *output, size_t nblocks, shake128ctx *state)
 
 void shake128_release(shake128ctx *state) { (void)state; }
 
-#define shake256ctx FIPS202_NAMESPACE(shake256ctx)
+#define shake256ctx MLKEM_NAMESPACE(shake256ctx)
 typedef shake128ctx shake256ctx;
 void shake256(uint8_t *output, size_t outlen, const uint8_t *input,
               size_t inlen)

diff --git a/mlkem/fips202/fips202.h b/mlkem/fips202/fips202.h
@@ -17,7 +17,7 @@
 
 
 /* Context for non-incremental API */
-#define shake128ctx FIPS202_NAMESPACE(shake128ctx)
+#define shake128ctx MLKEM_NAMESPACE(shake128ctx)
 typedef struct
 {
   uint64_t ctx[25];
@@ -28,7 +28,7 @@ typedef struct
  * This function does not support being called multiple times
  * with the same state.
  */
-#define shake128_absorb_once FIPS202_NAMESPACE(shake128_absorb_once)
+#define shake128_absorb_once MLKEM_NAMESPACE(shake128_absorb_once)
 /*************************************************
  * Name:        shake128_absorb_once
  *
@@ -55,7 +55,7 @@ __contract__(
  *
  * Supports being called multiple times
  */
-#define shake128_squeezeblocks FIPS202_NAMESPACE(shake128_squeezeblocks)
+#define shake128_squeezeblocks MLKEM_NAMESPACE(shake128_squeezeblocks)
 /*************************************************
  * Name:        shake128_squeezeblocks
  *
@@ -77,12 +77,12 @@ __contract__(
 );
 
 /* Free the state */
-#define shake128_release FIPS202_NAMESPACE(shake128_release)
+#define shake128_release MLKEM_NAMESPACE(shake128_release)
 void shake128_release(shake128ctx *state);
 
 /* One-stop SHAKE256 call. Aliasing between input and
  * output is not permitted */
-#define shake256 FIPS202_NAMESPACE(shake256)
+#define shake256 MLKEM_NAMESPACE(shake256)
 /*************************************************
  * Name:        shake256
  *
@@ -104,7 +104,7 @@ __contract__(
 /* One-stop SHA3_256 call. Aliasing between input and
  * output is not permitted */
 #define SHA3_256_HASHBYTES 32
-#define sha3_256 FIPS202_NAMESPACE(sha3_256)
+#define sha3_256 MLKEM_NAMESPACE(sha3_256)
 /*************************************************
  * Name:        sha3_256
  *
@@ -124,7 +124,7 @@ __contract__(
 /* One-stop SHA3_512 call. Aliasing between input and
  * output is not permitted */
 #define SHA3_512_HASHBYTES 64
-#define sha3_512 FIPS202_NAMESPACE(sha3_512)
+#define sha3_512 MLKEM_NAMESPACE(sha3_512)
 /*************************************************
  * Name:        sha3_512
  *