Merge pull request #619 from pq-code-package/kem_h

Introduce header for mlkem-native's public API
pq-code-package · Jan 7, 2025 · dc3d0cd · dc3d0cd · oqs-bot · Jan 7, 2025
2 parents 1a95417 + 95dcffe
commit dc3d0cd
Show file tree

Hide file tree

Showing 28 changed files with 3,539 additions and 2,943 deletions.
diff --git a/examples/bring_your_own_fips202/custom_fips202/fips202x4.h b/examples/bring_your_own_fips202/custom_fips202/fips202x4.h
@@ -17,8 +17,6 @@
 #include <stdint.h>
 
 #include "cbmc.h"
-#include "namespace.h"
-
 #include "fips202.h"
 
 typedef shake128ctx shake128x4ctx[4];

diff --git a/examples/bring_your_own_fips202/main.c b/examples/bring_your_own_fips202/main.c
@@ -6,7 +6,7 @@
 #include <stdio.h>
 #include <string.h>
 
-#include <kem.h>
+#include <mlkem_native.h>
 
 const uint8_t expected_key[] = {0xe9, 0x13, 0x77, 0x84, 0x0e, 0x6b, 0x66, 0x94,
                                 0xea, 0xa9, 0xf0, 0x1c, 0x97, 0xff, 0x68, 0x87,

diff --git a/examples/custom_backend/main.c b/examples/custom_backend/main.c
@@ -6,7 +6,7 @@
 #include <stdio.h>
 #include <string.h>
 
-#include <kem.h>
+#include <mlkem_native.h>
 
 const uint8_t expected_key[] = {0xe9, 0x13, 0x77, 0x84, 0x0e, 0x6b, 0x66, 0x94,
                                 0xea, 0xa9, 0xf0, 0x1c, 0x97, 0xff, 0x68, 0x87,

diff --git a/examples/custom_backend/mlkem_native/custom_config.h b/examples/custom_backend/mlkem_native/custom_config.h
@@ -108,4 +108,14 @@
  *****************************************************************************/
 #define MLKEM_NATIVE_FIPS202_BACKEND "fips202/native/custom/custom.h"
 
+/******************************************************************************
+ * Name:        MLKEM_NATIVE_API_STANDARD
+ *
+ * Description: Define this to extend api.h to also export key sizes and public
+ *              API in the CRYPTO_xxx and crypto_kem_xxx format as used e.g. by
+ *              SUPERCOP.
+ *
+ *****************************************************************************/
+#define MLKEM_NATIVE_API_STANDARD
+
 #endif /* MLkEM_NATIVE_CONFIG_H */
diff --git a/examples/custom_backend/mlkem_native/mlkem/mlkem_native.h b/examples/custom_backend/mlkem_native/mlkem/mlkem_native.h
@@ -0,0 +1 @@
+../../../../mlkem/mlkem_native.h
diff --git a/examples/custom_backend/mlkem_native/mlkem/namespace.h b/examples/custom_backend/mlkem_native/mlkem/namespace.h
diff --git a/examples/mlkem_native_as_code_package/main.c b/examples/mlkem_native_as_code_package/main.c
@@ -6,7 +6,7 @@
 #include <stdio.h>
 #include <string.h>
 
-#include <kem.h>
+#include <mlkem_native.h>
 
 int main(void)
 {

diff --git a/examples/monolithic_build/Makefile b/examples/monolithic_build/Makefile
@@ -31,14 +31,27 @@ RNG_SOURCE=$(wildcard test_only_rng/*.c)
 # Part C:
 #
 # Your application source code
-APP_SOURCE=main.c
+APP_SOURCE=main.c mlkem_native_all.c
 
 ALL_SOURCE=$(MLKEM_NATIVE_SOURCE) $(RNG_SOURCE) $(APP_SOURCE)
 
 BUILD_DIR=build
 BIN=test_binary
 
-CFLAGS=-std=c90
+CFLAGS := \
+	-Wall \
+	-Wextra \
+	-Wmissing-prototypes \
+	-Wshadow \
+	-Wpointer-arith \
+	-Wno-long-long \
+	-Wno-unknown-pragmas \
+	-Wno-unused-command-line-argument \
+	-O3 \
+	-fomit-frame-pointer \
+	-std=c90 \
+	-pedantic \
+	-MMD
 
 BINARY_NAME_FULL=$(BUILD_DIR)/$(BIN)
 

diff --git a/examples/monolithic_build/config_b.h → examples/monolithic_build/config_1024.h b/examples/monolithic_build/config_b.h → examples/monolithic_build/config_1024.h
diff --git a/examples/monolithic_build/config_512.h b/examples/monolithic_build/config_512.h
@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2024 The mlkem-native project authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef MLKEM_NATIVE_CONFIG_H
+#define MLKEM_NATIVE_CONFIG_H
+
+/******************************************************************************
+ * Name:        MLKEM_K
+ *
+ * Description: Determines the security level for ML-KEM
+ *              - MLKEM_K=2 corresponds to ML-KEM-512
+ *              - MLKEM_K=3 corresponds to ML-KEM-768
+ *              - MLKEM_K=4 corresponds to ML-KEM-1024
+ *
+ *              This can also be set using CFLAGS.
+ *
+ *****************************************************************************/
+#ifndef MLKEM_K
+#define MLKEM_K 2 /* Change this for different security strengths */
+#endif
+
+/******************************************************************************
+ * Name:        MLKEM_NATIVE_CONFIG_FILE
+ *
+ * Description: If defined, this is a header that will be included instead
+ *              of mlkem/config.h.
+ *
+ *              This _must_ be set on the command line using
+ *              `-DMLKEM_NATIVE_CONFIG_FILE="..."`.
+ *
+ *              When you need to build mlkem-native in multiple configurations,
+ *              using varying MLKEM_NATIE_CONFIG_FILE can be more convenient
+ *              then configuring everything through CFLAGS.
+ *
+ *****************************************************************************/
+/* #define MLKEM_NATIVE_CONFIG_FILE "config.h" */
+
+/******************************************************************************
+ * Name:        MLKEM_NAMESPACE
+ *
+ * Description: The macros to use to namespace global symbols
+ *              from mlkem/.
+ *****************************************************************************/
+#define CONCAT(a, b) a##b
+#define MLKEM_NAMESPACE(sym) CONCAT(mlkem512_, sym)
+
+/******************************************************************************
+ * Name:        FIPS202_NAMESPACE
+ *
+ * Description: The macros to use to namespace global symbols
+ *              from mlkem/fips202/.
+ *****************************************************************************/
+#define FIPS202_NAMESPACE(sym) CONCAT(mlkem512_, sym)
+
+/******************************************************************************
+ * Name:        MLKEM_USE_NATIVE
+ *
+ * Description: Determines whether a native backend should
+ *              be used, if available.
+ *
+ *              This can also be set using CFLAGS.
+ *
+ *****************************************************************************/
+/* #define MLKEM_USE_NATIVE */
+
+/******************************************************************************
+ * Name:        MLKEM_NATIVE_ARITH_BACKEND
+ *
+ * Description: The arithmetic backend to use.
+ *
+ *              This must be the filename of an arithmetic backend.
+ *              See the existing backends for examples.
+ *
+ *              This can be set using CFLAGS.
+ *
+ *****************************************************************************/
+#if defined(MLKEM_USE_NATIVE) && !defined(MLKEM_NATIVE_ARITH_BACKEND)
+#define MLKEM_NATIVE_ARITH_BACKEND "native/default.h"
+#endif /* MLKEM_NATIVE_ARITH_BACKEND */
+
+/******************************************************************************
+ * Name:        MLKEM_NATIVE_FIPS202_BACKEND
+ *
+ * Description: The FIPS-202 backend to use.
+ *
+ *              This must be the filename of an FIPS-202 backend.
+ *
+ *              This can be set using CFLAGS.
+ *
+ *****************************************************************************/
+#if defined(MLKEM_USE_NATIVE) && !defined(MLKEM_NATIVE_FIPS202_BACKEND)
+#define MLKEM_NATIVE_FIPS202_BACKEND "fips202/native/default.h"
+#endif /* MLKEM_NATIVE_FIPS202_BACKEND */
+
+#endif /* MLkEM_NATIVE_CONFIG_H */
diff --git a/examples/monolithic_build/config_a.h → examples/monolithic_build/config_768.h b/examples/monolithic_build/config_a.h → examples/monolithic_build/config_768.h
diff --git a/examples/monolithic_build/main.c b/examples/monolithic_build/main.c
@@ -3,42 +3,38 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#define MLKEM_NATIVE_CONFIG_FILE "config_a.h"
-#include "mlkem_native_all.c"
-#undef MLKEM_NATIVE_CONFIG_FILE
-
-#define MLKEM_NATIVE_CONFIG_FILE "config_b.h"
-#include "mlkem_native_all.c"
-#undef MLKEM_NATIVE_CONFIG_FILE
-
-/* Some scheme parameters from META.json
- *
- * TODO: One should be able to get those more easily,
- * but after mlkem_native_all.c the MLKEM_XXX macros
- * have already been undefined.
- * This should be sorted by providing a new api.h
- * header that can be included and relies solely on
- * the config.h; the present kem.h does not yet have
- * this property. */
-#define MLKEM768_SECRETKEYBYTES 2400
-#define MLKEM768_PUBLICKEYBYTES 1184
-#define MLKEM768_CIPHERTEXTBYTES 1088
-#define MLKEM768_BYTES 32
-
-#define MLKEM1024_SECRETKEYBYTES 3168
-#define MLKEM1024_PUBLICKEYBYTES 1568
-#define MLKEM1024_CIPHERTEXTBYTES 1568
-#define MLKEM1024_BYTES 32
-
-/* Public API declaration -- those, too, should not be done
- * manually, but come from a config-dependent api.h. */
-int mlkem768_keypair(uint8_t *pk, uint8_t *sk);
-int mlkem768_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
-int mlkem768_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
-
-int mlkem1024_keypair(uint8_t *pk, uint8_t *sk);
-int mlkem1024_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
-int mlkem1024_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "mlkem_native_all.h"
+
+static int test_keys_mlkem512(void)
+{
+  uint8_t pk[MLKEM512_PUBLICKEYBYTES];
+  uint8_t sk[MLKEM512_SECRETKEYBYTES];
+  uint8_t ct[MLKEM512_CIPHERTEXTBYTES];
+  uint8_t key_a[MLKEM512_BYTES];
+  uint8_t key_b[MLKEM512_BYTES];
+
+  /* Alice generates a public key */
+  mlkem512_keypair(pk, sk);
+
+  /* Bob derives a secret key and creates a response */
+  mlkem512_enc(ct, key_b, pk);
+
+  /* Alice uses Bobs response to get her shared key */
+  mlkem512_dec(key_a, ct, sk);
+
+  if (memcmp(key_a, key_b, MLKEM512_BYTES))
+  {
+    printf("[MLKEM-512] ERROR keys\n");
+    return 1;
+  }
+
+  printf("[MLKEM-512] OK\n");
+  return 0;
+}
 
 static int test_keys_mlkem768(void)
 {
@@ -63,6 +59,7 @@ static int test_keys_mlkem768(void)
     return 1;
   }
 
+  printf("[MLKEM-768] OK\n");
   return 0;
 }
 
@@ -89,11 +86,17 @@ static int test_keys_mlkem1024(void)
     return 1;
   }
 
+  printf("[MLKEM-1024] OK\n");
   return 0;
 }
 
 int main(void)
 {
+  if (test_keys_mlkem512() != 0)
+  {
+    return 1;
+  }
+
   if (test_keys_mlkem768() != 0)
   {
     return 1;
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`29062` cycles	`29061` cycles	`1.00`
`ML-KEM-512 encaps`	`35383` cycles	`35384` cycles	`1.00`
`ML-KEM-512 decaps`	`45860` cycles	`45860` cycles	`1`
`ML-KEM-768 keypair`	`49395` cycles	`49388` cycles	`1.00`
`ML-KEM-768 encaps`	`55568` cycles	`55566` cycles	`1.00`
`ML-KEM-768 decaps`	`70311` cycles	`70304` cycles	`1.00`
`ML-KEM-1024 keypair`	`72048` cycles	`72050` cycles	`1.00`
`ML-KEM-1024 encaps`	`80821` cycles	`80825` cycles	`1.00`
`ML-KEM-1024 decaps`	`100697` cycles	`100700` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`13911` cycles	`13522` cycles	`1.03`
`ML-KEM-512 encaps`	`17239` cycles	`17307` cycles	`1.00`
`ML-KEM-512 decaps`	`23069` cycles	`22850` cycles	`1.01`
`ML-KEM-768 keypair`	`22563` cycles	`22521` cycles	`1.00`
`ML-KEM-768 encaps`	`24501` cycles	`24448` cycles	`1.00`
`ML-KEM-768 decaps`	`32532` cycles	`32387` cycles	`1.00`
`ML-KEM-1024 keypair`	`31369` cycles	`31386` cycles	`1.00`
`ML-KEM-1024 encaps`	`34920` cycles	`34920` cycles	`1`
`ML-KEM-1024 decaps`	`45821` cycles	`45791` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`18127` cycles	`18123` cycles	`1.00`
`ML-KEM-512 encaps`	`23200` cycles	`23219` cycles	`1.00`
`ML-KEM-512 decaps`	`30491` cycles	`30517` cycles	`1.00`
`ML-KEM-768 keypair`	`31076` cycles	`31112` cycles	`1.00`
`ML-KEM-768 encaps`	`34166` cycles	`34158` cycles	`1.00`
`ML-KEM-768 decaps`	`44731` cycles	`44736` cycles	`1.00`
`ML-KEM-1024 keypair`	`44615` cycles	`44735` cycles	`1.00`
`ML-KEM-1024 encaps`	`49907` cycles	`49899` cycles	`1.00`
`ML-KEM-1024 decaps`	`64356` cycles	`64342` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`20336` cycles	`20329` cycles	`1.00`
`ML-KEM-512 encaps`	`27016` cycles	`27016` cycles	`1`
`ML-KEM-512 decaps`	`35814` cycles	`35820` cycles	`1.00`
`ML-KEM-768 keypair`	`34895` cycles	`34903` cycles	`1.00`
`ML-KEM-768 encaps`	`38146` cycles	`38130` cycles	`1.00`
`ML-KEM-768 decaps`	`50971` cycles	`50970` cycles	`1.00`
`ML-KEM-1024 keypair`	`47950` cycles	`47958` cycles	`1.00`
`ML-KEM-1024 encaps`	`54107` cycles	`54119` cycles	`1.00`
`ML-KEM-1024 decaps`	`71636` cycles	`71659` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`34853` cycles	`34896` cycles	`1.00`
`ML-KEM-512 encaps`	`45050` cycles	`45026` cycles	`1.00`
`ML-KEM-512 decaps`	`58927` cycles	`58961` cycles	`1.00`
`ML-KEM-768 keypair`	`59275` cycles	`59186` cycles	`1.00`
`ML-KEM-768 encaps`	`71891` cycles	`71842` cycles	`1.00`
`ML-KEM-768 decaps`	`89446` cycles	`89371` cycles	`1.00`
`ML-KEM-1024 keypair`	`87544` cycles	`87532` cycles	`1.00`
`ML-KEM-1024 encaps`	`104559` cycles	`104588` cycles	`1.00`
`ML-KEM-1024 decaps`	`127643` cycles	`127572` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`18965` cycles	`18965` cycles	`1`
`ML-KEM-512 encaps`	`23587` cycles	`23590` cycles	`1.00`
`ML-KEM-512 decaps`	`30671` cycles	`30673` cycles	`1.00`
`ML-KEM-768 keypair`	`32288` cycles	`32290` cycles	`1.00`
`ML-KEM-768 encaps`	`35873` cycles	`35872` cycles	`1.00`
`ML-KEM-768 decaps`	`46039` cycles	`46043` cycles	`1.00`
`ML-KEM-1024 keypair`	`46611` cycles	`46612` cycles	`1.00`
`ML-KEM-1024 encaps`	`52445` cycles	`52449` cycles	`1.00`
`ML-KEM-1024 decaps`	`66245` cycles	`66245` cycles	`1`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`15060` cycles	`15058` cycles	`1.00`
`ML-KEM-512 encaps`	`19672` cycles	`19653` cycles	`1.00`
`ML-KEM-512 decaps`	`26313` cycles	`26288` cycles	`1.00`
`ML-KEM-768 keypair`	`25624` cycles	`25469` cycles	`1.01`
`ML-KEM-768 encaps`	`28174` cycles	`28135` cycles	`1.00`
`ML-KEM-768 decaps`	`37871` cycles	`37833` cycles	`1.00`
`ML-KEM-1024 keypair`	`35627` cycles	`35647` cycles	`1.00`
`ML-KEM-1024 encaps`	`40994` cycles	`40999` cycles	`1.00`
`ML-KEM-1024 decaps`	`54621` cycles	`54506` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`52168` cycles	`52177` cycles	`1.00`
`ML-KEM-512 encaps`	`65776` cycles	`65785` cycles	`1.00`
`ML-KEM-512 decaps`	`88405` cycles	`88423` cycles	`1.00`
`ML-KEM-768 keypair`	`84751` cycles	`84786` cycles	`1.00`
`ML-KEM-768 encaps`	`101453` cycles	`101479` cycles	`1.00`
`ML-KEM-768 decaps`	`132106` cycles	`132101` cycles	`1.00`
`ML-KEM-1024 keypair`	`124354` cycles	`124028` cycles	`1.00`
`ML-KEM-1024 encaps`	`145704` cycles	`145920` cycles	`1.00`
`ML-KEM-1024 decaps`	`183673` cycles	`183661` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`56637` cycles	`56667` cycles	`1.00`
`ML-KEM-512 encaps`	`69483` cycles	`69506` cycles	`1.00`
`ML-KEM-512 decaps`	`91396` cycles	`91492` cycles	`1.00`
`ML-KEM-768 keypair`	`91863` cycles	`91911` cycles	`1.00`
`ML-KEM-768 encaps`	`107820` cycles	`107825` cycles	`1.00`
`ML-KEM-768 decaps`	`136371` cycles	`136585` cycles	`1.00`
`ML-KEM-1024 keypair`	`134966` cycles	`134891` cycles	`1.00`
`ML-KEM-1024 encaps`	`155230` cycles	`155385` cycles	`1.00`
`ML-KEM-1024 decaps`	`191729` cycles	`191709` cycles	`1.00`
Benchmark suite	Current: `dc3d0cd`	Previous: `1a95417`	Ratio
`ML-KEM-512 keypair`	`18135` cycles	`18133` cycles	`1.00`
`ML-KEM-512 encaps`	`22162` cycles	`22162` cycles	`1`
`ML-KEM-512 decaps`	`28771` cycles	`28770` cycles	`1.00`
`ML-KEM-768 keypair`	`30561` cycles	`30563` cycles	`1.00`
`ML-KEM-768 encaps`	`33620` cycles	`33618` cycles	`1.00`
`ML-KEM-768 decaps`	`43142` cycles	`43146` cycles	`1.00`
`ML-KEM-1024 keypair`	`44197` cycles	`44194` cycles	`1.00`
`ML-KEM-1024 encaps`	`49663` cycles	`49660` cycles	`1.00`
`ML-KEM-1024 decaps`	`62653` cycles	`62656` cycles	`1.00`