Merge pull request #1105 from pq-code-package/issue_550

Allow customization of memcpy and memset

Author: mkannwischer

.github/workflows/ci.yml

@@ -469,6 +469,36 @@ jobs:
           kat: true
           acvp: true
           examples: false # Some examples use a custom config themselves
+      - name: "Custom memcpy"
+        uses: ./.github/actions/multi-functest
+        with:
+          gh_token: ${{ secrets.GITHUB_TOKEN }}
+          compile_mode: native
+          cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_memcpy_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+          func: true
+          kat: true
+          acvp: true
+          examples: false # Some examples use a custom config themselves
+      - name: "Custom memset"
+        uses: ./.github/actions/multi-functest
+        with:
+          gh_token: ${{ secrets.GITHUB_TOKEN }}
+          compile_mode: native
+          cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_memset_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+          func: true
+          kat: true
+          acvp: true
+          examples: false # Some examples use a custom config themselves
+      - name: "Custom stdlib (memcpy + memset)"
+        uses: ./.github/actions/multi-functest
+        with:
+          gh_token: ${{ secrets.GITHUB_TOKEN }}
+          compile_mode: native
+          cflags: "-std=c11 -D_GNU_SOURCE -DMLK_CONFIG_FILE=\\\\\\\"../../test/custom_stdlib_config.h\\\\\\\" -fsanitize=address -fsanitize=undefined -fno-sanitize-recover=all"
+          func: true
+          kat: true
+          acvp: true
+          examples: false # Some examples use a custom config themselves
       - name: "MLKEM_GEN_MATRIX_NBLOCKS=1"
         uses: ./.github/actions/multi-functest
         with:

.github/workflows/integration-awslc.yml

@@ -44,6 +44,10 @@ jobs:
         run: |
           cd $AWSLC_DIR/crypto/fipsmodule/ml_kem
           GITHUB_REPOSITORY=$GITHUB_REPOSITORY GITHUB_SHA=$GITHUB_SHA ./importer.sh --force
+      - name: Apply custom stdlib patch
+        run: |
+          cd $AWSLC_DIR
+          patch -p0 < $GITHUB_WORKSPACE/integration/aws-lc/add-custom-stdlib.patch
       - name: Build+Test AWS-LC (FIPS=${{ matrix.fips }})
         run: |
           cd $AWSLC_DIR
@@ -91,6 +95,10 @@ jobs:
         run: |
           cd $AWSLC_DIR/crypto/fipsmodule/ml_kem
           GITHUB_REPOSITORY=$GITHUB_REPOSITORY GITHUB_SHA=$GITHUB_SHA ./importer.sh --force
+      - name: Apply custom stdlib patch
+        run: |
+          cd $AWSLC_DIR
+          patch -p0 < $GITHUB_WORKSPACE/integration/aws-lc/add-custom-stdlib.patch
       - name: Run test
         run: |
           cd $AWSLC_DIR
@@ -123,6 +131,10 @@ jobs:
         run: |
           cd $AWSLC_DIR/crypto/fipsmodule/ml_kem
           GITHUB_REPOSITORY=$GITHUB_REPOSITORY GITHUB_SHA=$GITHUB_SHA ./importer.sh --force
+      - name: Apply custom stdlib patch
+        run: |
+          cd $AWSLC_DIR
+          patch -p0 < $GITHUB_WORKSPACE/integration/aws-lc/add-custom-stdlib.patch
       - name: Run test
         run: |
           cd $AWSLC_DIR

BIBLIOGRAPHY.md

@@ -50,7 +50,10 @@ source code and documentation.
   - [mlkem/src/config.h](mlkem/src/config.h)
   - [mlkem/src/kem.c](mlkem/src/kem.c)
   - [test/break_pct_config.h](test/break_pct_config.h)
+  - [test/custom_memcpy_config.h](test/custom_memcpy_config.h)
+  - [test/custom_memset_config.h](test/custom_memset_config.h)
   - [test/custom_randombytes_config.h](test/custom_randombytes_config.h)
+  - [test/custom_stdlib_config.h](test/custom_stdlib_config.h)
   - [test/custom_zeroize_config.h](test/custom_zeroize_config.h)
   - [test/no_asm_config.h](test/no_asm_config.h)
 

STDLIB.md

