From e80f650442eba8effccab7badc12382c358d5e83 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 17 Dec 2024 20:22:23 +0000 Subject: [PATCH] Fix ordering of includes in arith/fips202 backend The backend API `mlkem/native/api.h` includes sanity checks on the arithmetic backend. For example, if a custom NTT domain coefficient ordering is defined, then the backend must provide native replacements for almost all functions, and they have to be adapted to the custom order. Previously, however, `mlkem/native/api.h` was included _beffore_ the backend. This still served the purpose of ensuring that the native API is indeed what the backend implements, but it rendered the sanity checks effectless. This commit fixes this by reordering the includes accordingly, in both the arithmetic and the FIPS-202 backend. Signed-off-by: Hanno Becker --- mlkem/arith_backend.h | 10 ++++-- mlkem/fips202/fips202_backend.h | 11 +++++-- mlkem/fips202/native/api.h | 35 +++++++++++++------- mlkem/native/aarch64/src/clean_impl.h | 3 ++ mlkem/native/aarch64/src/opt_impl.h | 3 ++ mlkem/native/api.h | 44 +++++++++++++++----------- mlkem/native/x86_64/src/default_impl.h | 1 + 7 files changed, 72 insertions(+), 35 deletions(-) diff --git a/mlkem/arith_backend.h b/mlkem/arith_backend.h index 7fb3df84d..32ce6f6e4 100644 --- a/mlkem/arith_backend.h +++ b/mlkem/arith_backend.h @@ -8,11 +8,17 @@ #else #define MLKEM_NATIVE_ARITH_IMPL_H -/* Include to enforce consistency of API and implementation */ -#include "native/api.h" +#include "common.h" #if defined(MLKEM_NATIVE_ARITH_BACKEND_IMPL) #include MLKEM_NATIVE_ARITH_BACKEND_IMPL + +/* Include to enforce consistency of API and implementation, + * and conduct sanity checks on the backend. + * + * Keep this _after_ the inclusion of the backend; otherwise, + * the sanity checks won't have an effect. */ +#include "native/api.h" #endif #endif /* MLKEM_NATIVE_ARITH_IMPL_H */ diff --git a/mlkem/fips202/fips202_backend.h b/mlkem/fips202/fips202_backend.h index 24e6593b2..98a74ed6f 100644 --- a/mlkem/fips202/fips202_backend.h +++ b/mlkem/fips202/fips202_backend.h @@ -8,11 +8,16 @@ #else #define MLKEM_NATIVE_FIPS202_IMPL_H -/* Include to enforce consistency of API and implementation */ -#include "native/api.h" - #if defined(MLKEM_NATIVE_FIPS202_BACKEND_IMPL) #include MLKEM_NATIVE_FIPS202_BACKEND_IMPL + +/* Include to enforce consistency of API and implementation, + * and conduct sanity checks on the backend. + * + * Keep this _after_ the inclusion of the backend; otherwise, + * the sanity checks won't have an effect. */ +#include "fips202/native/api.h" #endif + #endif /* MLKEM_NATIVE_FIPS202_IMPL_H */ diff --git a/mlkem/fips202/native/api.h b/mlkem/fips202/native/api.h index 685b8bfc5..cd4149b0b 100644 --- a/mlkem/fips202/native/api.h +++ b/mlkem/fips202/native/api.h @@ -2,22 +2,33 @@ * Copyright (c) 2024 The mlkem-native project authors * SPDX-License-Identifier: Apache-2.0 */ -#ifndef FIPS202_NATIVE_H -#define FIPS202_NATIVE_H - -#include -#include "common.h" /* - * FIPS202 native interface + * FIPS-202 native interface + * + * This header is primarily for documentation purposes. + * It should not be included by backend implementations. */ +#ifdef MLKEM_NATIVE_FIPS202_NATIVE_API_H +#error \ + "The FIPS-202 backend API `mlkem/fips202/native/api.h` " \ + "should not be directly included. Please include the relevant " \ + "structure headers directly." +#else /* MLKEM_NATIVE_FIPS202_NATIVE_API_H */ +#define MLKEM_NATIVE_FIPS202_NATIVE_API_H + +#include /* - * Those functions are meant to be trivial wrappers around - * the chosen native implementation. The are static inline - * to avoid unnecessary calls. - * The macro before each declaration controls whether a native - * implementation is present. + * This is the C<->native interface allowing for the drop-in + * of custom Keccak-F1600 implementations. + * + * A _backend_ is a specific implementation of parts of this interface. + * + * You can replace 1-fold, 2-fold, or 4-fold batched Keccak-F1600. + * To enable, set MLKEM_USE_FIPS202_X{1,2,4}_NATIVE in your backend, + * and define the inline wrapper keccak_f1600_x{1,2,4}_native() to + * forward to your implementation. */ #if defined(MLKEM_USE_FIPS202_X1_NATIVE) @@ -30,4 +41,4 @@ static INLINE void keccak_f1600_x2_native(uint64_t *state); static INLINE void keccak_f1600_x4_native(uint64_t *state); #endif -#endif /* FIPS202_NATIVE_H */ +#endif /* MLKEM_NATIVE_FIPS202_NATIVE_API_H */ diff --git a/mlkem/native/aarch64/src/clean_impl.h b/mlkem/native/aarch64/src/clean_impl.h index 0a40199e7..c91a7eedd 100644 --- a/mlkem/native/aarch64/src/clean_impl.h +++ b/mlkem/native/aarch64/src/clean_impl.h @@ -12,6 +12,9 @@ #include "arith_native_aarch64.h" +#include "poly.h" +#include "polyvec.h" + /* Set of primitives that this backend replaces */ #define MLKEM_USE_NATIVE_NTT #define MLKEM_USE_NATIVE_INTT diff --git a/mlkem/native/aarch64/src/opt_impl.h b/mlkem/native/aarch64/src/opt_impl.h index bc9af0dee..5e4d00e1f 100644 --- a/mlkem/native/aarch64/src/opt_impl.h +++ b/mlkem/native/aarch64/src/opt_impl.h @@ -12,6 +12,9 @@ #include "arith_native_aarch64.h" +#include "poly.h" +#include "polyvec.h" + /* Set of primitives that this backend replaces */ #define MLKEM_USE_NATIVE_NTT #define MLKEM_USE_NATIVE_INTT diff --git a/mlkem/native/api.h b/mlkem/native/api.h index 5a2d92b1d..792ecb8a4 100644 --- a/mlkem/native/api.h +++ b/mlkem/native/api.h @@ -2,28 +2,37 @@ * Copyright (c) 2024 The mlkem-native project authors * SPDX-License-Identifier: Apache-2.0 */ -#ifndef MLKEM_ARITH_NATIVE_H -#define MLKEM_ARITH_NATIVE_H -#include +/* + * Native arithmetic interface + * + * This header is primarily for documentation purposes. + * It should not be included by backend implementations. + * + * To ensure consistency with backends, the header will be + * included automatically after inclusion of the active + * backend, to ensure consistency of function signatures, + * and run sanity checks. + */ +#ifdef MLKEM_NATIVE_ARITH_NATIVE_API_H +#error \ + "The arithmetic backend API `mlkem/native/api.h` " \ + "should not be directly included. Please include the relevant " \ + "structure headers directly." +#else /* MLKEM_NATIVE_ARITH_NATIVE_API_H */ +#define MLKEM_NATIVE_ARITH_NATIVE_API_H -#include "cbmc.h" +#include #include "poly.h" #include "polyvec.h" -#include "common.h" - /* - * MLKEM native arithmetic interface - * - * This is the C<->native arithmetic interface used in this repository - * to allow for the drop-in of native code for performance critical - * components of ML-KEM. + * This is the C<->native interface allowing for the drop-in of + * native code for performance critical arithmetic components of ML-KEM. * - * A _profile_ is a specific implementation of (part of) this interface. - * The active profile (if any) is determined in profile.h. + * A _backend_ is a specific implementation of (part of) this interface. * - * To add a function to a profile, define MLKEM_USE_NATIVE_XXX and + * To add a function to a backend, define MLKEM_USE_NATIVE_XXX and * implement `static inline xxx(...)` in the profile header. * * The only exception is MLKEM_USE_NATIVE_NTT_CUSTOM_ORDER. This option can @@ -37,9 +46,8 @@ */ /* - * Those functions are meant to be trivial wrappers around - * the chosen native implementation. The are static inline - * to avoid unnecessary calls. + * Those functions are meant to be trivial wrappers around the chosen native + * implementation. The are static inline to avoid unnecessary calls. * The macro before each declaration controls whether a native * implementation is present. */ @@ -244,4 +252,4 @@ static INLINE int rej_uniform_native(int16_t *r, unsigned int len, const uint8_t *buf, unsigned int buflen); #endif /* MLKEM_USE_NATIVE_REJ_UNIFORM */ -#endif /* MLKEM_ARITH_NATIVE_H */ +#endif /* MLKEM_NATIVE_ARITH_NATIVE_API_H */ diff --git a/mlkem/native/x86_64/src/default_impl.h b/mlkem/native/x86_64/src/default_impl.h index 4f3cd2c9a..55a1a3c10 100644 --- a/mlkem/native/x86_64/src/default_impl.h +++ b/mlkem/native/x86_64/src/default_impl.h @@ -14,6 +14,7 @@ #include "arith_native_x86_64.h" #include "poly.h" +#include "polyvec.h" #define MLKEM_USE_NATIVE_NTT_CUSTOM_ORDER