Skip to content

Commit a3de52c

Browse files
author
Becker
committed
Make arithmetic and FIPS202 backends independently configurable
Previously, the configuration option MLKEM_USE_NATIVE would guard whether native backends would be used or not. Specifically, it would control both the arithmetic backend and the FIPS202 backend. The specific choice of backend would then be provided through MLKEM_NATIVE_{ARITH,FIPS202}_BACKEND. This setup does allow the user to use a native arithmetic backend but no native FIPS202 backend -- however, it requires a custom config, since the default config would auto-define MLKEM_NATIVE_FIPS202_BACKEND when unset -- this cannot be altered through CFLAGS. To make everything configurable through CFLAGS as well as a custom config file, this commit explicitly separates MLKEM_USE_NATIVE in two configurations options - MLKEM_USE_NATIVE_BACKEND_ARITH - MLKEM_USE_NATIVE_BACKEND_FIPS202, which control whether an arithmetic resp. FIPS202 native backend should be used. When those options are set, MLKEM_NATIVE_{ARITH,FIPS202}_BACKEND_FILE must either be unset -- in which case the default backends will be used -- or point to a backend metadata file. Signed-off-by: Becker <[email protected]>
1 parent 8b8e1f8 commit a3de52c

File tree

13 files changed

+330
-124
lines changed

13 files changed

+330
-124
lines changed

‎.github/workflows/bench.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ jobs:
4343
name: Arm Cortex-A55 (Snapdragon 888) benchmarks
4444
bench_pmu: PERF
4545
archflags: "-mcpu=cortex-a55 -march=armv8.2-a"
46-
cflags: "-flto -static -DFORCE_AARCH64 -DMLKEM_NATIVE_FIPS202_BACKEND=\\\\\\\"fips202/native/aarch64/cortex_a55.h\\\\\\\""
46+
cflags: "-flto -static -DFORCE_AARCH64 -DMLKEM_NATIVE_FIPS202_BACKEND_FILE=\\\\\\\"fips202/native/aarch64/cortex_a55.h\\\\\\\""
4747
bench_extra_args: -w exec-on-a55
4848
- system: bpi
4949
name: Bananapi bpi-f3 benchmarks

‎examples/custom_backend/mlkem_native/custom_config.h

+47-27
Original file line numberDiff line numberDiff line change
@@ -42,58 +42,78 @@
4242
#define MLKEM_NAMESPACE_PREFIX CUSTOM_TINY_SHA3
4343

4444
/******************************************************************************
45-
* Name: MLKEM_USE_NATIVE
45+
* Name: MLKEM_USE_NATIVE_BACKEND_ARITH
4646
*
47-
* Description: Determines whether a native backend should
48-
* be used, if available.
47+
* Description: Determines whether an native arithmetic backend should be used.
48+
*
49+
* The arithmetic backend covers performance critical functions
50+
* such as the number-theoretic transform (NTT).
51+
*
52+
* If this option is unset, the C backend will be used.
53+
*
54+
* If this option is set, the arithmetic backend to be use is
55+
* determined by MLKEM_NATIVE_ARITH_BACKEND: If the latter is
56+
* unset, the default backend for your the target architecture
57+
* will be used. If set, it must be the name of a backend metadata
58+
* file.
4959
*
5060
* This can also be set using CFLAGS.
5161
*
5262
*****************************************************************************/
53-
#define MLKEM_USE_NATIVE
63+
/* No native arithmetic backend */
64+
/* #define MLKEM_USE_NATIVE_BACKEND_ARITH */
5465

5566
/******************************************************************************
56-
* Name: MLKEM_NATIVE_ARITH_BACKEND
67+
* Name: MLKEM_NATIVE_ARITH_BACKEND_FILE
5768
*
5869
* Description: The arithmetic backend to use.
5970
*
60-
* This must be the filename of an arithmetic
61-
* backend. The backend is expected to define
62-
*
63-
* - MLKEM_NATIVE_ARITH_BACKEND_NAME
71+
* If MLKEM_USE_NATIVE_BACKEND_ARITH is unset, this option
72+
* is ignored.
6473
*
65-
* The name of the backend as used in the default namespace.
74+
* If MLKEM_USE_NATIVE_BACKEND_ARITH is set, this option must
75+
* either be undefined or the filename of an arithmetic backend.
76+
* If unset, the default backend will be used.
6677
*
67-
* - MLKEM_NATIVE_ARITH_BACKEND_IMPL
68-
*
69-
* The filename of the implementation of the arithmetic backend.
70-
*
71-
* See the existing backends for more information.
78+
* This can be set using CFLAGS.
7279
*
7380
*****************************************************************************/
74-
/* Let's pretend we don't want an arithmetic backend */
75-
/* #define MLKEM_NATIVE_ARITH_BACKEND "native/default.h" */
81+
/* #define MLKEM_NATIVE_ARITH_BACKEND_FILE "native/default.h" */
7682

