sign: Add configurable signing hooks (resume/attempt/finish)

Add three optional, independently configurable hooks into the ML-DSA
signing rejection-sampling loop, declared in context.h and reached from
sign.c via the names mld_sign_resume / mld_sign_attempt / mld_sign_finish.
Each appends (or drops) the trailing context argument via
MLD_CONTEXT_PARAMETERS_n, and is callable with or without
MLD_CONFIG_CONTEXT_PARAMETER.

  - MLD_CONFIG_SIGN_HOOK_RESUME: mld_sign_hook_resume() returns the nonce to
    resume from, making signing resumable. Combined with a small
    MLD_CONFIG_MAX_SIGNING_ATTEMPTS bound, a timing-constrained caller can
    keep a predictable per-call runtime and, on MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED,
    re-invoke signing to continue -- producing the bit-for-bit FIPS 204
    signature without a non-compliant attempt cap. Requires
    MLD_CONFIG_NO_RANDOMIZED_API, since resuming is only sound with fixed rnd.
  - MLD_CONFIG_SIGN_HOOK_ATTEMPT: mld_sign_hook_attempt(nonce) is called once
    per attempt. Observe-only (logging/benchmarking); randomized-API compatible.
  - MLD_CONFIG_SIGN_HOOK_FINISH: mld_sign_hook_finish() is called on success.
    Observe-only; randomized-API compatible.

When an option is unset the corresponding hook is a no-op (resume -> 0),
leaving the default build -- and, with all three unset, its proofs --
byte-for-byte unchanged. The hooks carry CBMC contracts; add trivial proofs
for each and use them by contract in the sign_signature_internal and
attempt_signature_generation proofs. Add examples/restartable_sign
demonstrating resumption under per-call attempt budgets of 1/2/4.

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

Author: hanno-becker

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

@@ -35,7 +35,7 @@ runs:
         acvp: true
         opt: ${{ inputs.opt }}
         examples: true
-        extra_args: "--exclude-example basic_deterministic"
+        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
@@ -64,7 +64,7 @@ runs:
         alloc: true
         opt: ${{ inputs.opt }}
         examples: true
-        extra_args: "--exclude-example basic_deterministic"
+        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

@@ -233,6 +233,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

BIBLIOGRAPHY.md

@@ -82,6 +82,7 @@ source code and documentation.
   - [examples/monolithic_build_native/mldsa_native/mldsa_native_config.h](examples/monolithic_build_native/mldsa_native/mldsa_native_config.h)
   - [examples/multilevel_build/mldsa_native/mldsa_native_config.h](examples/multilevel_build/mldsa_native/mldsa_native_config.h)
   - [examples/multilevel_build_native/mldsa_native/mldsa_native_config.h](examples/multilevel_build_native/mldsa_native/mldsa_native_config.h)
+  - [examples/restartable_sign/mldsa_native/mldsa_native_config.h](examples/restartable_sign/mldsa_native/mldsa_native_config.h)
   - [integration/liboqs/config_aarch64.h](integration/liboqs/config_aarch64.h)
   - [integration/liboqs/config_c.h](integration/liboqs/config_c.h)
   - [integration/liboqs/config_x86_64.h](integration/liboqs/config_x86_64.h)
@@ -133,6 +134,7 @@ source code and documentation.
   - [examples/monolithic_build_native/mldsa_native/mldsa_native_config.h](examples/monolithic_build_native/mldsa_native/mldsa_native_config.h)
   - [examples/multilevel_build/mldsa_native/mldsa_native_config.h](examples/multilevel_build/mldsa_native/mldsa_native_config.h)
   - [examples/multilevel_build_native/mldsa_native/mldsa_native_config.h](examples/multilevel_build_native/mldsa_native/mldsa_native_config.h)
+  - [examples/restartable_sign/mldsa_native/mldsa_native_config.h](examples/restartable_sign/mldsa_native/mldsa_native_config.h)
   - [mldsa/mldsa_native.h](mldsa/mldsa_native.h)
   - [mldsa/mldsa_native_config.h](mldsa/mldsa_native_config.h)
   - [mldsa/src/ct.h](mldsa/src/ct.h)

Makefile

@@ -297,6 +297,7 @@ EXAMPLE_DIRS := \
 	examples/basic \
 	examples/basic_deterministic \
 	examples/basic_lowram \
+	examples/restartable_sign \
 	examples/monolithic_build \
 	examples/monolithic_build_native \
 	examples/monolithic_build_multilevel \

examples/README.md

