docs: specify FROST share re-enrollment

This commit is contained in:
Kgothatso Ngako committed 2026-11-19 22:51:56 +02:00
1 parent 1eda3416c1
commit 7df2dca551
2 files changed
+226

No files matched your search

+1
View File
@@ -17,6 +17,7 @@ the [retired](./retired/) notes now.
| [subgroups.md](./subgroups.md) | a group making another group — the four ceremonies, what the parent's signature actually covers, and why the child's key is fresh rather than derived |
| [ceremony-creation.md](./ceremony-creation.md) | one place to start a key ceremony — how joining a subgroup's ceremony opened a second one for the parent room, the screen that showed a ceremony and offered to start one in the same button, and the removal of the nip30303 documents, whose kinds collided with the ceremony's, leaving the member chronicle with nothing to carry and nothing to say |
| [frost-batch-signing.md](./frost-batch-signing.md) | signing several events in one ceremony — why one nonce can never cover two messages, and the phased schema, wire and UI work that follows from it |
| [frost-re-enrollment.md](./frost-re-enrollment.md) | re-issuing every member's share under the same group key — the zero-sharing construction, why enrollment alone is not a refresh, candidate-signed epoch activation, and the old-quorum compromise boundary |
| [frost-session-resend.md](./frost-session-resend.md) | asking the members who never got a signing proposal to look again — why a proposer can repeat only what it wrote, why a member's availability signal needs no repeating, and the one half that has to come from the silent member's own device |
| [marmot-membership.md](./marmot-membership.md) | how members join an MLS group, and the epoch race that makes a missing member look like a successful invite |
| [member-chronicle.md](./member-chronicle.md) | handing a member added after the work was done the group's signed record — why the events are not on the wire at all, and why the room's id is enough to verify them |
+225
View File
@@ -0,0 +1,225 @@
# FROST re-enrollment
**Status: protocol specification, implementation in progress.**
Re-enrollment is a proactive share refresh: every member of an existing FROST group
receives a newly generated share of the **same threshold public key**. It is not a fresh
ChillDKG ceremony, an enrollment of a new participant, or a repair of an existing share.
The existing `FrostEnrollment` API turns a `(t, n)` group into a `(t, n + 1)` group and
repairs a share by reproducing it. Its native specification explicitly says that it does
not refresh keys. Re-enrollment needs a different primitive and a new application
ceremony.
## Security boundary
A refresh supersedes shares for the group's future operation. It does **not** revoke an
old threshold quorum. Any `t` shares from one old epoch still describe the same group
secret and can still produce signatures that verify against the unchanged group key.
The protection a refresh buys is against an adversary collecting fewer than `t` shares in
several different epochs. Honest members must delete their previous shares, and old and
new shares must never be accepted into one signing session.
A group that suspects a threshold of current shares is compromised must run a new DKG and
move to the room derived from the new key. Re-enrollment cannot solve that case.
## Scope
The first protocol version keeps all of these fixed:
- the threshold public key and the Marmot room id derived from it;
- the derivation path and any subgroup birth certificate;
- `t`, `n`, member identities and their FROST signer ids;
- the share-holder roster.
It runs in an existing Marmot room. Every share holder must eventually participate:
signing needs `t`, but refreshing every member's share requires all `n` to stage and
acknowledge a candidate. Membership changes, threshold changes, NIP-17-only groups and
automatic refreshes are separate work.
A share epoch is an application-level FROST version. It is unrelated to an MLS epoch.
## Cryptographic construction
Write `f` for the current sharing polynomial, `x = f(0)` for the group secret and
`Y = xG` for the group public key. Participant `i` currently holds `s_i = f(x_i)` and has
public share `P_i = s_iG`.
Each participant independently generates a degree-at-most-`t - 1` polynomial with a zero
constant term:
```
g_i(X) = a_i1 X + a_i2 X^2 + ... + a_i(t-1) X^(t-1)
```
The participant publishes commitments to every non-constant coefficient, `a_i,k G`, and
sends `g_i(x_j)` privately to participant `j`. The zero constant is implicit; no point at
infinity is serialised as a public key.
Recipient `j` verifies each evaluation against its dealer's public commitments, then
computes:
```
s'_j = s_j + sum_i g_i(x_j)
P'_j = P_j + sum_i sum_k x_j^k (a_i,k G)
```
The resulting polynomial and group key are:
```
f' = f + sum_i g_i
f'(0) = f(0) = x
s'_jG = P'_j
```
The candidate public-share table must also pass `frostThresholdInfoValidate` against the
independently authenticated threshold public key. A per-recipient evaluation check names
a faulty dealer; the final public-share check catches any remaining inconsistency.
### Randomness and replay
Each dealer uses fresh uniform randomness for every refresh session. The derivation is
domain-separated by the protocol version, refresh session id, group key, old and new share
epochs, threshold and ordered participant ids.
Recomputing one session from its stored seed reproduces identical commitments and
evaluations, which makes redelivery safe. A failed refresh gets a new session id and fresh
randomness. Randomness is never reused between sessions.
## Ceremony
```text
coordinator -> everyone: proposal
participant -> everyone: public coefficient commitments
participant -> each other participant privately: one evaluation
participant -> coordinator and everyone: READY(candidate transcript hash)
a quorum, using candidate shares: sign the next key-epoch state
every device, independently: atomically activate the candidate and retire old secrets
```
### Proposal
The proposal fixes the protocol version, session id, room and root DKG ids, current and
next share epochs, threshold, participant ids and previous signed key-state event id.
Every receiver checks these against its local key state. A proposal publishes nothing on a
member's behalf until that member approves joining.
### Commitments and evaluations
Public commitments travel as Marmot protocol events. Private evaluations travel only in
`MarmotDirectMessage`: NIP-44 to one recipient, a sender-signed seal bound to the MLS
sender identity, and `MarmotInnerEvent` as the outbound and inbound store. They never go
through `GiftWrapPayload`, a relay broadcast request or an ordinary chat row.
A message is keyed by `(session, sender, recipient, kind)`. The first payload wins. A
conflicting redelivery is ignored rather than allowed to change the ceremony.
### Candidate and READY
Once all commitments and evaluations are present and valid, each device derives and stores
its candidate secret share and the complete candidate public-share table without making
them active. It checks its own candidate against its public share and validates the whole
table against the threshold key.
`READY` commits to a canonical transcript hash covering the protocol version, session id,
room and key identifiers, both epochs, roster, threshold, previous key-state event and
ordered commitments. Activation requires matching `READY` messages from all `n` members.
### Activation
Any member holding the complete transcript may propose activation. A threshold of members
then signs a new key-epoch state **with their candidate shares**. Activation uses a new
signing session with fresh nonce seeds. If it fails, retrying creates another signing
session with fresh seeds; the verified candidate is retained and the share refresh is not
rerun.
The signed state names the unchanged threshold key, root DKG id, derivation path and
parentage, plus the next share epoch, refresh session id, transcript hash, previous
key-state event id and candidate public-share hash. It travels on a new kind so an old
build cannot adopt it accidentally.
A device applies it only after checking the group signature, room derivation, epoch
successor, previous state, transcript and its own staged candidate. In one database
transaction it:
- replaces the root `DkgSession`'s secret and public shares and increments its share epoch;
- installs the new `GroupKeyState` epoch;
- completes the refresh session and fences superseded signing sessions;
- clears staged candidates and secret refresh inputs;
- schedules any remaining old-secret cleanup.
A device that knows a higher signed epoch but lacks its matching candidate blocks signing
and asks for replay. It does not silently fall back to its old share.
## Signing rules
Every signing session records its share epoch. Proposal acceptance, nonce generation,
partial signing, aggregation, completion and resend all require that epoch to match the
active key epoch. Activation sessions are the only exception and can use only the named,
staged candidate.
Post-genesis signing uses an epoch-aware proposal kind that old builds do not route. An
old proposal or key-state event cannot move a device backwards. Key states are ordered by
share epoch before timestamp; conflicting states at one epoch are an error, not a race won
by the newest timestamp.
## Failure and recovery
Before `READY`, a participant may cancel. Cancellation deletes pending secret material and
leaves the old epoch active.
After broadcasting `READY`, a participant retains its candidate until activation or an
unambiguously abandoned refresh. A valid signed activation takes precedence over a local
failure display. This avoids deleting a candidate after other members have already signed
its activation.
Messages are persisted before dispatch and all advancement is idempotent. Resends reuse
stored bytes. A private resend wraps the same evaluation afresh for the current MLS
generation; it never regenerates a polynomial. A different member can take over activation
from the stored transcript.
After activation, original ChillDKG recovery data and round randomness no longer describe
the active share and are scrubbed. Private evaluations are scrubbed from refresh and inner
event rows. Cleanup is idempotent and resumes at startup. SQLite checkpoints can reduce
residual copies, but exported backups and filesystem snapshots are outside the ceremony's
reach and the UI must not claim otherwise.
A refreshed share is not recoverable from the profile recovery phrase alone. Current-epoch
repair uses `FrostEnrollment` in repair mode, with an independently authenticated group
key, a validated current public-share table, an expected current public share, and
explicit helper approval. Production availability requires this repair path or an explicit
decision to accept loss of signing on reinstall.
## Persistence
The root `DkgSession` id and signer mapping remain stable. Its share fields describe the
current epoch rather than necessarily the original ChillDKG output.
Existing rows start at share epoch zero. New refresh session and message tables store the
inputs needed to recompute every native step. Activation-signing rows name their refresh
session. Transcript rows name their refresh session just as they already name DKG and
signing sessions.
Migration must be additive: rebuilding a signing or DKG table risks its child rows and
cascades. An upgrade by itself changes no share material and starts no ceremony.
## Verification and rollout gates
The native module needs deterministic vectors, algebra and fault tests, constant-time
secret arithmetic, cleansing on failure, and tests on JVM and native targets. App tests
need real multi-device refreshes, every threshold signer subset, mixed-epoch rejection,
out-of-order delivery, malicious dealers, activation retry, crash recovery, downgrade
rejection and proof that private values never enter a transcript or relay queue.
Implementation ships dark in this order: crypto, schema, transport, manager, UI. Activation
requires `READY` from all `n`, which is also the proof that every member runs a compatible
build. General availability additionally requires independent cryptographic review,
physical Android and iOS ceremonies, and a working current-epoch repair flow.
The project's standard gates remain:
```bash
./gradlew :composeApp:m3Audit
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
```