proof_fair/

lib.rs

use hmac::{Hmac, Mac};
use rand::{thread_rng, Rng};
use sha2::{Digest, Sha256, Sha512};

// Server seed is generated by the server and is kept secret until the game is over.
// Client seed is generated by the client and is also kept secret if there is more than one player for the game.
// Nonce is incremented by one for each game round, to ensure that each game round is unique and cannot be repeated or manipulated.
// It's important to note that the nonce should never be predictable or repeatable, and it should be kept secret from players to prevent any attempts to manipulate the game outcome.
// These combined are used to generate a HMAC-SHA512 hash.
const ALPHA: &str = "abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789";

/// Proof represents a provably fair random number generator (RNG) using HMAC-SHA512 hash.
///
/// This struct allows users to create a new RNG instance, log its state, roll the RNG,
/// calculate random numbers, and verify the validity of generated numbers.
///
/// # Examples
///
/// ```
/// use hmac_rng::Proof;
///
/// let mut proof = Proof::new(None, None, 0);
/// proof.log_state();
/// let result = proof.roll();
/// match result {
///     Ok(random_number) => println!("Random number: {}", random_number),
///     Err(err) => eprintln!("Error: {}", err),
/// }
/// ```

#[derive(Debug)]
pub struct Proof {
    pub client_seed: Vec<u8>,
    pub server_seed: Vec<u8>,
    pub blinded_server_seed: Vec<u8>,
    pub nonce: i64,
}

impl Proof {
    /// Creates a new instance of the Proof struct with the provided or random server seed,
    /// client seed, and nonce value.
    ///
    /// # Arguments
    ///
    /// * `client_seed` - An optional client seed.
    /// * `server_seed` - An optional server seed.
    /// * `nonce` - The nonce value.
    ///
    /// # Examples
    ///
    /// ```
    /// use hmac_rng::Proof;
    ///
    /// let mut proof = Proof::new(None, None, 0);
    /// ```
    pub fn new(client_seed: Option<Vec<u8>>, server_seed: Option<Vec<u8>>, nonce: i64) -> Self {
        // Generate a client seed if one isn't provided
        let client_seed = match client_seed {
            Some(seed) => seed,
            None => new_seed(64),
        };

        // Generate a random server seed if one isn't provided
        let server_seed = match server_seed {
            Some(seed) => seed,
            None => new_seed(64),
        };

        // Hash the serverSeed to show the client
        let blinded_seed = Sha256::digest(&server_seed);

        Proof {
            nonce,
            client_seed,
            server_seed,
            blinded_server_seed: blinded_seed.to_vec(),
        }
    }

    // prints the current state of the proof to the console
    pub fn log_state(&self) {
        let wnr = self.calculate().unwrap();
        println!("[Proof] Random number: {}", wnr);
        println!(
            "[Proof] Client Seed (public) : {}",
            String::from_utf8_lossy(&self.client_seed)
        );
        println!(
            "[Proof] Server Seed (secret): {}",
            String::from_utf8_lossy(&self.server_seed)
        );
        println!(
            "[Proof] Server Seed (public): {}",
            hex::encode(&self.blinded_server_seed)
        );
        println!("[Proof] Nonce: {}", self.nonce);
    }

    /// Increments the nonce value and calculates the random number for the current
    /// state of the Proof struct.
    ///
    /// This method ensures that the first nonce used is 0.
    ///
    /// # Returns
    ///
    /// * `Ok(random_number)` - The generated random number.
    /// * `Err(err)` - An error message if the calculation fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use hmac_rng::Proof;
    ///
    /// let mut proof = Proof::new(None, None, 0);
    /// let result = proof.roll();
    /// match result {
    ///     Ok(random_number) => println!("Random number: {}", random_number),
    ///     Err(err) => eprintln!("Error: {}", err),
    /// }
    /// ```
    pub fn roll(&mut self) -> Result<f64, String> {
        self.nonce += 1;
        self.calculate()
    }

