From a04dc1edd71783990e1fcde648fa42ac5d03eefa Mon Sep 17 00:00:00 2001 From: Kgothatso Ngako Date: Wed, 18 Nov 2026 23:40:59 +0200 Subject: [PATCH] frost_enrollment: document future Kyber lessons --- Makefile.am | 1 + .../frost_enrollment/frost_enrollment.md | 4 + src/modules/frost_enrollment/kyber-future.md | 469 ++++++++++++++++++ 3 files changed, 474 insertions(+) create mode 100644 src/modules/frost_enrollment/kyber-future.md diff --git a/Makefile.am b/Makefile.am index 17834053..39b6a642 100644 --- a/Makefile.am +++ b/Makefile.am @@ -332,6 +332,7 @@ EXTRA_DIST += doc/release-process.md doc/safegcd_implementation.md EXTRA_DIST += doc/ellswift.md doc/musig.md doc/iceberg.md doc/prefractal.md EXTRA_DIST += src/modules/frost/frost.md src/modules/chilldkg/chilldkg.md EXTRA_DIST += src/modules/frost_enrollment/frost_enrollment.md +EXTRA_DIST += src/modules/frost_enrollment/kyber-future.md EXTRA_DIST += examples/EXAMPLES_COPYING EXTRA_DIST += sage/gen_exhaustive_groups.sage EXTRA_DIST += sage/gen_split_lambda_constants.sage diff --git a/src/modules/frost_enrollment/frost_enrollment.md b/src/modules/frost_enrollment/frost_enrollment.md index 5535cd6b..5a3e0c4a 100644 --- a/src/modules/frost_enrollment/frost_enrollment.md +++ b/src/modules/frost_enrollment/frost_enrollment.md @@ -22,6 +22,10 @@ The full and reduced protocols MUST NOT be mixed within a run. They have incompatible message graphs and tagged-hash encodings. The example in `examples/frost_enrollment.c` uses reduced enrollment. +For optional future distributed-integration lessons from Kyber, see +`src/modules/frost_enrollment/kyber-future.md`. That design note does not change +the current protocol or API. + Unlike the frost module, which tracks BIP 445, these protocols have no BIP. Their tagged hashes and parameter serializations are this module's own and are pinned by `src/modules/frost_enrollment/vectors.h`. diff --git a/src/modules/frost_enrollment/kyber-future.md b/src/modules/frost_enrollment/kyber-future.md new file mode 100644 index 00000000..f31b65c6 --- /dev/null +++ b/src/modules/frost_enrollment/kyber-future.md @@ -0,0 +1,469 @@ +Future optional lessons from Kyber resharing +============================================ + +Status +------ + +This is a design note for possible future work, not a specification of the +current API and not a commitment to change it. The reduced-enrollment +implementation should remain lightweight until there is a concrete deployment +requirement for these layers. + +The reference for this note is dedis/kyber at commit +`3194be036a906ef79fa0e87d439bfd7d6e4e0afe`, primarily its Pedersen DKG +resharing implementation: + +- https://github.com/dedis/kyber/tree/3194be036a906ef79fa0e87d439bfd7d6e4e0afe/share/dkg/pedersen +- https://github.com/dedis/kyber/blob/3194be036a906ef79fa0e87d439bfd7d6e4e0afe/share/dkg/pedersen/dkg.go +- https://github.com/dedis/kyber/blob/3194be036a906ef79fa0e87d439bfd7d6e4e0afe/share/dkg/pedersen/structs.go +- https://github.com/dedis/kyber/blob/3194be036a906ef79fa0e87d439bfd7d6e4e0afe/share/dkg/pedersen/protocol.go + +Kyber calls the relevant operation resharing, not re-enrollment. Its operation +is cryptographically different from this module's enrollment RTS. + +Current design to preserve +-------------------------- + +The current reduced protocol evaluates the existing joint polynomial at a new +participant index. It has these important properties: + +- enrollment changes `(t, n)` to `(t, n+1)` and repair reproduces an existing + share; +- the group public key, threshold, joint polynomial and existing shares do not + change; +- no trusted dealer or reconstruction of the group secret is needed during + enrollment or repair; +- any sufficient helper set can run the protocol; +- helpers exchange a triangular additive-share matrix, using u(u+1)/2 secret + values for u helpers; +- the public API operates on bytes and does not impose a network, identity, + storage, authorization or consensus implementation; +- fresh session identifiers and helper randomness, per-helper session hashes, + mandatory target public-share verification and constant-time secret arithmetic + are already implemented; +- public shares can be derived by interpolation or from an aggregate VSS + commitment polynomial. + +The original full-enrollment API and its regression vectors must remain +unaffected by optional integration work. The reduced API and vectors should also +remain stable unless a separately versioned protocol change is deliberately +specified. + +The key difference from Kyber +----------------------------- + +Kyber resharing has every old participant create a fresh random polynomial whose +constant term is that participant's old share. New participants interpolate the +qualified dealers' shares and commitments. The resulting joint polynomial has +the same constant-term secret but fresh coefficients, and its degree can change +with the new threshold. + +Kyber therefore addresses proactive refresh, membership changes and threshold +changes as well as adding participants. The current enrollment module does not. +It should not acquire those semantics implicitly. + +Useful Kyber ideas to adapt +--------------------------- + +The most useful lessons are operational rather than changes to the reduced +scalar arithmetic: + +1. Kyber's `Node` associates a stable participant index with a long-term public + key, and `DistKeyShare` carries public polynomial commitments. +2. Its packets have canonical hashes and signatures, with signature verification + based on the sender's old- or new-group role. +3. Its packet collector accepts an identical retransmission but treats a + different packet from the same sender in the same role as equivocation. +4. Its explicit phases separate deal processing, responses, justifications and + finalization. +5. Its result contains the public commitments and qualified participant list, + allowing participants to compare their public results before accepting them. +6. Its resharing configuration explicitly distinguishes the old threshold from + the new threshold, preventing an implicit threshold downgrade. + +The first five ideas can be adapted without changing the enrollment algorithm. +The sixth matters only for a future resharing protocol with distinct old and +new thresholds; the current enrollment session already binds its unchanged +threshold explicitly. + +Proposed layering +----------------- + +Keep the existing scalar-level API as the inner layer. Add optional integration +layers only when needed: + + application policy, authorization, persistent storage and consensus + --------------------------------------------------------------- + optional protocol driver, timeouts, retries and finalization + --------------------------------------------------------------- + optional canonical requests, message hashes and message collector + --------------------------------------------------------------- + authenticated group descriptor and long-term participant identities + --------------------------------------------------------------- + existing full/reduced enrollment arithmetic (unchanged) + +The first versions of these layers can live in the example or in the consuming +application. They should become public library APIs only after their semantics +and wire formats are stable and independently reviewed. + +No layer should silently turn into a bespoke transport, encryption, signature, +consensus or persistent-database framework. Those remain application choices. + +1. Authenticated group descriptor +--------------------------------- + +Define a versioned public descriptor containing at least: + +- protocol and serialization versions; +- group threshold public key; +- current n and t; +- participant identifiers and their long-term host public keys; +- the public-share table or aggregate VSS commitment polynomial; +- any group epoch or configuration sequence number required by the application. + +Define a canonical serialization and a descriptor hash. The descriptor binds +identifiers to host identities and public key material, rather than treating a +bare integer identifier as a network identity. + +The descriptor must be authenticated independently of enrollment messages. +Possible distributed sources include a certified DKG transcript, an existing +signed group configuration, or another mechanism already trusted by the group. +A hash embedded in the descriptor does not authenticate the descriptor itself. +There is no need to introduce a trusted dealer merely to provide this metadata. + +The descriptor should be validated before use: + +- all identifiers and host keys are unique and in range; +- n and t match the authenticated configuration; +- public shares validate against the threshold public key with + `secp256k1_frost_threshold_info_validate`, or commitments have the expected + constant-term commitment and encoding; +- every participant uses the same descriptor hash for the session. + +The current aggregate-commitment derivation can be reused. It does not need a +ChillDKG build dependency. + +2. Signed enrollment or repair request +-------------------------------------- + +Define a request containing: + +- request protocol version; +- fresh 32-byte session identifier; +- authenticated group descriptor hash; +- enrollment or repair mode; +- target participant identifier; +- target long-term host public key; +- canonically sorted helper identifier set; +- current n and t, even though the descriptor also commits to them; +- an application-defined expiration, epoch or timeout value if required; +- an application authorization reference or policy version, if applicable. + +Define a canonical request hash. The target signs the request with its long-term +host key. Every helper verifies the signature, descriptor, participant roles, +helper set, mode and expiration before applying its own authorization policy. + +This is particularly important for repair. The requester cannot prove possession +of the lost FROST share, so it needs an independent, stable identity. A target +host key provides that identity without introducing a dealer. + +Authentication is not authorization. A valid target signature proves which host +made the request; it does not prove that the group permits the requested +operation. Each helper still needs an explicit approval decision. + +Any change to the existing reduced parameters-hash encoding must be a new +protocol version with new tags and vectors. An optional request hash can instead +reference the existing parameters hash without changing it. + +3. Canonical message hashes and transcript +------------------------------------------ + +Define canonical hashes for delta, sigma and finalization messages. These are +separate from the existing parameters hash, which remains the common session +identifier used by the reduced arithmetic. + +A delta message hash should bind: + +- request hash or reduced parameters hash; +- message type and protocol version; +- sender identifier; +- recipient identifier; +- the 32-byte delta value. + +A sigma message hash should bind the same fields except that it has the target +as its recipient role and carries the 32-byte sigma value. + +A finalization message hash should additionally bind the post-enrollment public +state described below. + +Canonical encodings must define integer widths and endianness, point encoding, +array ordering, message lengths and rejection of trailing data. Reordering a +set must not change a set-level hash; changing a sender, recipient, message type +or value must change it. Secret values still require confidential transport. +Signing or hashing a secret message does not make it safe to publish. + +Applications may sign these hashes with their existing host-key scheme. The +library need not mandate Kyber's ECIES or invent a new encryption scheme. +Where secure channels already exist, canonical hashes are primarily useful for +transcript consistency, equivocation detection, auditing and interoperability. + +4. Duplicate and equivocation-aware message collection +------------------------------------------------------ + +Add an optional collector, initially in the driver or reference integration, +that keys messages by: + + (session, protocol phase, sender identifier, recipient identifier) + +Its behavior should be deterministic: + +- an identical duplicate is idempotent and does not produce a second + contribution; +- a different message in the same slot is equivocation: reject it, record the + sender and abort the run; +- an unknown sender, unexpected recipient or out-of-phase message is rejected; +- an incomplete expected set cannot proceed to the next phase; +- a message with an invalid scalar, incorrect parameters hash or nonzero + structurally omitted delta fails according to the existing arithmetic API. + +Record enough public evidence to diagnose the abort, such as both message hashes +for an equivocation. Do not log delta or sigma values themselves. + +The current array-based APIs remain valid. The collector is responsible for +constructing those arrays and establishing exactly one contribution per expected +sender before calling them. + +5. Explicit driver and failure model +------------------------------------ + +An optional driver can use a small state machine: + + REQUESTED -> DELTAS -> SIGMAS -> VERIFIED -> FINALIZED + \ \ \ \ + ----------+---------+----------> ABORTED + +It should validate every transition, reject calls in the wrong phase and ensure +that all secret temporary values are erased on abort. + +Timeouts and retries are liveness concerns, not reasons to change the scalar +protocol. A timeout may abort a run, but it must not cause the caller to reuse +helper randomness or accept a partial set as though it were complete. + +On an unrecoverable fault: + +1. erase temporary deltas, sigmas and helper randomness; +2. abort the current session; +3. select helpers and authorize a fresh session according to policy; +4. generate fresh session and helper randomness; +5. restart from round 1.1. + +Do not drop a bad sigma and continue with the remaining contributions. Reduced +Lagrange coefficients depend on the helper set committed at session creation. +Removing a helper changes those coefficients and invalidates the run. + +Crash recovery needs the same caution. Unless a separately reviewed persistent +protocol state exists, a process restart should abort rather than resume from +partial secret intermediate values. Session randomness must never be replayed. + +6. Deterministic finalization +----------------------------- + +Define a finalization message binding: + +- request hash and session identifier; +- original descriptor hash; +- target identifier and derived public share; +- unchanged threshold public key and t; +- updated n and participant list; +- updated public-share table or new group descriptor hash; +- successful completion status, or a canonical abort reason for diagnostics. + +Every participant verifies the same finalization hash before committing any +state update. For enrollment, n and the public-share table are updated only +after verification. For repair, the public descriptor remains unchanged. + +The group still needs its own mechanism for distributing and agreeing on this +message. A finalization hash detects inconsistent states; it does not provide +consensus or atomic storage across processes. + +Tests should simulate a participant receiving a different finalization and +confirm that it performs no persistent update and cannot enter a signing session +with stale metadata. + +What not to import from Kyber +----------------------------- + +Public justifications +~~~~~~~~~~~~~~~~~~~~~ + +Kyber can resolve VSS complaints by revealing a dealer's share and can evict a +dealer once enough complaints make its polynomial reconstructable. That is part +of its VSS security design. + +Publishing reduced-enrollment deltas or sigmas is not an equivalent operation. +These values mask existing secret shares. Revealing them can expose helper share +information when combined with other transcript values. Do not add public +justification rounds to reduced enrollment without a new proof system and a new +security analysis. + +Qualified-helper filtering after round 1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kyber can construct a result from qualified VSS dealers after complaints and +justifications. Reduced enrollment cannot discard an arbitrary helper after the +weighted contributions have been generated, because all weights were computed +for the original helper set. Abort and restart instead. + +Threshold changes inside the current API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kyber explicitly tracks old and new thresholds. Current enrollment keeps t +fixed and already binds it into every session. If threshold changes are ever +required, specify old and new thresholds separately and design a new resharing +protocol rather than overloading `new_id` or adding a threshold argument to the +existing calls. + +Consensus assumptions +~~~~~~~~~~~~~~~~~~~~~ + +Kyber's complaint and eviction consistency relies on its protocol and broadcast +assumptions. Signed messages alone do not give every participant the same view. +Do not claim robust Byzantine agreement, guaranteed termination or identifiable +misbehavior for an integration that lacks those mechanisms. + +Optional future resharing module +-------------------------------- + +If proactive refresh, signer removal or threshold changes become requirements, +consider a separate `frost_resharing` design based on Kyber's fresh-polynomial +approach. It should not change the meaning of the current enrollment functions. + +That design would need, at minimum: + +- independently specified old and new participant sets and thresholds; +- fresh random polynomials with each old share as a constant term; +- encrypted secret deals and authenticated, session-bound messages; +- verification that each dealer's constant commitment equals its old public + share; +- a complaint/justification and qualification model with an explicit security + proof for FROST; +- coefficient-wise reconstruction of the new public polynomial; +- verification of every resulting secret share; +- deterministic finalization and persistent epoch handling; +- explicit deletion of old shares where revocation is intended. + +Fresh coefficients do not magically revoke old shares. Old participants that +retain a threshold of old shares can still reconstruct or use the old secret. +Deletion assumptions and collusion remaining after a refresh must be documented +just as carefully as the new protocol's correctness properties. + +Phased implementation roadmap +----------------------------- + +Phase A: integration specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Write the descriptor, request, message and finalization encodings. +- Define host-key and authentication interfaces without mandating a scheme. +- Document the broadcast, timeout, crash and authorization assumptions. +- Decide which components remain application examples and which justify public + APIs. +- Preserve all current vectors and call signatures. + +Exit criterion: two independent reviewers can derive identical message graphs, +hashes, trust inputs and failure transitions from the specification. + +Phase B: descriptor and signed request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Implement canonical descriptor and request hashing in a reference integration. +- Validate descriptor provenance and group key material. +- Verify target host signatures and helper authorization checkpoints. +- Bind requests to the existing reduced parameters hash without altering it. + +Exit criterion: wrong target identity, group, descriptor, helper set, mode, +threshold, session or expiration is rejected before any secret share is used. + +Phase C: transcript and collector +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Add canonical delta and sigma hashes. +- Add exact-duplicate idempotence and conflicting-duplicate detection. +- Add phase, sender, recipient and completeness validation. +- Exercise the existing reduced rounds through the collector rather than by + manually assembling arrays. + +Exit criterion: all malformed, reordered, duplicated, conflicting, missing and +out-of-phase messages have deterministic outcomes, with no secret data logged. + +Phase D: finalization and driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Add finalization hashes and post-update descriptor validation. +- Add explicit driver states, abort cleanup and fresh-session restart. +- Add timeouts and crash-abort behavior at the application layer. +- Demonstrate the integration in a multi-process example initialized by a + distributed DKG rather than the current single-process trusted-dealer example. + +Exit criterion: every participant either accepts the same public result or +performs no update; a failed run cannot reuse randomness or continue with a +partial helper set. + +Phase E: separate resharing evaluation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Only if refresh, removal or threshold changes are required: + +- write a standalone protocol specification and threat model; +- obtain cryptographic review before selecting public APIs; +- implement it as a separate module with separate vectors and documentation; +- do not weaken or repurpose reduced enrollment to accommodate it. + +Test requirements for future layers +----------------------------------- + +Retain all existing full and reduced tests and vectors, then add: + +- descriptor round trips, non-canonical encoding rejection and provenance tests; +- request signatures with wrong keys, targets, modes, groups, thresholds, + sessions, helper sets and expired requests; +- identical versus conflicting duplicate delta and sigma messages; +- sender/recipient swapping, phase confusion and incomplete sets; +- finalization disagreement and stale-signing-state rejection; +- aborts at every state transition, checking secret cleanup and output zeroing; +- retries with different helper sets and rejection of old-session messages; +- process crashes before and after each round, without randomness reuse; +- multi-process enrollment and repair initialized by a distributed DKG; +- constant-time, sanitizer, Valgrind and installed-library checks for any new + secret-bearing code; +- interoperability vectors for all new public encodings and hashes. + +Review gates +------------ + +Before any new layer becomes a supported public API, review: + +- descriptor provenance and the absence of circular authentication; +- target identity and the authorization policy for repair; +- canonical encoding and transcript domain separation; +- equivocation behavior and whether honest participants reach consistent aborts; +- finalization consistency and stale-state handling; +- randomness and crash-recovery requirements; +- the difference between liveness failures and cryptographic faults; +- independent cryptographic review of any new resharing or complaint mechanism. + +The current module remains experimental. These future layers should not be used +to imply production readiness without the corresponding reviews. + +Recommended priority +-------------------- + +The highest-value, lowest-risk sequence is: + +1. authenticated descriptor and signed target request; +2. canonical message hashes and duplicate/equivocation-aware collection; +3. deterministic finalization and an optional driver; +4. only later, a separately reviewed resharing protocol. + +This sequence keeps the current lightweight enrollment implementation intact +while addressing the practical lessons most relevant to distributed deployments.