Skip to content

Commit ec79a2c

Browse files
hanno-beckerhanno-becker
committed
autogen: Regenerate configs for the signing hooks
Rerun scripts/autogen after the preceding commits, updating various files. Done separately to ease reviewing of the core of the changes. Signed-off-by: Hanno Becker <beckphan@amazon.co.uk>
1 parent 87b4c1e commit ec79a2c

33 files changed

Lines changed: 3196 additions & 192 deletions

File tree

‎BIBLIOGRAPHY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ source code and documentation.
103103
- [test/configs/no_asm_config.h](test/configs/no_asm_config.h)
104104
- [test/configs/serial_fips202_config.h](test/configs/serial_fips202_config.h)
105105
- [test/configs/test_alloc_config.h](test/configs/test_alloc_config.h)
106+
- [test/configs/test_sign_hook_config.h](test/configs/test_sign_hook_config.h)
106107

107108
### `FIPS202`
108109

@@ -166,6 +167,7 @@ source code and documentation.
166167
- [test/configs/no_asm_config.h](test/configs/no_asm_config.h)
167168
- [test/configs/serial_fips202_config.h](test/configs/serial_fips202_config.h)
168169
- [test/configs/test_alloc_config.h](test/configs/test_alloc_config.h)
170+
- [test/configs/test_sign_hook_config.h](test/configs/test_sign_hook_config.h)
169171

170172
### `HYBRID`
171173

‎examples/basic_deterministic/mldsa_native/mldsa_native_config.h‎

Lines changed: 86 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -712,24 +712,103 @@
712712
/**
713713
* MLD_CONFIG_CONTEXT_PARAMETER
714714
*
715-
* Set this to add a context parameter that is provided to public
716-
* API functions and is then available in custom callbacks.
715+
* Set this to add a caller-supplied context parameter to the public API
716+
* functions, which is then forwarded unchanged to the custom callbacks
717+
* (allocation, and signing hooks below).
717718
*
718-
* The type of the context parameter is configured via
719-
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
719+
* When this option is set, every public API function gains a trailing
720+
* parameter
721+
*
722+
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
723+
*
724+
* as its last argument; its type is configured via
725+
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this
726+
* value as opaque: it never dereferences it and only passes it on to the
727+
* configurable hook macros. It is meant to carry per-caller state -- e.g. a
728+
* pointer to a memory pool for the allocation hooks, or the resume state for
729+
* the signing hooks -- into those hooks.
730+
*
731+
* When this option is unset (the default), no extra parameter is added and
732+
* the hook macros never receive a context argument.
733+
*
734+
* The hooks that receive the context are the allocation hooks (see
735+
* MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see
736+
* MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with
737+
* its own option below.
720738
*/
721739
/* #define MLD_CONFIG_CONTEXT_PARAMETER */
722740

723741
/**
724742
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE
725743
*
726-
* Set this to define the type for the context parameter used by
727-
* MLD_CONFIG_CONTEXT_PARAMETER.
744+
* Set this to define the type of the context parameter added by
745+
* MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function
746+
* parameter, e.g. `void *` or a pointer to a caller-defined struct such as
747+
* `struct my_ctx *`.
728748
*
729-
* This is only relevant if MLD_CONFIG_CONTEXT_PARAMETER is set.
749+
* This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is
750+
* defined; defining one without the other is a compile-time error.
730751
*/
731752
/* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */
732753

