gen_pass

Secure password generation library and CLI written in Rust.

Features

• Configurable password length and character sets (lowercase, uppercase, digits, symbols)
• Combines multiple entropy sources for strong randomness:
  • rand::rngs::OsRng (system entropy)
  • rand_chacha::ChaCha20Rng seeded from system entropy
  • rand::rngs::StdRng seeded with SHA-256 digest of previous random data
• Can be used as a library in your own Rust projects or as a standalone command-line tool.
• Optional clipboard copy (macOS pbcopy, Linux xclip).

Installation

As a Library

Add to your Cargo.toml:

[dependencies]
gen_pass = { git = "https://github.com/suenot/gen_pass_rs", tag = "v0.1.0" }

As a CLI

# Clone and install
cargo install --path .

# Or install directly from crates.io (after publishing)
cargo install gen_pass

Usage (CLI)

$ gen_pass --help
Generate secure passwords

Usage: gen_pass [OPTIONS]

Options:
  -l, --length <LENGTH>      Desired password length [default: 16]
      --lowercase <BOOL>     Include lowercase letters [default: true]
      --uppercase <BOOL>     Include uppercase letters [default: true]
      --digits <BOOL>        Include digits [default: true]
      --symbols <BOOL>       Include symbols [default: true]
  -s, --salt <SALT>          Salt string to modify password generation [default: "suenot"]
  -o, --output <OUTPUT>      Output format [default: plain] [possible values: plain, copy]
  -h, --help                 Print help info
  -V, --version              Print version info

Examples:

# 24-character password with all character sets
$ gen_pass -l 24

# 32-character password without symbols, copy to clipboard
$ gen_pass -l 32 --symbols=false -o copy

# Password with a custom salt for deterministic generation
$ gen_pass -l 20 -s "my-custom-salt"

# Default salt is "suenot" (author's nickname as an easter egg)
$ gen_pass -l 20

Usage (Library)

use gen_pass::{PassConfig, PasswordGenerator};

fn main() -> anyhow::Result<()> {
    let cfg = PassConfig {
        length: 24,
        salt: Some("my-custom-salt".to_string()), // Custom salt (default is "suenot")
        ..Default::default()
    };

    let generator = PasswordGenerator::from_config(&cfg)?;
    let password = generator.generate(cfg.length);
    println!("{password}");
    Ok(())
}

Algorithm Flow

flowchart TD
    A[Start] --> B{CLI or Library?}
    B -->|CLI| C[Parse CLI Args]
    B -->|Library| D[Use PassConfig]
    C --> E[Build PassConfig]
    D --> E
    E --> F[Select RNG Algorithm]
    F --> G[Collect Random Bytes]
    G --> H1{Salt Provided?}
    H1 -->|Yes| H2[Apply Salt Hash]
    H1 -->|No| H3[Skip Salt]
    H2 --> H4[Map To Allowed Charset]
    H3 --> H4
    H4 --> I[Return / Print Password]
    I --> J{Copy to Clipboard?}
    J -->|Yes| K[Invoke pbcopy/xclip]
    J -->|No| L[Done]

Supported Random Algorithms

Algorithm Details

• mixed – Combines several independent entropy sources: the OS CSPRNG, a ChaCha20 stream cipher RNG seeded from that entropy, and finally StdRng re-seeded with SHA-256 of previous bytes. Enhances security through entropy mixing.
• os – Direct reading from the system cryptographically secure random number generator (/dev/urandom, getrandom(2), BCryptGenRandom). Maximally reliable, but may be slower on certain platforms.
• chacha20 – Implementation of ChaCha20 stream cipher RNG (IETF variant). Used in TLS and OpenSSH; provides high speed and cryptographic strength.
• hc128 – HC-128 generator from the eSTREAM family. Offers an excellent speed/security ratio; suitable for embedded devices.
• ring – Wrapper over ring C code, uses system RNG and additionally checks for errors; convenient if the project already depends on ring.
• xoshiro – Xoshiro/Xoroshiro family (non-crypto). Very fast, small state. Not intended for passwords, but useful when pseudorandomness without crypto requirements is needed.
• pcg64 – Permuted Congruential Generator 64-bit version. Good statistical properties, but not cryptographically secure.
• rdrand – Uses the Intel/AMD hardware instruction RDRAND. Fast, cryptographically secure, but only works on supported CPUs and depends on trust in microcode.

Select algorithm via CLI flag -a/--algo, or by setting algorithm field in PassConfig.

Algorithm Diagrams

mixed

Chain: OsRng → ChaCha20Rng → SHA-256 → StdRng → Password bytes

os

Chain: OsRng / getrandom → Password bytes

chacha20

Chain: Seed via OsRng → ChaCha20Rng → Password bytes

hc128

Chain: Seed via OsRng → Hc128Rng → Password bytes

ring

Chain: ring::SystemRandom → Password bytes

xoshiro

Chain: Seed via OsRng → Xoshiro256++ → Password bytes

pcg64

Chain: Seed via OsRng → PCG64Mcg → Password bytes

rdrand

Chain: CPU RDRAND → Password bytes

License

MIT