Examples: Add example for restartable signing via signing hooks

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

Author: hanno-becker

.github/actions/config-variations/action.yml

@@ -36,7 +36,9 @@ runs:
         sign_hook: false # SIGN_HOOK_RESUME is incompatible with KEYGEN_PCT
         opt: ${{ inputs.opt }}
         examples: true
-        extra_args: "--exclude-example basic_deterministic"
+        # basic_deterministic and restartable_sign set MLD_CONFIG_NO_RANDOMIZED_API,
+        # which is incompatible with MLD_CONFIG_KEYGEN_PCT.
+        extra_args: "--exclude-example basic_deterministic --exclude-example restartable_sign"
     - name: "REDUCE_RAM"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'reduce-ram') }}
       uses: ./.github/actions/multi-functest
@@ -66,7 +68,9 @@ runs:
         sign_hook: false # SIGN_HOOK_RESUME is incompatible with KEYGEN_PCT
         opt: ${{ inputs.opt }}
         examples: true
-        extra_args: "--exclude-example basic_deterministic"
+        # basic_deterministic and restartable_sign set MLD_CONFIG_NO_RANDOMIZED_API,
+        # which is incompatible with MLD_CONFIG_KEYGEN_PCT.
+        extra_args: "--exclude-example basic_deterministic --exclude-example restartable_sign"
     - name: "PCT enabled + broken"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'pct-enabled-broken') }}
       shell: bash

.github/workflows/base.yml

@@ -243,6 +243,9 @@ jobs:
       - name: basic_lowram
         run: |
           CFLAGS="-O0" make run -C examples/basic_lowram
+      - name: restartable_sign
+        run: |
+          CFLAGS="-O0" make run -C examples/restartable_sign
       - name: bring_your_own_fips202
         run: |
           CFLAGS="-O0" make run -C examples/bring_your_own_fips202

examples/README.md

@@ -16,6 +16,13 @@ See [basic_deterministic](basic_deterministic) for a basic example of how to bui
 
 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.
 
+## Restartable signing
+
+See [restartable_sign](restartable_sign) for a minimal example of restartable signing using the signing hooks
+(`MLD_CONFIG_SIGN_HOOK_RESUME` / `_ATTEMPT` / `_FINISH`). It pauses the rejection-sampling loop and resumes it on a
+later call -- bounding per-call runtime while reproducing the same signature as an uninterrupted run -- keeping the
+resume state in a global variable.
+
 ## 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,

examples/restartable_sign/.gitignore

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
+
+build

examples/restartable_sign/Makefile

@@ -0,0 +1,100 @@
+# 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:
+#
+# Your application source code
+APP_SOURCE=$(wildcard *.c)
+
+ALL_SOURCE=$(MLD_SOURCE) $(APP_SOURCE)
+
+BUILD_DIR=build
+BIN=test_binary
+
+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)

examples/restartable_sign/README.md

@@ -0,0 +1,50 @@
+[//]: # (SPDX-License-Identifier: CC-BY-4.0)
+
+
+This directory contains a minimal example of *restartable signing*: pausing the
+ML-DSA rejection-sampling loop and resuming it later, so that each signing call
+has a bounded runtime while the overall result is identical to an uninterrupted
+signature.
+
+## Use Case
+
+ML-DSA signing retries until a candidate signature passes rejection sampling,
+so a single call has an unbounded runtime. On a system with strict timing
+constraints you may want to cap the work done per call and continue later.
+The signing hooks let you do that while retaining functional equivalence to
+an uninterrupted ML-DSA signature operation.
+
+## Configuration
+
+The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
+- `MLD_CONFIG_SIGN_HOOK_RESUME` / `_ATTEMPT` / `_FINISH`: the three hooks around
+  the rejection-sampling loop. The attempt hook may pause signing (which then
+  returns `MLD_ERR_SIGNING_PAUSED`); the resume hook continues from the paused
+  attempt on the next call.
+- `MLD_CONFIG_NO_RANDOMIZED_API`: resuming is only sound when the randomness is
+  fixed across calls, so the caller drives the deterministic internal API.
+- `MLD_CONFIG_NAMESPACE_PREFIX`: Symbol prefix (set to `mldsa`)
+
+## Resume state: global vs. context
+
+This example keeps the resume state in a **global variable**, so the hooks take
+no arguments beyond the attempt counter. That is the simplest integration and
+suits a single-threaded caller signing one message at a time.
+
+For concurrent or interleaved signing, keep the state **per caller** instead:
+enable `MLD_CONFIG_CONTEXT_PARAMETER`, give it your state type, and every public
+API function gains a trailing context argument that is forwarded to the hooks.
+See [test/src/test_sign_hook.c](../../test/src/test_sign_hook.c) for that
+variant.
+
+## Notes
+
+- This is incompatible with `MLD_CONFIG_KEYGEN_PCT` (pairwise consistency test):
+  the PCT runs a single internal signature that cannot be resumed.
+
+## Usage
+
+```bash
+make build   # Build the example
+make run     # Run the example
+```

examples/restartable_sign/auto.mk

@@ -0,0 +1 @@
+../../test/mk/auto.mk

examples/restartable_sign/expected_test_vectors.h

@@ -0,0 +1 @@
+../../test/test_vectors/expected_test_vectors.h