    /// Calculates the current value from the current state of the Proof struct.
    ///
    /// This method does not advance the state in any way. Calling Calculate multiple times
    /// with the same nonce will always result in the same value.
    ///
    /// # Returns
    ///
    /// * `Ok(random_number)` - The calculated random number.
    /// * `Err(err)` - An error message if the calculation fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use hmac_rng::Proof;
    ///
    /// let proof = Proof::new(None, None, 0);
    /// let result = proof.calculate();
    /// match result {
    ///     Ok(random_number) => println!("Random number: {}", random_number),
    ///     Err(err) => eprintln!("Error: {}", err),
    /// }
    /// ```
    pub fn calculate(&self) -> Result<f64, String> {
        let hmac = self.calculate_hmac();
        let our_hmac = hex::encode(hmac);

        for i in 0..(our_hmac.len() - 5) {
            let idx = i * 5;
            if our_hmac.len() < (idx + 5) {
                break;
            }
            let hex_segment = &our_hmac[idx..idx + 5];
            let rand_num = u64::from_str_radix(hex_segment, 16).map_err(|e| e.to_string())?;
            if rand_num <= 999_999 {
                return Ok((rand_num % 10_000) as f64 / 100.0);
            }
        }

        Err("Invalid Nonce".to_string())
    }

    /// Creates a SHA-512 HMAC object with the server seed as the secret key and updates it
    /// with the client seed and nonce concatenated with a '-' in between.
    ///
    /// # Returns
    ///
    /// The calculated HMAC as a vector of bytes.
    fn calculate_hmac(&self) -> Vec<u8> {
        let mut mac = Hmac::<Sha512>::new_from_slice(&self.server_seed).unwrap();
        let nonce_str = self.nonce.to_string();
        let mut message = self.client_seed.clone();
        message.push(b'-');
        message.extend_from_slice(nonce_str.as_bytes());
        mac.update(&message);
        mac.finalize().into_bytes().to_vec()
    }

    /// Verifies that the given random number is valid for the given client seed, server seed,
    /// and nonce values by recreating the Proof instance and comparing the calculated random
    /// number with the provided random number.
    ///
    /// # Arguments
    ///
    /// * `client_seed` - The client seed.
    /// * `server_seed` - An optional server seed. Pass `None` if not provided.
    /// * `nonce` - The nonce value.
    /// * `rand_num` - The random number to verify.
    ///
    /// # Returns
    ///
    /// * `Ok(valid)` - `true` if the random number is valid, `false` otherwise.
    /// * `Err(err)` - An error message if the verification fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use hmac_rng::Proof;
    ///
    /// let client_seed = vec![1, 2, 3];
    /// let server_seed = vec![4, 5, 6];
    /// let nonce = 0;
    /// let random_number = 0.42;
    /// let result = Proof::verify(&client_seed, Some(&server_seed), nonce, random_number);
    /// match result {
    ///     Ok(valid) => println!("Valid: {}", valid),
    ///     Err(err) => eprintln!("Error: {}", err),
    /// }
    /// ```
    pub fn verify(
        client_seed: &[u8],
        server_seed: Option<&[u8]>,
        nonce: i64,
        rand_num: f64,
    ) -> Result<bool, String> {
        let proof = Proof::new(
            Some(client_seed.to_vec()),
            server_seed.map(|seed| seed.to_vec()),
            nonce,
        );
        match proof.calculate() {
            Ok(calculated_num) => Ok((calculated_num - rand_num).abs() < f64::EPSILON),
            Err(_) => Err(String::from("Proof calculation failed.")),
        }
    }
}
/// Generates a new seed of the specified size using characters from the ALPHA character set.
///
/// # Arguments
///
/// * `size` - The size (length) of the generated seed.
///
/// # Returns
///
/// A vector of bytes representing the generated seed.
///
/// # Examples
///
/// ```
/// use hmac_rng::new_seed;
///
/// let seed = new_seed(64);
/// println!("Generated Seed: {:?}", seed);
/// ```
///
/// # Note
///
/// The ALPHA character set used for generating the seed includes alphanumeric characters
/// (excluding some potentially confusing characters like '0', 'O', '1', 'l', etc.), which
/// is commonly used in cryptographic applications.
fn new_seed(size: usize) -> Vec<u8> {
    let mut rng = thread_rng();
    (0..size)
        .map(|_| ALPHA.chars().nth(rng.gen_range(0..ALPHA.len())).unwrap() as u8)
        .collect()
}