754+
/**
755+
* Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH
756+
*
757+
* Three optional, independent hooks into the ML-DSA signing rejection-sampling
758+
* loop. Each is enabled by defining the matching option, in which case the
759+
* integration MUST provide the corresponding function. If a hook needs
760+
* per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then
761+
* appended as the last argument.
762+
*
763+
* - MLD_CONFIG_SIGN_HOOK_RESUME: uint16_t mld_sign_hook_resume([ctxt])
764+
* Returns the attempt to resume from (0 for a fresh operation), i.e. the one
765+
* recorded when a previous call paused. Re-invoking signing with the same
766+
* message, sk and rnd then reproduces the signature of an uninterrupted run.
767+
* Correct only if the randomness is fixed across calls, so this requires
768+
* MLD_CONFIG_NO_RANDOMIZED_API (deterministic mld_sign_signature_internal /
769+
* _extmu) and is incompatible with MLD_CONFIG_KEYGEN_PCT.
770+
*
771+
* - MLD_CONFIG_SIGN_HOOK_ATTEMPT: int mld_sign_hook_attempt(attempt[, ctxt])
772+
* Called before each attempt. Returns 0 to proceed, or non-zero to pause:
773+
* signing then returns MLD_ERR_SIGNING_PAUSED with `attempt` as the resume
774+
* point (needs MLD_CONFIG_SIGN_HOOK_RESUME to resume; otherwise just aborts).
775+
* Always returning 0 makes it a logging/benchmarking hook.
776+
*
777+
* - MLD_CONFIG_SIGN_HOOK_FINISH: void mld_sign_hook_finish(attempt[, ctxt])
778+
* Called on success with the succeeding attempt. Observe-only.
779+
*
780+
* When an option is unset, the hook is a no-op (resume to 0, attempt proceeds),
781+
* i.e. ordinary one-shot signing.
782+
*
783+
* Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS (the hard attempt bound, >=
784+
* 814 for FIPS 204, returning MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED): do not lower
785+
* that to pause/restart -- use the attempt hook (MLD_ERR_SIGNING_PAUSED)
786+
* instead.
787+
*
788+
* See test/src/test_sign_hook.c for a worked example using all three.
789+
*/
790+
/* #define MLD_CONFIG_SIGN_HOOK_RESUME
791+
#define MLD_CONFIG_SIGN_HOOK_ATTEMPT
792+
#define MLD_CONFIG_SIGN_HOOK_FINISH
793+
#if !defined(__ASSEMBLER__)
794+
#include <stdint.h>
795+
#include "src/sys.h"
796+
static MLD_INLINE uint16_t mld_sign_hook_resume(void)
797+
{
798+
... return the attempt to resume from ...
799+
}
800+
static MLD_INLINE int mld_sign_hook_attempt(uint16_t attempt)
801+
{
802+
... return non-zero to pause here; for resume, store attempt ...
803+
return 0;
804+
}
805+
static MLD_INLINE void mld_sign_hook_finish(uint16_t attempt)
806+
{
807+
... mark the operation complete (attempt = successful attempt) ...
808+
}
809+
#endif
810+
*/
811+
733812
/**
734813
* MLD_CONFIG_REDUCE_RAM
735814
*

‎examples/basic_lowram/mldsa_native/mldsa_native_config.h‎

Lines changed: 86 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -711,24 +711,103 @@
711711
/**
712712
* MLD_CONFIG_CONTEXT_PARAMETER
713713
*
714-
* Set this to add a context parameter that is provided to public
715-
* API functions and is then available in custom callbacks.
714+
* Set this to add a caller-supplied context parameter to the public API
715+
* functions, which is then forwarded unchanged to the custom callbacks
716+
* (allocation, and signing hooks below).
716717
*
717-
* The type of the context parameter is configured via
718-
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
718+
* When this option is set, every public API function gains a trailing
719+
* parameter
720+
*
721+
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
722+
*
723+
* as its last argument; its type is configured via
724+
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this
725+
* value as opaque: it never dereferences it and only passes it on to the
726+
* configurable hook macros. It is meant to carry per-caller state -- e.g. a
727+
* pointer to a memory pool for the allocation hooks, or the resume state for
728+
* the signing hooks -- into those hooks.
729+
*
730+
* When this option is unset (the default), no extra parameter is added and
731+
* the hook macros never receive a context argument.
732+
*
733+
* The hooks that receive the context are the allocation hooks (see
734+
* MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see
735+
* MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with
736+
* its own option below.
719737
*/
720738
/* #define MLD_CONFIG_CONTEXT_PARAMETER */
721739

722740
/**
723741
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE
724742
*
725-
* Set this to define the type for the context parameter used by
726-
* MLD_CONFIG_CONTEXT_PARAMETER.
743+
* Set this to define the type of the context parameter added by
744+
* MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function
745+
* parameter, e.g. `void *` or a pointer to a caller-defined struct such as
746+
* `struct my_ctx *`.
727747
*
728-
* This is only relevant if MLD_CONFIG_CONTEXT_PARAMETER is set.
748+
* This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is
749+
* defined; defining one without the other is a compile-time error.
729750
*/
730751
/* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */
731752

