Skip to content

Commit 41a3ad0

Browse files
mkannwischerhanno-becker
mkannwischer
authored and
hanno-becker
committed
Derive mldsa_native.h configuration from config file
Previously, mldsa_native.h required users to set MLD_CONFIG_API_* macros before including it, separate from the MLD_CONFIG_* macros used for the build configuration. This distinction between internal and external configuration it confusing. Now, mldsa_native.h derives all API settings from the same build configuration file used internally. - The legacy configuration via MLD_CONFIG_API_XXX still works for backwards compatibility, but will be removed in v2. - New Config Options: * MLD_CONFIG_MULTILEVEL_BUILD: Explicit flag for multi-level builds This makes it simpler to get headers for multi-level builds. In the common case, the configs used in a multi-level build are identical except for the setting of MLD_CONFIG_PARAMETER_SET and MLD_CONFIG_MULTILEVEL_{NO,WITH}_SHARED. However, the latter only affect the build, not the API. With MLD_CONFIG_MULTILEVEL_BUILD exposed as a separate option, mldsa_native.h can use it to determine whether to suffix the namespace prefix with the parameter set (44/65/87) or not, so no adaptation of MLD_CONFIG_MULTILEVEL_{NO,WITH}_SHARED is needed. Instead, a multi-level header simply becomes: ```c #define MLD_CONFIG_PARAMETER_SET 44 #include "mldsa_native.h" #undef MLD_CONFIG_PARAMETER_SET #define MLD_CONFIG_PARAMETER_SET 65 #include "mldsa_native.h" #undef MLD_CONFIG_PARAMETER_SET #define MLD_CONFIG_PARAMETER_SET 87 #include "mldsa_native.h" #undef MLD_CONFIG_PARAMETER_SET ``` For backwards compatibility, MLD_CONFIG_MULTILEVEL_BUILD is not used in the build, which continues to detect multilevel builds via the existing options MLD_CONFIG_MULTILEVEL_{WITH,NO}_SHARED. * MLD_CONFIG_NO_SUPERCOP: We had this before in mldsa_native.h as MLD_CONFIG_API_NO_SUPERCOP; it's now in the config and documented. * MLD_CONFIG_CONSTANTS_ONLY: We had this before in mldsa_native.h as MLD_CONFIG_API_CONSTANTS_ONLY; it's now in the config and documented. - Build-Internal vs API Config Separation: Config file now guards build-only options with #if defined(MLD_BUILD_INTERNAL). Signed-off-by: Matthias J. Kannwischer <matthias@kannwischer.eu>
1 parent 2b90b3e commit 41a3ad0

28 files changed

+2294
-896
lines changed

‎examples/custom_backend/mldsa_native/custom_config.h‎

