diff --git a/book/src/tutorial/dkg.md b/book/src/tutorial/dkg.md index ce467b54..5bab3dd6 100644 --- a/book/src/tutorial/dkg.md +++ b/book/src/tutorial/dkg.md @@ -56,9 +56,13 @@ insecure.** Upon receiving the other participants' `round1::Package`s, each participant then calls [`dkg::part2()`](https://docs.rs/frost-ristretto255/latest/frost_ristretto255/keys/dkg/fn.part2.html) -passing their own previously created `round1::SecretPackage` and the list of -received `round1::Packages`. It returns a `round2::SecretPackage` and a -`BTreeMap` mapping other participants's `Identifier`s to `round2::Package`s: +passing their own previously created `round1::SecretPackage` and a map of the +received `round1::Packages`, keyed by the Identifiers of the participant that +sent each one of them. (These identifiers must come from whatever mapping the +coordinator has between communication channels and participants, i.e. they must +have assurance that the `round1::Package` came from the participant with that +identifier.) It returns a `round2::SecretPackage` and a `BTreeMap` mapping other +participants's `Identifier`s to `round2::Package`s: ```rust,no_run,noplayground {{#include ../../../frost-ristretto255/dkg.md:dkg_part2}} @@ -77,9 +81,10 @@ Finally, upon receiving the other participant's `round2::Package`, the DKG is concluded by calling [`dkg::part3()`](https://docs.rs/frost-ristretto255/latest/frost_ristretto255/keys/dkg/fn.part3.html) passing the same `round1::Package`s received in Part 2, the `round2::Package`s -just received, and the previously stored `round2::SecretPackage` for the -participant. It returns a `KeyPackage`, with the participant's secret share, -and a `PublicKeyPackage` containing the group verifying key: +just received (again keyed by the Identifier of the participant that sent each +one of them), and the previously stored `round2::SecretPackage` for the +participant. It returns a `KeyPackage`, with the participant's secret share, and +a `PublicKeyPackage` containing the group verifying key: ```rust,no_run,noplayground {{#include ../../../frost-ristretto255/dkg.md:dkg_part3}} diff --git a/frost-core/src/keys/dkg.rs b/frost-core/src/keys/dkg.rs index 3850662f..aa3a56ae 100644 --- a/frost-core/src/keys/dkg.rs +++ b/frost-core/src/keys/dkg.rs @@ -277,7 +277,7 @@ pub mod round2 { /// /// It returns the [`round1::SecretPackage`] that must be kept in memory /// by the participant for the other steps, and the [`round1::Package`] that -/// must be sent to other participants. +/// must be sent to each other participant in the DKG run. pub fn part1( identifier: Identifier, max_signers: u16, @@ -388,19 +388,21 @@ pub(crate) fn verify_proof_of_knowledge( Ok(()) } -/// Performs the second part of the distributed key generation protocol -/// for the participant holding the given [`round1::SecretPackage`], -/// given the received [`round1::Package`]s received from the other participants. +/// Performs the second part of the distributed key generation protocol for the +/// participant holding the given [`round1::SecretPackage`], given the received +/// [`round1::Package`]s received from the other participants. /// -/// `round1_packages` maps the identifier of each participant to the -/// [`round1::Package`] they sent. These identifiers must come from whatever mapping -/// the coordinator has between communication channels and participants, i.e. -/// they must have assurance that the [`round1::Package`] came from -/// the participant with that identifier. +/// `round1_packages` maps the identifier of each other participant to the +/// [`round1::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round1::Package`] came from the participant +/// with that identifier. /// -/// It returns the [`round2::SecretPackage`] that must be kept in memory -/// by the participant for the final step, and the a map of [`round2::Package`]s that -/// must be sent to each participant who has the given identifier in the map key. +/// It returns the [`round2::SecretPackage`] that must be kept in memory by the +/// participant for the final step, and the map of [`round2::Package`]s that +/// must be sent to each other participant who has the given identifier in the +/// map key. pub fn part2( secret_package: round1::SecretPackage, round1_packages: &BTreeMap, round1::Package>, @@ -461,22 +463,22 @@ pub fn part2( } /// Performs the third and final part of the distributed key generation protocol -/// for the participant holding the given [`round2::SecretPackage`], -/// given the received [`round1::Package`]s and [`round2::Package`]s received from -/// the other participants. +/// for the participant holding the given [`round2::SecretPackage`], given the +/// received [`round1::Package`]s and [`round2::Package`]s received from the +/// other participants. /// /// `round1_packages` must be the same used in [`part2()`]. /// -/// `round2_packages` maps the identifier of each participant to the -/// [`round2::Package`] they sent. These identifiers must come from whatever mapping -/// the coordinator has between communication channels and participants, i.e. -/// they must have assurance that the [`round2::Package`] came from -/// the participant with that identifier. +/// `round2_packages` maps the identifier of each other participant to the +/// [`round2::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round2::Package`] came from the participant +/// with that identifier. /// /// It returns the [`KeyPackage`] that has the long-lived key share for the -/// participant, and the [`PublicKeyPackage`]s that has public information -/// about all participants; both of which are required to compute FROST -/// signatures. +/// participant, and the [`PublicKeyPackage`]s that has public information about +/// all participants; both of which are required to compute FROST signatures. pub fn part3( round2_secret_package: &round2::SecretPackage, round1_packages: &BTreeMap, round1::Package>, diff --git a/frost-ed25519/src/keys/dkg.rs b/frost-ed25519/src/keys/dkg.rs index 08247758..42407bbd 100644 --- a/frost-ed25519/src/keys/dkg.rs +++ b/frost-ed25519/src/keys/dkg.rs @@ -45,7 +45,7 @@ pub mod round2 { /// /// It returns the [`round1::SecretPackage`] that must be kept in memory /// by the participant for the other steps, and the [`round1::Package`] that -/// must be sent to other participants. +/// must be sent to each other participant in the DKG run. pub fn part1( identifier: Identifier, max_signers: u16, @@ -55,13 +55,21 @@ pub fn part1( frost::keys::dkg::part1(identifier, max_signers, min_signers, &mut rng) } -/// Performs the second part of the distributed key generation protocol -/// for the participant holding the given [`round1::SecretPackage`], -/// given the received [`round1::Package`]s received from the other participants. +/// Performs the second part of the distributed key generation protocol for the +/// participant holding the given [`round1::SecretPackage`], given the received +/// [`round1::Package`]s received from the other participants. /// -/// It returns the [`round2::SecretPackage`] that must be kept in memory -/// by the participant for the final step, and the [`round2::Package`]s that -/// must be sent to other participants. +/// `round1_packages` maps the identifier of each other participant to the +/// [`round1::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round1::Package`] came from the participant +/// with that identifier. +/// +/// It returns the [`round2::SecretPackage`] that must be kept in memory by the +/// participant for the final step, and the map of [`round2::Package`]s that +/// must be sent to each other participant who has the given identifier in the +/// map key. pub fn part2( secret_package: round1::SecretPackage, round1_packages: &BTreeMap, @@ -70,14 +78,22 @@ pub fn part2( } /// Performs the third and final part of the distributed key generation protocol -/// for the participant holding the given [`round2::SecretPackage`], -/// given the received [`round1::Package`]s and [`round2::Package`]s received from -/// the other participants. +/// for the participant holding the given [`round2::SecretPackage`], given the +/// received [`round1::Package`]s and [`round2::Package`]s received from the +/// other participants. +/// +/// `round1_packages` must be the same used in [`part2()`]. +/// +/// `round2_packages` maps the identifier of each other participant to the +/// [`round2::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round2::Package`] came from the participant +/// with that identifier. /// /// It returns the [`KeyPackage`] that has the long-lived key share for the -/// participant, and the [`PublicKeyPackage`]s that has public information -/// about all participants; both of which are required to compute FROST -/// signatures. +/// participant, and the [`PublicKeyPackage`]s that has public information about +/// all participants; both of which are required to compute FROST signatures. pub fn part3( round2_secret_package: &round2::SecretPackage, round1_packages: &BTreeMap, diff --git a/frost-ed448/src/keys/dkg.rs b/frost-ed448/src/keys/dkg.rs index 08247758..42407bbd 100644 --- a/frost-ed448/src/keys/dkg.rs +++ b/frost-ed448/src/keys/dkg.rs @@ -45,7 +45,7 @@ pub mod round2 { /// /// It returns the [`round1::SecretPackage`] that must be kept in memory /// by the participant for the other steps, and the [`round1::Package`] that -/// must be sent to other participants. +/// must be sent to each other participant in the DKG run. pub fn part1( identifier: Identifier, max_signers: u16, @@ -55,13 +55,21 @@ pub fn part1( frost::keys::dkg::part1(identifier, max_signers, min_signers, &mut rng) } -/// Performs the second part of the distributed key generation protocol -/// for the participant holding the given [`round1::SecretPackage`], -/// given the received [`round1::Package`]s received from the other participants. +/// Performs the second part of the distributed key generation protocol for the +/// participant holding the given [`round1::SecretPackage`], given the received +/// [`round1::Package`]s received from the other participants. /// -/// It returns the [`round2::SecretPackage`] that must be kept in memory -/// by the participant for the final step, and the [`round2::Package`]s that -/// must be sent to other participants. +/// `round1_packages` maps the identifier of each other participant to the +/// [`round1::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round1::Package`] came from the participant +/// with that identifier. +/// +/// It returns the [`round2::SecretPackage`] that must be kept in memory by the +/// participant for the final step, and the map of [`round2::Package`]s that +/// must be sent to each other participant who has the given identifier in the +/// map key. pub fn part2( secret_package: round1::SecretPackage, round1_packages: &BTreeMap, @@ -70,14 +78,22 @@ pub fn part2( } /// Performs the third and final part of the distributed key generation protocol -/// for the participant holding the given [`round2::SecretPackage`], -/// given the received [`round1::Package`]s and [`round2::Package`]s received from -/// the other participants. +/// for the participant holding the given [`round2::SecretPackage`], given the +/// received [`round1::Package`]s and [`round2::Package`]s received from the +/// other participants. +/// +/// `round1_packages` must be the same used in [`part2()`]. +/// +/// `round2_packages` maps the identifier of each other participant to the +/// [`round2::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round2::Package`] came from the participant +/// with that identifier. /// /// It returns the [`KeyPackage`] that has the long-lived key share for the -/// participant, and the [`PublicKeyPackage`]s that has public information -/// about all participants; both of which are required to compute FROST -/// signatures. +/// participant, and the [`PublicKeyPackage`]s that has public information about +/// all participants; both of which are required to compute FROST signatures. pub fn part3( round2_secret_package: &round2::SecretPackage, round1_packages: &BTreeMap, diff --git a/frost-p256/src/keys/dkg.rs b/frost-p256/src/keys/dkg.rs index ae7dec6c..dfd95384 100644 --- a/frost-p256/src/keys/dkg.rs +++ b/frost-p256/src/keys/dkg.rs @@ -45,7 +45,7 @@ pub mod round2 { /// /// It returns the [`round1::SecretPackage`] that must be kept in memory /// by the participant for the other steps, and the [`round1::Package`] that -/// must be sent to other participants. +/// must be sent to each other participant in the DKG run. pub fn part1( identifier: Identifier, max_signers: u16, @@ -55,13 +55,21 @@ pub fn part1( frost::keys::dkg::part1(identifier, max_signers, min_signers, &mut rng) } -/// Performs the second part of the distributed key generation protocol -/// for the participant holding the given [`round1::SecretPackage`], -/// given the received [`round1::Package`]s received from the other participants. +/// Performs the second part of the distributed key generation protocol for the +/// participant holding the given [`round1::SecretPackage`], given the received +/// [`round1::Package`]s received from the other participants. /// -/// It returns the [`round2::SecretPackage`] that must be kept in memory -/// by the participant for the final step, and the [`round2::Package`]s that -/// must be sent to other participants. +/// `round1_packages` maps the identifier of each other participant to the +/// [`round1::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round1::Package`] came from the participant +/// with that identifier. +/// +/// It returns the [`round2::SecretPackage`] that must be kept in memory by the +/// participant for the final step, and the map of [`round2::Package`]s that +/// must be sent to each other participant who has the given identifier in the +/// map key. pub fn part2( secret_package: round1::SecretPackage, round1_packages: &BTreeMap, @@ -70,14 +78,22 @@ pub fn part2( } /// Performs the third and final part of the distributed key generation protocol -/// for the participant holding the given [`round2::SecretPackage`], -/// given the received [`round1::Package`]s and [`round2::Package`]s received from -/// the other participants. +/// for the participant holding the given [`round2::SecretPackage`], given the +/// received [`round1::Package`]s and [`round2::Package`]s received from the +/// other participants. +/// +/// `round1_packages` must be the same used in [`part2()`]. +/// +/// `round2_packages` maps the identifier of each other participant to the +/// [`round2::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round2::Package`] came from the participant +/// with that identifier. /// /// It returns the [`KeyPackage`] that has the long-lived key share for the -/// participant, and the [`PublicKeyPackage`]s that has public information -/// about all participants; both of which are required to compute FROST -/// signatures. +/// participant, and the [`PublicKeyPackage`]s that has public information about +/// all participants; both of which are required to compute FROST signatures. pub fn part3( round2_secret_package: &round2::SecretPackage, round1_packages: &BTreeMap, diff --git a/frost-ristretto255/src/keys/dkg.rs b/frost-ristretto255/src/keys/dkg.rs index 6f8b7124..2d13265b 100644 --- a/frost-ristretto255/src/keys/dkg.rs +++ b/frost-ristretto255/src/keys/dkg.rs @@ -45,7 +45,7 @@ pub mod round2 { /// /// It returns the [`round1::SecretPackage`] that must be kept in memory /// by the participant for the other steps, and the [`round1::Package`] that -/// must be sent to other participants. +/// must be sent to each other participant in the DKG run. pub fn part1( identifier: Identifier, max_signers: u16, @@ -55,13 +55,21 @@ pub fn part1( frost::keys::dkg::part1(identifier, max_signers, min_signers, &mut rng) } -/// Performs the second part of the distributed key generation protocol -/// for the participant holding the given [`round1::SecretPackage`], -/// given the received [`round1::Package`]s received from the other participants. +/// Performs the second part of the distributed key generation protocol for the +/// participant holding the given [`round1::SecretPackage`], given the received +/// [`round1::Package`]s received from the other participants. /// -/// It returns the [`round2::SecretPackage`] that must be kept in memory -/// by the participant for the final step, and the [`round2::Package`]s that -/// must be sent to other participants. +/// `round1_packages` maps the identifier of each other participant to the +/// [`round1::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round1::Package`] came from the participant +/// with that identifier. +/// +/// It returns the [`round2::SecretPackage`] that must be kept in memory by the +/// participant for the final step, and the map of [`round2::Package`]s that +/// must be sent to each other participant who has the given identifier in the +/// map key. pub fn part2( secret_package: round1::SecretPackage, round1_packages: &BTreeMap, @@ -70,14 +78,22 @@ pub fn part2( } /// Performs the third and final part of the distributed key generation protocol -/// for the participant holding the given [`round2::SecretPackage`], -/// given the received [`round1::Package`]s and [`round2::Package`]s received from -/// the other participants. +/// for the participant holding the given [`round2::SecretPackage`], given the +/// received [`round1::Package`]s and [`round2::Package`]s received from the +/// other participants. +/// +/// `round1_packages` must be the same used in [`part2()`]. +/// +/// `round2_packages` maps the identifier of each other participant to the +/// [`round2::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round2::Package`] came from the participant +/// with that identifier. /// /// It returns the [`KeyPackage`] that has the long-lived key share for the -/// participant, and the [`PublicKeyPackage`]s that has public information -/// about all participants; both of which are required to compute FROST -/// signatures. +/// participant, and the [`PublicKeyPackage`]s that has public information about +/// all participants; both of which are required to compute FROST signatures. pub fn part3( round2_secret_package: &round2::SecretPackage, round1_packages: &BTreeMap, diff --git a/frost-secp256k1/src/keys/dkg.rs b/frost-secp256k1/src/keys/dkg.rs index 91c6286c..9ea40b26 100644 --- a/frost-secp256k1/src/keys/dkg.rs +++ b/frost-secp256k1/src/keys/dkg.rs @@ -45,7 +45,7 @@ pub mod round2 { /// /// It returns the [`round1::SecretPackage`] that must be kept in memory /// by the participant for the other steps, and the [`round1::Package`] that -/// must be sent to other participants. +/// must be sent to each other participant in the DKG run. pub fn part1( identifier: Identifier, max_signers: u16, @@ -55,13 +55,21 @@ pub fn part1( frost::keys::dkg::part1(identifier, max_signers, min_signers, &mut rng) } -/// Performs the second part of the distributed key generation protocol -/// for the participant holding the given [`round1::SecretPackage`], -/// given the received [`round1::Package`]s received from the other participants. +/// Performs the second part of the distributed key generation protocol for the +/// participant holding the given [`round1::SecretPackage`], given the received +/// [`round1::Package`]s received from the other participants. /// -/// It returns the [`round2::SecretPackage`] that must be kept in memory -/// by the participant for the final step, and the [`round2::Package`]s that -/// must be sent to other participants. +/// `round1_packages` maps the identifier of each other participant to the +/// [`round1::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round1::Package`] came from the participant +/// with that identifier. +/// +/// It returns the [`round2::SecretPackage`] that must be kept in memory by the +/// participant for the final step, and the map of [`round2::Package`]s that +/// must be sent to each other participant who has the given identifier in the +/// map key. pub fn part2( secret_package: round1::SecretPackage, round1_packages: &BTreeMap, @@ -70,14 +78,22 @@ pub fn part2( } /// Performs the third and final part of the distributed key generation protocol -/// for the participant holding the given [`round2::SecretPackage`], -/// given the received [`round1::Package`]s and [`round2::Package`]s received from -/// the other participants. +/// for the participant holding the given [`round2::SecretPackage`], given the +/// received [`round1::Package`]s and [`round2::Package`]s received from the +/// other participants. +/// +/// `round1_packages` must be the same used in [`part2()`]. +/// +/// `round2_packages` maps the identifier of each other participant to the +/// [`round2::Package`] they sent to the current participant (the owner of +/// `secret_package`). These identifiers must come from whatever mapping the +/// coordinator has between communication channels and participants, i.e. they +/// must have assurance that the [`round2::Package`] came from the participant +/// with that identifier. /// /// It returns the [`KeyPackage`] that has the long-lived key share for the -/// participant, and the [`PublicKeyPackage`]s that has public information -/// about all participants; both of which are required to compute FROST -/// signatures. +/// participant, and the [`PublicKeyPackage`]s that has public information about +/// all participants; both of which are required to compute FROST signatures. pub fn part3( round2_secret_package: &round2::SecretPackage, round1_packages: &BTreeMap,