@@ -16,6 +16,10 @@ 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 an example of how to bound the per-call signing time while staying FIPS 204 compliant, by making signing restartable: each call performs at most `MLD_CONFIG_MAX_SIGNING_ATTEMPTS` rejection-sampling iterations and, on exhaustion, the caller resumes the operation (via the `MLD_CONFIG_SIGN_HOOK_*` hooks). This is useful in timing-constrained environments.
+
 ## 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/basic_deterministic/mldsa_native/mldsa_native_config.h

@@ -714,24 +714,142 @@
 /**
  * MLD_CONFIG_CONTEXT_PARAMETER
  *
- * Set this to add a context parameter that is provided to public
- * API functions and is then available in custom callbacks.
- *
- * The type of the context parameter is configured via
- * MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ * Set this to add a caller-supplied context parameter to the public API
+ * functions, which is then forwarded unchanged to the custom callbacks
+ * (allocation, and the restartable-signing hooks below).
+ *
+ * When this option is set, every public API function gains a trailing
+ * parameter
+ *
+ *   MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
+ *
+ * as its last argument; its type is configured via
+ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this
+ * value as opaque: it never dereferences it and only passes it on to the
+ * configurable hook macros. It is meant to carry per-caller state -- e.g. a
+ * pointer to a memory pool for the allocation hooks, or the resume state for
+ * the restartable-signing hooks -- into those hooks.
+ *
+ * When this option is unset (the default), no extra parameter is added and
+ * the hook macros never receive a context argument.
+ *
+ * Memory-allocation hooks (MLD_ALLOC / MLD_FREE):
+ *
+ *   Internally, mldsa-native allocates and releases its large temporary
+ *   buffers via two macros, MLD_ALLOC(v, T, N, context) and
+ *   MLD_FREE(v, T, N, context), where `v` is the pointer variable to
+ *   declare/clear, `T` its element type, and `N` the element count. By
+ *   default these allocate `N` elements of type `T` on the stack and, on
+ *   free, zeroize the buffer. If MLD_CONFIG_CUSTOM_ALLOC_FREE is set, they
+ *   instead expand to the user-provided MLD_CUSTOM_ALLOC / MLD_CUSTOM_FREE,
+ *   forwarding `context` as the extra argument when (and only when)
+ *   MLD_CONFIG_CONTEXT_PARAMETER is set. This is the mechanism by which a
+ *   caller's allocator gains access to per-call state. See
+ *   MLD_CONFIG_CUSTOM_ALLOC_FREE for the macro signatures.
+ *
+ * Signing hooks (mld_sign_hook_resume / _attempt / _finish):
+ *
+ *   The MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH options let signing
+ *   call into caller-provided functions around its rejection-sampling loop.
+ *   Each takes `context` only if MLD_CONFIG_CONTEXT_PARAMETER is also set (the
+ *   context is then its last argument); otherwise it takes no context. See
+ *   those options below for the full contract.
  */
 /* #define MLD_CONFIG_CONTEXT_PARAMETER */
 
 /**
  * MLD_CONFIG_CONTEXT_PARAMETER_TYPE
  *
- * Set this to define the type for the context parameter used by
- * MLD_CONFIG_CONTEXT_PARAMETER.
+ * Set this to define the type of the context parameter added by
+ * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function
+ * parameter, e.g. `void *` or a pointer to a caller-defined struct such as
+ * `struct my_ctx *`.
  *
- * This is only relevant if MLD_CONFIG_CONTEXT_PARAMETER is set.
+ * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is
+ * defined; defining one without the other is a compile-time error.
  */
 /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */
 
