passgen/

random.rs

//! # Randomness generation
//!
//! This module contains various sources of randomness. Randomness itself is handled by the `rand`
//! crate. These types implement the [RandomSource] trait to generate *n* independent streams of
//! randomness.
//!
//! Fundamentally, there are two types of randomness:
//! * *Non-deterministic*, typically using whatever strong randomness generator is available on the
//!   system. This is the default for Passgen, and should be used when you want to generate a new
//!   random passphrase and do not need the ability to later re-generate it.
//! * *Deterministic*. These are used for generating passphrases from some known secret using a
//!   pseudorandom number generator (such as a stream cipher). These should be used when you want
//!   to be able to later re-generate the same passphrase from the secret.
//!
//! Some of the randomness sources (specifically the [Zero] and [Xoshiro] ones) exist mainly for
//! testing purposes and should not be used by end-users. They may be gated by some feature in the
//! future to remove them from the Passgen tool.
//!
//! For each source of randomness, Passgen requires the ability to create *n* random number
//! generators with independent streams of random values to allow it to generate passphrases
//! from multiple threads, see the [RandomSource] documentation for more information on this.
//!
//! ## Examples
//!
//! Creating a randomness source, instantiating multiple random number generators from it
//! and showing the the streams are independent and deterministic.
//!
//! ```
//! use passgen::random::*;
//! use rand::Rng;
//!
//! // using the xoshiro deterministic pseudorandom number generator
//! let random = Xoshiro::new(564);
//!
//! // stream zero
//! let mut rng = random.get_rng(0);
//! assert_eq!(rng.gen::<u8>(), 45);
//! assert_eq!(rng.gen::<u8>(), 106);
//!
//! // stream one (independent from zero)
//! let mut rng = random.get_rng(1);
//! assert_eq!(rng.gen::<u8>(), 156);
//! assert_eq!(rng.gen::<u8>(), 212);
//! ```

use argon2::Argon2;
use rand::RngCore;
use rand::SeedableRng;
use rand_chacha::ChaCha20Rng;
use rand_xoshiro::Xoshiro256PlusPlus;
use std::str::FromStr;

/// Randomness source
///
/// Applications using Passgen should allow the user to configure the source of randomness by
/// specifying this value. It defaults to using the [System] randomness generator, which is
/// non-deterministic.
#[derive(Debug, Clone, PartialEq)]
pub enum Random {
    System(System),
    Zero(Zero),
    Xoshiro(Xoshiro),
    ChaCha20(ChaCha20),
}

impl Default for Random {
    fn default() -> Self {
        Self::System(System)
    }
}

impl Random {
    /// When using master pass mode, this method should be used (with the specified master
    /// passphrase) to generate the appropriate source of randomness.
    pub fn from_master_pass(pass: &str, salt: &str) -> Self {
        let mut seed = [0; 32];
        Argon2::new_with_secret(
            b"passgen",
            Default::default(),
            Default::default(),
            Default::default(),
        )
        .unwrap()
        .hash_password_into(pass.as_bytes(), salt.as_bytes(), &mut seed)
        .unwrap();
        Self::ChaCha20(ChaCha20(seed))
    }
}

/// Error parsing a [Random] value from a string.
#[derive(thiserror::Error, Debug)]
pub enum ParseError {
    #[error("unknown randomness source '{0:}'")]
    Unknown(String),
}

impl FromStr for Random {
    type Err = ParseError;

    fn from_str(input: &str) -> Result<Self, Self::Err> {
        let split = input
            .split_once(':')
            .map(|(name, opt)| (name, Some(opt)))
            .unwrap_or((input, None));
        match split {
            ("system", None) => Ok(Self::System(System)),
            ("zero", None) => Ok(Self::Zero(Zero)),
            ("xoshiro", Some(params)) => Ok(Self::Xoshiro(Xoshiro(params.parse().unwrap()))),
            _ => Err(ParseError::Unknown(input.to_string())),
        }
    }
}

/// Source of randomness
///
/// ## Streams
///
/// When Passgen generates multiple random sequences, it could use a single stream of randomness
/// sequentially, however this makes it impossible to use multi-threading. For that reason, every
/// sequence it generates uses an independent stream of randomness. For nondeterministic
/// randomness, these independent streams can actually be the same stream. For deterministic
/// sources of randomness, these streams should be independent and each stream should always
/// produce the same (pseudorandom) data.
pub trait RandomSource {
    /// Underlying type of the randomness source.
    type Rng: RngCore + 'static;

    /// Return a stream of randomness for the given index.
    fn get_rng(&self, index: usize) -> Self::Rng;

    /// Return a type-erased stream of randomness for the given index.
    fn get_rng_boxed(&self, index: usize) -> Box<dyn RngCore> {
        Box::new(self.get_rng(index))
    }
}

impl RandomSource for Random {
    type Rng = Box<dyn RngCore>;

    fn get_rng(&self, index: usize) -> Box<dyn RngCore> {
        match self {
            Self::System(random) => random.get_rng_boxed(index),
            Self::Zero(random) => random.get_rng_boxed(index),
            Self::Xoshiro(random) => random.get_rng_boxed(index),
            Self::ChaCha20(random) => random.get_rng_boxed(index),
        }
    }

    fn get_rng_boxed(&self, index: usize) -> Box<dyn RngCore> {
        self.get_rng(index)
    }
}

/// System randomness generator for secure, non-deterministic passphrase generation.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct System;

impl RandomSource for System {
    type Rng = rand::rngs::ThreadRng;

    fn get_rng(&self, _index: usize) -> Self::Rng {
        rand::thread_rng()
    }
}

/// Source of randomness that always returns zeroes.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Zero;

impl RandomSource for Zero {
    type Rng = rand::rngs::mock::StepRng;

    fn get_rng(&self, _index: usize) -> Self::Rng {
        rand::rngs::mock::StepRng::new(0, 0)
    }
}

/// [Xoshiro256PlusPlus] based pseudorandom generator.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Xoshiro(u64);

impl Xoshiro {
    pub fn new(seed: u64) -> Self {
        Xoshiro(seed)
    }
}

impl RandomSource for Xoshiro {
    type Rng = Xoshiro256PlusPlus;

    fn get_rng(&self, index: usize) -> Self::Rng {
        let mut rng = Xoshiro256PlusPlus::seed_from_u64(self.0);
        for _ in 0..index {
            rng.jump();
        }
        rng
    }
}

/// [ChaCha20Rng]-based pseudorandom generator.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ChaCha20([u8; 32]);

impl RandomSource for ChaCha20 {
    type Rng = ChaCha20Rng;

    fn get_rng(&self, index: usize) -> Self::Rng {
        let mut rng = ChaCha20Rng::from_seed(self.0);
        rng.set_stream(index as u64);
        rng
    }
}