frost_enrollment: document and demonstrate reduced enrollment

This commit is contained in:
Kgothatso Ngako committed 2026-11-18 22:59:18 +02:00
1 parent 9d930cf145
commit b1ccf390a0
2 files changed
+355 -422

No files matched your search

+59 -43
View File
@@ -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));
+296 -379
View File
@@ -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.