frost/secp256k1-zkp
3
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chilldkg: Phase 3 - public participant API and CertEq

Browse Source 
Add the public participant-facing ChillDKG API to
include/secp256k1_chilldkg.h and the CertEq sub-protocol, completing
the participant side of the protocol (bip-frost-dkg v0.3.0-dev,
reference pinned at a91896883f85b159415ecf298d5e844879af112d).

New module files:
- certeq.h / certeq_impl.h: CertEq sub-protocol. Participants sign
  pad33("BIP DKG/certeq message") || u32be(i) || eq_input with plain
  BIP0340-tagged Schnorr signatures under their host key
  (certeq_participant_step); verification is per-index against the
  x-only hostpubkeys[i][1:33] exactly as the reference
  (certeq_verify). The coordinator side reuses certeq_verify in
  Phase 4.

Public API (all no-malloc, caller-allocated buffers, outputs zeroed on
failure, secret paths cleared):
- secp256k1_chilldkg_hostpubkey_gen: plain compressed host pubkey
  generation; rejects zero / >= group order seckeys.
- secp256k1_chilldkg_params_hash: validates session params (participant
  and threshold ranges, strictly compressed non-infinity pubkeys, no
  duplicates) and computes TH("BIP DKG/params_hash", u32be(t) ||
  hostpubkeys).
- Message-length helpers so callers can size buffers:
  participant_msg1_len (33t+32n+97), coordinator_msg1_len
  (162n+33(t-1)), participant_msg2_len (64), coordinator_msg2_len
  (64n), recovery_data_len (4+33t+162n).
- secp256k1_chilldkg_participant_step1: full EncPedPop step1 with
  seed=deckey=hostseckey; rejects zero randomness and hostseckeys not
  matching the claimed hostpubkey (input errors, not protocol faults).
- secp256k1_chilldkg_participant_step2: parses and verifies cmsg1 via
  the Phase 2 encpedpop/simplpedpop participant path, computes the
  tweaked secshare/pubshares/threshold pubkey, appends enc_secshares
  to eq_input (matching the reference for recovery consistency), and
  emits the 64-byte CertEq signature.
- secp256k1_chilldkg_participant_finalize: re-verifies all n CertEq
  signatures in the certificate, then outputs the 32-byte secshare,
  33-byte threshold pubkey, n pubshares and the self-delimiting
  recovery data (eq_input || cert).

Blame reporting without exceptions: public enum
secp256k1_chilldkg_fault (OK / FAULTY_COORDINATOR /
FAULTY_PARTICIPANT / FAULTY_PARTICIPANT_OR_COORDINATOR /
UNKNOWN_FAULTY_PARTICIPANT_OR_COORDINATOR / INVALID_INPUT) plus an out
fault_index, mapping the reference's exception taxonomy:
- hostseckey invalid/mismatch -> INVALID_INPUT (HostSeckeyError),
- cmsg1 scalar overflow/parse -> FAULTY_COORDINATOR (MsgParseError),
- pubnonce/commitment/PoP faults -> FAULTY_PARTICIPANT_OR_COORDINATOR(i),
- share-vs-pubshare mismatch -> UNKNOWN with fault_index = UINT32_MAX,
- certificate signature failure -> FAULTY_COORDINATOR (documented
  deviation: fault_index carries the failing signature index as
  diagnostic info; the reference discards it).
Enum-returning functions use a local CHILLDKG_ARG_CHECK that fires the
illegal-argument callback and returns INVALID_INPUT (ARG_CHECK would
return 0 = OK).

Opaque state objects with magic-validated save/load (frost idiom):
participant_state1 (4306 bytes, no secrets) and participant_state2
(21073 bytes, contains the secshare; documented keep-secret/no-copy).
Fixed-size at SECP256K1_CHILLDKG_MAX_PARTICIPANTS = 128.

Also fixes a noverify-build bug: state1_load ran point_load inside
VERIFY_CHECK, which compiles out in noverify builds and left the
commitment uninitialized; now called unconditionally.