753+
/**
754+
* Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH
755+
*
756+
* Three optional, independent hooks into the ML-DSA signing rejection-sampling
757+
* loop. Each is enabled by defining the matching option, in which case the
758+
* integration MUST provide the corresponding function. If a hook needs
759+
* per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then
760+
* appended as the last argument.
761+
*
762+
* - MLD_CONFIG_SIGN_HOOK_RESUME: uint16_t mld_sign_hook_resume([ctxt])
763+
* Returns the attempt to resume from (0 for a fresh operation), i.e. the one
764+
* recorded when a previous call paused. Re-invoking signing with the same
765+
* message, sk and rnd then reproduces the signature of an uninterrupted run.
766+
* Correct only if the randomness is fixed across calls, so this requires
767+
* MLD_CONFIG_NO_RANDOMIZED_API (deterministic mld_sign_signature_internal /
768+
* _extmu) and is incompatible with MLD_CONFIG_KEYGEN_PCT.
769+
*
770+
* - MLD_CONFIG_SIGN_HOOK_ATTEMPT: int mld_sign_hook_attempt(attempt[, ctxt])
771+
* Called before each attempt. Returns 0 to proceed, or non-zero to pause:
772+
* signing then returns MLD_ERR_SIGNING_PAUSED with `attempt` as the resume
773+
* point (needs MLD_CONFIG_SIGN_HOOK_RESUME to resume; otherwise just aborts).
774+
* Always returning 0 makes it a logging/benchmarking hook.
775+
*
776+
* - MLD_CONFIG_SIGN_HOOK_FINISH: void mld_sign_hook_finish(attempt[, ctxt])
777+
* Called on success with the succeeding attempt. Observe-only.
778+
*
779+
* When an option is unset, the hook is a no-op (resume to 0, attempt proceeds),
780+
* i.e. ordinary one-shot signing.
781+
*
782+
* Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS (the hard attempt bound, >=
783+
* 814 for FIPS 204, returning MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED): do not lower
784+
* that to pause/restart -- use the attempt hook (MLD_ERR_SIGNING_PAUSED)
785+
* instead.
786+
*
787+
* See test/src/test_sign_hook.c for a worked example using all three.
788+
*/
789+
/* #define MLD_CONFIG_SIGN_HOOK_RESUME
790+
#define MLD_CONFIG_SIGN_HOOK_ATTEMPT
791+
#define MLD_CONFIG_SIGN_HOOK_FINISH
792+
#if !defined(__ASSEMBLER__)
793+
#include <stdint.h>
794+
#include "src/sys.h"
795+
static MLD_INLINE uint16_t mld_sign_hook_resume(void)
796+
{
797+
... return the attempt to resume from ...
798+
}
799+
static MLD_INLINE int mld_sign_hook_attempt(uint16_t attempt)
800+
{
801+
... return non-zero to pause here; for resume, store attempt ...
802+
return 0;
803+
}
804+
static MLD_INLINE void mld_sign_hook_finish(uint16_t attempt)
805+
{
806+
... mark the operation complete (attempt = successful attempt) ...
807+
}
808+
#endif
809+
*/
810+
732811
/**
733812
* MLD_CONFIG_REDUCE_RAM
734813
*

‎examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h‎

Lines changed: 86 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -712,24 +712,103 @@
712712
/**
713713
* MLD_CONFIG_CONTEXT_PARAMETER
714714
*
715-
* Set this to add a context parameter that is provided to public
716-
* API functions and is then available in custom callbacks.
715+
* Set this to add a caller-supplied context parameter to the public API
716+
* functions, which is then forwarded unchanged to the custom callbacks
717+
* (allocation, and signing hooks below).
717718
*
718-
* The type of the context parameter is configured via
719-
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
719+
* When this option is set, every public API function gains a trailing
720+
* parameter
721+
*
722+
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
723+
*
724+
* as its last argument; its type is configured via
725+
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this
726+
* value as opaque: it never dereferences it and only passes it on to the
727+
* configurable hook macros. It is meant to carry per-caller state -- e.g. a
728+
* pointer to a memory pool for the allocation hooks, or the resume state for
729+
* the signing hooks -- into those hooks.
730+
*
731+
* When this option is unset (the default), no extra parameter is added and
732+
* the hook macros never receive a context argument.
733+
*
734+
* The hooks that receive the context are the allocation hooks (see
735+
* MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see
736+
* MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with
737+
* its own option below.
720738
*/
721739
/* #define MLD_CONFIG_CONTEXT_PARAMETER */
722740

