diff --git a/.github/actions/config-variations/action.yml b/.github/actions/config-variations/action.yml index 2fa196c310..6ebe76360a 100644 --- a/.github/actions/config-variations/action.yml +++ b/.github/actions/config-variations/action.yml @@ -8,7 +8,7 @@ inputs: description: 'GitHub token' required: true tests: - description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled, pct-enabled-broken, signing-bound-exhausted, reduce-ram, reduce-ram-pct, custom-alloc-heap, custom-zeroize, native-cap-ON, native-cap-OFF, native-cap-ID_AA64PFR1_EL1, native-cap-CPUID_AVX2, no-asm, serial-fips202, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib, nblocks-1, nblocks-4, nblocks-6, keygen-only, sign-only, verify-only, keygen-sign, keygen-verify, sign-verify, no-randomized' + description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled, pct-enabled-broken, signing-bound-exhausted, reduce-ram, reduce-ram-pct, custom-alloc-heap, custom-zeroize, native-cap-ON, native-cap-OFF, native-cap-ID_AA64PFR1_EL1, native-cap-CPUID_AVX2, no-asm, serial-fips202, custom-randombytes, custom-memcpy, custom-memset, custom-stdlib, custom-align, nblocks-1, nblocks-4, nblocks-6, keygen-only, sign-only, verify-only, keygen-sign, keygen-verify, sign-verify, no-randomized' required: false default: 'all' opt: @@ -291,6 +291,22 @@ runs: alloc: false # Requires custom config sign_hook: false # Requires custom config rng_fail: true + - name: "Custom alignment attribute" + if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-align') }} + uses: ./.github/actions/multi-functest + with: + gh_token: ${{ inputs.gh_token }} + compile_mode: native + cflags: "${{ inputs.extra_cflags }} -std=c11 -D_GNU_SOURCE -Itest -DMLD_CONFIG_FILE=\\\\\\\"configs/custom_align_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + ldflags: "-fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all" + func: true + kat: true + acvp: true + opt: ${{ inputs.opt }} + examples: false # Some examples use a custom config themselves + alloc: false # Requires custom config + sign_hook: false # Requires custom config + rng_fail: true - name: "MLD_POLY_UNIFORM_NBLOCKS=1" if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'nblocks-1') }} uses: ./.github/actions/multi-functest diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 25d301b869..3f5ee068e9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -502,7 +502,7 @@ jobs: - name: reduce-ram ids: reduce-ram reduce-ram-pct - name: custom-hooks - ids: custom-alloc-heap custom-zeroize custom-randombytes custom-memcpy custom-memset custom-stdlib + ids: custom-alloc-heap custom-zeroize custom-randombytes custom-memcpy custom-memset custom-stdlib custom-align - name: native-cap ids: native-cap-ON native-cap-OFF native-cap-ID_AA64PFR1_EL1 native-cap-CPUID_AVX2 - name: asm-fips202 diff --git a/BIBLIOGRAPHY.md b/BIBLIOGRAPHY.md index d69700bec7..852746830e 100644 --- a/BIBLIOGRAPHY.md +++ b/BIBLIOGRAPHY.md @@ -90,6 +90,7 @@ source code and documentation. - [mldsa/src/sign.c](mldsa/src/sign.c) - [proofs/cbmc/mldsa_native_config_cbmc.h](proofs/cbmc/mldsa_native_config_cbmc.h) - [test/configs/break_pct_config.h](test/configs/break_pct_config.h) + - [test/configs/custom_align_config.h](test/configs/custom_align_config.h) - [test/configs/custom_heap_alloc_config.h](test/configs/custom_heap_alloc_config.h) - [test/configs/custom_memcpy_config.h](test/configs/custom_memcpy_config.h) - [test/configs/custom_memset_config.h](test/configs/custom_memset_config.h) @@ -155,6 +156,7 @@ source code and documentation. - [mldsa/src/sign.h](mldsa/src/sign.h) - [proofs/cbmc/mldsa_native_config_cbmc.h](proofs/cbmc/mldsa_native_config_cbmc.h) - [test/configs/break_pct_config.h](test/configs/break_pct_config.h) + - [test/configs/custom_align_config.h](test/configs/custom_align_config.h) - [test/configs/custom_heap_alloc_config.h](test/configs/custom_heap_alloc_config.h) - [test/configs/custom_memcpy_config.h](test/configs/custom_memcpy_config.h) - [test/configs/custom_memset_config.h](test/configs/custom_memset_config.h) @@ -195,6 +197,7 @@ source code and documentation. - [mldsa/src/sign.c](mldsa/src/sign.c) - [proofs/cbmc/mldsa_native_config_cbmc.h](proofs/cbmc/mldsa_native_config_cbmc.h) - [test/configs/break_pct_config.h](test/configs/break_pct_config.h) + - [test/configs/custom_align_config.h](test/configs/custom_align_config.h) - [test/configs/custom_heap_alloc_config.h](test/configs/custom_heap_alloc_config.h) - [test/configs/custom_memcpy_config.h](test/configs/custom_memcpy_config.h) - [test/configs/custom_memset_config.h](test/configs/custom_memset_config.h) diff --git a/dev/aarch64_clean/meta.h b/dev/aarch64_clean/meta.h index 5b4585c02d..2ebc2ca86f 100644 --- a/dev/aarch64_clean/meta.h +++ b/dev/aarch64_clean/meta.h @@ -7,6 +7,12 @@ #ifndef MLD_NATIVE_AARCH64_META_H #define MLD_NATIVE_AARCH64_META_H +/* This backend loads and stores polynomials through Q registers, which fault + * on operands that are not 16-byte aligned if alignment checking is on. */ +#if MLD_DEFAULT_ALIGN < 16 +#error Bad configuration: The AArch64 backend requires MLD_CONFIG_ALIGN to be at least 16 +#endif + /* Set of primitives that this backend replaces */ #define MLD_USE_NATIVE_NTT #define MLD_USE_NATIVE_INTT diff --git a/dev/aarch64_opt/meta.h b/dev/aarch64_opt/meta.h index 5b4585c02d..2ebc2ca86f 100644 --- a/dev/aarch64_opt/meta.h +++ b/dev/aarch64_opt/meta.h @@ -7,6 +7,12 @@ #ifndef MLD_NATIVE_AARCH64_META_H #define MLD_NATIVE_AARCH64_META_H +/* This backend loads and stores polynomials through Q registers, which fault + * on operands that are not 16-byte aligned if alignment checking is on. */ +#if MLD_DEFAULT_ALIGN < 16 +#error Bad configuration: The AArch64 backend requires MLD_CONFIG_ALIGN to be at least 16 +#endif + /* Set of primitives that this backend replaces */ #define MLD_USE_NATIVE_NTT #define MLD_USE_NATIVE_INTT diff --git a/dev/x86_64/meta.h b/dev/x86_64/meta.h index ead52f0aaf..5ef0cb17bd 100644 --- a/dev/x86_64/meta.h +++ b/dev/x86_64/meta.h @@ -7,6 +7,12 @@ #ifndef MLD_NATIVE_X86_64_META_H #define MLD_NATIVE_X86_64_META_H +/* This backend loads and stores polynomials with vmovdqa, which faults on + * operands that are not 32-byte aligned. */ +#if MLD_DEFAULT_ALIGN < 32 +#error Bad configuration: The x86_64 backend requires MLD_CONFIG_ALIGN to be at least 32 +#endif + /* Identifier for this backend so that source and assembly files * in the build can be appropriately guarded. */ #define MLD_ARITH_BACKEND_X86_64_DEFAULT diff --git a/examples/basic_deterministic/mldsa_native/mldsa_native_config.h b/examples/basic_deterministic/mldsa_native/mldsa_native_config.h index c8ba9d2835..3ddc769ff9 100644 --- a/examples/basic_deterministic/mldsa_native/mldsa_native_config.h +++ b/examples/basic_deterministic/mldsa_native/mldsa_native_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -757,6 +798,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/basic_lowram/mldsa_native/mldsa_native_config.h b/examples/basic_lowram/mldsa_native/mldsa_native_config.h index 74ecd5c654..53df099bd6 100644 --- a/examples/basic_lowram/mldsa_native/mldsa_native_config.h +++ b/examples/basic_lowram/mldsa_native/mldsa_native_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -756,6 +797,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h b/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h index 5dfc7a44ba..2b2598fa70 100644 --- a/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h +++ b/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h @@ -381,6 +381,47 @@ */ #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "../custom_fips202/fips202x4.h" +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -757,6 +798,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h b/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h index 58823d7819..cef7f22ea4 100644 --- a/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h +++ b/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h @@ -382,6 +382,47 @@ */ #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "../custom_fips202/fips202x4.h" +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -485,7 +526,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -758,6 +799,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/custom_backend/mldsa_native/mldsa_native_config.h b/examples/custom_backend/mldsa_native/mldsa_native_config.h index 30143bc27e..98f6f348ba 100644 --- a/examples/custom_backend/mldsa_native/mldsa_native_config.h +++ b/examples/custom_backend/mldsa_native/mldsa_native_config.h @@ -377,6 +377,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -480,7 +521,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -753,6 +794,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/monolithic_build/mldsa_native/mldsa_native_config.h b/examples/monolithic_build/mldsa_native/mldsa_native_config.h index 37e10ee576..e69a6cf11f 100644 --- a/examples/monolithic_build/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build/mldsa_native/mldsa_native_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -756,6 +797,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h b/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h index 6cfbe0a651..6fd1e9b658 100644 --- a/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -757,6 +798,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h b/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h index 75a39a573c..aeb057b46a 100644 --- a/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -490,7 +531,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -763,6 +804,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h b/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h index 407768cfc9..2292db1b8f 100644 --- a/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -756,6 +797,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/multilevel_build/mldsa_native/mldsa_native_config.h b/examples/multilevel_build/mldsa_native/mldsa_native_config.h index 6b37f22bbb..5f1fe4c248 100644 --- a/examples/multilevel_build/mldsa_native/mldsa_native_config.h +++ b/examples/multilevel_build/mldsa_native/mldsa_native_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -756,6 +797,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h b/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h index 17c704448a..b917587b9c 100644 --- a/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h +++ b/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h @@ -378,6 +378,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -481,7 +522,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -754,6 +795,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/examples/restartable_sign/mldsa_native/mldsa_native_config.h b/examples/restartable_sign/mldsa_native/mldsa_native_config.h index fc7237527d..5ed6b1b41d 100644 --- a/examples/restartable_sign/mldsa_native/mldsa_native_config.h +++ b/examples/restartable_sign/mldsa_native/mldsa_native_config.h @@ -382,6 +382,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -485,7 +526,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -758,6 +799,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/mldsa/mldsa_native.h b/mldsa/mldsa_native.h index a38a2c4154..4ebae4c845 100644 --- a/mldsa/mldsa_native.h +++ b/mldsa/mldsa_native.h @@ -885,7 +885,11 @@ int MLD_API_NAMESPACE(pk_from_sk)( * * These constants may be used to implement custom allocations using a * fixed-sized buffer and a simple allocator (e.g., bump allocator). + * + * They are measured for the default alignment of 32 bytes and are therefore + * not defined when MLD_CONFIG_ALIGN customizes the alignment. */ +#if !defined(MLD_CONFIG_ALIGN) || MLD_CONFIG_ALIGN == 32 /* check-magic: off */ #if !defined(MLD_CONFIG_REDUCE_RAM) #define MLD_TOTAL_ALLOC_44_KEYPAIR_NO_PCT 26912 @@ -952,5 +956,6 @@ int MLD_API_NAMESPACE(pk_from_sk)( #define MLD_TOTAL_ALLOC_87 \ MLD_MAX4_(MLD_TOTAL_ALLOC_87_KEYPAIR, MLD_TOTAL_ALLOC_87_PK_FROM_SK, \ MLD_TOTAL_ALLOC_87_SIGN, MLD_TOTAL_ALLOC_87_VERIFY) +#endif /* !MLD_CONFIG_ALIGN || MLD_CONFIG_ALIGN == 32 */ #endif /* !MLD_H */ diff --git a/mldsa/mldsa_native_config.h b/mldsa/mldsa_native_config.h index 43803dee5a..70d807bc78 100644 --- a/mldsa/mldsa_native_config.h +++ b/mldsa/mldsa_native_config.h @@ -365,6 +365,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -468,7 +509,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -741,6 +782,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/mldsa/src/native/aarch64/meta.h b/mldsa/src/native/aarch64/meta.h index 5b4585c02d..2ebc2ca86f 100644 --- a/mldsa/src/native/aarch64/meta.h +++ b/mldsa/src/native/aarch64/meta.h @@ -7,6 +7,12 @@ #ifndef MLD_NATIVE_AARCH64_META_H #define MLD_NATIVE_AARCH64_META_H +/* This backend loads and stores polynomials through Q registers, which fault + * on operands that are not 16-byte aligned if alignment checking is on. */ +#if MLD_DEFAULT_ALIGN < 16 +#error Bad configuration: The AArch64 backend requires MLD_CONFIG_ALIGN to be at least 16 +#endif + /* Set of primitives that this backend replaces */ #define MLD_USE_NATIVE_NTT #define MLD_USE_NATIVE_INTT diff --git a/mldsa/src/native/x86_64/meta.h b/mldsa/src/native/x86_64/meta.h index ead52f0aaf..5ef0cb17bd 100644 --- a/mldsa/src/native/x86_64/meta.h +++ b/mldsa/src/native/x86_64/meta.h @@ -7,6 +7,12 @@ #ifndef MLD_NATIVE_X86_64_META_H #define MLD_NATIVE_X86_64_META_H +/* This backend loads and stores polynomials with vmovdqa, which faults on + * operands that are not 32-byte aligned. */ +#if MLD_DEFAULT_ALIGN < 32 +#error Bad configuration: The x86_64 backend requires MLD_CONFIG_ALIGN to be at least 32 +#endif + /* Identifier for this backend so that source and assembly files * in the build can be appropriately guarded. */ #define MLD_ARITH_BACKEND_X86_64_DEFAULT diff --git a/mldsa/src/sys.h b/mldsa/src/sys.h index 7bff445443..8bcf3f577b 100644 --- a/mldsa/src/sys.h +++ b/mldsa/src/sys.h @@ -205,10 +205,29 @@ #define MLD_RESTRICT restrict #endif /* restrict */ +/* + * MLD_DEFAULT_ALIGN: Alignment, in bytes, of large buffers and structures. + * Set through MLD_CONFIG_ALIGN. + */ +#if defined(MLD_CONFIG_ALIGN) +#define MLD_DEFAULT_ALIGN MLD_CONFIG_ALIGN +#else #define MLD_DEFAULT_ALIGN 32 +#endif + #define MLD_ALIGN_UP(N) \ ((((N) + (MLD_DEFAULT_ALIGN - 1)) / MLD_DEFAULT_ALIGN) * MLD_DEFAULT_ALIGN) -#if defined(__GNUC__) + +/* + * MLD_ALIGN: Declarator prefix aligning to MLD_DEFAULT_ALIGN bytes. + * - MLD_CONFIG_ALIGN_ATTRIBUTE, if set + * - GCC/Clang: __attribute__((aligned(N))) + * - MSVC: __declspec(align(N)) + * - Other: empty + */ +#if defined(MLD_CONFIG_ALIGN_ATTRIBUTE) +#define MLD_ALIGN MLD_CONFIG_ALIGN_ATTRIBUTE +#elif defined(__GNUC__) #define MLD_ALIGN __attribute__((aligned(MLD_DEFAULT_ALIGN))) #elif defined(_MSC_VER) #define MLD_ALIGN __declspec(align(MLD_DEFAULT_ALIGN)) diff --git a/proofs/cbmc/mldsa_native_config_cbmc.h b/proofs/cbmc/mldsa_native_config_cbmc.h index dbb0035d92..85f84821a8 100644 --- a/proofs/cbmc/mldsa_native_config_cbmc.h +++ b/proofs/cbmc/mldsa_native_config_cbmc.h @@ -383,6 +383,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -494,7 +535,7 @@ __contract__( */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -765,6 +806,7 @@ __contract__( /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/break_pct_config.h b/test/configs/break_pct_config.h index 7f7214b901..7abdb6102e 100644 --- a/test/configs/break_pct_config.h +++ b/test/configs/break_pct_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -761,6 +802,7 @@ static MLD_INLINE int mld_break_pct(void) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/configs.yml b/test/configs/configs.yml index 1bcfbd88c1..78524e384d 100644 --- a/test/configs/configs.yml +++ b/test/configs/configs.yml @@ -146,6 +146,13 @@ configs: } #endif + - path: test/configs/custom_align_config.h + description: "Test configuration with a non-default alignment" + defines: + MLD_CONFIG_ALIGN: + content: | + #define MLD_CONFIG_ALIGN 64 + - path: test/configs/break_pct_config.h description: "Test configuration for PCT breakage testing" defines: diff --git a/test/configs/custom_align_config.h b/test/configs/custom_align_config.h new file mode 100644 index 0000000000..80d8d17a5b --- /dev/null +++ b/test/configs/custom_align_config.h @@ -0,0 +1,913 @@ +/* + * Copyright (c) The mldsa-native project authors + * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + */ + +/* References + * ========== + * + * - [FIPS140_3_IG] + * Implementation Guidance for FIPS 140-3 and the Cryptographic Module + * Validation Program + * National Institute of Standards and Technology + * https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-ig-announcements + * + * - [FIPS204] + * FIPS 204 Module-Lattice-Based Digital Signature Standard + * National Institute of Standards and Technology + * https://csrc.nist.gov/pubs/fips/204/final + * + * - [FIPS204_UPDATES] + * FIPS 204 Potential Updates (Errata) + * National Institute of Standards and Technology + * https://csrc.nist.gov/files/pubs/fips/204/final/docs/fips-204-potential-updates.xlsx + */ + +/* + * WARNING: This file is auto-generated from scripts/autogen + * in the mldsa-native repository. + * Do not modify it directly. + */ + +/* + * Test configuration: Test configuration with a non-default alignment + * + * This configuration differs from the default mldsa/mldsa_native_config.h in + * the following places: + * - MLD_CONFIG_ALIGN + */ + + +#ifndef MLD_CONFIG_H +#define MLD_CONFIG_H + +/** + * MLD_CONFIG_PARAMETER_SET + * + * Specifies the parameter set for ML-DSA + * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * + * If you want to support multiple parameter sets, build the + * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. + * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * minimizing code duplication. + * + * This can also be set using CFLAGS. + */ +#ifndef MLD_CONFIG_PARAMETER_SET +#define MLD_CONFIG_PARAMETER_SET \ + 44 /* Change this for different security strengths */ +#endif + +/** + * MLD_CONFIG_FILE + * + * If defined, this is a header that will be included instead + * of the default configuration file mldsa/mldsa_native_config.h. + * + * When you need to build mldsa-native in multiple configurations, + * using varying MLD_CONFIG_FILE can be more convenient + * than configuring everything through CFLAGS. + * + * To use, MLD_CONFIG_FILE _must_ be defined prior + * to the inclusion of any mldsa-native headers. For example, + * it can be set by passing `-DMLD_CONFIG_FILE="..."` + * on the command line. + */ +/* #define MLD_CONFIG_FILE "mldsa_native_config.h" */ + +/** + * MLD_CONFIG_NAMESPACE_PREFIX + * + * The prefix to use to namespace global symbols from mldsa/. + * + * In a multi-level build, level-dependent symbols will + * additionally be prefixed with the parameter set (44/65/87). + * + * This can also be set using CFLAGS. + */ +#if !defined(MLD_CONFIG_NAMESPACE_PREFIX) +#define MLD_CONFIG_NAMESPACE_PREFIX MLD_DEFAULT_NAMESPACE_PREFIX +#endif + +/** + * MLD_CONFIG_MULTILEVEL_BUILD + * + * Set this if the build is part of a multi-level build supporting + * multiple parameter sets. + * + * If you need only a single parameter set, keep this unset. + * + * To build mldsa-native with support for all parameter sets, + * build it three times -- once per parameter set -- and set the + * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + */ +/* #define MLD_CONFIG_MULTILEVEL_BUILD */ + +/** + * MLD_CONFIG_EXTERNAL_API_QUALIFIER + * + * If set, this option provides an additional function + * qualifier to be added to declarations of mldsa-native's + * public API. + * + * The primary use case for this option are single-CU builds + * where the public API exposed by mldsa-native is wrapped by + * another API in the consuming application. In this case, + * even mldsa-native's public API can be marked `static`. + */ +/* #define MLD_CONFIG_EXTERNAL_API_QUALIFIER */ + +/** + * MLD_CONFIG_NO_KEYPAIR_API + * + * By default, mldsa-native includes support for generating key + * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * to exclude keypair, keypair_internal, + * pk_from_sk, and all internal APIs only needed by + * those functions. + */ +/* #define MLD_CONFIG_NO_KEYPAIR_API */ + +/** + * MLD_CONFIG_NO_SIGN_API + * + * By default, mldsa-native includes support for creating + * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * to exclude signature, + * signature_extmu, signature_internal, + * signature_pre_hash_internal, + * signature_pre_hash_shake256, and all internal APIs + * only needed by those functions. + */ +/* #define MLD_CONFIG_NO_SIGN_API */ + +/** + * MLD_CONFIG_NO_VERIFY_API + * + * By default, mldsa-native includes support for verifying + * signatures. If you don't need this, set + * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * verify_extmu, verify_internal, + * verify_pre_hash_internal, + * verify_pre_hash_shake256, and all internal APIs + * only needed by those functions. + */ +/* #define MLD_CONFIG_NO_VERIFY_API */ + +/** + * MLD_CONFIG_CORE_API_ONLY + * + * Set this to remove all public APIs except + * keypair_internal, signature_internal, + * and verify_internal. + */ +/* #define MLD_CONFIG_CORE_API_ONLY */ + +/** + * MLD_CONFIG_NO_RANDOMIZED_API + * + * If this option is set, mldsa-native will be built without the + * randomized API functions (keypair, + * signature, and signature_extmu). + * This allows users to build mldsa-native without providing a + * randombytes() implementation if they only need the + * internal deterministic API + * (keypair_internal, signature_internal). + * + * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires + * signature(). + */ +/* #define MLD_CONFIG_NO_RANDOMIZED_API */ + +/** + * MLD_CONFIG_CONSTANTS_ONLY + * + * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * + * This only affects the public header mldsa_native.h, not + * the implementation. + */ +/* #define MLD_CONFIG_CONSTANTS_ONLY */ +/****************************************************************************** + * + * Build-only configuration options + * + * The remaining configurations are build-options only. + * They do not affect the API described in mldsa_native.h. + * + *****************************************************************************/ +#if defined(MLD_BUILD_INTERNAL) + +/** + * MLD_CONFIG_MULTILEVEL_WITH_SHARED + * + * This is for multi-level builds of mldsa-native only. If you + * need only a single parameter set, keep this unset. + * + * If this is set, all MLD_CONFIG_PARAMETER_SET-independent + * code will be included in the build, including code needed only + * for other parameter sets. + * + * Example: mld_polyw1_pack_88 is only needed for + * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * + * To build mldsa-native with support for all parameter sets, + * build it three times -- once per parameter set -- and set the + * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + */ +/* #define MLD_CONFIG_MULTILEVEL_WITH_SHARED */ + +/** + * MLD_CONFIG_MULTILEVEL_NO_SHARED + * + * This is for multi-level builds of mldsa-native only. If you + * need only a single parameter set, keep this unset. + * + * If this is set, no MLD_CONFIG_PARAMETER_SET-independent code + * will be included in the build. + * + * To build mldsa-native with support for all parameter sets, + * build it three times -- once per parameter set -- and set the + * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * + * See examples/multilevel_build for an example. + * + * This can also be set using CFLAGS. + */ +/* #define MLD_CONFIG_MULTILEVEL_NO_SHARED */ + +/** + * MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS + * + * This is only relevant for single compilation unit (SCU) + * builds of mldsa-native. In this case, it determines whether + * directives defined in parameter-set-independent headers should + * be #undef'ined or not at the end of the SCU file. This is + * needed in multilevel builds. + * + * See examples/multilevel_build_native for an example. + * + * This can also be set using CFLAGS. + */ +/* #define MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS */ + +/** + * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH + * + * Determines whether a native arithmetic backend should be used. + * + * The arithmetic backend covers performance-critical functions + * such as the number-theoretic transform (NTT). + * + * If this option is unset, the C backend will be used. + * + * If this option is set, the arithmetic backend to be used is + * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * unset, the default backend for your target architecture + * will be used. If set, it must be the name of a backend metadata + * file. + * + * This can also be set using CFLAGS. + */ +#if !defined(MLD_CONFIG_USE_NATIVE_BACKEND_ARITH) +/* #define MLD_CONFIG_USE_NATIVE_BACKEND_ARITH */ +#endif + +/** + * MLD_CONFIG_ARITH_BACKEND_FILE + * + * The arithmetic backend to use. + * + * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * is ignored. + * + * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * either be undefined or the filename of an arithmetic backend. + * If unset, the default backend will be used. + * + * This can be set using CFLAGS. + */ +#if defined(MLD_CONFIG_USE_NATIVE_BACKEND_ARITH) && \ + !defined(MLD_CONFIG_ARITH_BACKEND_FILE) +#define MLD_CONFIG_ARITH_BACKEND_FILE "native/meta.h" +#endif + +/** + * MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 + * + * Determines whether a native FIPS202 backend should be used. + * + * The FIPS202 backend covers 1x/2x/4x-fold Keccak-f1600, which is + * the performance bottleneck of SHA3 and SHAKE. + * + * If this option is unset, the C backend will be used. + * + * If this option is set, the FIPS202 backend to be used is + * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * unset, the default backend for your target architecture + * will be used. If set, it must be the name of a backend metadata + * file. + * + * This can also be set using CFLAGS. + */ +#if !defined(MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202) +/* #define MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 */ +#endif + +/** + * MLD_CONFIG_FIPS202_BACKEND_FILE + * + * The FIPS-202 backend to use. + * + * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * must either be undefined or the filename of a FIPS202 backend. + * If unset, the default backend will be used. + * + * This can be set using CFLAGS. + */ +#if defined(MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202) && \ + !defined(MLD_CONFIG_FIPS202_BACKEND_FILE) +#define MLD_CONFIG_FIPS202_BACKEND_FILE "fips202/native/auto.h" +#endif + +/** + * MLD_CONFIG_FIPS202_CUSTOM_HEADER + * + * Custom header to use for FIPS-202 + * + * This should only be set if you intend to use a custom + * FIPS-202 implementation, different from the one shipped + * with mldsa-native. + * + * If set, it must be the name of a file serving as the + * replacement for mldsa/src/fips202/fips202.h, and exposing + * the same API (see FIPS202.md). + */ +/* #define MLD_CONFIG_FIPS202_CUSTOM_HEADER "SOME_FILE.h" */ + +/** + * MLD_CONFIG_FIPS202X4_CUSTOM_HEADER + * + * Custom header to use for FIPS-202-X4 + * + * This should only be set if you intend to use a custom + * FIPS-202 implementation, different from the one shipped + * with mldsa-native. + * + * If set, it must be the name of a file serving as the + * replacement for mldsa/src/fips202/fips202x4.h, and exposing + * the same API (see FIPS202.md). + */ +/* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ + +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +#define MLD_CONFIG_ALIGN 64 + + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + +/** + * MLD_CONFIG_CUSTOM_ZEROIZE + * + * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes + * intermediate buffers before returning from function calls. By default, + * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * is set, they are (mostly -- few exceptions remain at present) allocated from + * the configured custom allocator. + * + * mldsa-native also zeroizes caller-owned output buffers as needed to uphold + * the API convention that outputs be either unmodified or zeroized upon + * failure. + * + * Set this option and define `mld_zeroize` if you want to use a custom + * method to zeroize intermediate and output buffers. + * + * The default implementation uses SecureZeroMemory on Windows and a + * memset + compiler barrier otherwise. If neither of those is available on + * the target platform, compilation will fail, and you will need to use + * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * `mld_zeroize()`. + * + * @warning + * The zeroization conducted by mldsa-native reduces the likelihood of data + * leaking on the stack or custom allocators, but it does not eliminate it. + * For example, the C standard makes no guarantee about where a compiler + * allocates local structures and whether/where it makes copies of them. + * Also, in addition to entire structures, there may also be potentially + * exploitable leakage of individual values on the stack. If you need + * bullet-proof zeroization of the stack, you need to consider additional + * measures instead of what this feature provides. In this case, you can + * set mld_zeroize to a no-op. Note that in this case you are also responsible + * for zeroizing output buffers upon failure. + */ +/* #define MLD_CONFIG_CUSTOM_ZEROIZE + #if !defined(__ASSEMBLER__) + #include + #include "src/src.h" + static MLD_INLINE void mld_zeroize(void *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/** + * MLD_CONFIG_CUSTOM_RANDOMBYTES + * + * mldsa-native does not provide a secure randombytes + * implementation. Such an implementation has to be provided by + * the consumer. + * + * If this option is not set, mldsa-native expects a function + * int randombytes(uint8_t *out, size_t outlen). + * + * Set this option and define `mld_randombytes` if you want to + * use a custom method to sample randombytes with a different name + * or signature. + */ +/* #define MLD_CONFIG_CUSTOM_RANDOMBYTES + #if !defined(__ASSEMBLER__) + #include + #include "src/src.h" + static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) + { + ... your implementation ... + return 0; + } + #endif +*/ + +/** + * MLD_CONFIG_CUSTOM_CAPABILITY_FUNC + * + * mldsa-native backends may rely on specific hardware features. + * Those backends will only be included in an mldsa-native build + * if support for the respective features is enabled at + * compile-time. However, when building for a heterogeneous set + * of CPUs to run the resulting binary/library on, feature + * detection at _runtime_ is needed to decide whether a backend + * can be used or not. + * + * Set this option and define `mld_sys_check_capability` if you + * want to use a custom method to dispatch between implementations. + * + * Return value 1 indicates that a capability is supported. + * Return value 0 indicates that a capability is not supported. + * + * If this option is not set, mldsa-native uses compile-time + * feature detection only to decide which backend to use. + * + * If you compile mldsa-native on a system with different + * capabilities than the system that the resulting binary/library + * will be run on, you must use this option. + */ +/* #define MLD_CONFIG_CUSTOM_CAPABILITY_FUNC + static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) + { + ... your implementation ... + } +*/ + +/** + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] + * + * Set this option and define `MLD_CUSTOM_ALLOC` and + * `MLD_CUSTOM_FREE` if you want to use custom allocation for + * large local structures or buffers. + * + * By default, all buffers/structures are allocated on the stack. + * If this option is set, most of them will be allocated via + * MLD_CUSTOM_ALLOC. + * + * Parameters to MLD_CUSTOM_ALLOC: + * - T* v: Target pointer to declare. + * - T: Type of structure to be allocated + * - N: Number of elements to be allocated. + * + * Parameters to MLD_CUSTOM_FREE: + * - T* v: Target pointer to free. May be NULL. + * - T: Type of structure to be freed. + * - N: Number of elements to be freed. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + * + * @note Even if this option is set, some allocations further down + * the call stack will still be made from the stack. Those will + * likely be added to the scope of this option in the future. + * + * @note MLD_CUSTOM_ALLOC need not guarantee a successful + * allocation nor include error handling. Upon failure, the + * target pointer should simply be set to NULL. The calling + * code will handle this case and invoke MLD_CUSTOM_FREE. + */ +/* #define MLD_CONFIG_CUSTOM_ALLOC_FREE + #if !defined(__ASSEMBLER__) + #include + #define MLD_CUSTOM_ALLOC(v, T, N) \ + T* (v) = (T *)aligned_alloc(MLD_DEFAULT_ALIGN, \ + MLD_ALIGN_UP(sizeof(T) * (N))) + #define MLD_CUSTOM_FREE(v, T, N) free(v) + #endif +*/ + +/** + * MLD_CONFIG_CUSTOM_MEMCPY + * + * Set this option and define `mld_memcpy` if you want to + * use a custom method to copy memory instead of the standard + * library memcpy function. + * + * The custom implementation must have the same signature and + * behavior as the standard memcpy function: + * void *mld_memcpy(void *dest, const void *src, size_t n) + */ +/* #define MLD_CONFIG_CUSTOM_MEMCPY + #if !defined(__ASSEMBLER__) + #include + #include "src/src.h" + static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/** + * MLD_CONFIG_CUSTOM_MEMSET + * + * Set this option and define `mld_memset` if you want to + * use a custom method to set memory instead of the standard + * library memset function. + * + * The custom implementation must have the same signature and + * behavior as the standard memset function: + * void *mld_memset(void *s, int c, size_t n) + */ +/* #define MLD_CONFIG_CUSTOM_MEMSET + #if !defined(__ASSEMBLER__) + #include + #include "src/src.h" + static MLD_INLINE void *mld_memset(void *s, int c, size_t n) + { + ... your implementation ... + } + #endif +*/ + +/** + * MLD_CONFIG_INTERNAL_API_QUALIFIER + * + * If set, this option provides an additional qualifier + * to be added to declarations of internal API functions and data. + * + * The primary use case for this option are single-CU builds, + * in which case this option can be set to `static`. + */ +/* #define MLD_CONFIG_INTERNAL_API_QUALIFIER */ + +/** + * MLD_CONFIG_CT_TESTING_ENABLED + * + * If set, mldsa-native annotates data as secret / public using + * valgrind's annotations VALGRIND_MAKE_MEM_UNDEFINED and + * VALGRIND_MAKE_MEM_DEFINED, enabling various checks for secret- + * dependent control flow of variable time execution (depending + * on the exact version of valgrind installed). + */ +/* #define MLD_CONFIG_CT_TESTING_ENABLED */ + +/** + * MLD_CONFIG_NO_ASM + * + * If this option is set, mldsa-native will be built without + * use of native code or inline assembly. + * + * By default, inline assembly is used to implement value barriers. + * Without inline assembly, mldsa-native will use a global volatile + * 'opt blocker' instead; see ct.h. + * + * Inline assembly is also used to implement a secure zeroization + * function on non-Windows platforms. If this option is set and + * the target platform is not Windows, you MUST set + * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * function. + * + * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * native backends will be used. + */ +/* #define MLD_CONFIG_NO_ASM */ + +/** + * MLD_CONFIG_NO_ASM_VALUE_BARRIER + * + * If this option is set, mldsa-native will be built without + * use of native code or inline assembly for value barriers. + * + * By default, inline assembly (if available) is used to implement + * value barriers. + * Without inline assembly, mldsa-native will use a global volatile + * 'opt blocker' instead; see ct.h. + */ +/* #define MLD_CONFIG_NO_ASM_VALUE_BARRIER */ + +/** + * MLD_CONFIG_KEYGEN_PCT + * + * Compliance with @[FIPS140_3_IG, p.87] requires a + * Pairwise Consistency Test (PCT) to be carried out on a freshly + * generated keypair before it can be exported. + * + * Set this option if such a check should be implemented. + * In this case, keypair_internal and + * keypair will return MLD_ERR_PCT_FAIL if the + * PCT failed. + * + * @note This feature will drastically lower the performance of + * key generation. + * + * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API + * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * requires signature() and verify(). + */ +/* #define MLD_CONFIG_KEYGEN_PCT */ + +/** + * MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST + * + * If this option is set, the user must provide a runtime + * function `static inline int mld_break_pct() { ... }` to + * indicate whether the PCT should be made fail. + * + * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + */ +/* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST + #if !defined(__ASSEMBLER__) + #include "src/src.h" + static MLD_INLINE int mld_break_pct(void) + { + ... return 0/1 depending on whether PCT should be broken ... + } + #endif +*/ + +/** + * MLD_CONFIG_MAX_SIGNING_ATTEMPTS + * + * Upper bound on the number of rejection-sampling iterations + * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). + * + * If a valid signature is not produced within this many + * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * This is useful in timing-sensitive environments that + * require a deterministic worst-case bound on signing time. + * + * For FIPS 204 compliance, this value MUST be at least 821, + * cf. @[FIPS204, Appendix C] and @[FIPS204_UPDATES], which is + * chosen so that the signing failure rate is < 2^{-256}. + * + * Default: Largest possible value before internal counters + * would overflow. This is larger than the FIPS204 bound. + * + * In particular, in the default configuration, the signing + * failure rate is < 2^{-256}. + */ +/* #define MLD_CONFIG_MAX_SIGNING_ATTEMPTS 821 */ + +/** + * MLD_CONFIG_SERIAL_FIPS202_ONLY + * + * Set this to use a FIPS202 implementation with global state + * that supports only one active Keccak computation at a time + * (e.g. some hardware accelerators). + * + * If this option is set, ML-DSA will use FIPS202 operations + * serially, ensuring that only one SHAKE context is active + * at any given time. + * + * This allows offloading Keccak computations to a hardware + * accelerator that holds only a single Keccak state locally, + * rather than requiring support for multiple concurrent + * Keccak states. + * + * @note Depending on the target CPU, this may reduce + * performance when using software FIPS202 implementations. + * Only enable this when you have to. + */ +/* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ + +/** + * MLD_CONFIG_CONTEXT_PARAMETER + * + * Set this to add a caller-supplied context parameter to the public API + * functions, which is then forwarded unchanged to the custom callbacks + * (allocation, and signing hooks below). + * + * When this option is set, every public API function gains a trailing + * parameter + * + * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context + * + * as its last argument; its type is configured via + * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * value as opaque: it never dereferences it and only passes it on to the + * configurable hook macros. It is meant to carry per-caller state -- e.g. a + * pointer to a memory pool for the allocation hooks, or the resume state for + * the signing hooks -- into those hooks. + * + * When this option is unset (the default), no extra parameter is added and + * the hook macros never receive a context argument. + * + * The hooks that receive the context are the allocation hooks (see + * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with + * its own option below. + */ +/* #define MLD_CONFIG_CONTEXT_PARAMETER */ + +/** + * MLD_CONFIG_CONTEXT_PARAMETER_TYPE + * + * Set this to define the type of the context parameter added by + * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * parameter, e.g. `void *` or a pointer to a caller-defined struct such as + * `struct my_ctx *`. + * + * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * defined; defining one without the other is a compile-time error. + */ +/* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ + +/** + * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] + * + * Three optional, independent hooks into the ML-DSA signing rejection-sampling + * loop. Each is enabled by defining the matching option, in which case the + * integration must provide the corresponding function. If a hook needs + * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then + * appended as the last argument. + * + * @warning This feature is experimental. Its scope, configuration and + * function signatures may change at any time, including after v2. + * + * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * the public API to deterministic operations). This is because the restartable + * signing as enabled by the signing hooks only produces the uninterrupted + * signature when the randomness is fixed across calls. A logging-only use + * (attempt always returns 0; resume/finish merely observe) would be safe with + * the randomized API too, but for now the requirement is imposed uniformly on + * all three hooks. + * + * Note: Randomized signing is a shim wrapper around deterministic signing, and + * all helper functions you need to build it are exposed publicly. Thus, if you + * need a restartable, randomized signing operation, you can build your own by + * replicating the logic and adding the RNG seed to the restart context. In this + * case, please also consider letting the mldsa-native maintainers know of your + * need for randomized, restartable signing, so the feature can be appropriately + * prioritized. + * + * - MLD_CONFIG_SIGN_HOOK_ATTEMPT: int mld_sign_hook_attempt(attempt[, ctxt]) + * Called before each attempt. Returns 0 to proceed, or non-zero to pause: + * signing then returns MLD_ERR_SIGNING_PAUSED with `attempt` as the resume + * point (needs MLD_CONFIG_SIGN_HOOK_RESUME to resume; otherwise just aborts). + * Always returning 0 makes it a logging/benchmarking hook. + * + * - MLD_CONFIG_SIGN_HOOK_RESUME: uint16_t mld_sign_hook_resume([ctxt]) + * Returns the attempt to resume from (0 for a fresh operation), i.e. the one + * recorded when a previous call paused. + * + * - MLD_CONFIG_SIGN_HOOK_FINISH: void mld_sign_hook_finish(attempt[, ctxt]) + * Called on success with the succeeding attempt. Observe-only. + * + * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), + * i.e. ordinary one-shot signing. + * + * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound + * on the number of signing attempts. + * + * See test/src/test_sign_hook.c for a worked example using all three. + */ +/* #define MLD_CONFIG_SIGN_HOOK_RESUME + #define MLD_CONFIG_SIGN_HOOK_ATTEMPT + #define MLD_CONFIG_SIGN_HOOK_FINISH + #if !defined(__ASSEMBLER__) + #include + #include "src/sys.h" + static MLD_INLINE uint16_t mld_sign_hook_resume(void) + { + ... return the attempt to resume from ... + } + static MLD_INLINE int mld_sign_hook_attempt(uint16_t attempt) + { + ... return non-zero to pause here; for resume, store attempt ... + return 0; + } + static MLD_INLINE void mld_sign_hook_finish(uint16_t attempt) + { + ... mark the operation complete (attempt = successful attempt) ... + } + #endif +*/ + +/** + * MLD_CONFIG_REDUCE_RAM + * + * Set this to reduce RAM usage. This trades memory for performance. + * + * For expected memory usage, see the MLD_TOTAL_ALLOC_* constants defined in + * mldsa_native.h. + * + * This option is useful for embedded systems with tight RAM constraints but + * relaxed performance requirements. + * + */ +/* #define MLD_CONFIG_REDUCE_RAM */ + +/************************* Config internals ********************************/ + +#endif /* MLD_BUILD_INTERNAL */ + +/* Default namespace + * + * Don't change this. If you need a different namespace, re-define + * MLD_CONFIG_NAMESPACE_PREFIX above instead, and remove the following. + * + * The default MLDSA namespace is + * + * PQCP_MLDSA_NATIVE_MLDSA_ + * + * e.g., PQCP_MLDSA_NATIVE_MLDSA44_ + */ + +#if defined(MLD_CONFIG_MULTILEVEL_BUILD) +/* In a multi-level build the parameter set is appended by the namespacing + * machinery, so the default prefix must not embed it. */ +#define MLD_DEFAULT_NAMESPACE_PREFIX PQCP_MLDSA_NATIVE_MLDSA +#elif MLD_CONFIG_PARAMETER_SET == 44 +#define MLD_DEFAULT_NAMESPACE_PREFIX PQCP_MLDSA_NATIVE_MLDSA44 +#elif MLD_CONFIG_PARAMETER_SET == 65 +#define MLD_DEFAULT_NAMESPACE_PREFIX PQCP_MLDSA_NATIVE_MLDSA65 +#elif MLD_CONFIG_PARAMETER_SET == 87 +#define MLD_DEFAULT_NAMESPACE_PREFIX PQCP_MLDSA_NATIVE_MLDSA87 +#endif + +#endif /* !MLD_CONFIG_H */ diff --git a/test/configs/custom_heap_alloc_config.h b/test/configs/custom_heap_alloc_config.h index 1890789180..ca65d0baab 100644 --- a/test/configs/custom_heap_alloc_config.h +++ b/test/configs/custom_heap_alloc_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -774,6 +815,7 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_memcpy_config.h b/test/configs/custom_memcpy_config.h index 2422680e1d..5f376a4a4d 100644 --- a/test/configs/custom_memcpy_config.h +++ b/test/configs/custom_memcpy_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -764,6 +805,7 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_memset_config.h b/test/configs/custom_memset_config.h index 6f876fb6d2..6b3843ea2c 100644 --- a/test/configs/custom_memset_config.h +++ b/test/configs/custom_memset_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -763,6 +804,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_native_capability_config_0.h b/test/configs/custom_native_capability_config_0.h index 29da7faa3c..c7bf10a878 100644 --- a/test/configs/custom_native_capability_config_0.h +++ b/test/configs/custom_native_capability_config_0.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -490,7 +531,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -763,6 +804,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_native_capability_config_1.h b/test/configs/custom_native_capability_config_1.h index 111ffff1ec..588e05b181 100644 --- a/test/configs/custom_native_capability_config_1.h +++ b/test/configs/custom_native_capability_config_1.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -489,7 +530,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -762,6 +803,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_native_capability_config_CPUID_AVX2.h b/test/configs/custom_native_capability_config_CPUID_AVX2.h index 94f0643508..146213bd77 100644 --- a/test/configs/custom_native_capability_config_CPUID_AVX2.h +++ b/test/configs/custom_native_capability_config_CPUID_AVX2.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -521,7 +562,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -794,6 +835,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h b/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h index d96f35b440..d583727f43 100644 --- a/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h +++ b/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -521,7 +562,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -794,6 +835,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_randombytes_config.h b/test/configs/custom_randombytes_config.h index e6d0e3f5ca..c896e52c30 100644 --- a/test/configs/custom_randombytes_config.h +++ b/test/configs/custom_randombytes_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -756,6 +797,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_stdlib_config.h b/test/configs/custom_stdlib_config.h index d8678fbe71..008018be3f 100644 --- a/test/configs/custom_stdlib_config.h +++ b/test/configs/custom_stdlib_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -772,6 +813,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/custom_zeroize_config.h b/test/configs/custom_zeroize_config.h index d89f1245bd..d220b43fe9 100644 --- a/test/configs/custom_zeroize_config.h +++ b/test/configs/custom_zeroize_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -757,6 +798,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/low_signing_bound_config.h b/test/configs/low_signing_bound_config.h index d273a5274f..44f48a7f44 100644 --- a/test/configs/low_signing_bound_config.h +++ b/test/configs/low_signing_bound_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -484,7 +525,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -759,6 +800,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/no_asm_config.h b/test/configs/no_asm_config.h index b05e321403..e38e38a95e 100644 --- a/test/configs/no_asm_config.h +++ b/test/configs/no_asm_config.h @@ -381,6 +381,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -485,7 +526,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -758,6 +799,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/serial_fips202_config.h b/test/configs/serial_fips202_config.h index 826a193669..ea86531d74 100644 --- a/test/configs/serial_fips202_config.h +++ b/test/configs/serial_fips202_config.h @@ -380,6 +380,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -483,7 +524,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -756,6 +797,7 @@ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/test_alloc_config.h b/test/configs/test_alloc_config.h index e6be5d96a7..e4e62f1091 100644 --- a/test/configs/test_alloc_config.h +++ b/test/configs/test_alloc_config.h @@ -383,6 +383,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -486,7 +527,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -764,6 +805,7 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/configs/test_sign_hook_config.h b/test/configs/test_sign_hook_config.h index dd13988f0e..4ee189eb59 100644 --- a/test/configs/test_sign_hook_config.h +++ b/test/configs/test_sign_hook_config.h @@ -384,6 +384,47 @@ */ /* #define MLD_CONFIG_FIPS202X4_CUSTOM_HEADER "SOME_FILE.h" */ +/** + * MLD_CONFIG_ALIGN [EXPERIMENTAL] + * + * Alignment, in bytes, of large buffers and structures. + * Must be a power of two. If unset, 32 bytes are used. + * + * Set this only to change the alignment. Wherever mldsa-native knows a + * declarator prefix for the compiler, that prefix follows the new value + * automatically; otherwise set MLD_CONFIG_ALIGN_ATTRIBUTE as well. + * + * Native backends require a minimum alignment to avoid faulting on + * alignment-sensitive load and store instructions; this is enforced at + * compile time. + * + * The MLD_TOTAL_ALLOC_* constants in mldsa_native.h are measured for the + * default alignment and are not defined if you customize it. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN 32 */ + +/** + * MLD_CONFIG_ALIGN_ATTRIBUTE [EXPERIMENTAL] + * + * Declarator prefix aligning the declared object. + * + * Set this only if mldsa-native knows no spelling for your compiler. Without + * one, it falls back to the alignment the compiler picks by itself, which is + * insufficient for the native backends. + * + * This option carries its own byte count, so it must align to at least + * MLD_CONFIG_ALIGN bytes, or to 32 bytes if MLD_CONFIG_ALIGN is unset. + * + * @warning This option is experimental. Its scope, configuration and + * function/macro signatures may change at any time. We expect a + * stable API in a future version. + */ +/* #define MLD_CONFIG_ALIGN_ATTRIBUTE __attribute__((aligned(32))) */ + /** * MLD_CONFIG_CUSTOM_ZEROIZE * @@ -487,7 +528,7 @@ */ /** - * MLD_CONFIG_CUSTOM_ALLOC_FREE + * MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL] * * Set this option and define `MLD_CUSTOM_ALLOC` and * `MLD_CUSTOM_FREE` if you want to use custom allocation for @@ -767,6 +808,7 @@ struct test_sign_hook_ctx; /* Forward declaration */ /** * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH + * [EXPERIMENTAL] * * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the diff --git a/test/src/test_alloc.c b/test/src/test_alloc.c index 1042190b38..3dd1e2bd3f 100644 --- a/test/src/test_alloc.c +++ b/test/src/test_alloc.c @@ -15,6 +15,15 @@ #include "expected_test_vectors.h" #include "test_namespace.h" +/* + * The limits this test checks against are only published for the default + * alignment. With a customized one there is nothing to compare to, so the + * test reports itself as skipped. + */ +#if !defined(MLD_CONFIG_ALIGN) || MLD_CONFIG_ALIGN == 32 +#define MLD_TEST_ALLOC_LIMITS +#endif + /* * Level-dependent allocation limit macros. * These expand to the right MLD_TOTAL_ALLOC_{44,65,87}_* constant @@ -151,8 +160,7 @@ static void alloc_tracker_pop(test_ctx_t *ctx, void *addr, size_t size, static void *bump_alloc(test_ctx_t *ctx, size_t sz) { - /* Align to 32 bytes */ - size_t aligned_sz = (sz + 31) & ~((size_t)31); + size_t aligned_sz = MLD_ALIGN_UP(sz); void *p; if (sz > MLD_BUMP_ALLOC_SIZE || @@ -190,6 +198,7 @@ static int bump_free(test_ctx_t *ctx, void *p) return 0; } +#if defined(MLD_TEST_ALLOC_LIMITS) static void reset_all(test_ctx_t *ctx) { randombytes_reset(); @@ -198,6 +207,7 @@ static void reset_all(test_ctx_t *ctx) ctx->offset = 0; ctx->fail_on_counter = -1; } +#endif /* MLD_TEST_ALLOC_LIMITS */ void *custom_alloc(test_ctx_t *ctx, size_t sz, const char *file, int line, const char *var, const char *type) @@ -336,6 +346,8 @@ void custom_free(test_ctx_t *ctx, void *p, size_t sz, const char *file, } \ } while (0) +#if defined(MLD_TEST_ALLOC_LIMITS) + /* Keygen tests */ #if !defined(MLD_CONFIG_NO_KEYPAIR_API) @@ -453,10 +465,20 @@ static int test_verify_pre_hash_shake256_alloc_failure(test_ctx_t *ctx) } \ } while (0) +#endif /* MLD_TEST_ALLOC_LIMITS */ + /* Prototype for a re-#define'd main, to satisfy -Wmissing-prototypes. */ #if defined(main) int main(void); #endif + +#if !defined(MLD_TEST_ALLOC_LIMITS) +int main(void) +{ + printf("Allocation test skipped: no published limits for this alignment.\n"); + return 0; +} +#else /* !MLD_TEST_ALLOC_LIMITS */ int main(void) { int r = 0; @@ -533,3 +555,4 @@ int main(void) return 0; } +#endif /* MLD_TEST_ALLOC_LIMITS */