frost_bluepallas/

keys.rs

//! This module contains utilities for FROST key management using the BluePallas curve

use alloc::collections::BTreeMap;

use frost_core::{self as frost};
use rand_core::{CryptoRng, RngCore};

use crate::{BluePallas, ChallengeMessage, Error, Identifier, SigningKey};

pub type IdentifierList<'a, M> = frost::keys::IdentifierList<'a, BluePallas<M>>;

/// Secret and public key material generated by a dealer performing
/// [`generate_with_dealer`].
///
/// # Security
///
/// To derive a FROST(Pallas, Poseidon) keypair, the receiver of the [`SecretShare`] *must* call
/// .into(), which under the hood also performs validation.
pub type SecretShare<M> = frost::keys::SecretShare<BluePallas<M>>;

/// A secret scalar value representing a signer's share of the group secret.
pub type SigningShare<M> = frost::keys::SigningShare<BluePallas<M>>;

/// A public group element that represents a single signer's public verification share.
pub type VerifyingShare<M> = frost::keys::VerifyingShare<BluePallas<M>>;

/// A FROST(Pallas, Poseidon) keypair, which can be generated either by a trusted dealer or using
/// a DKG.
///
/// When using a central dealer, [`SecretShare`]s are distributed to
/// participants, who then perform verification, before deriving
/// [`KeyPackage`]s, which they store to later use during signing.
pub type KeyPackage<M> = frost::keys::KeyPackage<BluePallas<M>>;

/// Public data that contains all the signers' public keys as well as the
/// group public key.
///
/// Used for verification purposes before publishing a signature.
pub type PublicKeyPackage<M> = frost::keys::PublicKeyPackage<BluePallas<M>>;

/// Contains the commitments to the coefficients for our secret polynomial _f_,
/// used to generate participants' key shares.
///
/// [`VerifiableSecretSharingCommitment`] contains a set of commitments to the coefficients (which
/// themselves are scalars) for a secret polynomial f, where f is used to
/// generate each ith participant's key share f(i). Participants use this set of
/// commitments to perform verifiable secret sharing.
///
/// Note that participants MUST be assured that they have the *same*
/// [`VerifiableSecretSharingCommitment`], either by performing pairwise comparison, or by using
/// some agreed-upon public location for publication, where each participant can
/// ensure that they received the correct (and same) value.
pub type VerifiableSecretSharingCommitment<M> =
    frost::keys::VerifiableSecretSharingCommitment<BluePallas<M>>;
type DealerOutput<M> = (BTreeMap<Identifier<M>, SecretShare<M>>, PublicKeyPackage<M>);

/// Generate a random keypair and split into FROST keyshares.
pub fn generate_with_dealer<M, RNG: RngCore + CryptoRng>(
    max_signers: u16,
    min_signers: u16,
    identifiers: IdentifierList<'_, M>,
    mut rng: RNG,
) -> Result<DealerOutput<M>, Error<M>>
where
    M: ChallengeMessage,
{
    frost::keys::generate_with_dealer(max_signers, min_signers, identifiers, &mut rng)
}

/// Splits an existing key into FROST shares.
///
/// This is identical to [`generate_with_dealer`] but receives an existing key
/// instead of generating a fresh one. This is useful in scenarios where
/// the key needs to be generated externally or must be derived from e.g. a
/// seed phrase.
pub fn split<M, R: RngCore + CryptoRng>(
    key: &SigningKey<M>,
    max_signers: u16,
    min_signers: u16,
    identifiers: IdentifierList<'_, M>,
    rng: &mut R,
) -> Result<DealerOutput<M>, Error<M>>
where
    M: ChallengeMessage,
{
    frost::keys::split(key, max_signers, min_signers, identifiers, rng)
}

/// Distributed Key Generation (DKG) protocol types and functions.
pub mod dkg {
    use super::*;
    type DkgPart2Output<M> = (
        round2::SecretPackage<M>,
        BTreeMap<Identifier<M>, round2::Package<M>>,
    );

    /// DKG Round 1 structures.
    pub mod round1 {
        use super::*;

        /// The secret package that must be kept in memory by the participant
        /// between the first and second parts of the DKG protocol (round 1).
        ///
        /// # Security
        ///
        /// This package MUST NOT be sent to other participants!
        pub type SecretPackage<M> = frost::keys::dkg::round1::SecretPackage<BluePallas<M>>;

        /// The package that must be broadcast by each participant to all other participants
        /// between the first and second parts of the DKG protocol (round 1).
        pub type Package<M> = frost::keys::dkg::round1::Package<BluePallas<M>>;
    }

    /// DKG Round 2 structures.
    pub mod round2 {
        use super::*;

        /// The secret package that must be kept in memory by the participant
        /// between the second and third parts of the DKG protocol (round 2).
        ///
        /// # Security
        ///
        /// This package MUST NOT be sent to other participants!
        pub type SecretPackage<M> = frost::keys::dkg::round2::SecretPackage<BluePallas<M>>;

        /// A package that must be sent by each participant to some other participants
        /// in Round 2 of the DKG protocol. Note that there is one specific package
        /// for each specific recipient, in contrast to Round 1.
        ///
        /// # Security
        ///
        /// The package must be sent on an *confidential* and *authenticated* channel.
        pub type Package<M> = frost::keys::dkg::round2::Package<BluePallas<M>>;
    }

    /// Performs the first part of the distributed key generation protocol
    /// for the given participant.
    ///
    /// 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.
    pub fn part1<M, R: RngCore + CryptoRng>(
        identifier: Identifier<M>,
        max_signers: u16,
        min_signers: u16,
        mut rng: R,
    ) -> Result<(round1::SecretPackage<M>, round1::Package<M>), Error<M>>
    where
        M: ChallengeMessage,
    {
        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.
    ///
    /// 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.
    pub fn part2<M>(
        secret_package: round1::SecretPackage<M>,
        round1_packages: &BTreeMap<Identifier<M>, round1::Package<M>>,
    ) -> Result<DkgPart2Output<M>, Error<M>>
    where
        M: ChallengeMessage,
    {
        frost::keys::dkg::part2(secret_package, round1_packages)
    }

    /// 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.
    ///
    /// 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.
    pub fn part3<M>(
        round2_secret_package: &round2::SecretPackage<M>,
        round1_packages: &BTreeMap<Identifier<M>, round1::Package<M>>,
        round2_packages: &BTreeMap<Identifier<M>, round2::Package<M>>,
    ) -> Result<(KeyPackage<M>, PublicKeyPackage<M>), Error<M>>
    where
        M: ChallengeMessage,
    {
        let (key_package, public_key_package) =
            frost::keys::dkg::part3(round2_secret_package, round1_packages, round2_packages)?;
        Ok((key_package, public_key_package))
    }
}