Introduce global config and reorganize backends

.github/workflows/bench.yml

@@ -43,7 +43,7 @@ jobs:
           name: Arm Cortex-A55 (Snapdragon 888) benchmarks
           bench_pmu: PERF
           archflags: "-mcpu=cortex-a55 -march=armv8.2-a"
-          cflags: "-flto -static -DFORCE_AARCH64 -DFIPS202_NATIVE_PROFILE=\"aarch64/profiles/cortex_a55.h\""
+          cflags: "-flto -static -DFORCE_AARCH64 -DMLKEM_NATIVE_FIPS202_BACKEND=\\\\\\\"aarch64/cortex_a55.h\\\\\\\""
           bench_extra_args: -w exec-on-a55
         - system: bpi
           name: Bananapi bpi-f3 benchmarks

.github/workflows/ci.yml

@@ -119,6 +119,9 @@ jobs:
       - name: bring_your_own_fips202
         run: |
           make run -C examples/bring_your_own_fips202
+      - name: custom_backend
+        run: |
+          make run -C examples/custom_backend
   build_kat:
     needs: [quickcheck, quickcheck-windows]
     strategy:

README.md

@@ -93,7 +93,7 @@ in this repository is for experimental and development purposes only. If you pre
 ### Can I bring my own backend?
 
 Absolutely: You can add further backends for ML-KEM native arithmetic and/or for FIPS-202. Follow the existing backends
-as templates.
+as templates, or see [examples/custom_backend](examples/custom_backend) for a minimal example how to register a custom backend.
 
 ### Can I bring my own FIPS-202?
 

examples/README.md

@@ -12,3 +12,8 @@ See [mlkem_native_as_code_package](mlkem_native_as_code_package).
 
 See [bring_your_own_fips202](bring_your_own_fips202) for an example of how to use mlkem-native with your own FIPS-202
 implementation.
+
+## Using mlkem-native as a code package, custom config + custom FIPS-202 backend
+
+See [custom_backend](custom_backend) for an example of how to use mlkem-native with a custom configuration file and a
+custom FIPS-202 backend.

examples/bring_your_own_fips202/Makefile

@@ -19,7 +19,6 @@ INC=
 INC+=-Imlkem_native/mlkem
 INC+=-Imlkem_native/mlkem
 INC+=-Imlkem_native/mlkem/native
-INC+=-Imlkem_native/mlkem/sys
 
 # Part B:
 #

examples/bring_your_own_fips202/custom_fips202/fips202.h

@@ -11,7 +11,7 @@
 #ifndef FIPS202_H
 #define FIPS202_H
 
-#include "namespace.h"
+#include "common.h"
 #include "tiny_sha3/sha3.h"
 
 #define SHAKE128_RATE 168

examples/custom_backend/Makefile

@@ -0,0 +1,64 @@
+# (SPDX-License-Identifier: CC-BY-4.0)
+
+.PHONY: build run clean
+
+# Part A:
+#
+# mlkem-native source and header files
+#
+# If you are not concerned about minimizing for a specific backend,
+# you can just include _all_ source files into your build.
+MLKEM_NATIVE_SOURCE=$(wildcard          \
+	mlkem_native/**/*.c	  	\
+	mlkem_native/**/*.c		\
+	mlkem_native/**/**/*.c		\
+	mlkem_native/**/**/**/*.c	\
+	mlkem_native/**/**/**/**/*.c)
+
+INC=
+INC+=-Imlkem_native/
+INC+=-Imlkem_native/mlkem
+INC+=-Imlkem_native/mlkem/native
+INC+=-Imlkem_native/fips202
+INC+=-Imlkem_native/fips202/native
+
+# Part B:
+#
+# Random number generator
+#
+# !!! WARNING !!!
+#
+# The randombytes() implementation used here is for TESTING ONLY.
+# You MUST NOT use this implementation outside of testing.
+#
+# !!! WARNING !!!
+RNG_SOURCE=$(wildcard test_only_rng/*.c)
+
+# Part C:
+#
+# Your application source code
+APP_SOURCE=$(wildcard *.c)
+
+ALL_SOURCE=$(MLKEM_NATIVE_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
+
+BUILD_DIR=build
+BIN=test_binary
+
+CFLAGS=-DMLKEM_NATIVE_CONFIG_FILE="\"custom_config.h\""
+
+BINARY_NAME_FULL=$(BUILD_DIR)/$(BIN)
+
+$(BINARY_NAME_FULL): $(ALL_SOURCE)
+	echo "$@"
+	mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@
+
+all: run
+
+build: $(BINARY_NAME_FULL)
+
+run: $(BINARY_NAME_FULL)
+	./$(BINARY_NAME_FULL)
+
+clean:
+	rm -rf $(BUILD_DIR)