From b1ccf390a0440e6729277b1a2442731090a0bcd3 Mon Sep 17 00:00:00 2001 From: Kgothatso Ngako Date: Wed, 18 Nov 2026 22:59:18 +0200 Subject: [PATCH] frost_enrollment: document and demonstrate reduced enrollment --- examples/frost_enrollment.c | 102 +-- .../frost_enrollment/frost_enrollment.md | 675 ++++++++---------- 2 files changed, 355 insertions(+), 422 deletions(-) diff --git a/examples/frost_enrollment.c b/examples/frost_enrollment.c index fdf5d73f..b99364f7 100644 --- a/examples/frost_enrollment.c +++ b/examples/frost_enrollment.c @@ -6,10 +6,11 @@ * EXAMPLES_COPYING or https://creativecommons.org/publicdomain/zero/1.0 * *************************************************************************/ -/** This file demonstrates how to use the FROST enrollment module: first to - * grow a 2-of-3 group into a 2-of-4 one without re-running key generation, - * then to repair a participant's lost share. Additionally, see the - * documentation in include/secp256k1_frost_enrollment.h and +/** This file demonstrates reduced FROST enrollment from Section 4.1.3 of + * "A Survey and Refinement of Repairable Threshold Schemes": first growing a + * 2-of-3 group into a 2-of-4 one without re-running key generation, then + * repairing a participant's lost share. Additionally, see the documentation + * in include/secp256k1_frost_enrollment.h and * src/modules/frost_enrollment/frost_enrollment.md. * * The example runs all roles (trusted dealer, helpers, the party receiving @@ -47,10 +48,10 @@ #define N_PARTICIPANTS_AFTER (N_PARTICIPANTS + 1) /* Threshold t */ #define THRESHOLD 2 -/* Number of helpers u taking part in the enrollment run. Any u with - * THRESHOLD <= u <= N_PARTICIPANTS works; the result does not depend on the - * choice. */ -#define N_HELPERS 2 +/* Number of helpers u taking part in each run. Three helpers demonstrate the + * triangular exchange with u > THRESHOLD; any u with THRESHOLD <= u <= the + * current participant count (excluding a repair target) gives the same share. */ +#define N_HELPERS 3 /* The identifier the new participant will hold. In enrollment mode this must * be exactly the current participant count. */ #define NEW_ID N_PARTICIPANTS @@ -64,9 +65,9 @@ struct helper { /* The helper's own secret share of the group key. Never leaves the * helper. */ unsigned char secshare[32]; - /* Round 1.1 output, aligned with the helper id array: entry j goes to the - * helper at position j. The entry at this helper's own position is kept - * locally. These are secret. */ + /* Round 1.1 triangular row, aligned with the helper id array. Entry j has + * a message only when helper j's identifier is larger than this helper's; + * smaller-identifier entries are zero and the own entry is kept. Secret. */ unsigned char shares[N_HELPERS * 32]; /* The parameters hash this helper computed, sent alongside every share it * distributes and to the enrollee. Public. */ @@ -114,60 +115,70 @@ static int trusted_dealer_keygen(const secp256k1_context* ctx, unsigned char *th static int enroll(const secp256k1_context* ctx, unsigned char *new_secshare, secp256k1_pubkey *new_pubshare, struct helper *helpers, const uint32_t *ids, const secp256k1_pubkey *helper_pubshares, const secp256k1_pubkey *thresh_pk, uint32_t new_id, size_t n_participants) { unsigned char sigmas[N_HELPERS * 32]; unsigned char all_shares[N_HELPERS * 32]; - unsigned char enrollee_params_hash[32]; + unsigned char enrollee_params_hashes[N_HELPERS * 32]; + unsigned char session_id[32]; int i, j; int ret = 0; memset(sigmas, 0, sizeof(sigmas)); memset(all_shares, 0, sizeof(all_shares)); + /* The target creates a fresh session request. In a real deployment it + * sends session_id and the complete parameter tuple to every helper. Each + * helper must independently authorize that exact request before running + * round 1.1; this example's single-process flow stands in for approval. */ + if (!fill_random(session_id, sizeof(session_id))) { + printf("Failed to generate an enrollment session identifier\n"); + goto cleanup; + } + /* --- Round 1.1 ------------------------------------------------------ - * Every helper splits its Lagrange-weighted share into one additive share - * per helper, keeps its own and sends the rest out. */ + * Each helper splits its Lagrange-weighted share into the reduced + * protocol's triangular row: masking shares go only to larger helper + * identifiers, smaller-identifier cells stay zero, and the diagonal + * remainder is kept locally. */ for (i = 0; i < N_HELPERS; i++) { unsigned char session_secrand[32]; /* Fresh randomness for every run: reusing it across runs leaks share - * information. No secure_erase is needed here -- shares_gen wipes the - * seed itself, on success and on failure alike, so that a failed call - * cannot be retried on the same randomness. */ + * information. No secure_erase is needed here -- reduced_shares_gen + * wipes the seed itself, on success and on failure alike, so that a + * failed call cannot be retried on the same randomness. */ if (!fill_random(session_secrand, sizeof(session_secrand))) { printf("Failed to generate randomness\n"); secure_erase(session_secrand, sizeof(session_secrand)); goto cleanup; } - if (!secp256k1_frost_enrollment_shares_gen(ctx, helpers[i].shares, helpers[i].params_hash, session_secrand, helpers[i].secshare, thresh_pk, ids, N_HELPERS, helpers[i].id, new_id, n_participants, THRESHOLD)) { - /* shares_gen wipes the seed on every path, including this one. */ + if (!secp256k1_frost_enrollment_reduced_shares_gen(ctx, helpers[i].shares, helpers[i].params_hash, session_secrand, helpers[i].secshare, thresh_pk, ids, N_HELPERS, helpers[i].id, new_id, n_participants, THRESHOLD, session_id)) { + /* reduced_shares_gen wipes the seed on every path, including here. */ goto cleanup; } } /* --- Round 1.2 ------------------------------------------------------ - * Helper j receives entry j of every other helper's buffer, over a - * confidential and authenticated channel, together with that helper's - * parameters hash. It recomputes the hash itself and compares. */ + * Helper j receives entry j only from helpers with smaller identifiers, + * over confidential and authenticated channels, together with their + * parameters hashes. Its own diagonal entry is local. Entries from larger + * identifiers have no message and must remain zero. */ for (j = 0; j < N_HELPERS; j++) { unsigned char received_hashes[N_HELPERS * 32]; uint32_t mismatch_id; - /* The two buffers take deliberately opposite conventions at this - * helper's own position: the share kept locally IS read, while the - * hash slot is never read and stays zero. The own hash is - * recomputed, never taken from a buffer -- which is what makes this - * a recomputation check rather than a comparison between two strings - * the caller supplied. */ + /* Only lower-ranked hash slots are read. The helper recomputes its own + * hash rather than reading its own slot, and larger-ranked slots are + * ignored along with their nonexistent messages. */ memset(received_hashes, 0, sizeof(received_hashes)); for (i = 0; i < N_HELPERS; i++) { memcpy(&all_shares[32 * i], &helpers[i].shares[32 * j], 32); - if (i != j) { + if (helpers[i].id < helpers[j].id) { memcpy(&received_hashes[32 * i], helpers[i].params_hash, 32); } } - if (!secp256k1_frost_enrollment_share_agg(ctx, helpers[j].sigma, &mismatch_id, all_shares, received_hashes, thresh_pk, ids, N_HELPERS, helpers[j].id, new_id, n_participants, THRESHOLD)) { + if (!secp256k1_frost_enrollment_reduced_share_agg(ctx, helpers[j].sigma, &mismatch_id, all_shares, received_hashes, thresh_pk, ids, N_HELPERS, helpers[j].id, new_id, n_participants, THRESHOLD, session_id)) { if (mismatch_id != UINT32_MAX) { - /* Either that helper ran round 1.1 on different parameters, - * or its share did not survive transit. share_agg does not - * distinguish the two, so neither can this message. */ + /* The helper disagreed on parameters, supplied an invalid + * scalar, or filled a structurally omitted cell. + * reduced_share_agg does not distinguish those cases. */ printf("\nHelper %u contributed a share this helper cannot use\n", mismatch_id); } goto cleanup; @@ -175,24 +186,25 @@ static int enroll(const secp256k1_context* ctx, unsigned char *new_secshare, sec } /* --- Round 2 -------------------------------------------------------- - * The enrollee receives one value from each helper, again confidentially - * and authenticated, plus the parameters hash. + * The enrollee receives one value and parameters hash from every helper, + * again confidentially and authenticated. It checks every hash against + * its own recomputation, not merely a representative helper's hash. * * The expected public share is derived from the helpers' public shares -- * which the caller has already validated against an independently - * authenticated threshold public key (see main). Without that step both + * authenticated threshold public key (see main). Without that step the * checks below would be circular: t colluding helpers could present a * consistent but fabricated polynomial and every check would pass on a * worthless share. */ for (i = 0; i < N_HELPERS; i++) { memcpy(&sigmas[32 * i], helpers[i].sigma, 32); + memcpy(&enrollee_params_hashes[32 * i], helpers[i].params_hash, 32); } - memcpy(enrollee_params_hash, helpers[0].params_hash, 32); if (!secp256k1_frost_enrollment_pubshare_derive(ctx, new_pubshare, helper_pubshares, ids, N_HELPERS, new_id, n_participants, THRESHOLD)) { goto cleanup; } - if (!secp256k1_frost_enrollment_secshare_gen(ctx, new_secshare, sigmas, thresh_pk, ids, N_HELPERS, new_id, n_participants, THRESHOLD, enrollee_params_hash, new_pubshare)) { + if (!secp256k1_frost_enrollment_reduced_secshare_gen(ctx, new_secshare, sigmas, enrollee_params_hashes, thresh_pk, ids, N_HELPERS, new_id, n_participants, THRESHOLD, session_id, new_pubshare)) { goto cleanup; } ret = 1; @@ -296,14 +308,14 @@ int main(void) { /* The enrollment run for the new participant 3. */ struct helper helpers[N_HELPERS]; - uint32_t helper_ids[N_HELPERS] = { 0, 1 }; + uint32_t helper_ids[N_HELPERS] = { 0, 1, 2 }; secp256k1_pubkey helper_pubshares[N_HELPERS]; unsigned char new_secshare[32]; secp256k1_pubkey new_pubshare; /* The repair run for participant 1. */ struct helper repair_helpers[N_HELPERS]; - uint32_t repair_ids[N_HELPERS] = { 0, 2 }; + uint32_t repair_ids[N_HELPERS] = { 0, 2, 3 }; secp256k1_pubkey repair_pubshares[N_HELPERS]; unsigned char repaired_secshare[32]; secp256k1_pubkey repaired_pubshare; @@ -355,7 +367,7 @@ int main(void) { } printf("ok\n"); - /* Enrollment: helpers 0 and 1 give participant 3 a share. */ + /* Enrollment: helpers 0, 1 and 2 give participant 3 a share. */ for (i = 0; i < N_HELPERS; i++) { helpers[i].id = helper_ids[i]; memcpy(helpers[i].secshare, &secshares[32 * helper_ids[i]], 32); @@ -418,7 +430,11 @@ int main(void) { * 1's actual share. */ for (i = 0; i < N_HELPERS; i++) { repair_helpers[i].id = repair_ids[i]; - memcpy(repair_helpers[i].secshare, &secshares[32 * repair_ids[i]], 32); + if (repair_ids[i] == NEW_ID) { + memcpy(repair_helpers[i].secshare, new_secshare, 32); + } else { + memcpy(repair_helpers[i].secshare, &secshares[32 * repair_ids[i]], 32); + } repair_pubshares[i] = pubshares[repair_ids[i]]; } printf("Repairing participant 1's lost share..."); @@ -443,7 +459,7 @@ int main(void) { * swapping them to disk. Hence, we overwrite secret key material with * zeros. * - * The session randomness was already wiped by shares_gen, and the + * The session randomness was already wiped by reduced_shares_gen, and the * secnonces by frost_sign. */ secure_erase(threshold_seckey, sizeof(threshold_seckey)); secure_erase(secshares, sizeof(secshares)); diff --git a/src/modules/frost_enrollment/frost_enrollment.md b/src/modules/frost_enrollment/frost_enrollment.md index 283840ed..5535cd6b 100644 --- a/src/modules/frost_enrollment/frost_enrollment.md +++ b/src/modules/frost_enrollment/frost_enrollment.md @@ -1,441 +1,358 @@ Notes on the frost_enrollment module API ======================================== -This module implements FROST enrollment, the full enrollment RTS of Section -4.1.1 of "A Survey and Refinement of Repairable Threshold Schemes" -(https://eprint.iacr.org/2017/1155.pdf). It turns a (t, n) FROST group into a -(t, n+1) group without re-running key generation and without any participant -revealing its secret share, and it repairs a lost share by running the same -protocol at the identifier of an existing participant. +This module adds and repairs FROST participants without rerunning key +generation. Enrollment turns a `(t, n)` group into a `(t, n+1)` group; repair +reproduces the share at an existing participant identifier. Both preserve the +group public key, threshold, joint polynomial and every existing share. -Unlike the frost module, which tracks BIP 445, this protocol has no BIP. It is -specified by the paper and by the reference proof of concept at -https://github.com/siv2r/frost-enrollment. The tagged hash strings and the -parameter serialization used here are this module's own. +Two explicitly separated protocol versions are available: -The following sections contain additional notes on the API of the -frost_enrollment module (`include/secp256k1_frost_enrollment.h`). A usage -example can be found in `examples/frost_enrollment.c`. +- The original entry points implement the full enrollment RTS from Section + 4.1.1 of "A Survey and Refinement of Repairable Threshold Schemes" + (https://eprint.iacr.org/2017/1155.pdf). Their proof of concept is + https://github.com/siv2r/frost-enrollment. +- The `reduced_` entry points implement the reduced enrollment RTS from + Section 4.1.3 of that survey, linked from + https://gist.github.com/nickfarrow/64c2e65191cde6a1a47bbd4572bf8cf8. + They use a triangular share matrix, fresh session identifiers, separate hash + domains and mandatory target-side verification. -**This module is experimental.** Do not use it in production. The API should -not be considered stable. +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. -"Not stable" and "frozen" apply to different things, and the distinction -matters if you are writing an interoperating implementation. The C API — the -function signatures, the argument order, the buffer conventions — may change. -The wire-visible encodings — the two tagged hashes below, the parameters hash -serialization and the share-splitting derivation — are frozen by the -regression vectors, so changing one is a deliberate, vector-breaking change -rather than a silent one. +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`. -Reduced enrollment version 2 specification -========================================== +**This module is experimental.** Do not use it in production. The API is not +stable. In particular, the generalized `u > t` reduced protocol follows the +same triangular construction as the paper's `u = t` protocol, but its +generalized coalition argument still requires independent review. -This is the normative specification for the reduced-enrollment revision being -implemented. Until the versioned API lands, the sections below describe the -existing version 1 full-enrollment implementation. The target protocol is the -reduced enrollment RTS from Section 4.1.3 of Laing and Stinson's survey, linked -from https://gist.github.com/nickfarrow/64c2e65191cde6a1a47bbd4572bf8cf8. +Common parameters and modes +=========================== -Scope and security model ------------------------- +Identifiers follow the frost module: participant `id` is a `uint32` in +`0..n-1` and sits at polynomial x-coordinate `id+1`. The target uses `new_id`: -Version 2 has two operations. Enrollment turns a `(t, n)` group into a `(t, -n+1)` group at `new_id = n`; repair recreates the existing share at `new_id < -n`. Both retain the original group public key, threshold, polynomial and -existing shares. Neither operation refreshes the polynomial or revokes a copied -share. Signer removal, threshold changes, proactive refresh and fragment-based -enrollment are outside this protocol. +- enrollment: `new_id == n_participants`, so the resulting group has n+1 + participants and n must be below `SECP256K1_FROST_MAX_PARTICIPANTS`; +- repair: `new_id < n_participants`, so n is unchanged and may equal the + maximum. -Participants are identified by `uint32` identifiers `0..n-1`, and identifier -`i` corresponds to polynomial x-coordinate `i+1`. The helper set contains `u` -unique existing participant identifiers, sorted numerically for protocol -purposes, with `2 <= t <= u`. The target cannot be a helper. Enrollment allows -`u <= n`; repair allows at most `n-1` helpers. The paper specifies `u = t`. -Support for `u > t` uses the same triangular-matrix construction and requires -the generalized coalition argument to be reviewed before the experimental -warning can be removed. +A run has u helpers, with `2 <= threshold <= u`. Helpers are unique existing +participants and the target cannot be a helper. Enrollment permits u <= n; +repair permits at most n-1 helpers. Any helper set of sufficient size produces +the same target share. -The privacy goal is the enrollment RTS goal against coalitions of fewer than t -participants executing the protocol honestly. Every helper-to-helper and -helper-to-target secret value MUST use a confidential and authenticated channel. -Public-share verification detects a bad result but does not identify a helper -that supplied a bad sigma; identifiable malicious fault tolerance is not -claimed. Authorization is separate from authentication and remains a caller -precondition: a helper must run only after approving the exact session, group, -helper set, operation and target. - -Triangular share exchange -------------------------- - -Write `h_0, ..., h_(u-1)` for the sorted helpers, `x_new = new_id+1`, and `q` -for the secp256k1 group order. Helper `h_i` computes +Write `f` for the joint polynomial of degree at most t-1 and `s_i = f(i+1)` for +participant i's secret share. For helpers `h_0, ..., h_(u-1)`, numerically +sorted, helper i's public Lagrange coefficient at the target is lambda_i = product_{k != i} (new_id-h_k)/(h_i-h_k) mod q + +where q is the secp256k1 group order. The +1 in x-coordinates cancels in each +difference. Correctness follows from + + f(new_id+1) = sum_i lambda_i*s_i. + +The protocol computes this sum without sending an unmasked `lambda_i*s_i` to +the target, which could otherwise multiply by `lambda_i^-1` and recover helper +i's share. + +Arrays of length u are aligned with the caller's own `ids` array. The full +protocol's parameters hash and both reduced hashes sort identifiers before +hashing, so array order does not affect session agreement. Reduced routing is +also based on numeric identifiers, not array positions. This lets every helper +use a different array order as long as the caller maps messages by sender and +recipient identifier. + +Reduced enrollment (version 2) +============================== + +Round 1.1: generate a triangular row +------------------------------------ + +Each helper calls `secp256k1_frost_enrollment_reduced_shares_gen`. It computes + v_i = lambda_i * secshare_i. -For every `j > i`, it generates a random masking scalar `delta_(j,i)`. Entries -`delta_(j,i)` with `j < i` are structurally zero and are not transmitted. The -helper keeps the diagonal remainder +For every `j > i`, it derives a random masking scalar `delta_(j,i)`. Entries +with `j < i` are structurally zero and have no message. The helper retains the +diagonal remainder - delta_(i,i) = v_i - sum_{j=i+1}^{u-1} delta_(j,i) mod q + delta_(i,i) = v_i - sum_{j=i+1}^{u-1} delta_(j,i) mod q. -and sends `delta_(j,i)` to helper `h_j` only when `j > i`. Helper `h_j` then -computes and sends to the target +It sends `delta_(j,i)` to helper `h_j` only when `j > i`, together with the +parameters hash, sender identifier and recipient identifier. These values are +secret and require a confidential, authenticated channel. - sigma_j = sum_{i=0}^{j} delta_(j,i) mod q. +The output buffer remains u*32 bytes aligned with the caller's `ids` order. +Entries for smaller identifiers are zero, the own entry is retained, and +entries for larger identifiers are sent. Zero is NOT a routing marker: numeric +sender and recipient identifiers determine whether a matrix cell has a +message. -The target sums all u sigma values. The result is `f(x_new)` because every row -sums to `v_i`, every column sums to `sigma_j`, and the sum of the weighted -shares is the Lagrange interpolation of `f` at `x_new`. +Round 1.2: aggregate a column +----------------------------- -The triangular exchange sends `u(u-1)/2` helper-to-helper values and u -helper-to-target values, for `u(u+1)/2` values in total. For `u = t`, this is -the communication complexity proven optimal for the reduced enrollment RTS. -Buffers may retain a square `u*32` representation for API alignment, but zero -cells are not routing markers: canonical sender and recipient identifiers -determine which cells have messages. +Helper `h_j` calls `secp256k1_frost_enrollment_reduced_share_agg` with its own +retained entry and the entries received from helpers `h_i`, `i < j`. It checks +each lower-ranked helper's parameters hash against its own recomputation. The +own and higher-ranked hash slots are ignored; higher-ranked share entries must +be zero. It computes -Session and message contract ----------------------------- + sigma_j = sum_{i=0}^{j} delta_(j,i) mod q -A target starts a run with a fresh 32-byte session identifier. A version 2 -parameters hash binds the reduced-protocol domain, threshold public key, n, t, -new_id, sorted helper identifiers and session identifier. The share-splitting -hash has a separate reduced-protocol domain and binds the same parameters hash -as well as the sender and recipient identifiers. These version 2 tags and -encodings are exposed through explicit `reduced_` entry points alongside the -frozen version 1 API; there is no implicit wire compatibility between the full -and reduced protocols. +and sends `sigma_j`, its identifier and its parameters hash to the target over +a confidential, authenticated channel. -Every transmitted delta or sigma is accompanied by its parameters hash and -sender identifier; a delta also names its recipient. A recipient accepts only -the exact expected sender/recipient pairs and one contribution per sender. The -target checks every helper's parameters hash, not merely a representative one. -The checked target API requires an expected public share and returns a secret -share only after `secshare*G` equals it. +A parameters-hash mismatch, an invalid scalar or a nonzero structurally omitted +entry aborts aggregation and can be attributed to the corresponding helper. -The expected public share may be interpolated from authenticated public shares -or evaluated from an authenticated aggregate VSS commitment polynomial. Neither -construction authenticates its own inputs. In particular, matching the constant -commitment or interpolated group key does not stop colluding helpers from -supplying a different polynomial with the same constant term. The target MUST -authenticate the group descriptor independently of the enrollment messages. - -After enrollment, all existing participants and the target must update n and -append the derived public share only after verification. Repair leaves group -metadata unchanged. The library supplies deterministic derivation and -verification; transport, authorization, consensus and atomic persistent state -updates remain application responsibilities. - -Version 1 full-enrollment protocol -================================== - -The protocol ------------- - -Write `f` for the group's secret sharing polynomial of degree t-1, `s_i = -f(x_i)` for the secret share of participant `i` at x-coordinate `x_i = i + 1`, -and `L_i(x)` for the Lagrange basis polynomial of participant `i` over the set -of the u participating helpers. For any u >= t helpers, - - f(x_new) = sum_i L_i(x_new) * s_i - -so the target share is a fixed public linear combination of the helpers' -shares. The protocol computes that sum without any helper learning another's -term. - -1. **Round 1.1** (`secp256k1_frost_enrollment_shares_gen`, each helper). Helper - `i` computes `v_i = L_i(x_new) * s_i` and splits it into u additive shares - `d_{j,i}` with `sum_j d_{j,i} = v_i`, one per helper. It keeps `d_{i,i}` and - sends `d_{j,i}` to helper `j`. - - The random split is the security step. Without it, helper `i` would send - `v_i` itself to the target, who could multiply by `L_i(x_new)^-1` and - recover `s_i`. - -2. **Round 1.2** (`secp256k1_frost_enrollment_share_agg`, each helper). Helper - `j` sums the share it kept and the u-1 shares it received: - `sigma_j = sum_i d_{j,i}`, and sends `sigma_j` to the target. - -3. **Round 2** (`secp256k1_frost_enrollment_secshare_gen`, target). The target - sums the u values it received: - - sum_j sigma_j = sum_j sum_i d_{j,i} = sum_i v_i = f(x_new) - - which is a valid share at `x_new`. - -No individual helper ever sees more than one additive share of any `v_i`, and -the target sees only `u` sums, each of which is masked by every helper's -randomness. - -Who sends what to whom, for u = 3 helpers A, B, C and target N: - -``` -round 1.1 A computes v_A and splits it: d_AA d_BA d_CA - B computes v_B and splits it: d_AB d_BB d_CB - C computes v_C and splits it: d_AC d_BC d_CC - each helper KEEPS its own column entry (d_AA, d_BB, d_CC) - and sends the other two, with its params hash, to their owners - A --d_BA--> B A --d_CA--> C - B --d_AB--> A B --d_CB--> C - C --d_AC--> A C --d_BC--> B - -round 1.2 A: checks the hashes from B and C against its own recomputation, - then sigma_A = d_AA + d_AB + d_AC - B: sigma_B = d_BA + d_BB + d_BC - C: sigma_C = d_CA + d_CB + d_CC - A --sigma_A--> N - B --sigma_B--> N - C --sigma_C--> N - -round 2 N: checks the hash against its own recomputation, then - s_N = sigma_A + sigma_B + sigma_C = f(x_N), - and verifies s_N*G against the expected public share -``` - -Everything on an arrow except the parameters hash is secret. - -The API, in the same order -------------------------- - -| function | who runs it | when | -|----------|-------------|------| -| `secp256k1_frost_enrollment_params_hash` | anyone | any time; pure, public data | -| `secp256k1_frost_enrollment_shares_gen` | each helper | round 1.1 | -| `secp256k1_frost_enrollment_share_agg` | each helper | round 1.2 | -| `secp256k1_frost_enrollment_pubshare_derive` | anyone | before round 2; pure, public data | -| `secp256k1_frost_enrollment_secshare_gen` | the target | round 2 | - -Two conventions run through the whole API and are worth stating once: - -- Arrays of length u — the round 1.1 output, the round 1.2 inputs, the sigma - values, the helper public shares — are aligned with the caller's own `ids` - array, in whatever order the caller wrote it. The parameters hash is the one - thing that does not depend on that order: it sorts a local copy of the - identifiers before hashing, so helpers holding the same set in different - orders still agree. -- The two u*32 buffers of `share_agg` take OPPOSITE conventions at the - caller's own position: `all_shares32` reads it (that is the share - `shares_gen` kept), and `received_params_hashes32` never reads it. The - second half is what makes the check a recomputation rather than a - comparison between two strings the caller supplied. - -Enrollment mode and repair mode +Round 2: reconstruct and verify ------------------------------- -`new_id` selects the mode, and the bounds differ: +The target collects exactly one sigma and parameters hash from every expected +helper and calls `secp256k1_frost_enrollment_reduced_secshare_gen`. The function +recomputes the session-bound parameters hash, checks EVERY received hash, and +computes -| mode | condition | bound on n | -|------------|----------------------------|-----------------------------------------------| -| enrollment | `new_id == n_participants` | `n < SECP256K1_FROST_MAX_PARTICIPANTS` | -| repair | `new_id < n_participants` | `n <= SECP256K1_FROST_MAX_PARTICIPANTS` | + new_secshare = sum_j sigma_j = f(new_id+1). -Enrollment needs the stricter bound because the resulting group has n+1 -participants, and a 129-participant group is rejected by the frost module -everywhere. Repair does not change n, so the full range is allowed. +It rejects invalid scalar encodings and a zero result. Success additionally +requires -In both modes `new_id` must not be one of the helper identifiers: a helper -cannot be the target of its own run. + new_secshare*G == expected_pubshare. -After a successful enrollment, every participant must update its record of n to -n+1 and append the output of `secp256k1_frost_enrollment_pubshare_derive` to -its table of public shares. Nothing in the library enforces this bookkeeping; -participants that disagree about n will compute different Lagrange -coefficients in later signing sessions. +The expected public share is mandatory in the reduced API. Unlike the original +full-enrollment API, there is no successful unchecked target path. The target +must use a signing-capable context, and the output is wiped on failure. -Repair mode reproduces the lost share exactly, byte for byte, because the -target x-coordinate determines the value: the share is `f(x_j)`, not a fresh -random value. A repaired participant therefore keeps its old public share. +Communication complexity +------------------------ -Transport ---------- +The triangular exchange sends u(u-1)/2 helper-to-helper deltas and u sigmas, +for u(u+1)/2 secret values in total. At u = t this matches Section 4.1.3's +optimal reduced-enrollment communication complexity. The full protocol sends +u(u-1) helper-to-helper values and u sigmas, or u^2 in total. -The `d` values of round 1.1 and the `sigma` values of round 1.2 are additive -shares of real secret shares. They MUST be transmitted over confidential and -authenticated channels, both helper to helper and helper to target. Like the -chilldkg module, this module handles bytes only; the caller owns transport. - -Authorization -------------- - -The protocol has no authorization step. Any party that convinces t helpers to -run it at `x_new` walks away with a valid share at `x_new`. In repair mode this -is acute: an attacker who impersonates participant `j` and reaches t helpers -obtains participant `j`'s actual share. - -Authenticated channels are necessary but not sufficient — they establish who is -speaking, not that the helpers agreed this party is entitled to a share. The -library cannot enforce the missing step; it is a caller-side precondition, to -be met by the group's existing approval policy out of band. This is the same -gap that motivated ChillDKG's certification round. - -Verification, and what it is worth ----------------------------------- - -`secp256k1_frost_enrollment_secshare_gen` checks the derived share against the -expected public share `sum_i L_i(x_new) * P_i`, where `P_i` is helper `i`'s -public share. This catches any helper that contributed a wrong value, using -public data only. - -The check is only as strong as the provenance of its inputs. If the target -obtains both the helpers' public shares and the threshold public key from those -same helpers, then t colluding helpers can hand it a consistent fabricated -polynomial, and the check passes on a worthless share. The required flow is: - -1. Obtain `thresh_pk` from a source authenticated independently of the helpers. -2. Validate the helpers' public shares against it with - `secp256k1_frost_threshold_info_validate`. -3. Derive `expected_pubshare` from the validated public shares with - `secp256k1_frost_enrollment_pubshare_derive`. -4. Only then run `secp256k1_frost_enrollment_secshare_gen`, passing the same - authenticated `thresh_pk`. - -`examples/frost_enrollment.c` demonstrates exactly this sequence, and the -tests exercise the failure it prevents: a flipped bit in one `sigma` makes -`secp256k1_frost_enrollment_secshare_gen` fail and wipe its output, while the -same call with `expected_pubshare = NULL` succeeds and hands back a wrong -share. - -The parameter is therefore load-bearing. Pass NULL only if something else -validates the resulting share — for instance, a subsequent -`secp256k1_frost_threshold_info_validate` over the extended public share -table, which catches the same fault one step later. - -Parameter agreement and domain separation +Session identifiers and message agreement ----------------------------------------- -Three distinct mechanisms, which should not be conflated: +The target generates a fresh 32-byte `session_id` for each enrollment or repair +request. It is public but must not be reused to identify an unrelated request. +Every helper must authorize and use the exact tuple -1. *Helper against helper.* All u helpers must use byte-identical - `(thresh_pk, ids, new_id, n_participants, threshold)`. The `d` values cannot - cross-check this because they are per-helper private randomness, so - `secp256k1_frost_enrollment_share_agg` recomputes its own parameters hash - from the group key and the tuple, and compares every received hash against - the recomputed value. It never compares two caller-supplied strings, and it - never reads a hash out of its own slot — otherwise a caller could copy a - received hash into that slot and launder a mismatch into a pass. A - disagreement aborts round 1 and reports the disagreeing helper's identifier. + (session_id, threshold public key, n, t, new_id, helper set). -2. *Helper against target.* The round-1.2 check says nothing about the target's - view. `secp256k1_frost_enrollment_secshare_gen` therefore recomputes the - hash from the authenticated `thresh_pk` and the tuple the target believes, - and compares it against the helpers' hash. This catches "every helper agreed - on new_id = 7 while the target expected 5", and it catches a target being - fed a run from an entirely different group, before any secret arithmetic - happens. +The reduced parameters hash binds all of these values and the reduced protocol +domain. It prevents mixing full and reduced messages, groups, operations, +helper sets and sessions. Fresh session identifiers also provide domain +separation between repeated runs at the same target. They do not replace fresh +per-helper randomness. -3. *Domain separation.* The share-splitting randomness binds the parameters - hash, and therefore the group key and the whole tuple. Two runs that share a - `session_secrand32` but differ in group or parameters would otherwise produce - identical `d` sets, and differencing the `sigma` values would leak share - information. +Each delta envelope names its sender and recipient; each sigma envelope names +its sender. The caller must reject duplicates, missing contributions, wrong +recipients and messages outside the authorized session. The library operates +on bytes and does not provide networking or a transport state machine. -Because the hash commits to `thresh_pk` and not only to the integers, agreement -covers group identity: two unrelated groups with the same `(t, n, ids, new_id)` -produce different hashes. +Full enrollment (version 1) +=========================== -What none of this covers: once the parameter gates pass, a *corrupted* `sigma` -value is still only detectable, by the public-share check in round 2, and not -attributable to a particular helper. +The original functions implement the full share-exchange matrix: -Threshold must be at least 2 ----------------------------- +1. `secp256k1_frost_enrollment_shares_gen`: helper i splits + `v_i = lambda_i*secshare_i` into u values `delta_(j,i)`, keeps its own and + sends one to every other helper. +2. `secp256k1_frost_enrollment_share_agg`: helper j checks every received + parameters hash and computes `sigma_j = sum_i delta_(j,i)`, including its + retained entry. +3. `secp256k1_frost_enrollment_secshare_gen`: the target sums all u sigmas. -The frost module accepts `threshold >= 1`. This module refuses `threshold < 2`. +The full target API retains its historical optional parameters-hash and +public-share checks. They should both be enabled. Passing +`expected_pubshare = NULL` can return a well-formed but incorrect secret share +if a sigma is corrupted. New integrations should use the reduced API, where +this check is mandatory. -The reason is not that t = 1 is a weak threshold — a lone member of a 1-of-n -group can already sign anything. It is that this API permits any -`threshold <= n_ids`, so t = 1 would permit u = 1, and at u = 1 the additive -split degenerates to a single share: the lone helper sends the unsplit `v_1`, -which at t = 1 is the entire group secret. The protocol's security property -would be vacuous rather than merely weak. Requiring `threshold >= 2` forces -`n_ids >= 2`, which is what actually guarantees the split is non-degenerate. +In `share_agg`, `all_shares32` reads the caller's own slot, while +`received_params_hashes32` does not. The own hash is always recomputed rather +than copied from an input buffer. + +Public-share and commitment verification +======================================== + +Interpolating authenticated public shares +----------------------------------------- + +`secp256k1_frost_enrollment_pubshare_derive` computes + + P_new = sum_i lambda_i*P_i + +from the helpers' public shares. It works with both protocol versions and in +both enrollment and repair modes. A repaired participant's derived public share +equals its original public share. + +Evaluating an aggregate VSS commitment +-------------------------------------- + +`secp256k1_frost_enrollment_pubshare_derive_from_commitments` implements the +commitment-polynomial route discussed in the gist. For aggregate commitments +`C[k]` to the coefficient of x^k, it computes + + P_new = sum_{k=0}^{t-1} (new_id+1)^k*C[k] + +and checks `C[0] == threshold_public_key`. Input is t*33 bytes in ascending +coefficient order. Ordinary entries use compressed public-key encoding; 33 zero +bytes encode infinity for a zero coefficient. Invalid points, a mismatched +constant commitment and an infinity result are rejected. + +The aggregate commitment is the coefficient-wise sum of the original DKG +dealers' commitments. The enrollment module does not require ChillDKG and does +not add a build dependency on it. + +Authentication must not be circular +----------------------------------- + +Neither public-share interpolation nor commitment evaluation authenticates its +inputs. Colluding helpers can construct a different polynomial with the same +constant-term public key and present internally consistent public shares or +commitments. Therefore the target MUST authenticate the group descriptor +independently of the enrollment messages. + +The required public-share flow is: + +1. Authenticate the threshold public key and group metadata independently. +2. Validate the public-share table with + `secp256k1_frost_threshold_info_validate`, or authenticate the aggregate + commitment polynomial through the group's existing configuration mechanism. +3. Derive the expected target public share. +4. Run target reconstruction with that expected share and the same + authenticated threshold key. + +A corrupted delta or sigma can be detected by the final public-share check, but +it cannot be attributed to a particular helper. The module does not claim +identifiable malicious fault tolerance or robust completion. + +Finalizing enrollment and repair +================================ + +After successful enrollment, every existing participant and the target must: + +1. obtain the same derived `new_pubshare` through authenticated group metadata; +2. append it at `new_id`; +3. increment n to n+1; and +4. validate the extended table with + `secp256k1_frost_threshold_info_validate` before signing. + +Non-helper participants need this update too. Participants using different n +or public-share tables cannot reliably sign together. Transport, +authorization, consensus and atomic persistent state updates remain application +responsibilities. The example demonstrates the library-side validation and +bookkeeping. + +Repair leaves n and the public-share table unchanged. It recreates the original +secret share byte for byte; it does not rotate or revoke a copied share. +Enrollment and repair are not proactive refresh, signer removal or threshold +change protocols. + +Transport, authorization and privacy +==================================== + +All deltas and sigmas are additive shares of real secret shares and MUST use +confidential, authenticated channels. Parameters hashes, identifiers and public +group metadata are public, but their session and provenance checks are still +required. + +Authenticated transport establishes who sent a message, not whether that +request should be approved. Any party that convinces t helpers to participate +receives a valid share. In repair mode this is an existing participant's actual +share. Helpers MUST authorize the exact session, group, helper set, operation +and target out of band before generating shares. + +The enrollment RTS privacy argument considers coalitions of fewer than t +participants executing the protocol honestly. The public checks add correctness +detection but do not provide a general malicious-secure complaint or recovery +protocol. Randomness ----------- +========== -`secp256k1_frost_enrollment_shares_gen` requires fresh uniform randomness for -every run. Reusing `session_secrand32` across runs leaks share information; the -domain-separation binding above mitigates this for runs that differ in their -parameters, but does not excuse it. The function wipes the seed before -returning and masks the derived randomness with the secret share, so that a -weak random number generator alone does not reveal the split. +Each helper supplies fresh uniform 32-byte session randomness to every full or +reduced `shares_gen` call. Reusing it can leak share information. The function +wipes the seed on success and on every failure path that enters its body. -No key refresh --------------- +The derived randomness is masked with the helper's secret share as defense in +depth against a weak random source. The parameters hash is included in every +mask derivation; reduced masks additionally depend on the session identifier +through that hash. Mask derivation uses the recipient identifier rather than +its array position. -Enrollment does not change the polynomial and does not change any existing -share. The group's long-term security assumptions are unchanged: an adversary -who had collected shares before an enrollment still holds valid shares -afterwards. This protocol adds a participant; it is not a proactive refresh. +Threshold must be at least 2 +============================ -Test vectors ------------- +The frost module accepts threshold 1, but enrollment rejects it. A one-helper +additive split would be degenerate: the target could receive the unsplit +weighted share, which at threshold 1 is the group secret. Requiring t >= 2 +forces u >= 2 and avoids that degenerate protocol. -`src/modules/frost_enrollment/vectors.h` is generated by -`tools/test_vectors_frost_enrollment_generate.py`. These are REGRESSION -vectors, not cross-validation vectors, and the distinction matters. +Frozen encodings and vectors +============================ -This protocol has no BIP and no published vectors, and the reference proof of -concept draws its randomness from `secrets.randbits`, which is not seedable — -so there is nothing to check the implementation against. The generator instead -re-implements the same math in stdlib-only Python, writing the group -arithmetic out from the secp256k1 parameters rather than borrowing it, and -freezes the result. - -What that pins: the two tag strings, the parameters hash serialization, the -share-splitting derivation and the identifier conventions. Changing any of -them is a vector-breaking change, and that is the point. What it does not -establish is protocol correctness — the algebraic invariants in -`src/modules/frost_enrollment/tests_impl.h` carry that: reconstruction from -every threshold-sized subset, a real BIP340 signature from a set including the -new participant, byte equality in repair mode, and -`secp256k1_frost_threshold_info_validate` accepting the extended public share -table. - -Frozen encodings ----------------- - -Two tagged hashes, both using SHA256 with the BIP340-style tag prefix: +The full protocol uses params_hash = TH("FROST enrollment/params_hash", cbytes(thresh_pk) || ser32(n) || ser32(t) || - ser32(new_id) || ser32(u) || - ser32(sorted_ids[0]) || ... || ser32(sorted_ids[u-1])) + ser32(new_id) || ser32(u) || ser32(sorted_ids...)) - rand = TH("FROST enrollment/share_split", session_secrand32) - XOR secshare32 - d_recipient = Scalar.from_bytes_wrapping( - TH("FROST enrollment/share_split", - rand || params_hash || ser32(my_id) || - ser32(recipient_id))) + rand = TH("FROST enrollment/share_split", session_secrand32) + XOR secshare32 -where `cbytes` is the 33-byte compressed point serialization, `ser32` is the -32-bit big-endian encoding, and `from_bytes_wrapping` reduces modulo the group -order rather than rejecting (the statistical distance is about 2^-128, and -rejection sampling would add a variable-time loop for nothing). + delta_recipient = Scalar.from_bytes_wrapping( + TH("FROST enrollment/share_split", + rand || params_hash || ser32(my_id) || ser32(recipient_id))). -The masking share is indexed by the recipient's IDENTIFIER rather than by its -position in the caller's array, so the split does not depend on the order the -helper set was written in. Identifiers are unique, so this is injective. +The reduced protocol uses separate domains: -Constant time -------------- + reduced_hash = TH("FROST enrollment/reduced/params_hash", + cbytes(thresh_pk) || ser32(n) || ser32(t) || + ser32(new_id) || ser32(u) || ser32(sorted_ids...) || + session_id32) -All arithmetic on secret data uses the constant-time `secp256k1_scalar` -operations. Every branch driven by identifiers, counts or hash comparisons -operates on public values. Secret intermediates are cleansed with -`secp256k1_memclear_explicit` before the functions return, and outputs are -zeroed on every failure path. + reduced_rand = TH("FROST enrollment/reduced/share_split", + session_secrand32) XOR secshare32 -The one exception is `shares32_out` in -`secp256k1_frost_enrollment_shares_gen`, the only output in this module whose -size is caller-supplied. When the parameter tuple is rejected, that buffer is -left untouched rather than zeroed: its extent is only known to be `u*32` once -`n_ids` has been validated against the rest of the tuple, so zeroing first -would write past a buffer whose length the caller got wrong. Failures -detected after validation — an unusable `thresh_pk`, `my_id` not among the -helpers, an invalid secret share — do zero it. Callers that inspect an output -buffer after a failed call must therefore treat a rejected tuple as leaving it -unmodified, not as leaving it zeroed. + delta_recipient = Scalar.from_bytes_wrapping( + TH("FROST enrollment/reduced/share_split", + reduced_rand || reduced_hash || ser32(my_id) || + ser32(recipient_id))), only for recipient_id > my_id. + +Reduced entries for smaller recipient identifiers are zero and are not derived +or sent. `ser32` is big-endian, `cbytes` is 33-byte compressed public-key +encoding, and wrapping reduces modulo the group order. The statistical distance +from uniform is about 2^-128. + +`tools/test_vectors_frost_enrollment_generate.py` independently reimplements +the arithmetic in stdlib-only Python and emits both full and reduced regression +cases. These pin tags, serialization, session binding, matrices and identifier +conventions. They are not published interoperability vectors: the reference +proofs of concept do not provide deterministic MPC transcripts. Algebraic +invariants, signing tests, fault injection and randomized tests in +`tests_impl.h` provide the correctness coverage. + +Constant time and failure hygiene +================================= + +Secret arithmetic uses constant-time scalar operations. Branches based on +identifiers, counts, public hashes and public validity results do not depend on +secret values. Secret intermediates and consumed randomness are cleared before +return, and secret outputs are zeroed on failure. `src/ctime_tests.c` exercises +both full and reduced rounds under Valgrind. + +The variable-length `shares32_out` buffer is the one exception to blanket output +zeroing. If the parameter tuple is rejected before its u*32 extent can be +validated, it is left untouched. Once validation succeeds, later failures zero +that buffer. Fixed-size outputs are zeroed on failure.