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

The runtime of ML-DSA signatures is theoretically unbounded. Even the
bound of max 814 signature attempts -- approved by NIST as lowering the
chance of signing failure below 2^{-256} -- leaves a performance distribution
whose peak percentiles can be unacceptable for constrained systems with
strict timing requirements.

As a remedy, the library already provides a configuration option
MLD_CONFIG_MAX_SIGNING_ATTEMPTS to limit the number of signing attempts.
However, FIPS 204 explicitly forbids lowering the number of signing attempts
below 814, rendering the use of this option in constrained environments
non-compliant.

As a remedy, this commit introduces a facility for _restartable signing_:
In addition to using MLD_CONFIG_MAX_SIGNING_ATTEMPTS, the user can provide
a custom hook for remembering the last signing attempt, and continuing the
next signing call at that point.

More specifically, the idea is to introduce three 'signing hooks'
into the core signature routine:
- `nonce = sign_resume()`: Return the nonce corresponding to the next
  signing attempt. `0` for an initial / non-restartable signing
  operation.
- `sign_attempt(nonce)`: Note the nonce for the next signing attempt.
- `sign_finish(nonce)`: Note the nonce for which signing succeeded.

Here, only `sign_resume()` affects the signing process functionally,
while `sign_attempt()` and `sign_finish()` are passive logging operations.

This approach to restartable signing only works if the consumer works
directly with the internal signing API. If they use the randomized API,
a fresh seed would be chosen even on supposedly restarted signing operations,
leading to non-compliant signatures. The use of a `sign_resume()` hook
is therefore only safe with MLD_CONFIG_NO_RANDOMIZED_API.

In contrast, `sign_attempt` and `sign_finish` are passive, and can safely
be used on their own with any configuration. Indeed, these hooks serve
other uses outside of restartable signing:
- sign_attempt can be used to get finer-grained benchmarks for individual
  signing attempts
- sign_finish can be used to log the number of signing attempts, which
  can be useful again for benchmarking, or for checking the expected
  distribution of signing attempts.

Finally, sign_{resume|attempt|finish} can all be implemented based on
mutable globals, or based on a context. It therefore makes sense to
introduce them under the existing MLD_CONFIG_CONTEXT_PARAMETER
wrapper, which allows functions to be called with or without an
application-specific context pointer.

Taking all these considerations together, here's what the commit changes:

- Add independent MLD_CONFIG_SIGN_HOOK_{RESUME|FINISH|ATTEMPT} configuration
  options for registering signing hooks as above. When set, the user provides
  the following functions, respectively:

  - `nonce = mld_sign_resume([ctx])`: Provide initial or resuming nonce
  - `mld_sign_attempt(nonce [, ctx])`: Log/remember nonce for next attempt
  - `mld_sign_finish(nonce [, ctx])`: Log/remember nonce for successful attempt

- The option can be used with or without MLD_CONFIG_CONTEXT_PARAMETER. If the
  latter is set, the user-provided context will be passed to `mld_sign_xxx`
  as the last argument.

- An example is added illustrating the use of the hooks to implement restartable
  signing.

Note: A consumer might want to use restartable signing with randomized APIs.
This is not natively supported. However, it is expected to be easily implementable
since the components required to build randomized signing from deterministic
signing are all public. Note that resuming additionally requires the consumer
to hold the signing randomness `rnd` fixed across the resumed calls.

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

