secure-passgen

Military-grade, fool-proof, international password generator & CSV database creator

§1NAME

secure-passgen — military-grade, fool-proof, international (i18n) password generator and LibreOffice/Excel-compatible CSV database creator, written in Rust with a plugin architecture and Deep-Entropy (SHA-512 hash-chaining) engine.

§2SYNOPSIS

secure-passgen [OPTIONS] [COUNT] [-COUNT_SHORTHAND]

secure-passgen -c -n -s -l 16 -1M -o database.csv
secure-passgen --password-db --charset chinese -c -n -2500 -o grid.csv
secure-passgen --language hu --charset hu -c -n -s --extreme-random -l 20
secure-passgen --plugins uppercase,hyphen -c -n -100K -o bulk.csv

§3DESCRIPTION

secure-passgen generates cryptographically secure passwords using the operating system's CSPRNG (getrandom: Linux getrandom(2) syscall, macOS getentropy(2), Windows BCryptGenRandom). It re-implements and extends the classic pwgen(1) tool with modern safety guarantees:

§4OPTIONS

4.1 Password style (pwgen-compatible)

4.2 Generation

4.3 Output & database

4.4 International & system

§5CHARACTER SETS (live samples)

The samples below were generated by this binary at documentation build time (12 characters each):

§6UI LANGUAGES

All console banners, progress labels, success messages and the auto-recovery panel are translated. Detected automatically from $LANG, overridable with --language. Supported: English, Magyar, Español, 中文, हिन्दी, العربية, বাংলা, Português, Русский, 日本語, Deutsch, Français, 한국어, Türkçe, Tiếng Việt, Italiano, Polski, Українська, Nederlands, Română.

§7DEEP ENTROPY ENGINE

1. seed = 64 bytes from OS CSPRNG (getrandom syscall)
2. for i in 0..iterations:            # up to 1,000,000
       seed = SHA512(seed || i.to_le_bytes())
3. for each character position p:
       index = u16(seed[2p], seed[2p+1]) mod charset_len
       password[p] = charset[index]

§8MEMORY ARCHITECTURE

• Streaming write: one password lives in memory at a time, then Rust ownership drops it deterministically.
• BufWriter (8 KB): syscalls are batched; 100K passwords produce a handful of writes.
• Periodic flush: every 1000 rows, so a crash never loses more than 1000 rows.
• Constant RSS: 2.6–2.8 MB measured from 10 to 100,000 passwords (see benchmarks).
• Valgrind clean: 0 bytes definitely/indirectly/possibly lost.

§9PLUGIN SYSTEM (developer guide)

// src/plugins/my_plugin.rs  (~20 lines)
use super::Plugin;

pub struct MyPlugin;

impl Plugin for MyPlugin {
    fn name(&self) -> &str { "MyPlugin" }
    fn description(&self) -> &str { "Does something custom" }
    fn process_password(&self, password: String) -> String {
        password.to_uppercase()   // any transformation
    }
}

Register it in src/plugins/mod.rs and in load_plugins() in main.rs, then use --plugins myplugin. Future roadmap: dynamic .so loading via libloading and WASM plugins.

§10AUTO-RECOVERY (fool-proof engine)

Every applied fix is listed in the final yellow panel, so soldiers and beginners always see what happened and where the file really is.

§11BENCHMARKS (measured on this host)

Values injected from the latest benchmarks_*/results.csv run on this machine:

§12EXAMPLES

./secure-passgen -c -n -s -l 16 -1M -o million.csv
  [########################################] 100% (1000000/1000000)
  SUCCESS - Operation completed successfully 0.082 seconds
  File saved to /home/boldwelder/secure-passgen/million.csv

./secure-passgen --password-db --charset chinese -c -n -2500 -o grid.csv
  Mode: Password Database Grid | Columns: A B C | Rows: 1000
  SUCCESS  # open with: libreoffice --calc grid.csv

./secure-passgen -c -n -s -o same.csv   # run twice
  ⚠ AUTOMATIC RECOVERY ACTIVATED — Problems found: 1
  ║  Fix #1  Problem:  File 'same.csv' already exists
  ║           Solution: Auto-renamed to 'same_1.csv'

§13BEGINNER GUIDE

1. Build once: cargo build --release
2. Generate your first safe passwords: ./target/release/secure-passgen -c -n -s -l 16 -50 -o my.csv
3. Double-click my.csv → opens in LibreOffice Calc / Excel.
4. If anything goes wrong, read the yellow panel at the end — it tells you exactly what the program fixed and where your file is.

§14ADVANCED GUIDE

• Combine Deep Entropy with plugins: --extreme-random --extreme-iter 100000 --plugins uppercase,hyphen
• Generate a Hungarian-charset vault: --language hu --charset hu -c -n -s -B -l 20 -10K
• Audit run with metadata log: --debug --log audit.log (passwords are never logged).
• Re-run the full QA suite any time with ./patch_and_benchmark.sh.

§15SECURITY NOTES

• Entropy source: OS kernel CSPRNG only; no rand(), no time-based seeds.
• No network access, no telemetry, no logging of secrets by design.
• Unicode passwords increase entropy per character (larger alphabet), but verify the target system accepts UTF-8 input.

§16FILES

~/.cargo/bin or ./target/release/secure-passgen   binary
./passwords.csv                                   default output
./benchmarks_*/results.csv                        QA results
./documentation_v2/README.html                    this manual

§17SEE ALSO

pwgen(1), openssl-rand(1), getrandom(2), apg(1), makepasswd(1), NIST SP 800-90A (DRBG), RFC 4180 (CSV).

§18AUTHORS

Boldwelder (micro-electric technician, welder, ex-diplomat MFA, 4-generation Hungarian military family) — concept, requirements, QA. Adjutans-1 — Rust architecture & implementation.

§19CHANGELOG