+/**
+ * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH
+ *
+ * Three optional, independently configurable hooks into the ML-DSA signing
+ * rejection-sampling loop. Each is enabled by defining the matching option, in
+ * which case the integration MUST provide the corresponding function. The
+ * functions are level-generic (one set serves all parameter sets).
+ *
+ * If a hook needs per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the
+ * context is then appended as the LAST argument to each function. Otherwise the
+ * functions take no context argument. Either way they must be callable for
+ * every parameter set in the build.
+ *
+ *   MLD_CONFIG_SIGN_HOOK_RESUME
+ *     uint16_t mld_sign_hook_resume([context])
+ *
+ *     Returns the nonce (rejection-sampling counter) to resume the signing
+ *     operation from; must be 0 at the start of a fresh operation. This makes
+ *     signing *resumable*: combined with a small
+ * MLD_CONFIG_MAX_SIGNING_ATTEMPTS bound, each call performs at most that many
+ * further attempts and, on MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED, the caller
+ * re-invokes signing -- with the *same* message, sk and rnd -- to continue from
+ * the recorded nonce. No attempt is repeated or skipped, so the result is
+ * bit-for-bit the FIPS 204 signature, while each call has a bounded,
+ * predictable runtime. This lets a timing-constrained caller keep a small
+ * per-call bound *and* stay FIPS 204 compliant (a bound < 814 is otherwise
+ * non-compliant, as signing could give up on a message it should have signed).
+ *
+ *     Because resuming only yields the correct signature if the randomness is
+ *     fixed across calls, this option requires MLD_CONFIG_NO_RANDOMIZED_API (a
+ *     compile-time error is raised otherwise): the caller drives signing via
+ * the deterministic internal API and supplies `rnd` itself. Resuming is only
+ *     sound for the deterministic variants mld_sign_signature_internal and
+ *     mld_sign_signature_extmu.
+ *
+ *   MLD_CONFIG_SIGN_HOOK_ATTEMPT
+ *     void mld_sign_hook_attempt(uint16_t nonce[, context])
+ *
+ *     Called once per signing attempt, with the current nonce, before the
+ *     attempt runs. Observe-only -- useful for logging or benchmarking
+ *     individual attempts. A resumable integration may also use it to record
+ *     `nonce + 1` as the next resume point. It does not affect the result and
+ * is compatible with the randomized API.
+ *
+ *   MLD_CONFIG_SIGN_HOOK_FINISH
+ *     void mld_sign_hook_finish([context])
+ *
+ *     Called when a signing operation completes successfully. Observe-only (a
+ *     resumable integration typically resets its stored nonce to 0 here);
+ *     compatible with the randomized API.
+ *
+ * When an option is unset, the corresponding hook defaults to a no-op (and
+ * resume to a constant 0), i.e. ordinary one-shot signing.
+ *
+ * @warning These hooks are experimental. Their configuration and signatures may
+ * change at any time.
+ *
+ * See examples/restartable_sign for a complete worked example using all three.
+ */
+/* #define MLD_CONFIG_SIGN_HOOK_RESUME
+   #define MLD_CONFIG_SIGN_HOOK_ATTEMPT
+   #define MLD_CONFIG_SIGN_HOOK_FINISH
+   #if !defined(__ASSEMBLER__)
+   #include <stdint.h>
+   #include "src/sys.h"
+   static MLD_INLINE uint16_t mld_sign_hook_resume(void)
+   {
+       ... return the nonce to resume from ...
+   }
+   static MLD_INLINE void mld_sign_hook_attempt(uint16_t nonce)
+   {
+       ... log the attempt; for resume, store nonce + 1 ...
+   }
+   static MLD_INLINE void mld_sign_hook_finish(void)
+   {
+       ... mark the operation complete ...
+   }
+   #endif
+*/
+
 /**
  * MLD_CONFIG_REDUCE_RAM
  *

examples/basic_lowram/mldsa_native/mldsa_native_config.h

@@ -713,24 +713,142 @@
 /**
  * MLD_CONFIG_CONTEXT_PARAMETER
  *
- * Set this to add a context parameter that is provided to public
- * API functions and is then available in custom callbacks.
- *
- * The type of the context parameter is configured via
- * MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ * Set this to add a caller-supplied context parameter to the public API
+ * functions, which is then forwarded unchanged to the custom callbacks
+ * (allocation, and the restartable-signing hooks below).
+ *
+ * When this option is set, every public API function gains a trailing
+ * parameter
+ *
+ *   MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
+ *
+ * as its last argument; its type is configured via
+ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this
+ * value as opaque: it never dereferences it and only passes it on to the
+ * configurable hook macros. It is meant to carry per-caller state -- e.g. a
+ * pointer to a memory pool for the allocation hooks, or the resume state for
+ * the restartable-signing hooks -- into those hooks.
+ *
+ * When this option is unset (the default), no extra parameter is added and
+ * the hook macros never receive a context argument.
+ *
+ * Memory-allocation hooks (MLD_ALLOC / MLD_FREE):
+ *
+ *   Internally, mldsa-native allocates and releases its large temporary
+ *   buffers via two macros, MLD_ALLOC(v, T, N, context) and
+ *   MLD_FREE(v, T, N, context), where `v` is the pointer variable to
+ *   declare/clear, `T` its element type, and `N` the element count. By
+ *   default these allocate `N` elements of type `T` on the stack and, on
+ *   free, zeroize the buffer. If MLD_CONFIG_CUSTOM_ALLOC_FREE is set, they
+ *   instead expand to the user-provided MLD_CUSTOM_ALLOC / MLD_CUSTOM_FREE,
+ *   forwarding `context` as the extra argument when (and only when)
+ *   MLD_CONFIG_CONTEXT_PARAMETER is set. This is the mechanism by which a
+ *   caller's allocator gains access to per-call state. See
+ *   MLD_CONFIG_CUSTOM_ALLOC_FREE for the macro signatures.
+ *
+ * Signing hooks (mld_sign_hook_resume / _attempt / _finish):
+ *
+ *   The MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH options let signing
+ *   call into caller-provided functions around its rejection-sampling loop.
+ *   Each takes `context` only if MLD_CONFIG_CONTEXT_PARAMETER is also set (the
+ *   context is then its last argument); otherwise it takes no context. See
+ *   those options below for the full contract.
  */
 /* #define MLD_CONFIG_CONTEXT_PARAMETER */
 
 /**
  * MLD_CONFIG_CONTEXT_PARAMETER_TYPE
  *
- * Set this to define the type for the context parameter used by
- * MLD_CONFIG_CONTEXT_PARAMETER.
+ * Set this to define the type of the context parameter added by
+ * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function
+ * parameter, e.g. `void *` or a pointer to a caller-defined struct such as
+ * `struct my_ctx *`.
  *
- * This is only relevant if MLD_CONFIG_CONTEXT_PARAMETER is set.
+ * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is
+ * defined; defining one without the other is a compile-time error.
  */
 /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */
 
