Add signing hooks for observing signature attempts and implementing restartable signing

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

@@ -33,9 +33,12 @@ runs:
         func: true
         kat: true
         acvp: true
+        sign_hook: false # Signing hooks require NO_RANDOMIZED_API, 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
@@ -62,9 +65,12 @@ runs:
         kat: true
         acvp: true
         alloc: true
+        sign_hook: false # Signing hooks require NO_RANDOMIZED_API, 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
@@ -107,6 +113,7 @@ runs:
         extra_env: 'ASAN_OPTIONS=detect_leaks=1'
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom zeroization (explicit_bzero)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-zeroize') }}
@@ -122,6 +129,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom native capability functions (static ON)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'native-cap-ON') }}
@@ -137,6 +145,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom native capability functions (static OFF)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'native-cap-OFF') }}
@@ -152,6 +161,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom native capability functions (ID_AA64PFR1_EL1 detection)"
       if: ${{ (inputs.tests == 'all' || contains(inputs.tests, 'native-cap-ID_AA64PFR1_EL1')) && runner.os == 'Linux' && runner.arch == 'ARM64' }}
@@ -167,6 +177,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom native capability functions (CPUID AVX2 detection)"
       if: ${{ (inputs.tests == 'all' || contains(inputs.tests, 'native-cap-CPUID_AVX2')) && runner.os == 'Linux' && runner.arch == 'X64' }}
@@ -182,6 +193,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "No ASM"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'no-asm') }}
@@ -197,6 +209,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Serial FIPS202 (no batched Keccak)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'serial-fips202') }}
@@ -212,6 +225,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom randombytes"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-randombytes') }}
@@ -227,6 +241,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: false # Uses its own randombytes implementation
     - name: "Custom memcpy"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-memcpy') }}
@@ -242,6 +257,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom memset"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-memset') }}
@@ -257,6 +273,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Custom stdlib (memcpy + memset)"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'custom-stdlib') }}
@@ -272,6 +289,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "MLD_POLY_UNIFORM_NBLOCKS=1"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'nblocks-1') }}
@@ -287,6 +305,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "MLD_POLY_UNIFORM_NBLOCKS=4"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'nblocks-4') }}
@@ -302,6 +321,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "MLD_POLY_UNIFORM_NBLOCKS=6"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'nblocks-6') }}
@@ -317,6 +337,7 @@ runs:
         opt: ${{ inputs.opt }}
         examples: false # Some examples use a custom config themselves
         alloc: false # Requires custom config
+        sign_hook: false # Requires custom config
         rng_fail: true
     - name: "Keygen-only API"
       if: ${{ inputs.tests == 'all' || contains(inputs.tests, 'keygen-only') }}

.github/actions/functest/action.yml

@@ -63,6 +63,9 @@ inputs:
   alloc:
     description: Determine whether to run alloc tests or not
     default: "true"
+  sign_hook:
+    description: Determine whether to run sign hook tests or not
+    default: "true"
   rng_fail:
     description: Determine whether to run rng fail tests or not
     default: "true"
@@ -88,6 +91,7 @@ runs:
           echo EXAMPLES="${{ inputs.examples == 'true' && 'examples' || 'no-examples' }}" >> $GITHUB_ENV
           echo STACK="${{ inputs.stack == 'true' && 'stack' || 'no-stack' }}" >> $GITHUB_ENV
           echo ALLOC="${{ inputs.alloc == 'true' && 'alloc' || 'no-alloc' }}" >> $GITHUB_ENV
+          echo SIGN_HOOK="${{ inputs.sign_hook == 'true' && 'sign-hook' || 'no-sign-hook' }}" >> $GITHUB_ENV
           echo RNGFAIL="${{ inputs.rng_fail == 'true' && 'rng-fail' || 'no-rng-fail' }}" >> $GITHUB_ENV
       - name: Setup nix
         uses: ./.github/actions/setup-shell
@@ -119,13 +123,13 @@ runs:
             - $(python3 --version)
             - $(${{ inputs.cross_prefix }}${CC} --version | grep -m1 "")
           EOF
-      - name: ${{ env.MODE }} ${{ inputs.opt }} tests (${{ env.FUNC }}, ${{ env.KAT }}, ${{ env.EXAMPLES }}, ${{ env.STACK }}, ${{ env.UNIT }}, ${{ env.ALLOC }}, ${{ env.RNGFAIL }})
+      - name: ${{ env.MODE }} ${{ inputs.opt }} tests (${{ env.FUNC }}, ${{ env.KAT }}, ${{ env.EXAMPLES }}, ${{ env.STACK }}, ${{ env.UNIT }}, ${{ env.ALLOC }}, ${{ env.SIGN_HOOK }}, ${{ env.RNGFAIL }})
         shell: ${{ env.SHELL }}
         env:
           GH_TOKEN: ${{ inputs.gh_token }}
         run: |
           make clean