Lines changed: 99 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,11 @@
4747
* - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65
4848
* - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87
4949
*
50+
* If you want to support multiple parameter sets, build the
51+
* library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD.
52+
* See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while
53+
* minimizing code duplication.
54+
*
5055
* This can also be set using CFLAGS.
5156
*
5257
*****************************************************************************/
@@ -80,17 +85,104 @@
8085
*
8186
* Description: The prefix to use to namespace global symbols from mldsa/.
8287
*
83-
* In a multi-level build (that is, if either
84-
* - MLD_CONFIG_MULTILEVEL_WITH_SHARED, or
85-
* - MLD_CONFIG_MULTILEVEL_NO_SHARED,
86-
* are set, level-dependent symbols will additionally be prefixed
87-
* with the parameter set (44/65/87).
88+
* In a multi-level build, level-dependent symbols will
89+
* additionally be prefixed with the parameter set (44/65/87).
8890
*
8991
* This can also be set using CFLAGS.
9092
*
9193
*****************************************************************************/
9294
#define MLD_CONFIG_NAMESPACE_PREFIX CUSTOM_TINY_SHA3
9395

96+
/******************************************************************************
97+
* Name: MLD_CONFIG_MULTILEVEL_BUILD
98+
*
99+
* Description: Set this if the build is part of a multi-level build supporting
100+
* multiple parameter sets.
101+
*
102+
* If you need only a single parameter set, keep this unset.
103+
*
104+
* To build mldsa-native with support for all parameter sets,
105+
* build it three times -- once per parameter set -- and set the
106+
* option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of
107+
* them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others.
108+
* MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them.
109+
*
110+
* See examples/multilevel_build for an example.
111+
*
112+
* This can also be set using CFLAGS.
113+
*
114+
*****************************************************************************/
115+
/* #define MLD_CONFIG_MULTILEVEL_BUILD */
116+
117+
/******************************************************************************
118+
* Name: MLD_CONFIG_EXTERNAL_API_QUALIFIER
119+
*
120+
* Description: If set, this option provides an additional function
121+
* qualifier to be added to declarations of mldsa-native's
122+
* public API.
123+
*
124+
* The primary use case for this option are single-CU builds
125+
* where the public API exposed by mldsa-native is wrapped by
126+
* another API in the consuming application. In this case,
127+
* even mldsa-native's public API can be marked `static`.
128+
*
129+
*****************************************************************************/
130+
/* #define MLD_CONFIG_EXTERNAL_API_QUALIFIER */
131+
132+
/******************************************************************************
133+
* Name: MLD_CONFIG_NO_RANDOMIZED_API
134+
*
135+
* Description: If this option is set, mldsa-native will be built without the
136+
* randomized API functions (crypto_sign_keypair,
137+
* crypto_sign, crypto_sign_signature, and
138+
* crypto_sign_signature_extmu).
139+
* This allows users to build mldsa-native without providing a
140+
* randombytes() implementation if they only need the
141+
* internal deterministic API
142+
* (crypto_sign_keypair_internal, crypto_sign_signature_internal).
143+
*
144+
* NOTE: This option is incompatible with MLD_CONFIG_KEYGEN_PCT
145+
* as the current PCT implementation requires
146+
* crypto_sign_signature().
147+
*
148+
*****************************************************************************/
149+
/* #define MLD_CONFIG_NO_RANDOMIZED_API */
150+
151+
/******************************************************************************
152+
* Name: MLD_CONFIG_NO_SUPERCOP
153+
*
154+
* Description: By default, mldsa_native.h exposes the mldsa-native API in the
155+
* SUPERCOP naming convention (crypto_sign_xxx). If you don't need
156+
* this, set MLD_CONFIG_NO_SUPERCOP.
157+
*
158+
* NOTE: You must set this for a multi-level build as the SUPERCOP
159+
* naming does not disambiguate between the parameter sets.
160+
*
161+
*****************************************************************************/
162+
/* #define MLD_CONFIG_NO_SUPERCOP */
163+
164+
/******************************************************************************
165+
* Name: MLD_CONFIG_CONSTANTS_ONLY
166+
*
167+
* Description: If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.)
168+
* but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY.
169+
*
170+
* This only affects the public header mldsa_native.h, not
171+
* the implementation.
172+
*
173+
*****************************************************************************/
174+
/* #define MLD_CONFIG_CONSTANTS_ONLY */
175+
176+
/******************************************************************************
177+
*
178+
* Build-only configuration options
179+
*
180+
* The remaining configurations are build-options only.
181+
* They do not affect the API described in mldsa_native.h.
182+
*
183+
*****************************************************************************/
184+
185+
#if defined(MLD_BUILD_INTERNAL)
94186
/******************************************************************************
95187
* Name: MLD_CONFIG_MULTILEVEL_WITH_SHARED
96188
*
@@ -415,21 +507,6 @@
415507
*****************************************************************************/
416508
/* #define MLD_CONFIG_INTERNAL_API_QUALIFIER */
417509

418-
/******************************************************************************
419-
* Name: MLD_CONFIG_EXTERNAL_API_QUALIFIER
420-
*
421-
* Description: If set, this option provides an additional function
422-
* qualifier to be added to declarations of mldsa-native's
423-
* public API.
424-
*
425-
* The primary use case for this option are single-CU builds
426-
* where the public API exposed by mldsa-native is wrapped by
427-
* another API in the consuming application. In this case,
428-
* even mldsa-native's public API can be marked `static`.
429-
*
430-
*****************************************************************************/
431-
/* #define MLD_CONFIG_EXTERNAL_API_QUALIFIER */
432-
433510
/******************************************************************************
434511
* Name: MLD_CONFIG_CT_TESTING_ENABLED
435512
*
@@ -479,25 +556,6 @@
479556
*****************************************************************************/
480557
/* #define MLD_CONFIG_NO_ASM_VALUE_BARRIER */
481558

482-
/******************************************************************************
483-
* Name: MLD_CONFIG_NO_RANDOMIZED_API
484-
*
485-
* Description: If this option is set, mldsa-native will be built without the
486-
* randomized API functions (crypto_sign_keypair,
487-
* crypto_sign, crypto_sign_signature, and
488-
* crypto_sign_signature_extmu).
489-
* This allows users to build mldsa-native without providing a
490-
* randombytes() implementation if they only need the
491-
* internal deterministic API
492-
* (crypto_sign_keypair_internal, crypto_sign_signature_internal).
493-
*
494-
* NOTE: This option is incompatible with MLD_CONFIG_KEYGEN_PCT
495-
* as the current PCT implementation requires
496-
* crypto_sign_signature().
497-
*
498-
*****************************************************************************/
499-
/* #define MLD_CONFIG_NO_RANDOMIZED_API */
500-
501559
/******************************************************************************
502560
* Name: MLD_CONFIG_KEYGEN_PCT
503561
*
@@ -561,6 +619,8 @@
561619

562620
/************************* Config internals ********************************/
563621

622+
#endif /* MLD_BUILD_INTERNAL */
623+
564624
/* Default namespace
565625
*
566626
* Don't change this. If you need a different namespace, re-define

‎examples/monolithic_build/mldsa/config_44.h‎

Lines changed: 99 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,11 @@
4747
* - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65
4848
* - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87
4949
*
50+
* If you want to support multiple parameter sets, build the
51+
* library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD.
52+
* See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while
53+
* minimizing code duplication.
54+
*
5055
* This can also be set using CFLAGS.
5156
*
5257
*****************************************************************************/
@@ -76,17 +81,104 @@
7681
*
7782
* Description: The prefix to use to namespace global symbols from mldsa/.
7883
*
79-
* In a multi-level build (that is, if either
80-
* - MLD_CONFIG_MULTILEVEL_WITH_SHARED, or
81-
* - MLD_CONFIG_MULTILEVEL_NO_SHARED,
82-
* are set, level-dependent symbols will additionally be prefixed
83-
* with the parameter set (44/65/87).
84+
* In a multi-level build, level-dependent symbols will
85+
* additionally be prefixed with the parameter set (44/65/87).
8486
*
8587
* This can also be set using CFLAGS.
8688
*
8789
*****************************************************************************/
8890
#define MLD_CONFIG_NAMESPACE_PREFIX mldsa
8991

92+
/******************************************************************************
93+
* Name: MLD_CONFIG_MULTILEVEL_BUILD
94+
*
95+
* Description: Set this if the build is part of a multi-level build supporting
96+
* multiple parameter sets.
97+
*
98+
* If you need only a single parameter set, keep this unset.
99+
*
100+
* To build mldsa-native with support for all parameter sets,
101+
* build it three times -- once per parameter set -- and set the
102+
* option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of
103+
* them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others.
104+
* MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them.
105+
*
106+
* See examples/multilevel_build for an example.
107+
*
108+
* This can also be set using CFLAGS.
109+
*
110+
*****************************************************************************/
111+
/* #define MLD_CONFIG_MULTILEVEL_BUILD */
112+
113+
/******************************************************************************
114+
* Name: MLD_CONFIG_EXTERNAL_API_QUALIFIER
115+
*
116+
* Description: If set, this option provides an additional function
117+
* qualifier to be added to declarations of mldsa-native's
118+
* public API.
119+
*
120+
* The primary use case for this option are single-CU builds
121+
* where the public API exposed by mldsa-native is wrapped by
122+
* another API in the consuming application. In this case,
123+
* even mldsa-native's public API can be marked `static`.
124+
*
125+
*****************************************************************************/
126+
/* #define MLD_CONFIG_EXTERNAL_API_QUALIFIER */
127+
128+
/******************************************************************************
129+
* Name: MLD_CONFIG_NO_RANDOMIZED_API
130+
*
131+
* Description: If this option is set, mldsa-native will be built without the
132+
* randomized API functions (crypto_sign_keypair,
133+
* crypto_sign, crypto_sign_signature, and
134+
* crypto_sign_signature_extmu).
135+
* This allows users to build mldsa-native without providing a
136+
* randombytes() implementation if they only need the
137+
* internal deterministic API
138+
* (crypto_sign_keypair_internal, crypto_sign_signature_internal).
139+
*
140+
* NOTE: This option is incompatible with MLD_CONFIG_KEYGEN_PCT
141+
* as the current PCT implementation requires
142+
* crypto_sign_signature().
143+
*
144+
*****************************************************************************/
145+
/* #define MLD_CONFIG_NO_RANDOMIZED_API */
146+
147+
/******************************************************************************
148+
* Name: MLD_CONFIG_NO_SUPERCOP
149+
*
150+
* Description: By default, mldsa_native.h exposes the mldsa-native API in the
151+
* SUPERCOP naming convention (crypto_sign_xxx). If you don't need
152+
* this, set MLD_CONFIG_NO_SUPERCOP.
153+
*
154+
* NOTE: You must set this for a multi-level build as the SUPERCOP
155+
* naming does not disambiguate between the parameter sets.
156+
*
157+
*****************************************************************************/
158+
/* #define MLD_CONFIG_NO_SUPERCOP */
159+
160+
/******************************************************************************
161+
* Name: MLD_CONFIG_CONSTANTS_ONLY
162+
*
163+
* Description: If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.)
164+
* but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY.
165+
*
166+
* This only affects the public header mldsa_native.h, not
167+
* the implementation.
168+
*
169+
*****************************************************************************/
170+
/* #define MLD_CONFIG_CONSTANTS_ONLY */
171+
172+
/******************************************************************************
173+
*
174+
* Build-only configuration options
175+
*
176+
* The remaining configurations are build-options only.
177+
* They do not affect the API described in mldsa_native.h.
178+
*
179+
*****************************************************************************/
180+
181+
#if defined(MLD_BUILD_INTERNAL)
90182
/******************************************************************************
91183
* Name: MLD_CONFIG_MULTILEVEL_WITH_SHARED
92184
*
@@ -417,21 +509,6 @@
417509
*****************************************************************************/
418510
#define MLD_CONFIG_INTERNAL_API_QUALIFIER static
419511

420-
/******************************************************************************
421-
* Name: MLD_CONFIG_EXTERNAL_API_QUALIFIER
422-
*
423-
* Description: If set, this option provides an additional function
424-
* qualifier to be added to declarations of mldsa-native's
425-
* public API.
426-
*
427-
* The primary use case for this option are single-CU builds
428-
* where the public API exposed by mldsa-native is wrapped by
429-
* another API in the consuming application. In this case,
430-
* even mldsa-native's public API can be marked `static`.
431-
*
432-
*****************************************************************************/
433-
/* #define MLD_CONFIG_EXTERNAL_API_QUALIFIER */
434-
435512
/******************************************************************************
436513
* Name: MLD_CONFIG_CT_TESTING_ENABLED
437514
*
@@ -481,25 +558,6 @@
481558
*****************************************************************************/
482559
/* #define MLD_CONFIG_NO_ASM_VALUE_BARRIER */
483560

484-
/******************************************************************************
485-
* Name: MLD_CONFIG_NO_RANDOMIZED_API
486-
*
487-
* Description: If this option is set, mldsa-native will be built without the
488-
* randomized API functions (crypto_sign_keypair,
489-
* crypto_sign, crypto_sign_signature, and
490-
* crypto_sign_signature_extmu).
491-
* This allows users to build mldsa-native without providing a
492-
* randombytes() implementation if they only need the
493-
* internal deterministic API
494-
* (crypto_sign_keypair_internal, crypto_sign_signature_internal).
495-
*
496-
* NOTE: This option is incompatible with MLD_CONFIG_KEYGEN_PCT
497-
* as the current PCT implementation requires
498-
* crypto_sign_signature().
499-
*
500-
*****************************************************************************/
501-
/* #define MLD_CONFIG_NO_RANDOMIZED_API */
502-
503561
/******************************************************************************
504562
* Name: MLD_CONFIG_KEYGEN_PCT
505563
*
@@ -563,6 +621,8 @@
563621

564622
/************************* Config internals ********************************/
565623

624+
#endif /* MLD_BUILD_INTERNAL */
625+
566626
/* Default namespace
567627
*
568628
* Don't change this. If you need a different namespace, re-define

0 commit comments

Comments
 (0)