7783
/******************************************************************************
78-
* Name: MLKEM_NATIVE_FIPS202_BACKEND
84+
* Name: MLKEM_USE_NATIVE_BACKEND_FIPS202
7985
*
80-
* Description: The FIPS-202 backend to use.
86+
* Description: Determines whether an native FIPS202 backend should be used.
8187
*
82-
* This must be the filename of an FIPS-202
83-
* backend. The backend is expected to define
88+
* The FIPS202 backend covers 1x/2x/4x-fold Keccak-f1600, which is
89+
* the performance bottleneck of SHA3 and SHAKE.
8490
*
85-
* - MLKEM_NATIVE_FIPS202_BACKEND_NAME
91+
* If this option is unset, the C backend will be used.
8692
*
87-
* The name of the backend as used in the default namespace.
93+
* If this option is set, the FIPS202 backend to be use is
94+
* determined by MLKEM_NATIVE_FIPS202_BACKEND: If the latter is
95+
* unset, the default backend for your the target architecture
96+
* will be used. If set, it must be the name of a backend metadata
97+
* file.
8898
*
89-
* - MLKEM_NATIVE_FIPS202_BACKEND_IMPL
99+
* This can also be set using CFLAGS.
100+
*
101+
*****************************************************************************/
102+
#define MLKEM_USE_NATIVE_BACKEND_FIPS202
103+
104+
/******************************************************************************
105+
* Name: MLKEM_NATIVE_FIPS202_BACKEND_FILE
106+
*
107+
* Description: The FIPS-202 backend to use.
90108
*
91-
* The filename of the implementation of the FIPS-202 backend.
109+
* If MLKEM_USE_NATIVE_BACKEND_FIPS202 is set, this option must
110+
* either be undefined or the filename of a FIPS202 backend.
111+
* If unset, the default backend will be used.
92112
*
93-
* See the existing backends for more information.
113+
* This can be set using CFLAGS.
94114
*
95115
*****************************************************************************/
96-
#define MLKEM_NATIVE_FIPS202_BACKEND "fips202/native/custom/custom.h"
116+
#define MLKEM_NATIVE_FIPS202_BACKEND_FILE "fips202/native/custom/custom.h"
97117

98118
/******************************************************************************
99119
* Name: MLKEM_NATIVE_API_STANDARD

‎examples/monolithic_build/config_512.h

+58-15
Original file line numberDiff line numberDiff line change
@@ -49,43 +49,86 @@
4949
#define MLKEM_NAMESPACE_PREFIX mlkem512
5050

5151
/******************************************************************************
52-
* Name: MLKEM_USE_NATIVE
52+
* Name: MLKEM_USE_NATIVE_BACKEND_ARITH
5353
*
54-
* Description: Determines whether a native backend should
55-
* be used, if available.
54+
* Description: Determines whether an native arithmetic backend should be used.
55+
*
56+
* The arithmetic backend covers performance critical functions
57+
* such as the number-theoretic transform (NTT).
58+
*
59+
* If this option is unset, the C backend will be used.
60+
*
61+
* If this option is set, the arithmetic backend to be use is
62+
* determined by MLKEM_NATIVE_ARITH_BACKEND: If the latter is
63+
* unset, the default backend for your the target architecture
64+
* will be used. If set, it must be the name of a backend metadata
65+
* file.
5666
*
5767
* This can also be set using CFLAGS.
5868
*
5969
*****************************************************************************/
60-
/* #define MLKEM_USE_NATIVE */
70+
#if !defined(MLKEM_USE_NATIVE_BACKEND_ARITH)
71+
/* #define MLKEM_USE_NATIVE_BACKEND_ARITH */
72+
#endif
6173

