diff --git a/BIBLIOGRAPHY.md b/BIBLIOGRAPHY.md index 3b6fd3f5b..731d2350d 100644 --- a/BIBLIOGRAPHY.md +++ b/BIBLIOGRAPHY.md @@ -24,6 +24,7 @@ source code and documentation. * URL: https://csrc.nist.gov/projects/cryptographic-module-validation-program/fips-140-3-ig-announcements * Referenced from: - [examples/basic_deterministic/mldsa_native/mldsa_native_config.h](examples/basic_deterministic/mldsa_native/mldsa_native_config.h) + - [examples/basic_lowram/mldsa_native/mldsa_native_config.h](examples/basic_lowram/mldsa_native/mldsa_native_config.h) - [examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h) - [examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h) - [examples/custom_backend/mldsa_native/mldsa_native_config.h](examples/custom_backend/mldsa_native/mldsa_native_config.h) @@ -72,6 +73,7 @@ source code and documentation. * Referenced from: - [README.md](README.md) - [examples/basic_deterministic/mldsa_native/mldsa_native_config.h](examples/basic_deterministic/mldsa_native/mldsa_native_config.h) + - [examples/basic_lowram/mldsa_native/mldsa_native_config.h](examples/basic_lowram/mldsa_native/mldsa_native_config.h) - [examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h) - [examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h](examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h) - [examples/custom_backend/mldsa_native/mldsa_native_config.h](examples/custom_backend/mldsa_native/mldsa_native_config.h) diff --git a/Makefile b/Makefile index 33bf3f7be..49ce3b2de 100644 --- a/Makefile +++ b/Makefile @@ -257,6 +257,7 @@ EXAMPLE_DIRS := \ examples/custom_backend \ examples/basic \ examples/basic_deterministic \ + examples/basic_lowram \ examples/monolithic_build \ examples/monolithic_build_native \ examples/monolithic_build_multilevel \ diff --git a/README.md b/README.md index 1983c830d..fc7dfddfd 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,8 @@ make test We use the [C Bounded Model Checker (CBMC)](https://github.com/diffblue/cbmc) to prove absence of various classes of undefined behaviour in C, including out of bounds memory accesses and integer overflows. The proofs cover all C code in [mldsa/src/*](mldsa) and [mldsa/src/fips202/*](mldsa/src/fips202) involved in running mldsa-native with its C backend. See [proofs/cbmc](proofs/cbmc) for details. +**Note:** The `MLD_CONFIG_REDUCE_RAM` configuration option is not currently covered by CBMC proofs. + HOL-Light functional correctness proofs can be found in [proofs/hol_light/x86_64](proofs/hol_light/x86_64). So far, the following functions have been proven correct: - x86_64 NTT [ntt.S](mldsa/src/native/x86_64/src/ntt.S) diff --git a/examples/README.md b/examples/README.md index afc1758b1..61fac1119 100644 --- a/examples/README.md +++ b/examples/README.md @@ -11,6 +11,11 @@ See [basic](basic) for a basic example of how to build a single instance of mlds ## Basic_deterministic See [basic_deterministic](basic_deterministic) for a basic example of how to build a single instance of mldsa-native without `randombytes()` implementation. This allows users to build mldsa-native using only the deterministic API when randomized functions are not required. + +## Basic_lowram + +See [basic_lowram](basic_lowram) for a basic example of how to build a single instance of mldsa-native with reduced RAM usage (`MLD_CONFIG_REDUCE_RAM`). This is useful for embedded systems with tight RAM constraints. + ## Multi-level build (C only) See [multilevel_build](multilevel_build) for an example of how to build one instance of mldsa-native per security level, diff --git a/examples/basic_deterministic/mldsa_native/mldsa_native_config.h b/examples/basic_deterministic/mldsa_native/mldsa_native_config.h index 6590aeea4..6b72c383b 100644 --- a/examples/basic_deterministic/mldsa_native/mldsa_native_config.h +++ b/examples/basic_deterministic/mldsa_native/mldsa_native_config.h @@ -666,6 +666,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/examples/basic_lowram/.gitignore b/examples/basic_lowram/.gitignore new file mode 100644 index 000000000..14b55464c --- /dev/null +++ b/examples/basic_lowram/.gitignore @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + +build/ diff --git a/examples/basic_lowram/Makefile b/examples/basic_lowram/Makefile new file mode 100644 index 000000000..274ad8ed3 --- /dev/null +++ b/examples/basic_lowram/Makefile @@ -0,0 +1,119 @@ +# Copyright (c) The mlkem-native project authors +# Copyright (c) The mldsa-native project authors +# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + +.PHONY: build run clean +.DEFAULT_GOAL := all + +CC ?= gcc + +# Adjust CFLAGS if needed +CFLAGS := \ + -Wall \ + -Wextra \ + -Werror=unused-result \ + -Wpedantic \ + -Werror \ + -Wmissing-prototypes \ + -Wshadow \ + -Wpointer-arith \ + -Wredundant-decls \ + -Wconversion \ + -Wsign-conversion \ + -Wno-long-long \ + -Wno-unknown-pragmas \ + -Wno-unused-command-line-argument \ + -O3 \ + -fomit-frame-pointer \ + -std=c99 \ + -pedantic \ + -MMD \ + $(CFLAGS) + +# If you want to use the native backends, the compiler needs to know about +# the target architecture. Here, we import the default host detection from +# mldsa-native's tests, but you can write your own or specialize accordingly. +AUTO ?= 1 +include auto.mk + +# The following only concerns the cross-compilation tests. +# You can likely ignore the following for your application. +# +# Append cross-prefix for cross compilation +# When called from the root Makefile, CROSS_PREFIX has already been added here +ifeq (,$(findstring $(CROSS_PREFIX),$(CC))) +CC := $(CROSS_PREFIX)$(CC) +endif + +# Part A: +# +# mldsa-native source and header files +# +# If you are not concerned about minimizing for a specific backend, +# you can just include _all_ source files into your build. +# +# In this example, we compile the individual mldsa-native source files directly. +# Alternatively, you can compile the 'monobuild' source file mldsa_native.c. +# See examples/monolithic_build for that. +MLD_SOURCE=$(wildcard \ + mldsa_native/src/*.c \ + mldsa_native/src/**/*.c \ + mldsa_native/src/**/**/*.c \ + mldsa_native/src/**/**/**/*.c) + +INC=-Imldsa_native + +# Part B: +# +# Random number generator +# +# !!! WARNING !!! +# +# The randombytes() implementation used here is for TESTING ONLY. +# You MUST NOT use this implementation outside of testing. +# +# !!! WARNING !!! +RNG_SOURCE=$(wildcard test_only_rng/*.c) + +# Part C: +# +# Your application source code +APP_SOURCE=$(wildcard *.c) + +ALL_SOURCE=$(MLD_SOURCE) $(RNG_SOURCE) $(APP_SOURCE) + +BUILD_DIR=build +BIN=test_binary + +# +# Configuration adjustments +# + +# Pick prefix +CFLAGS += -DMLD_CONFIG_NAMESPACE_PREFIX=mldsa + +BINARY_NAME_FULL_44=$(BUILD_DIR)/$(BIN)44 +BINARY_NAME_FULL_65=$(BUILD_DIR)/$(BIN)65 +BINARY_NAME_FULL_87=$(BUILD_DIR)/$(BIN)87 +BINARIES_FULL=$(BINARY_NAME_FULL_44) $(BINARY_NAME_FULL_65) $(BINARY_NAME_FULL_87) + +$(BINARY_NAME_FULL_44): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=44 +$(BINARY_NAME_FULL_65): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=65 +$(BINARY_NAME_FULL_87): CFLAGS += -DMLD_CONFIG_PARAMETER_SET=87 + +$(BINARIES_FULL): $(ALL_SOURCE) + echo "$@" + mkdir -p $(BUILD_DIR) + $(CC) $(CFLAGS) $(INC) $^ -o $@ + +all: build + +build: $(BINARIES_FULL) + +run: $(BINARIES_FULL) + $(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_44) + $(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_65) + $(EXEC_WRAPPER) ./$(BINARY_NAME_FULL_87) + +clean: + rm -rf $(BUILD_DIR) diff --git a/examples/basic_lowram/README.md b/examples/basic_lowram/README.md new file mode 100644 index 000000000..eef6c3817 --- /dev/null +++ b/examples/basic_lowram/README.md @@ -0,0 +1,45 @@ +[//]: # (SPDX-License-Identifier: CC-BY-4.0) + +# Low RAM build + +This directory contains a minimal example for how to build mldsa-native with reduced RAM usage. + +## Use Case + +Use this approach when: +- You are building for an embedded system with tight RAM constraints +- You need to minimize stack usage +- Performance is less critical than memory footprint + +## Configuration + +The `MLD_CONFIG_REDUCE_RAM` option enables optimizations that reduce RAM usage: +- Uses unions for major allocations to reduce stack usage +- Trades some performance for lower memory footprint + +## Components + +1. mldsa-native source tree: [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202) +2. A secure random number generator implementing [`randombytes.h`](../../mldsa/src/randombytes.h) +3. Your application source code + +## Configuration + +The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets: +- `MLD_CONFIG_PARAMETER_SET`: Security level (44, 65, or 87). Default is 65. +- `MLD_CONFIG_NAMESPACE_PREFIX`: Symbol prefix for the API. Set to `mldsa` in this example. +- `MLD_CONFIG_REDUCE_RAM`: Enables reduced RAM usage optimizations. + +To change the security level, modify `MLD_CONFIG_PARAMETER_SET` in the config file or pass it via CFLAGS. + +## Usage + +```bash +make build # Build the example +make run # Run the example +``` + +## Warning + +The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY. +You MUST provide a cryptographically secure RNG for production use. diff --git a/examples/basic_lowram/auto.mk b/examples/basic_lowram/auto.mk new file mode 120000 index 000000000..ce5c161cb --- /dev/null +++ b/examples/basic_lowram/auto.mk @@ -0,0 +1 @@ +../../test/mk/auto.mk \ No newline at end of file diff --git a/examples/basic_lowram/expected_signatures.h b/examples/basic_lowram/expected_signatures.h new file mode 120000 index 000000000..694d65628 --- /dev/null +++ b/examples/basic_lowram/expected_signatures.h @@ -0,0 +1 @@ +../basic/expected_signatures.h \ No newline at end of file diff --git a/examples/basic_lowram/main.c b/examples/basic_lowram/main.c new file mode 100644 index 000000000..727869036 --- /dev/null +++ b/examples/basic_lowram/main.c @@ -0,0 +1,135 @@ +/* + * Copyright (c) The mldsa-native project authors + * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + */ + +#include +#include +#include +#include + +/* Import public mldsa-native API + * + * This requires specifying the parameter set and namespace prefix + * used for the build. + */ +#include +#include "expected_signatures.h" +#include "test_only_rng/notrandombytes.h" + +#define CHECK(x) \ + do \ + { \ + int rc; \ + rc = (x); \ + if (!rc) \ + { \ + fprintf(stderr, "ERROR (%s,%d)\n", __FILE__, __LINE__); \ + return 1; \ + } \ + } while (0) + +#define TEST_MSG \ + "This is a test message for ML-DSA digital signature algorithm!" +#define TEST_MSG_LEN (sizeof(TEST_MSG) - 1) + +#define TEST_CTX "test_context_123" +#define TEST_CTX_LEN (sizeof(TEST_CTX) - 1) + +int main(void) +{ + const char test_msg[] = TEST_MSG; + const char test_ctx[] = TEST_CTX; + + uint8_t pk[CRYPTO_PUBLICKEYBYTES]; + uint8_t sk[CRYPTO_SECRETKEYBYTES]; + uint8_t sig[CRYPTO_BYTES]; + uint8_t sm[TEST_MSG_LEN + CRYPTO_BYTES]; /* signed message buffer */ + uint8_t m2[TEST_MSG_LEN + CRYPTO_BYTES]; /* recovered message buffer */ + size_t siglen; + size_t smlen; + size_t mlen; + + /* WARNING: Test-only + * Normally, you would want to seed a PRNG with trustworthy entropy here. */ + randombytes_reset(); + + printf("ML-DSA-%d Low RAM Example\n", MLD_CONFIG_PARAMETER_SET); + printf("========================\n\n"); + + printf("Message: %s\n", test_msg); + printf("Context: %s\n\n", test_ctx); + + printf("Generating keypair ... "); + + /* Alice generates a public/private key pair */ + CHECK(crypto_sign_keypair(pk, sk) == 0); + + printf("DONE\n"); + printf("Signing message... "); + + /* Alice signs the message */ + CHECK(crypto_sign_signature(sig, &siglen, (const uint8_t *)test_msg, + TEST_MSG_LEN, (const uint8_t *)test_ctx, + TEST_CTX_LEN, sk) == 0); + + printf("DONE\n"); + printf("Verifying signature... "); + + /* Bob verifies Alice's signature */ + CHECK(crypto_sign_verify(sig, siglen, (const uint8_t *)test_msg, TEST_MSG_LEN, + (const uint8_t *)test_ctx, TEST_CTX_LEN, pk) == 0); + + printf("DONE\n"); + printf("Creating signed message... "); + + /* Alternative API: Create a signed message (signature + message combined) */ + CHECK(crypto_sign(sm, &smlen, (const uint8_t *)test_msg, TEST_MSG_LEN, + (const uint8_t *)test_ctx, TEST_CTX_LEN, sk) == 0); + + printf("DONE\n"); + printf("Opening signed message... "); + + /* Bob opens the signed message to recover the original message */ + CHECK(crypto_sign_open(m2, &mlen, sm, smlen, (const uint8_t *)test_ctx, + TEST_CTX_LEN, pk) == 0); + + printf("DONE\n"); + printf("Compare messages... "); + + /* Verify the recovered message matches the original */ + CHECK(mlen == TEST_MSG_LEN); + CHECK(memcmp(test_msg, m2, TEST_MSG_LEN) == 0); + + printf("DONE\n\n"); + + printf("Results:\n"); + printf("--------\n"); + printf("Public key size: %d bytes\n", CRYPTO_PUBLICKEYBYTES); + printf("Secret key size: %d bytes\n", CRYPTO_SECRETKEYBYTES); + printf("Signature size: %d bytes\n", CRYPTO_BYTES); + printf("Message length: %lu bytes\n", (unsigned long)TEST_MSG_LEN); + printf("Signature length: %lu bytes\n", (unsigned long)siglen); + printf("Signed msg length: %lu bytes\n", (unsigned long)smlen); + +#if !defined(MLD_CONFIG_KEYGEN_PCT) + /* Check against expected signature to make sure that + * we integrated the library correctly */ + printf("Checking deterministic signature... "); + { + /* Compare the generated signature directly against the expected signature + */ + CHECK(siglen == sizeof(expected_signature)); + CHECK(memcmp(sig, expected_signature, siglen) == 0); + } + printf("DONE\n"); +#else /* !MLD_CONFIG_KEYGEN_PCT */ + printf( + "[WARNING] Skipping KAT test since PCT is enabled and modifies PRNG\n"); +#endif /* MLD_CONFIG_KEYGEN_PCT */ + + printf("Signature verification completed successfully!\n"); + + printf("\nAll tests passed! ML-DSA signature verification successful.\n"); + return 0; +} diff --git a/examples/basic_lowram/mldsa_native/mldsa_native.h b/examples/basic_lowram/mldsa_native/mldsa_native.h new file mode 120000 index 000000000..f25191336 --- /dev/null +++ b/examples/basic_lowram/mldsa_native/mldsa_native.h @@ -0,0 +1 @@ +../../../mldsa/mldsa_native.h \ No newline at end of file diff --git a/examples/basic_lowram/mldsa_native/mldsa_native_config.h b/examples/basic_lowram/mldsa_native/mldsa_native_config.h new file mode 100644 index 000000000..e28bb4e56 --- /dev/null +++ b/examples/basic_lowram/mldsa_native/mldsa_native_config.h @@ -0,0 +1,716 @@ +/* + * 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 + */ + +/* + * WARNING: This file is auto-generated from scripts/autogen + * in the mldsa-native repository. + * Do not modify it directly. + */ + +/* + * Test configuration: Configuration for low RAM build of mldsa-native + * + * This configuration differs from the default mldsa/mldsa_native_config.h in + * the following places: + * - MLD_CONFIG_NAMESPACE_PREFIX + * - MLD_CONFIG_REDUCE_RAM + */ + + +#ifndef MLD_CONFIG_H +#define MLD_CONFIG_H + +/****************************************************************************** + * Name: MLD_CONFIG_PARAMETER_SET + * + * Description: 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 + +/****************************************************************************** + * Name: MLD_CONFIG_FILE + * + * Description: 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 + * then 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. + * + *****************************************************************************/ +/* No need to set this -- we _are_ already in a custom config */ +/* #define MLD_CONFIG_FILE "mldsa_native_config.h" */ + +/****************************************************************************** + * Name: MLD_CONFIG_NAMESPACE_PREFIX + * + * Description: 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. + * + *****************************************************************************/ +#define MLD_CONFIG_NAMESPACE_PREFIX mldsa + +/****************************************************************************** + * Name: MLD_CONFIG_MULTILEVEL_BUILD + * + * Description: 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_EXTERNAL_API_QUALIFIER + * + * Description: 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_NO_RANDOMIZED_API + * + * Description: If this option is set, mldsa-native will be built without the + * randomized API functions (crypto_sign_keypair, + * crypto_sign, crypto_sign_signature, and + * crypto_sign_signature_extmu). + * This allows users to build mldsa-native without providing a + * randombytes() implementation if they only need the + * internal deterministic API + * (crypto_sign_keypair_internal, crypto_sign_signature_internal). + * + * NOTE: This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * as the current PCT implementation requires + * crypto_sign_signature(). + * + *****************************************************************************/ +/* #define MLD_CONFIG_NO_RANDOMIZED_API */ + +/****************************************************************************** + * Name: MLD_CONFIG_NO_SUPERCOP + * + * Description: By default, mldsa_native.h exposes the mldsa-native API in the + * SUPERCOP naming convention (crypto_sign_xxx). If you don't need + * this, set MLD_CONFIG_NO_SUPERCOP. + * + * NOTE: You must set this for a multi-level build as the SUPERCOP + * naming does not disambiguate between the parameter sets. + * + *****************************************************************************/ +/* #define MLD_CONFIG_NO_SUPERCOP */ + +/****************************************************************************** + * Name: MLD_CONFIG_CONSTANTS_ONLY + * + * Description: 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) +/****************************************************************************** + * Name: MLD_CONFIG_MULTILEVEL_WITH_SHARED + * + * Description: 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: TODO: add example + * + * 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. + * + * See examples/multilevel_build_mldsa for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLD_CONFIG_MULTILEVEL_WITH_SHARED */ + +/****************************************************************************** + * Name: MLD_CONFIG_MULTILEVEL_NO_SHARED + * + * Description: 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. + * + * See examples/multilevel_build_mldsa for an example. + * + * This can also be set using CFLAGS. + * + *****************************************************************************/ +/* #define MLD_CONFIG_MULTILEVEL_NO_SHARED */ + +/****************************************************************************** + * Name: MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS + * + * Description: 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 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_USE_NATIVE_BACKEND_ARITH + * + * Description: Determines whether an 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 use is + * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * unset, the default backend for your the 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 + +/****************************************************************************** + * Name: MLD_CONFIG_ARITH_BACKEND_FILE + * + * Description: 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 + +/****************************************************************************** + * Name: MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 + * + * Description: Determines whether an 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 use is + * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * unset, the default backend for your the 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 + +/****************************************************************************** + * Name: MLD_CONFIG_FIPS202_BACKEND_FILE + * + * Description: 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 + +/****************************************************************************** + * Name: MLD_CONFIG_FIPS202_CUSTOM_HEADER + * + * Description: 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" */ + +/****************************************************************************** + * Name: MLD_CONFIG_FIPS202X4_CUSTOM_HEADER + * + * Description: 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" */ + +/****************************************************************************** + * Name: MLD_CONFIG_CUSTOM_ZEROIZE + * + * Description: In compliance with @[FIPS204, Section 3.6.3], mldsa-native, + * zeroizes intermediate stack buffers before returning from + * function calls. + * + * Set this option and define `mld_zeroize_native` if you want to + * use a custom method to zeroize intermediate stack 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_native()`. + * + * WARNING: + * The explicit stack zeroization conducted by mldsa-native + * reduces the likelihood of data leaking on the stack, but + * does not eliminate it! The C standard makes no guarantee about + * where a compiler allocates 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_native to a + * no-op. + * + *****************************************************************************/ +/* #define MLD_CONFIG_CUSTOM_ZEROIZE + #if !defined(__ASSEMBLER__) + #include + #include "src/src.h" + static MLD_INLINE void mld_zeroize_native(void *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLD_CONFIG_CUSTOM_RANDOMBYTES + * + * Description: mldsa-native does not provide a secure randombytes + * implementation. Such an implementation has to provided by the + * consumer. + * + * If this option is not set, mldsa-native expects a function + * void 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 void mld_randombytes(uint8_t *ptr, size_t len) + { + ... your implementation ... + } + #endif +*/ + +/****************************************************************************** + * Name: MLD_CONFIG_CUSTOM_CAPABILITY_FUNC + * + * Description: 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 heteroneous set + * of CPUs to run the resulting binary/library on, feature + * detection at _runtime_ is needed to decided 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. + * + * 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 ... + } +*/ + +/****************************************************************************** + * 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 + #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 + * + * Description: 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 +*/ + +/****************************************************************************** + * Name: MLD_CONFIG_CUSTOM_MEMSET + * + * Description: 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 +*/ + +/****************************************************************************** + * Name: MLD_CONFIG_INTERNAL_API_QUALIFIER + * + * Description: If set, this option provides an additional function + * qualifier to be added to declarations of internal API. + * + * 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_CT_TESTING_ENABLED + * + * Description: 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_NO_ASM + * + * Description: 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 + * and MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * native backends will be used. + * + *****************************************************************************/ +/* #define MLD_CONFIG_NO_ASM */ + +/****************************************************************************** + * Name: MLD_CONFIG_NO_ASM_VALUE_BARRIER + * + * Description: 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_KEYGEN_PCT + * + * Description: 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, crypto_sign_keypair_internal and + * crypto_sign_keypair will return a non-zero error code if the + * PCT failed. + * + * NOTE: This feature will drastically lower the performance of + * key generation. + * + *****************************************************************************/ +/* #define MLD_CONFIG_KEYGEN_PCT */ + +/****************************************************************************** + * Name: MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST + * + * Description: 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 +*/ + +/****************************************************************************** + * Name: MLD_CONFIG_SERIAL_FIPS202_ONLY + * + * Description: 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 */ + +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +#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 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/examples/basic_lowram/mldsa_native/src b/examples/basic_lowram/mldsa_native/src new file mode 120000 index 000000000..4ae7cf76f --- /dev/null +++ b/examples/basic_lowram/mldsa_native/src @@ -0,0 +1 @@ +../../../mldsa/src \ No newline at end of file diff --git a/examples/basic_lowram/test_only_rng b/examples/basic_lowram/test_only_rng new file mode 120000 index 000000000..440411ebf --- /dev/null +++ b/examples/basic_lowram/test_only_rng @@ -0,0 +1 @@ +../basic/test_only_rng \ No newline at end of file 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 9541b8a2f..940ee34dd 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 @@ -666,6 +666,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ 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 8232566d0..ebcf745ec 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 @@ -667,6 +667,30 @@ *****************************************************************************/ #define MLD_CONFIG_SERIAL_FIPS202_ONLY +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/examples/custom_backend/mldsa_native/mldsa_native_config.h b/examples/custom_backend/mldsa_native/mldsa_native_config.h index ca6b695b3..8eacc2fb7 100644 --- a/examples/custom_backend/mldsa_native/mldsa_native_config.h +++ b/examples/custom_backend/mldsa_native/mldsa_native_config.h @@ -662,6 +662,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/examples/monolithic_build/mldsa_native/mldsa_native_config.h b/examples/monolithic_build/mldsa_native/mldsa_native_config.h index 81d479879..83024baf6 100644 --- a/examples/monolithic_build/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build/mldsa_native/mldsa_native_config.h @@ -665,6 +665,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ 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 3895fb138..9fc368086 100644 --- a/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h @@ -666,6 +666,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ 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 10ea4c9dd..f9a6534ca 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 @@ -673,6 +673,30 @@ static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ 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 dff2c6333..bb1126874 100644 --- a/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h @@ -665,6 +665,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/examples/multilevel_build/mldsa_native/mldsa_native_config.h b/examples/multilevel_build/mldsa_native/mldsa_native_config.h index 716f820cf..139969d5d 100644 --- a/examples/multilevel_build/mldsa_native/mldsa_native_config.h +++ b/examples/multilevel_build/mldsa_native/mldsa_native_config.h @@ -665,6 +665,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ 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 ef5a0b048..b4c671e89 100644 --- a/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h +++ b/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h @@ -663,6 +663,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/mldsa/mldsa_native.S b/mldsa/mldsa_native.S index dc975e0c1..c4d9b3bc2 100644 --- a/mldsa/mldsa_native.S +++ b/mldsa/mldsa_native.S @@ -215,6 +215,7 @@ #undef MLD_NAMESPACE_KL #undef MLD_NAMESPACE_PREFIX #undef MLD_NAMESPACE_PREFIX_KL +#undef MLK_UNION_OR_STRUCT #undef mld_memcpy #undef mld_memset /* mldsa/src/packing.h */ diff --git a/mldsa/mldsa_native.c b/mldsa/mldsa_native.c index 9a9961c06..46c094090 100644 --- a/mldsa/mldsa_native.c +++ b/mldsa/mldsa_native.c @@ -211,6 +211,7 @@ #undef MLD_NAMESPACE_KL #undef MLD_NAMESPACE_PREFIX #undef MLD_NAMESPACE_PREFIX_KL +#undef MLK_UNION_OR_STRUCT #undef mld_memcpy #undef mld_memset /* mldsa/src/packing.h */ diff --git a/mldsa/mldsa_native_config.h b/mldsa/mldsa_native_config.h index 60e229b83..3bce1a4e2 100644 --- a/mldsa/mldsa_native_config.h +++ b/mldsa/mldsa_native_config.h @@ -650,6 +650,30 @@ *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/mldsa/src/common.h b/mldsa/src/common.h index 8ddd2a732..02a73a8e5 100644 --- a/mldsa/src/common.h +++ b/mldsa/src/common.h @@ -205,6 +205,20 @@ #endif /* MLD_CONFIG_CUSTOM_ALLOC_FREE */ +/* + * We are facing severe CBMC performance issues when using unions. + * As a temporary workaround, we use unions only when MLD_CONFIG_REDUCE_RAM is + * set. + * TODO: Remove the workaround once + * https://github.com/diffblue/cbmc/issues/8813 + * is resolved + */ +#if defined(MLD_CONFIG_REDUCE_RAM) +#define MLK_UNION_OR_STRUCT union +#else +#define MLK_UNION_OR_STRUCT struct +#endif + /****************************** Error codes ***********************************/ /* Generic failure condition */ diff --git a/mldsa/src/sign.c b/mldsa/src/sign.c index 4dfd19c50..820398df0 100644 --- a/mldsa/src/sign.c +++ b/mldsa/src/sign.c @@ -490,20 +490,32 @@ __contract__( unsigned int n; uint32_t z_invalid, w0_invalid, h_invalid; int ret; + /* TODO: Remove the following workaround for + * https://github.com/diffblue/cbmc/issues/8813 */ + typedef MLK_UNION_OR_STRUCT + { + mld_polyvecl y; + mld_polyveck h; + } + yh_u; + mld_polyvecl *y; + mld_polyveck *h; + MLD_ALLOC(challenge_bytes, uint8_t, MLDSA_CTILDEBYTES); - MLD_ALLOC(y, mld_polyvecl, 1); + MLD_ALLOC(yh, yh_u, 1); MLD_ALLOC(z, mld_polyvecl, 1); MLD_ALLOC(w1, mld_polyveck, 1); MLD_ALLOC(w0, mld_polyveck, 1); - MLD_ALLOC(h, mld_polyveck, 1); MLD_ALLOC(cp, mld_poly, 1); - if (challenge_bytes == NULL || y == NULL || z == NULL || w1 == NULL || - w0 == NULL || h == NULL || cp == NULL) + if (challenge_bytes == NULL || yh == NULL || z == NULL || w1 == NULL || + w0 == NULL || cp == NULL) { ret = MLD_ERR_OUT_OF_MEMORY; goto cleanup; } + y = &yh->y; + h = &yh->h; /* Sample intermediate vector y */ mld_polyvecl_uniform_gamma1(y, rhoprime, nonce); @@ -616,11 +628,10 @@ __contract__( cleanup: /* @[FIPS204, Section 3.6.3] Destruction of intermediate values. */ MLD_FREE(cp, mld_poly, 1); - MLD_FREE(h, mld_polyveck, 1); MLD_FREE(w0, mld_polyveck, 1); MLD_FREE(w1, mld_polyveck, 1); MLD_FREE(z, mld_polyvecl, 1); - MLD_FREE(y, mld_polyvecl, 1); + MLD_FREE(yh, yh_u, 1); MLD_FREE(challenge_bytes, uint8_t, MLDSA_CTILDEBYTES); return ret; diff --git a/scripts/tests b/scripts/tests index cc28fb752..3d70e623f 100755 --- a/scripts/tests +++ b/scripts/tests @@ -213,6 +213,7 @@ class TEST_TYPES(Enum): BASIC_DETERMINISTIC = 18 UNIT = 19 ALLOC = 20 + BASIC_LOWRAM = 21 def is_benchmark(self): return self in [TEST_TYPES.BENCH, TEST_TYPES.BENCH_COMPONENTS] @@ -234,6 +235,7 @@ class TEST_TYPES(Enum): TEST_TYPES.MULTILEVEL_BUILD, TEST_TYPES.MULTILEVEL_BUILD_NATIVE, TEST_TYPES.BASIC_DETERMINISTIC, + TEST_TYPES.BASIC_LOWRAM, ] @staticmethod @@ -271,6 +273,8 @@ class TEST_TYPES(Enum): return "Example (mldsa-native as code package)" if self == TEST_TYPES.BASIC_DETERMINISTIC: return "Example (mldsa-native as code package without randombytes() implementation)" + if self == TEST_TYPES.BASIC_LOWRAM: + return "Example (mldsa-native with reduced RAM usage)" if self == TEST_TYPES.MONOLITHIC_BUILD: return "Example (monobuild)" if self == TEST_TYPES.MONOLITHIC_BUILD_NATIVE: @@ -301,6 +305,8 @@ class TEST_TYPES(Enum): return "examples/basic" if self == TEST_TYPES.BASIC_DETERMINISTIC: return "examples/basic_deterministic" + if self == TEST_TYPES.BASIC_LOWRAM: + return "examples/basic_lowram" if self == TEST_TYPES.MONOLITHIC_BUILD: return "examples/monolithic_build" if self == TEST_TYPES.MONOLITHIC_BUILD_NATIVE: @@ -338,6 +344,8 @@ class TEST_TYPES(Enum): return "" if self == TEST_TYPES.BASIC_DETERMINISTIC: return "" + if self == TEST_TYPES.BASIC_LOWRAM: + return "" if self == TEST_TYPES.MONOLITHIC_BUILD: return "" if self == TEST_TYPES.MONOLITHIC_BUILD_NATIVE: @@ -1189,6 +1197,7 @@ def cli(): "custom_backend", "basic", "basic_deterministic", + "basic_lowram", "monolithic_build", "monolithic_build_native", "monolithic_build_multilevel", @@ -1254,6 +1263,7 @@ def cli(): "custom_backend", "basic", "basic_deterministic", + "basic_lowram", "monolithic_build", "monolithic_build_native", "monolithic_build_multilevel", diff --git a/test/break_pct_config.h b/test/break_pct_config.h index c6e02fd90..d39c9649b 100644 --- a/test/break_pct_config.h +++ b/test/break_pct_config.h @@ -670,6 +670,30 @@ static MLD_INLINE int mld_break_pct(void) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/configs.yml b/test/configs.yml index 5fed65f52..2e8ba5cf1 100644 --- a/test/configs.yml +++ b/test/configs.yml @@ -397,6 +397,14 @@ configs: MLD_CONFIG_FILE: comment: "/* No need to set this -- we _are_ already in a custom config */" + - path: examples/basic_lowram/mldsa_native/mldsa_native_config.h + description: "Configuration for low RAM build of mldsa-native" + defines: + MLD_CONFIG_NAMESPACE_PREFIX: mldsa + MLD_CONFIG_REDUCE_RAM: true + MLD_CONFIG_FILE: + comment: "/* No need to set this -- we _are_ already in a custom config */" + - path: test/test_alloc_config.h description: "Using custom allocation that can be made fail at specific invocation" defines: diff --git a/test/custom_memcpy_config.h b/test/custom_memcpy_config.h index 24ecd93df..8ca15f7f5 100644 --- a/test/custom_memcpy_config.h +++ b/test/custom_memcpy_config.h @@ -673,6 +673,30 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_memset_config.h b/test/custom_memset_config.h index 50c2c3dec..354ef0c8d 100644 --- a/test/custom_memset_config.h +++ b/test/custom_memset_config.h @@ -672,6 +672,30 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_native_capability_config_0.h b/test/custom_native_capability_config_0.h index 41a2d4946..b5ded334a 100644 --- a/test/custom_native_capability_config_0.h +++ b/test/custom_native_capability_config_0.h @@ -672,6 +672,30 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_native_capability_config_1.h b/test/custom_native_capability_config_1.h index ef11e706d..97060786d 100644 --- a/test/custom_native_capability_config_1.h +++ b/test/custom_native_capability_config_1.h @@ -671,6 +671,30 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_native_capability_config_CPUID_AVX2.h b/test/custom_native_capability_config_CPUID_AVX2.h index d90ed8f42..3cfe23b1b 100644 --- a/test/custom_native_capability_config_CPUID_AVX2.h +++ b/test/custom_native_capability_config_CPUID_AVX2.h @@ -703,6 +703,30 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_native_capability_config_ID_AA64PFR1_EL1.h b/test/custom_native_capability_config_ID_AA64PFR1_EL1.h index 2014b4f00..321ec6b87 100644 --- a/test/custom_native_capability_config_ID_AA64PFR1_EL1.h +++ b/test/custom_native_capability_config_ID_AA64PFR1_EL1.h @@ -690,6 +690,30 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_randombytes_config.h b/test/custom_randombytes_config.h index cb7866b84..4571b07a0 100644 --- a/test/custom_randombytes_config.h +++ b/test/custom_randombytes_config.h @@ -666,6 +666,30 @@ static MLD_INLINE void mld_randombytes(uint8_t *ptr, size_t len) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_stdlib_config.h b/test/custom_stdlib_config.h index 5682d760c..da1524e6e 100644 --- a/test/custom_stdlib_config.h +++ b/test/custom_stdlib_config.h @@ -681,6 +681,30 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/custom_zeroize_config.h b/test/custom_zeroize_config.h index fab10c3f9..3272ff1de 100644 --- a/test/custom_zeroize_config.h +++ b/test/custom_zeroize_config.h @@ -666,6 +666,30 @@ static MLD_INLINE void mld_zeroize_native(void *ptr, size_t len) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/no_asm_config.h b/test/no_asm_config.h index 6396f1454..012ba1700 100644 --- a/test/no_asm_config.h +++ b/test/no_asm_config.h @@ -667,6 +667,30 @@ static MLD_INLINE void mld_zeroize_native(void *ptr, size_t len) *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/serial_fips202_config.h b/test/serial_fips202_config.h index 44298be3e..999262a35 100644 --- a/test/serial_fips202_config.h +++ b/test/serial_fips202_config.h @@ -665,6 +665,30 @@ *****************************************************************************/ #define MLD_CONFIG_SERIAL_FIPS202_ONLY +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */ diff --git a/test/test_alloc_config.h b/test/test_alloc_config.h index dfd922253..a4ea1d967 100644 --- a/test/test_alloc_config.h +++ b/test/test_alloc_config.h @@ -674,6 +674,30 @@ void custom_free(void *p, size_t sz, const char *file, int line, *****************************************************************************/ /* #define MLD_CONFIG_SERIAL_FIPS202_ONLY */ +/****************************************************************************** + * Name: MLD_CONFIG_REDUCE_RAM [EXPERIMENTAL] + * + * Description: Set this to reduce RAM usage. + * + * This configuration option is work in progress. + * + * At present it results the following memory saving in signing + * with no impact on performance: + * - ML-DSA-44: 4 KiB + * - ML-DSA-65: 5 KiB + * - ML-DSA-87: 7 KiB + * + * This option is useful for embedded systems with tight RAM + * constraints but relaxed performance requirements. + * + * WARNING: This option is experimental! + * CBMC proofs do not currently cover this configuration option. + * Its scope and configuration may change at any time. + * + *****************************************************************************/ +/* #define MLD_CONFIG_REDUCE_RAM */ + + /************************* Config internals ********************************/ #endif /* MLD_BUILD_INTERNAL */