@@ -0,0 +1,27 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+# Standard Library Dependencies
+
+mlkem-native has minimal dependencies on the C standard library. This document lists all stdlib functions used and configuration options for custom replacements.
+
+## Dependencies
+
+### Memory Functions
+- **memcpy**: Used extensively for copying data structures, keys, and intermediate values (40+ occurrences)
+- **memset**: Used for zeroing state structures and buffers (3 occurrences). **Note**: This is NOT used for security-critical zeroing - that is handled by `mlk_zeroize` which has its own custom replacement mechanism
+
+### Debug Functions (MLKEM_DEBUG builds only)
+- **fprintf**: Used in debug.c for error reporting to stderr
+- **exit**: Used in debug.c to terminate on assertion failures
+
+## Custom Replacements
+
+Custom replacements can be provided for memory functions using the configuration options in `mlkem/src/config.h`:
+
+### MLK_CONFIG_CUSTOM_MEMCPY
+Replaces all `memcpy` calls with a custom implementation. When enabled, you must define a `mlk_memcpy` function with the same signature as the standard `memcpy`.
+
+### MLK_CONFIG_CUSTOM_MEMSET
+Replaces all `memset` calls with a custom implementation. When enabled, you must define a `mlk_memset` function with the same signature as the standard `memset`.
+
+See the configuration examples in `mlkem/src/config.h` and test configurations in `test/custom_*_config.h` for usage examples and implementation requirements.

dev/x86_64/src/compress_avx2.c

@@ -135,7 +135,7 @@ void mlk_poly_compress_d10_avx2(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D10],
     t1 = _mm256_extracti128_si256(f0, 1);
     t0 = _mm_blend_epi16(t0, t1, 0xE0);
     _mm_storeu_si128((__m128i *)&r[20 * i + 0], t0);
-    memcpy(&r[20 * i + 16], &t1, 4);
+    mlk_memcpy(&r[20 * i + 16], &t1, 4);
   }
 }
 
@@ -167,7 +167,7 @@ void mlk_poly_decompress_d10_avx2(
   }
 
   /* Handle load in last iteration especially to avoid buffer overflow */
-  memcpy(&f, &a[20 * i], 20);
+  mlk_memcpy(&f, &a[20 * i], 20);
   /* The rest is the same */
   f = _mm256_permute4x64_epi64(f, 0x94);
   f = _mm256_shuffle_epi8(f, shufbidx);
@@ -219,7 +219,7 @@ void mlk_poly_compress_d5_avx2(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D5],
     t1 = _mm256_extracti128_si256(f0, 1);
     t0 = _mm_blendv_epi8(t0, t1, _mm256_castsi256_si128(shufbidx));
     _mm_storeu_si128((__m128i *)&r[20 * i + 0], t0);
-    memcpy(&r[20 * i + 16], &t1, 4);
+    mlk_memcpy(&r[20 * i + 16], &t1, 4);
   }
 }
 