6274
/******************************************************************************
63-
* Name: MLKEM_NATIVE_ARITH_BACKEND
75+
* Name: MLKEM_NATIVE_ARITH_BACKEND_FILE
6476
*
6577
* Description: The arithmetic backend to use.
6678
*
67-
* This must be the filename of an arithmetic backend.
68-
* See the existing backends for examples.
79+
* If MLKEM_USE_NATIVE_BACKEND_ARITH is unset, this option
80+
* is ignored.
81+
*
82+
* If MLKEM_USE_NATIVE_BACKEND_ARITH is set, this option must
83+
* either be undefined or the filename of an arithmetic backend.
84+
* If unset, the default backend will be used.
6985
*
7086
* This can be set using CFLAGS.
7187
*
7288
*****************************************************************************/
73-
#if defined(MLKEM_USE_NATIVE) && !defined(MLKEM_NATIVE_ARITH_BACKEND)
74-
#define MLKEM_NATIVE_ARITH_BACKEND "native/default.h"
75-
#endif /* MLKEM_NATIVE_ARITH_BACKEND */
89+
#if defined(MLKEM_USE_NATIVE_BACKEND_ARITH) && \
90+
!defined(MLKEM_NATIVE_ARITH_BACKEND_FILE)
91+
#define MLKEM_NATIVE_ARITH_BACKEND_FILE "native/default.h"
92+
#endif
93+
94+
/******************************************************************************
95+
* Name: MLKEM_USE_NATIVE_BACKEND_FIPS202
96+
*
97+
* Description: Determines whether an native FIPS202 backend should be used.
98+
*
99+
* The FIPS202 backend covers 1x/2x/4x-fold Keccak-f1600, which is
100+
* the performance bottleneck of SHA3 and SHAKE.
101+
*
102+
* If this option is unset, the C backend will be used.
103+
*
104+
* If this option is set, the FIPS202 backend to be use is
105+
* determined by MLKEM_NATIVE_FIPS202_BACKEND: If the latter is
106+
* unset, the default backend for your the target architecture
107+
* will be used. If set, it must be the name of a backend metadata
108+
* file.
109+
*
110+
* This can also be set using CFLAGS.
111+
*
112+
*****************************************************************************/
113+
#if !defined(MLKEM_USE_NATIVE_BACKEND_FIPS202)
114+
/* #define MLKEM_USE_NATIVE_BACKEND_FIPS202 */
115+
#endif
76116

77117
/******************************************************************************
78-
* Name: MLKEM_NATIVE_FIPS202_BACKEND
118+
* Name: MLKEM_NATIVE_FIPS202_BACKEND_FILE
79119
*
80120
* Description: The FIPS-202 backend to use.
81121
*
82-
* This must be the filename of an FIPS-202 backend.
122+
* If MLKEM_USE_NATIVE_BACKEND_FIPS202 is set, this option must
123+
* either be undefined or the filename of a FIPS202 backend.
124+
* If unset, the default backend will be used.
83125
*
84126
* This can be set using CFLAGS.
85127
*
86128
*****************************************************************************/
87-
#if defined(MLKEM_USE_NATIVE) && !defined(MLKEM_NATIVE_FIPS202_BACKEND)
88-
#define MLKEM_NATIVE_FIPS202_BACKEND "fips202/native/default.h"
89-
#endif /* MLKEM_NATIVE_FIPS202_BACKEND */
129+
#if defined(MLKEM_USE_NATIVE_BACKEND_FIPS202) && \
130+
!defined(MLKEM_NATIVE_FIPS202_BACKEND_FILE)
131+
#define MLKEM_NATIVE_FIPS202_BACKEND_FILE "fips202/native/default.h"
132+
#endif
90133

91134
#endif /* MLkEM_NATIVE_CONFIG_H */

‎examples/monolithic_build/mlkem_native_monobuild.c

+4-4
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,8 @@
117117
#endif
118118

119119
/* mlkem/config.h */
120-
#if defined(MLKEM_NATIVE_ARITH_BACKEND)
121-
#undef MLKEM_NATIVE_ARITH_BACKEND
120+
#if defined(MLKEM_NATIVE_ARITH_BACKEND_FILE)
121+
#undef MLKEM_NATIVE_ARITH_BACKEND_FILE
122122
#endif
123123

124124
/* mlkem/config.h */
@@ -127,8 +127,8 @@
127127
#endif
128128

129129
/* mlkem/config.h */
130-
#if defined(MLKEM_NATIVE_FIPS202_BACKEND)
131-
#undef MLKEM_NATIVE_FIPS202_BACKEND
130+
#if defined(MLKEM_NATIVE_FIPS202_BACKEND_FILE)
131+
#undef MLKEM_NATIVE_FIPS202_BACKEND_FILE
132132
#endif
133133

134134
/* mlkem/indcpa.c */