tests_impl.h: participant_api_test with full-session reference vectors
(n=3, t=2; coordinator aggregation simulated through the internal
Phase 2 coordinator step and verified byte-identical to the
reference's coordinator_step1): msglen helpers, hostpubkey_gen and
params_hash vectors incl. duplicate/invalid/infinity rejection,
byte-exact pmsg1/cmsg1/CertEq sigs/secshare/thresh_pk/pubshares/
recovery, blame cases (tampered enc_secshare -> UNKNOWN, invalid
pubnonce -> FAULTY_PARTICIPANT_OR_COORDINATOR(1), overflowing
enc_secshare -> FAULTY_COORDINATOR, corrupted cert sig ->
FAULTY_COORDINATOR with fault_index and zeroed outputs), NULL-arg
misuse and bad-magic state rejection.

Verified: make check 3/3 (incl. noverify); CMake ctest 363/363;
make distdir includes all new files.
This commit is contained in:
Kgothatso Ngako
2026-08-31 05:22:53 +02:00
parent 580e4f6502
commit 2a0e14d076
12 changed files with 1135 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

276
include/secp256k1_chilldkg.h
View File

@@ -27,10 +27,286 @@ extern "C" {
* key, and the public shares of all participants) is designed to be used
* directly with the FROST signing module (see include/secp256k1_frost.h).
*
* A DKG session involves n participants (identified by uint32 identifiers
* 0..n-1) and an untrusted coordinator. The number of participants n must
* not exceed SECP256K1_CHILLDKG_MAX_PARTICIPANTS. The message flow is:
* 1. Every participant runs secp256k1_chilldkg_participant_step1 and sends
* the resulting pmsg1 to the coordinator.
* 2. The coordinator aggregates the pmsg1s into a single cmsg1 broadcast
* to all participants (coordinator API is not available yet).
* 3. Every participant runs secp256k1_chilldkg_participant_step2 and sends
* the resulting signature (pmsg2) to the coordinator.
* 4. The coordinator collects the n signatures into a certificate (cmsg2)
* broadcast to all participants.
* 5. Every participant runs secp256k1_chilldkg_participant_finalize to
* obtain the DKG output and the recovery data.
*
* It is recommended to read the documentation in this include file carefully.
* Further notes on API usage can be found in src/modules/chilldkg/chilldkg.md.
*/
/** The maximum number of participants n in a ChillDKG session. The state
* objects of this module are fixed-size and do not use dynamic allocation,
* so a compile-time cap is required. This matches the FROST module's
* SECP256K1_FROST_MAX_PARTICIPANTS. */
#define SECP256K1_CHILLDKG_MAX_PARTICIPANTS 128
/** Fault report of the ChillDKG protocol functions, mapping the exception
* taxonomy of the reference implementation.
*
* For SECP256K1_CHILLDKG_FAULTY_PARTICIPANT and
* SECP256K1_CHILLDKG_FAULTY_PARTICIPANT_OR_COORDINATOR, the fault_index
* output of the failing function is set to the identifier of the (suspected)
* faulty participant. For the other fault codes, fault_index is set to
* UINT32_MAX, except where documented otherwise. */
typedef enum {
/** No fault; the step succeeded. */
SECP256K1_CHILLDKG_OK = 0,
/** The coordinator is faulty. */
SECP256K1_CHILLDKG_FAULTY_COORDINATOR = 1,
/** The participant with the given fault_index is faulty. */
SECP256K1_CHILLDKG_FAULTY_PARTICIPANT = 2,
/** The participant with the given fault_index or the coordinator is
* faulty. */
SECP256K1_CHILLDKG_FAULTY_PARTICIPANT_OR_COORDINATOR = 3,
/** Some unknown participant or the coordinator is faulty; the
* investigation procedure of the protocol is necessary to determine a
* suspected participant. */
SECP256K1_CHILLDKG_UNKNOWN_FAULTY_PARTICIPANT_OR_COORDINATOR = 4,
/** The caller provided invalid input (e.g., an invalid host secret key or
* invalid session parameters). */
SECP256K1_CHILLDKG_INVALID_INPUT = 5
} secp256k1_chilldkg_fault;
/** Opaque data structures
*
* The exact representation of data inside the opaque data structures is
* implementation defined and not guaranteed to be portable between different
* platforms or versions. The data structures can be safely copied/moved.
*/
/** Opaque data structure that holds a participant's session state after
* secp256k1_chilldkg_participant_step1.
*
* The state does not contain secret key material (the secret shares it
* relates to are encrypted in pmsg1), but it must not be reused: it must be
* passed only to a single secp256k1_chilldkg_participant_step2 call.
*
* Guaranteed to be 4306 bytes in size.
*/
typedef struct secp256k1_chilldkg_participant_state1 {
unsigned char data[4 + 12 + 33 + 33 + 33 * SECP256K1_CHILLDKG_MAX_PARTICIPANTS];
} secp256k1_chilldkg_participant_state1;
/** Opaque data structure that holds a participant's session state after
* secp256k1_chilldkg_participant_step2.
*
* This structure contains the participant's secret share; it MUST be kept
* secret and MUST NOT be copied. It must not be reused: it must be passed
* only to a single secp256k1_chilldkg_participant_finalize call.
*
* Guaranteed to be 21073 bytes in size.
*/
typedef struct secp256k1_chilldkg_participant_state2 {
unsigned char data[12 + 4 + 131 * SECP256K1_CHILLDKG_MAX_PARTICIPANTS + 32 + 33 + 33 * SECP256K1_CHILLDKG_MAX_PARTICIPANTS];
} secp256k1_chilldkg_participant_state2;
/** Compute the participant's host public key from the host secret key.
*
* The host public key is the long-term cryptographic identity of the
* participant. This function interprets hostseckey32 as a big-endian integer
* and computes the corresponding "plain" public key in compressed
* serialization (33 bytes, starting with 0x02 or 0x03), equivalent to
* IndividualPubkey as defined in BIP 327.
*
* Returns: 1 on success, 0 if the host secret key is invalid (zero or not
* less than the group order). On failure, hostpubkey33 is set to
* zero.
* Args: ctx: pointer to a context object
* Out: hostpubkey33: pointer to a 33-byte array to store the host public key
* In: hostseckey32: pointer to the 32-byte host secret key
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_chilldkg_hostpubkey_gen(
const secp256k1_context *ctx,
unsigned char *hostpubkey33,
const unsigned char *hostseckey32
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
/** Return a hash of the session parameters for out-of-band comparison.
*
* If all participants have obtained an identical parameters hash (as can be
* verified out of band), then they all agree on all host public keys and the
* threshold t.
*
* Returns: 1 on success, 0 if the session parameters are invalid (not
* 1 <= t <= n <= SECP256K1_CHILLDKG_MAX_PARTICIPANTS, an invalid
* host public key, or a duplicate host public key). On failure,
* hash32 is set to zero.
* Args: ctx: pointer to a context object
* Out: hash32: pointer to a 32-byte array to store the parameters
* hash
* In: hostpubkeys33: pointer to an array of n_participants host public
* keys (33 bytes each, compressed serialization)
* n_participants: total number of participants n
* threshold: threshold t
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_chilldkg_params_hash(
const secp256k1_context *ctx,
unsigned char *hash32,
const unsigned char *hostpubkeys33,
size_t n_participants,
uint32_t threshold
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
/** Length of a participant's first message (pmsg1): 33*t + 32*n + 97 bytes.
* Returns 0 if the parameters are out of range. */
SECP256K1_API size_t secp256k1_chilldkg_participant_msg1_len(
size_t n_participants,
uint32_t threshold
);
/** Length of the coordinator's first message (cmsg1): 162*n + 33*(t-1) bytes.
* Returns 0 if the parameters are out of range. */
SECP256K1_API size_t secp256k1_chilldkg_coordinator_msg1_len(
size_t n_participants,
uint32_t threshold
);
/** Length of a participant's second message (pmsg2): 64 bytes. */
SECP256K1_API size_t secp256k1_chilldkg_participant_msg2_len(void);
/** Length of the coordinator's second message (cmsg2, the certificate):
* 64*n bytes. Returns 0 if the parameters are out of range. */
SECP256K1_API size_t secp256k1_chilldkg_coordinator_msg2_len(
size_t n_participants
);
/** Length of the recovery data output by
* secp256k1_chilldkg_participant_finalize: 4 + 33*t + 162*n bytes.
* Returns 0 if the parameters are out of range. */
SECP256K1_API size_t secp256k1_chilldkg_recovery_data_len(
size_t n_participants,
uint32_t threshold
);
/** Perform a participant's first step of a ChillDKG session.
*
* Returns: 1 on success, 0 on invalid input (invalid host secret key, host
* secret key not matching any host public key, invalid session
* parameters, or all-zero randomness). On failure, pmsg1 and the
* state are set to zero.
* Args: ctx: pointer to a context object
* Out: state1: pointer to a state1 object to be passed to
* secp256k1_chilldkg_participant_step2 (must not be
* reused)
* pmsg1: pointer to a 33*t + 32*n + 97 byte array (see
* secp256k1_chilldkg_participant_msg1_len) to store
* the message to be sent to the coordinator
* In: hostseckey32: pointer to the 32-byte host secret key
* hostpubkeys33: pointer to an array of n host public keys (33 bytes
* each); all participants must agree on the order
* n_participants: total number of participants n
* threshold: threshold t
* random32: pointer to 32 bytes of FRESH randomness
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_chilldkg_participant_step1(
const secp256k1_context *ctx,
secp256k1_chilldkg_participant_state1 *state1,
unsigned char *pmsg1,
const unsigned char *hostseckey32,
const unsigned char *hostpubkeys33,
size_t n_participants,
uint32_t threshold,
const unsigned char *random32
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(8);
/** Perform a participant's second step of a ChillDKG session.
*
* Verifies the coordinator's first message, computes the DKG output, and
* produces the CertEq signature over the session transcript.
*
* **Warning:** After sending the produced signature to the coordinator, the
* caller **must not** erase the hostseckey, even if the coordinator reply
* needed for secp256k1_chilldkg_participant_finalize is not received (some
* other participant may deem the session successful and use the resulting
* threshold public key).
*
* Returns: SECP256K1_CHILLDKG_OK on success, otherwise a fault code:
* SECP256K1_CHILLDKG_INVALID_INPUT if the host secret key is
* invalid or does not match the one used in step 1;
* SECP256K1_CHILLDKG_FAULTY_COORDINATOR,
* SECP256K1_CHILLDKG_FAULTY_PARTICIPANT_OR_COORDINATOR, or
* SECP256K1_CHILLDKG_UNKNOWN_FAULTY_PARTICIPANT_OR_COORDINATOR on
* protocol faults. On failure, sig64 and the state are set to zero.
* Args: ctx: pointer to a context object
* Out: state2: pointer to a state2 object to be passed to
* secp256k1_chilldkg_participant_finalize (must not be
* reused)
* sig64: pointer to a 64-byte array to store the CertEq
* signature (pmsg2) to be sent to the coordinator
* fault_index: pointer to a uint32 that receives the identifier of
* the (suspected) faulty participant where applicable,
* and UINT32_MAX otherwise
* In: state1: pointer to the state1 object output by
* secp256k1_chilldkg_participant_step1
* hostseckey32: pointer to the 32-byte host secret key (must be the
* same as in step 1)
* cmsg1: pointer to the coordinator's first message
* (162*n + 33*(t-1) bytes, see
* secp256k1_chilldkg_coordinator_msg1_len)
* aux_rand32: pointer to 32 bytes of auxiliary randomness for the
* CertEq signature (see BIP 340)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_chilldkg_fault secp256k1_chilldkg_participant_step2(
const secp256k1_context *ctx,
secp256k1_chilldkg_participant_state2 *state2,
unsigned char *sig64,
uint32_t *fault_index,
const secp256k1_chilldkg_participant_state1 *state1,
const unsigned char *hostseckey32,
const unsigned char *cmsg1,
const unsigned char *aux_rand32
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(6) SECP256K1_ARG_NONNULL(7) SECP256K1_ARG_NONNULL(8);
/** Perform a participant's final step of a ChillDKG session.
*
* Re-verifies all n CertEq signatures of the certificate and outputs the
* DKG output and the recovery data. If this function returns
* SECP256K1_CHILLDKG_OK, this participant deems the DKG session successful.
*
* Returns: SECP256K1_CHILLDKG_OK on success,
* SECP256K1_CHILLDKG_FAULTY_COORDINATOR if the certificate contains
* an invalid signature. As diagnostic information (deviating from
* the reference implementation, which does not report it),
* fault_index receives the index of the first invalid signature in
* the latter case. On failure, all outputs are set to zero.
* Args: ctx: pointer to a context object
* Out: secshare32: pointer to a 32-byte array to store the (tweaked)
* secret share
* thresh_pk33: pointer to a 33-byte array to store the threshold
* public key (compressed serialization)
* pubshares33: pointer to an array of n 33-byte elements to store
* the public shares of all participants
* recovery: pointer to a 4 + 33*t + 162*n byte array (see
* secp256k1_chilldkg_recovery_data_len) to store the
* recovery data
* fault_index: pointer to a uint32 (see above)
* In: state2: pointer to the state2 object output by
* secp256k1_chilldkg_participant_step2
* cmsg2: pointer to the coordinator's second message (the
* certificate, 64*n bytes)
*/
SECP256K1_API SECP256K1_WARN_UNUSED_RESULT secp256k1_chilldkg_fault secp256k1_chilldkg_participant_finalize(
const secp256k1_context *ctx,
unsigned char *secshare32,
unsigned char *thresh_pk33,
unsigned char *pubshares33,
unsigned char *recovery,
uint32_t *fault_index,
const secp256k1_chilldkg_participant_state2 *state2,
const unsigned char *cmsg2
) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(6) SECP256K1_ARG_NONNULL(7) SECP256K1_ARG_NONNULL(8);
#ifdef __cplusplus
}
#endif