@@ -245,7 +245,7 @@ void mlk_poly_decompress_d5_avx2(__m256i *MLK_RESTRICT r,
   for (i = 0; i < MLKEM_N / 16; i++)
   {
     t = _mm_loadl_epi64((__m128i *)&a[10 * i + 0]);
-    memcpy(&ti, &a[10 * i + 8], 2);
+    mlk_memcpy(&ti, &a[10 * i + 8], 2);
     t = _mm_insert_epi16(t, ti, 4);
     f = _mm256_broadcastsi128_si256(t);
     f = _mm256_shuffle_epi8(f, shufbidx);
@@ -326,7 +326,7 @@ void mlk_poly_compress_d11_avx2(uint8_t r[MLKEM_POLYCOMPRESSEDBYTES_D11],
   t0 = _mm_blendv_epi8(t0, t1, _mm256_castsi256_si128(shufbidx));
   _mm_storeu_si128((__m128i *)&r[22 * i + 0], t0);
   /* Handle store in last iteration especially to avoid overflow */
-  memcpy(&r[22 * i + 16], &t1, 6);
+  mlk_memcpy(&r[22 * i + 16], &t1, 6);
 }
 
 void mlk_poly_decompress_d11_avx2(
@@ -363,7 +363,7 @@ void mlk_poly_decompress_d11_avx2(
   }
 
   /* Handle load of last iteration especially */
-  memcpy(&f, &a[22 * i], 22);
+  mlk_memcpy(&f, &a[22 * i], 22);
   /* The rest of the iteration is the same */
   f = _mm256_permute4x64_epi64(f, 0x94);
   f = _mm256_shuffle_epi8(f, shufbidx);

integration/aws-lc/add-custom-stdlib.patch

@@ -0,0 +1,31 @@
+# Copyright (c) The mlkem-native project authors
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+--- crypto/fipsmodule/ml_kem/mlkem_native_config.h
++++ crypto/fipsmodule/ml_kem/mlkem_native_config.h
+@@ -64,6 +64,26 @@
+ }
+ #endif // !__ASSEMBLER__
+ 
++// Map memcpy function to the one used by AWS-LC
++#define MLK_CONFIG_CUSTOM_MEMCPY
++#if !defined(__ASSEMBLER__)
++#include <stdint.h>
++#include "mlkem/sys.h"
++static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n) {
++    return OPENSSL_memcpy(dest, src, n);
++}
++#endif // !__ASSEMBLER__
++
++// Map memset function to the one used by AWS-LC
++#define MLK_CONFIG_CUSTOM_MEMSET
++#if !defined(__ASSEMBLER__)
++#include <stdint.h>
++#include "mlkem/sys.h"
++static MLK_INLINE void *mlk_memset(void *s, int c, size_t n) {
++    return OPENSSL_memset(s, c, n);
++}
++#endif // !__ASSEMBLER__
++
+ #if defined(OPENSSL_NO_ASM)
+ #define MLK_CONFIG_NO_ASM
+ #endif

mlkem/mlkem_native.S

@@ -180,6 +180,8 @@
 #undef MLK_NAMESPACE_K
 #undef MLK_NAMESPACE_PREFIX
 #undef MLK_NAMESPACE_PREFIX_K
+#undef mlk_memcpy
+#undef mlk_memset
 /* mlkem/src/indcpa.h */
 #undef MLK_INDCPA_H
 #undef mlk_gen_matrix

mlkem/mlkem_native.c

@@ -169,6 +169,8 @@
 #undef MLK_NAMESPACE_K
 #undef MLK_NAMESPACE_PREFIX
 #undef MLK_NAMESPACE_PREFIX_K
+#undef mlk_memcpy
+#undef mlk_memset
 /* mlkem/src/indcpa.h */
 #undef MLK_INDCPA_H
 #undef mlk_gen_matrix

mlkem/src/common.h

@@ -135,6 +135,19 @@
 #define MLK_FIPS202X4_HEADER_FILE MLK_CONFIG_FIPS202X4_CUSTOM_HEADER
 #endif
 
+/* Standard library function replacements */
+#if !defined(__ASSEMBLER__)
+#if !defined(MLK_CONFIG_CUSTOM_MEMCPY)
+#include <string.h>
+#define mlk_memcpy memcpy
+#endif
+
+#if !defined(MLK_CONFIG_CUSTOM_MEMSET)
+#include <string.h>
+#define mlk_memset memset
+#endif
+#endif /* !__ASSEMBLER__ */
+
 /* Just in case we want to include mlkem_native.h, set the configuration
  * for that header in accordance with the configuration used here. */
 

mlkem/src/config.h

@@ -311,6 +311,52 @@
    #endif
 */
 
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_MEMCPY
+ *
+ * Description: Set this option and define `mlk_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 *mlk_memcpy(void *dest, const void *src, size_t n)
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_MEMCPY
+   #if !defined(__ASSEMBLER__)
+   #include <stdint.h>
+   #include "sys.h"
+   static MLK_INLINE void *mlk_memcpy(void *dest, const void *src, size_t n)
+   {
+       ... your implementation ...
+   }
+   #endif
+*/
+
+/******************************************************************************
+ * Name:        MLK_CONFIG_CUSTOM_MEMSET
+ *
+ * Description: Set this option and define `mlk_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 *mlk_memset(void *s, int c, size_t n)
+ *
+ *****************************************************************************/
+/* #define MLK_CONFIG_CUSTOM_MEMSET
+   #if !defined(__ASSEMBLER__)
+   #include <stdint.h>
+   #include "sys.h"
+   static MLK_INLINE void *mlk_memset(void *s, int c, size_t n)
+   {
+       ... your implementation ...
+   }
+   #endif
+*/
+
 /******************************************************************************
  * Name:        MLK_CONFIG_INTERNAL_API_QUALIFIER
  *