+/**
+ * Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH
+ *
+ * Three optional, independently configurable hooks into the ML-DSA signing
+ * rejection-sampling loop. Each is enabled by defining the matching option, in
+ * which case the integration MUST provide the corresponding function. The
+ * functions are level-generic (one set serves all parameter sets).
+ *
+ * If a hook needs per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the
+ * context is then appended as the LAST argument to each function. Otherwise the
+ * functions take no context argument. Either way they must be callable for
+ * every parameter set in the build.
+ *
+ *   MLD_CONFIG_SIGN_HOOK_RESUME
+ *     uint16_t mld_sign_hook_resume([context])
+ *
+ *     Returns the nonce (rejection-sampling counter) to resume the signing
+ *     operation from; must be 0 at the start of a fresh operation. This makes
+ *     signing *resumable*: combined with a small
+ * MLD_CONFIG_MAX_SIGNING_ATTEMPTS bound, each call performs at most that many
+ * further attempts and, on MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED, the caller
+ * re-invokes signing -- with the *same* message, sk and rnd -- to continue from
+ * the recorded nonce. No attempt is repeated or skipped, so the result is
+ * bit-for-bit the FIPS 204 signature, while each call has a bounded,
+ * predictable runtime. This lets a timing-constrained caller keep a small
+ * per-call bound *and* stay FIPS 204 compliant (a bound < 814 is otherwise
+ * non-compliant, as signing could give up on a message it should have signed).
+ *
+ *     Because resuming only yields the correct signature if the randomness is
+ *     fixed across calls, this option requires MLD_CONFIG_NO_RANDOMIZED_API (a
+ *     compile-time error is raised otherwise): the caller drives signing via
+ * the deterministic internal API and supplies `rnd` itself. Resuming is only
+ *     sound for the deterministic variants mld_sign_signature_internal and
+ *     mld_sign_signature_extmu.
+ *
+ *   MLD_CONFIG_SIGN_HOOK_ATTEMPT
+ *     void mld_sign_hook_attempt(uint16_t nonce[, context])
+ *
+ *     Called once per signing attempt, with the current nonce, before the
+ *     attempt runs. Observe-only -- useful for logging or benchmarking
+ *     individual attempts. A resumable integration may also use it to record
+ *     `nonce + 1` as the next resume point. It does not affect the result and
+ * is compatible with the randomized API.
+ *
+ *   MLD_CONFIG_SIGN_HOOK_FINISH
+ *     void mld_sign_hook_finish([context])
+ *
+ *     Called when a signing operation completes successfully. Observe-only (a
+ *     resumable integration typically resets its stored nonce to 0 here);
+ *     compatible with the randomized API.
+ *
+ * When an option is unset, the corresponding hook defaults to a no-op (and
+ * resume to a constant 0), i.e. ordinary one-shot signing.
+ *
+ * @warning These hooks are experimental. Their configuration and signatures may
+ * change at any time.
+ *
+ * See examples/restartable_sign for a complete worked example using all three.
+ */
+/* #define MLD_CONFIG_SIGN_HOOK_RESUME
+   #define MLD_CONFIG_SIGN_HOOK_ATTEMPT
+   #define MLD_CONFIG_SIGN_HOOK_FINISH
+   #if !defined(__ASSEMBLER__)
+   #include <stdint.h>
+   #include "src/sys.h"
+   static MLD_INLINE uint16_t mld_sign_hook_resume(void)
+   {
+       ... return the nonce to resume from ...
+   }
+   static MLD_INLINE void mld_sign_hook_attempt(uint16_t nonce)
+   {
+       ... log the attempt; for resume, store nonce + 1 ...
+   }
+   static MLD_INLINE void mld_sign_hook_finish(void)
+   {
+       ... mark the operation complete ...
+   }
+   #endif
+*/
+
 /**
  * MLD_CONFIG_REDUCE_RAM
  *