Make allocation of large structures/buffers configurable

This commit introduces the configuration option

MLD_CONFIG_CUSTOM_ALLOC_FREE

which allows users to provide custom macros

MLD_CUSTOM_ALLOC(v, T, N)
MLD_CUSTOM_FREE(v, T, N)

that should be used in place of the default stack-allocation
to allocate/free large internal structures. Those macros are
then wrapped into MLD_ALLOC/MLD_FREE and used in the source.
Importantly, MLD_FREE adds zeroization ahead of calling
MLD_CUSTOM_FREE, so the latter need not take care of this.

The macros are put to use in sign.c, but not yet
further down the call-stack.

The option is documented as experimental and (hence) unstable
so we have freedom to adjust this ahead of v2.

A custom configuration is added which implements the macros
based on C11's aligned_alloc. We enable the leak sanitizer
in the tests for this configuration to catch any missing calls
to MLD_FREE.

Since allocation can fail, additional error paths are introduced
to the functions using MLD_ALLOC. This uniformly follows the pattern
of all pointers being initialized to NULL before allocation, and a
cleanup section calling MLD_FREE on them before returning the result.

To distinguish between out-of-memory failure and other kinds of
functional failures, we introduce named error codes MLD_ERR_FAIL
and MLD_ERR_OUT_OF_MEMORY. This will likely need further refinement,
but this can only be done in v2.

We don't yet introduce MLD_ERR_FAIL in lower level functions which
signal success/failure through 0 or a (single) non-zero error code;
instead, we explicitly map the non-zero failure case to MLD_ERR_FAIL
at the top-level. At the occasion, however, we do add qualifiers
MLD_MUST_CHECK_RETURN_VALUE to ensure we don't forget to check
return values of those functions.

Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>

Author: hanno-becker

.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, 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'
+    description: 'List of tests to run (space-separated IDs) or "all" for all tests. Available IDs: pct-enabled, pct-enabled-broken, 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'
     required: false
     default: 'all'
   opt:
@@ -47,6 +47,20 @@ runs:
         else
            echo "PCT failed as expected"
         fi
+    - name: "Custom allocation (heap based)"
+      if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-alloc-heap') }}
+      uses: ./.github/actions/multi-functest
+      with:
+        gh_token: ${{ inputs.gh_token }}
+        compile_mode: native
+        cflags: "-std=c11 -D_GNU_SOURCE -Itest -DMLD_CONFIG_FILE=\\\\\\\"custom_heap_alloc_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 }}
+        extra_env: 'ASAN_OPTIONS=detect_leaks=1'
+        examples: false # Some examples use a custom config themselves
     - name: "Custom zeroization (explicit_bzero)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-zeroize') }}
       uses: ./.github/actions/multi-functest

BIBLIOGRAPHY.md

@@ -39,6 +39,7 @@ source code and documentation.
   - [mldsa/mldsa_native_config.h](mldsa/mldsa_native_config.h)
   - [mldsa/src/sign.c](mldsa/src/sign.c)
   - [test/break_pct_config.h](test/break_pct_config.h)
+  - [test/custom_heap_alloc_config.h](test/custom_heap_alloc_config.h)
   - [test/custom_memcpy_config.h](test/custom_memcpy_config.h)
   - [test/custom_memset_config.h](test/custom_memset_config.h)
   - [test/custom_native_capability_config_0.h](test/custom_native_capability_config_0.h)

examples/basic_deterministic/mldsa_native/mldsa_native_config.h

@@ -453,6 +453,51 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: 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 for v2.
+ *
+ *              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 <stdlib.h>
+   #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
+*/
+
 /******************************************************************************
  * Name:        MLD_CONFIG_CUSTOM_MEMCPY
  *

examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h

@@ -453,6 +453,51 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: 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 for v2.
+ *
+ *              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 <stdlib.h>
+   #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
+*/
+
 /******************************************************************************
  * Name:        MLD_CONFIG_CUSTOM_MEMCPY
  *

examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h

@@ -454,6 +454,51 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: 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 for v2.
+ *
+ *              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 <stdlib.h>
+   #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
+*/
+
 /******************************************************************************
  * Name:        MLD_CONFIG_CUSTOM_MEMCPY
  *

examples/custom_backend/mldsa_native/mldsa_native_config.h

@@ -449,6 +449,51 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: 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 for v2.
+ *
+ *              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 <stdlib.h>
+   #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
+*/
+
 /******************************************************************************
  * Name:        MLD_CONFIG_CUSTOM_MEMCPY
  *

examples/monolithic_build/mldsa_native/mldsa_native_config.h

@@ -452,6 +452,51 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: 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 for v2.
+ *
+ *              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 <stdlib.h>
+   #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
+*/
+
 /******************************************************************************
  * Name:        MLD_CONFIG_CUSTOM_MEMCPY
  *

examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h

@@ -453,6 +453,51 @@
    }
 */
 
+/******************************************************************************
+ * Name:        MLD_CONFIG_CUSTOM_ALLOC_FREE [EXPERIMENTAL]
+ *
+ * Description: 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 for v2.
+ *
+ *              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 <stdlib.h>
+   #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
+*/
+
 /******************************************************************************
  * Name:        MLD_CONFIG_CUSTOM_MEMCPY
  *