‎examples/monolithic_build_multilevel/config_1024.h

+43-17
Original file line numberDiff line numberDiff line change
@@ -50,43 +50,69 @@
5050
#define MLKEM_NAMESPACE_PREFIX_ADD_LEVEL
5151

5252
/******************************************************************************
53-
* Name: MLKEM_USE_NATIVE
53+
* Name: MLKEM_USE_NATIVE_BACKEND_ARITH
5454
*
55-
* Description: Determines whether a native backend should
56-
* be used, if available.
55+
* Description: Determines whether an native arithmetic backend should be used.
56+
*
57+
* The arithmetic backend covers performance critical functions
58+
* such as the number-theoretic transform (NTT).
59+
*
60+
* If this option is unset, the C backend will be used.
61+
*
62+
* If this option is set, the arithmetic backend to be use is
63+
* determined by MLKEM_NATIVE_ARITH_BACKEND: If the latter is
64+
* unset, the default backend for your the target architecture
65+
* will be used. If set, it must be the name of a backend metadata
66+
* file.
5767
*
5868
* This can also be set using CFLAGS.
5969
*
6070
*****************************************************************************/
61-
/* #define MLKEM_USE_NATIVE */
71+
#if !defined(MLKEM_USE_NATIVE_BACKEND_ARITH)
72+
/* #define MLKEM_USE_NATIVE_BACKEND_ARITH */
73+
#endif
6274

6375
/******************************************************************************
64-
* Name: MLKEM_NATIVE_ARITH_BACKEND
76+
* Name: MLKEM_NATIVE_ARITH_BACKEND_FILE
6577
*
6678
* Description: The arithmetic backend to use.
6779
*
68-
* This must be the filename of an arithmetic backend.
69-
* See the existing backends for examples.
80+
* If MLKEM_USE_NATIVE_BACKEND_ARITH is unset, this option
81+
* is ignored.
82+
*
83+
* If MLKEM_USE_NATIVE_BACKEND_ARITH is set, this option must
84+
* either be undefined or the filename of an arithmetic backend.
85+
* If unset, the default backend will be used.
7086
*
7187
* This can be set using CFLAGS.
7288
*
7389
*****************************************************************************/
74-
#if defined(MLKEM_USE_NATIVE) && !defined(MLKEM_NATIVE_ARITH_BACKEND)
75-
#define MLKEM_NATIVE_ARITH_BACKEND "native/default.h"
76-
#endif /* MLKEM_NATIVE_ARITH_BACKEND */
90+
#if defined(MLKEM_USE_NATIVE_BACKEND_ARITH) && \
91+
!defined(MLKEM_NATIVE_ARITH_BACKEND_FILE)
92+
#define MLKEM_NATIVE_ARITH_BACKEND_FILE "native/default.h"
93+
#endif
7794

7895
/******************************************************************************
79-
* Name: MLKEM_NATIVE_FIPS202_BACKEND
96+
* Name: MLKEM_USE_NATIVE_BACKEND_FIPS202
8097
*
81-
* Description: The FIPS-202 backend to use.
98+
* Description: Determines whether an native FIPS202 backend should be used.
8299
*
83-
* This must be the filename of an FIPS-202 backend.
100+
* The FIPS202 backend covers 1x/2x/4x-fold Keccak-f1600, which is
101+
* the performance bottleneck of SHA3 and SHAKE.
84102
*
85-
* This can be set using CFLAGS.
103+
* If this option is unset, the C backend will be used.
104+
*
105+
* If this option is set, the FIPS202 backend to be use is
106+
* determined by MLKEM_NATIVE_FIPS202_BACKEND: If the latter is
107+
* unset, the default backend for your the target architecture
108+
* will be used. If set, it must be the name of a backend metadata
109+
* file.
110+
*
111+
* This can also be set using CFLAGS.
86112
*
87113
*****************************************************************************/
88-
#if defined(MLKEM_USE_NATIVE) && !defined(MLKEM_NATIVE_FIPS202_BACKEND)
89-
#define MLKEM_NATIVE_FIPS202_BACKEND "fips202/native/default.h"
90-
#endif /* MLKEM_NATIVE_FIPS202_BACKEND */
114+
#if !defined(MLKEM_USE_NATIVE_BACKEND_FIPS202)
115+
/* #define MLKEM_USE_NATIVE_BACKEND_FIPS202 */
116+
#endif
91117

92118
#endif /* MLkEM_NATIVE_CONFIG_H */

0 commit comments

Comments
 (0)