-          ${{ inputs.extra_env }} ./scripts/tests all ${{ inputs.check_namespace == 'true' && '--check-namespace' || ''}} --exec-wrapper="${{ inputs.exec_wrapper }}" --cross-prefix="${{ inputs.cross_prefix }}" --cflags="${{ inputs.cflags }}" --ldflags="${{ inputs.ldflags }}" --opt=${{ inputs.opt }} --${{ env.FUNC }} --${{ env.KAT }} --${{ env.ACVP }} --${{ env.WYCHEPROOF }} --${{ env.EXAMPLES }} --${{ env.STACK }} --${{ env.UNIT }} --${{ env.ALLOC }} --${{ env.RNGFAIL }} -v ${{ inputs.extra_args }}
+          ${{ inputs.extra_env }} ./scripts/tests all ${{ inputs.check_namespace == 'true' && '--check-namespace' || ''}} --exec-wrapper="${{ inputs.exec_wrapper }}" --cross-prefix="${{ inputs.cross_prefix }}" --cflags="${{ inputs.cflags }}" --ldflags="${{ inputs.ldflags }}" --opt=${{ inputs.opt }} --${{ env.FUNC }} --${{ env.KAT }} --${{ env.ACVP }} --${{ env.WYCHEPROOF }} --${{ env.EXAMPLES }} --${{ env.STACK }} --${{ env.UNIT }} --${{ env.ALLOC }} --${{ env.SIGN_HOOK }} --${{ env.RNGFAIL }} -v ${{ inputs.extra_args }}
       - name: Post ${{ env.MODE }} Tests
         shell: ${{ env.SHELL }}
         if: success() || failure()

.github/actions/multi-functest/action.yml

@@ -63,6 +63,9 @@ inputs:
   alloc:
     description: Determine whether to run alloc tests or not
     default: "true"
+  sign_hook:
+    description: Determine whether to run sign hook tests or not
+    default: "true"
   rng_fail:
     description: Determine whether to run rng fail tests or not
     default: "true"
@@ -96,6 +99,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
@@ -122,6 +126,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
@@ -148,6 +153,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
@@ -174,6 +180,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
@@ -200,6 +207,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
@@ -226,6 +234,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}
@@ -252,6 +261,7 @@ runs:
           check_namespace: ${{ inputs.check_namespace }}
           stack: ${{ inputs.stack }}
           alloc: ${{ inputs.alloc }}
+          sign_hook: ${{ inputs.sign_hook }}
           rng_fail: ${{ inputs.rng_fail }}
           extra_args: ${{ inputs.extra_args }}
           extra_env: ${{ inputs.extra_env }}

.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

.github/workflows/ci.yml

@@ -435,11 +435,47 @@ jobs:
           stack: false
           unit: true
           alloc: false
+          sign_hook: false # Requires custom config
           rng_fail: false
           check_namespace: false
           # Disable AArch64 SHA3 extension: valgrind cannot emulate it
           extra_env: "MK_COMPILER_SUPPORTS_SHA3=0"
           exec_wrapper: "valgrind --error-exitcode=1"
+  sign_hook_distribution:
+    name: "Sign-hook attempt distribution (${{ matrix.target.name }}, ML-DSA-${{ matrix.level }})"
+    strategy:
+      fail-fast: false
+      # One matrix entry per (architecture, parameter set): each level runs on
+      # its own runner so the three ~9-minute 5M-signature runs proceed in
+      # parallel rather than sequentially.
+      matrix:
+        external:
+         - ${{ github.repository_owner != 'pq-code-package' }}
+        target:
+          - runner: ubuntu-latest
+            name: x86_64
+          - runner: ubuntu-24.04-arm
+            name: aarch64
+        level: [44, 65, 87]
+        exclude:
+          - external: true
+    runs-on: ${{ matrix.target.runner }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      # Fresh random seed each run: the test draws fresh keys and signing
+      # randomness from it, so this samples the attempts-per-signature
+      # distribution anew every time. The seed is printed by the test, so a
+      # failure is reproducible by re-running with the same SIGN_HOOK_SEED.
+      - name: Generate random seed
+        run: echo "SIGN_HOOK_SEED=seed=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
+      - uses: ./.github/actions/setup-shell
+        with:
+          gh_token: ${{ secrets.GITHUB_TOKEN }}
+          nix-shell: 'ci'
+          # At 5,000,000 signatures, a deviation by more than +-0.5% (the 5
+          # per-mille tolerance) is expected with probability < 10^{-30}.
+          script: |
+            CFLAGS=\"-DMLD_SIGN_HOOK_DIST_ITERATIONS=5000000 -DMLD_SIGN_HOOK_RATIO_TOL_PERMILLE=5\" make run_sign_hook_${{ matrix.level }} OPT=1 AUTO=1 -j$(nproc)
   config_variations:
     name: "Config: ${{ matrix.test.name }} (${{ matrix.target.name }})"
     strategy:

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)
@@ -103,6 +104,7 @@ source code and documentation.
   - [test/configs/no_asm_config.h](test/configs/no_asm_config.h)
   - [test/configs/serial_fips202_config.h](test/configs/serial_fips202_config.h)
   - [test/configs/test_alloc_config.h](test/configs/test_alloc_config.h)
+  - [test/configs/test_sign_hook_config.h](test/configs/test_sign_hook_config.h)
 
 ### `FIPS202`
 
@@ -133,6 +135,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)
@@ -166,6 +169,8 @@ source code and documentation.
   - [test/configs/no_asm_config.h](test/configs/no_asm_config.h)
   - [test/configs/serial_fips202_config.h](test/configs/serial_fips202_config.h)
   - [test/configs/test_alloc_config.h](test/configs/test_alloc_config.h)
+  - [test/configs/test_sign_hook_config.h](test/configs/test_sign_hook_config.h)
+  - [test/src/test_sign_hook.c](test/src/test_sign_hook.c)
 
 ### `HYBRID`