Make the alignment configurable

.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

.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

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)

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

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

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

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

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

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

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