@@ -712,24 +712,127 @@
 /**
  * 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, independent 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. If a hook needs
+ * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then
+ * appended as the last argument. The functions must be callable for every
+ * parameter set in the build.
+ *
+ * - MLD_CONFIG_SIGN_HOOK_RESUME: uint16_t mld_sign_hook_resume([ctxt])
+ *
+ *   Returns the nonce (rejection-sampling counter) to resume from; 0 for a
+ *   fresh operation. This makes signing resumable: with a small
+ *   MLD_CONFIG_MAX_SIGNING_ATTEMPTS bound, each call performs at most that many
+ *   attempts and, on MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED, the caller re-invokes
+ *   signing -- same message, sk and rnd -- to continue from the recorded nonce.
+ *   No attempt is repeated or skipped, so the result is the bit-for-bit FIPS
+ *   204 signature with bounded per-call runtime, keeping a < 814 bound (which
+ *   is otherwise non-compliant) FIPS 204 compliant. Resuming is only correct if
+ *   the randomness is fixed across calls, so this option requires
+ *   MLD_CONFIG_NO_RANDOMIZED_API and is sound only for the deterministic
+ *   mld_sign_signature_internal / mld_sign_signature_extmu. It is also
+ *   incompatible with MLD_CONFIG_KEYGEN_PCT, whose one-shot internal signature
+ *   cannot be resumed: a consumer needing both must run their own (trivial)
+ *   PCT built from the public API.
+ *
+ * - MLD_CONFIG_SIGN_HOOK_ATTEMPT: void mld_sign_hook_attempt(nonce[, ctxt])
+ *
+ *   Called before each attempt with the current nonce. Observe-only (logging,
+ *   benchmarking; a resumable integration may record nonce + 1 as the next
+ *   resume point) and compatible with any API.
+ *
+ * - MLD_CONFIG_SIGN_HOOK_FINISH: void mld_sign_hook_finish(nonce[, ctxt])
+ *
+ *   Called on success with the succeeding nonce. Observe-only (a resumable
+ *   integration typically resets its stored nonce here) and compatible with
+ *   any API.
+ *
+ * When an option is unset, the hook defaults to a no-op (resume to 0), i.e.
+ * ordinary one-shot signing.
+ *
+ * See examples/restartable_sign for a 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(uint16_t nonce)
+   {
+       ... mark the operation complete (nonce = successful attempt) ...
+   }
+   #endif
+*/
+
 /**
  * MLD_CONFIG_REDUCE_RAM
  *

examples/basic_lowram/mldsa_native/mldsa_native_config.h

@@ -711,24 +711,127 @@
 /**
  * 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, independent 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. If a hook needs
+ * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then
+ * appended as the last argument. The functions must be callable for every
+ * parameter set in the build.
+ *
+ * - MLD_CONFIG_SIGN_HOOK_RESUME: uint16_t mld_sign_hook_resume([ctxt])
+ *
+ *   Returns the nonce (rejection-sampling counter) to resume from; 0 for a
+ *   fresh operation. This makes signing resumable: with a small
+ *   MLD_CONFIG_MAX_SIGNING_ATTEMPTS bound, each call performs at most that many
+ *   attempts and, on MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED, the caller re-invokes
+ *   signing -- same message, sk and rnd -- to continue from the recorded nonce.
+ *   No attempt is repeated or skipped, so the result is the bit-for-bit FIPS
+ *   204 signature with bounded per-call runtime, keeping a < 814 bound (which
+ *   is otherwise non-compliant) FIPS 204 compliant. Resuming is only correct if
+ *   the randomness is fixed across calls, so this option requires
+ *   MLD_CONFIG_NO_RANDOMIZED_API and is sound only for the deterministic
+ *   mld_sign_signature_internal / mld_sign_signature_extmu. It is also
+ *   incompatible with MLD_CONFIG_KEYGEN_PCT, whose one-shot internal signature
+ *   cannot be resumed: a consumer needing both must run their own (trivial)
+ *   PCT built from the public API.
+ *
+ * - MLD_CONFIG_SIGN_HOOK_ATTEMPT: void mld_sign_hook_attempt(nonce[, ctxt])
+ *
+ *   Called before each attempt with the current nonce. Observe-only (logging,
+ *   benchmarking; a resumable integration may record nonce + 1 as the next
+ *   resume point) and compatible with any API.
+ *
+ * - MLD_CONFIG_SIGN_HOOK_FINISH: void mld_sign_hook_finish(nonce[, ctxt])
+ *
+ *   Called on success with the succeeding nonce. Observe-only (a resumable
+ *   integration typically resets its stored nonce here) and compatible with
+ *   any API.
+ *
+ * When an option is unset, the hook defaults to a no-op (resume to 0), i.e.
+ * ordinary one-shot signing.
+ *
+ * See examples/restartable_sign for a 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(uint16_t nonce)
+   {
+       ... mark the operation complete (nonce = successful attempt) ...
+   }
+   #endif
+*/
+
 /**
  * MLD_CONFIG_REDUCE_RAM
  *