723741
/**
724742
* MLD_CONFIG_CONTEXT_PARAMETER_TYPE
725743
*
726-
* Set this to define the type for the context parameter used by
727-
* MLD_CONFIG_CONTEXT_PARAMETER.
744+
* Set this to define the type of the context parameter added by
745+
* MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function
746+
* parameter, e.g. `void *` or a pointer to a caller-defined struct such as
747+
* `struct my_ctx *`.
728748
*
729-
* This is only relevant if MLD_CONFIG_CONTEXT_PARAMETER is set.
749+
* This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is
750+
* defined; defining one without the other is a compile-time error.
730751
*/
731752
/* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */
732753

754+
/**
755+
* Signing hooks: MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH
756+
*
757+
* Three optional, independent hooks into the ML-DSA signing rejection-sampling
758+
* loop. Each is enabled by defining the matching option, in which case the
759+
* integration MUST provide the corresponding function. If a hook needs
760+
* per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then
761+
* appended as the last argument.
762+
*
763+
* - MLD_CONFIG_SIGN_HOOK_RESUME: uint16_t mld_sign_hook_resume([ctxt])
764+
* Returns the attempt to resume from (0 for a fresh operation), i.e. the one
765+
* recorded when a previous call paused. Re-invoking signing with the same
766+
* message, sk and rnd then reproduces the signature of an uninterrupted run.
767+
* Correct only if the randomness is fixed across calls, so this requires
768+
* MLD_CONFIG_NO_RANDOMIZED_API (deterministic mld_sign_signature_internal /
769+
* _extmu) and is incompatible with MLD_CONFIG_KEYGEN_PCT.
770+
*
771+
* - MLD_CONFIG_SIGN_HOOK_ATTEMPT: int mld_sign_hook_attempt(attempt[, ctxt])
772+
* Called before each attempt. Returns 0 to proceed, or non-zero to pause:
773+
* signing then returns MLD_ERR_SIGNING_PAUSED with `attempt` as the resume
774+
* point (needs MLD_CONFIG_SIGN_HOOK_RESUME to resume; otherwise just aborts).
775+
* Always returning 0 makes it a logging/benchmarking hook.
776+
*
777+
* - MLD_CONFIG_SIGN_HOOK_FINISH: void mld_sign_hook_finish(attempt[, ctxt])
778+
* Called on success with the succeeding attempt. Observe-only.
779+
*
780+
* When an option is unset, the hook is a no-op (resume to 0, attempt proceeds),
781+
* i.e. ordinary one-shot signing.
782+
*
783+
* Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS (the hard attempt bound, >=
784+
* 814 for FIPS 204, returning MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED): do not lower
785+
* that to pause/restart -- use the attempt hook (MLD_ERR_SIGNING_PAUSED)
786+
* instead.
787+
*
788+
* See test/src/test_sign_hook.c for a worked example using all three.
789+
*/
790+
/* #define MLD_CONFIG_SIGN_HOOK_RESUME
791+
#define MLD_CONFIG_SIGN_HOOK_ATTEMPT
792+
#define MLD_CONFIG_SIGN_HOOK_FINISH
793+
#if !defined(__ASSEMBLER__)
794+
#include <stdint.h>
795+
#include "src/sys.h"
796+
static MLD_INLINE uint16_t mld_sign_hook_resume(void)
797+
{
798+
... return the attempt to resume from ...
799+
}
800+
static MLD_INLINE int mld_sign_hook_attempt(uint16_t attempt)
801+
{
802+
... return non-zero to pause here; for resume, store attempt ...
803+
return 0;
804+
}
805+
static MLD_INLINE void mld_sign_hook_finish(uint16_t attempt)
806+
{
807+
... mark the operation complete (attempt = successful attempt) ...
808+
}
809+
#endif
810+
*/
811+
733812
/**
734813
* MLD_CONFIG_REDUCE_RAM
735814
*

0 commit comments

Comments
 (0)