Struct Generator 

pub struct Generator {
    pub rng: ChaCha8Rng,
    /* private fields */
}

Generator is the core struct responsible for generating customizable, pronounceable passwords.

It allows generating passwords or passphrases based on wordlists, patterns, and custom token sets, and calculates the entropy of each generated password. The generator can be configured to generate more entropic but less pronounceable passwords or simple, easier-to-pronounce ones.

Features

• Generate passphrases from a wordlist (default: EFF wordlist).
• Use custom tokens and control the Markov chain depth for greater flexibility.
• Support for generating passwords from patterns (symbols, digits, etc.).
• Calculate the entropy of generated passwords.

Example Usage

use cryptirust::Generator;

// Create a default generator and generate a 4-word passphrase
let mut generator = Generator::new();
let (passphrase, entropy) = generator.gen_from_pattern("w-w-w-w-dd-ss");
println!("Generated passphrase: {}", passphrase); //e.g. contense-backside-creamed-sterous-06-"?
println!("Entropy: {:.2} bits", entropy); // e.g. 69.23

Performance

By default, the generator uses a Markov chain depth of 3, which balances pronounceability and complexity. For faster generation of more complex (but less pronounceable) passwords, use Generator::new_he(), which lowers the depth to 2.

Customization

You can provide your own token sets and control the Markov chain depth using new_custom().

use cryptirust::Generator;
let custom_tokens = vec![
    String::from("rust"),
    String::from("cargo"),
    String::from("ownership"),
];

let mut generator = Generator::new_custom(custom_tokens, 2).unwrap();
let (password, entropy) = generator.gen_from_pattern("w.w.w.w");
println!("Custom passphrase: {}", password);

Fields

rng: ChaCha8Rng

Implementations

impl Generator

pub fn new_custom(tokens: Vec<String>, depth: usize) -> Option<Generator>

Creates a new generator with a custom token set and a specified Markov chain depth.

pub fn new() -> Generator

Creates a new generator using the default wordlist (EFF’s word list) with a Markov chain depth of 3.

pub fn new_he() -> Generator

Similar to new(), but uses a Markov chain depth of 2 for quicker password generation at the expense of phonetic fidelity.

pub fn gen_from_pattern(&mut self, pattern: &str) -> (String, f64)

Generates a password based on a given pattern, while calculating its entropy.

The pattern string defines how the password is structured, where different characters in the pattern correspond to different token types:

• 's' - Inserts a symbol from the predefined symbol set (@#!$%&=?^+-*").
• 'd' - Inserts a digit from the set 0-9.
• 'c' - Generates a token using the markov chain.
• 'C' - Generates a token, capitalized.
• 'w' - Generates a word using the markov chain.
• 'W' - Generates a word, capitalized.

Additionally, any literal character (e.g., . or !) can be inserted into the pattern, which will be directly appended to the password as is.

The method also supports escape sequences (\) to treat characters as literals, allowing pattern symbols like 'w' or 's' to be included in the final password without triggering token generation.

Parameters

• pattern: A string that defines the structure of the generated password. Each character in the string corresponds to a token type, symbol, or literal.

Returns

A tuple containing:

• String: The generated password based on the given pattern.
• f64: The estimated entropy of the generated password, calculated using the log base 2 of the number of possible outcomes for each token.

Example

use cryptirust::Generator;
let mut gen = Generator::new();
let (password, entropy) = gen.gen_from_pattern("wWsdC");
println!("Generated password: {}, Entropy: {}", password, entropy);

In this example, the pattern "wWsdC" would generate a password such as "hunkindEreso2"Mus", with its corresponding entropy value.

Performance

The performance of this method depends on the length of the input pattern and the complexity of tokens defined in the jump table. Deeper chain depths or longer patterns may result in higher processing time.

pub fn gen_next_token(&mut self, seed: &str) -> Option<(String, f64)>

Generates the next token in a sequence, based on the current seed and internal state.

Example

let mut generator = Generator::new();
let (token, entropy) = generator.gen_next_token("he").unwrap();
println!("Next token: {}, Entropy: {}", token, entropy);

This example demonstrates how to generate the next token in a sequence starting with the seed "he". The method returns both the token and its associated entropy.

Trait Implementations

impl Default for Generator

fn default() -> Self

Returns the “default value” for a type.