rusty-pwgen 0.1.0

Generate pronounceable or random passwords from the OS CSPRNG — a Rust port of Theodore Ts'o's `pwgen` with strict-compat mode, deterministic `-H` reproducible mode (SHA256 + ChaCha20), and a typed library API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# Compatibility Matrix — `rusty-pwgen` vs upstream `pwgen`

> Pinned baseline: pwgen 2.08 (Debian stable 2026-05).

## Flag matrix

| Flag | Default mode | Strict mode |
|---|---|---|
| `-c` / `--capitalize` | Capitalize on | Same |
| `-A` / `--no-capitalize` | Capitalize off | Same |
| `-n` / `--numerals` | Numerals on | Same |
| `-0` / `--no-numerals` | Numerals off | Same |
| `-y` / `--symbols` | Symbol set on | Same |
| `-s` / `--secure` | Uniform random | Same |
| `-B` / `--ambiguous` | Drop `l 1 0 O I` | Same |
| `-v` / `--no-vowels` | Drop vowels; implies `-s` | Same |
| `-1` | One password per line | Same |
| `-C` | Force columnar output | Same |
| `-N <count>` / `--num-passwords <count>` | Override count (wins over positional) | Same |
| `-r <chars>` / `--remove-chars <chars>` | Drop chars; implies `-s` | Same |
| `-H <file>[#suffix]` / `--sha1 <file>[#suffix]` | SHA256-seeded ChaCha20 (NOT SHA1 despite the flag name) | Same |
| `-c` + `-A` (and other conflicting pairs) | **Rejected at parse time** | Last-wins (upstream parity) |
| `--help` / `--version` | clap-rendered | Rejected per first-error formatter |
| `completions <shell>` | Subcommand | Rejected |

## Intentional divergences from upstream

1. **Default-mode conflict rejection** — Default rejects `(-c, -A)` / `(-n, -0)` / `(-1, -C)` at parse time. Strict mode preserves upstream's last-wins behavior.
2. **`-H` uses SHA256 → ChaCha20Rng**, not SHA1. The 32-byte SHA256 digest seeds ChaCha20 natively (no padding). The flag name is preserved for upstream compat but the algorithm differs. Lock at v0.1.0; future changes are MAJOR bumps.
3. **First-error-only Strict-mode stderr** — option A pattern (mirrors rusty-sponge/vipe/pee).
4. **`-a/--alt-phonics` omitted** (upstream's legacy no-op).
5. **`--secure-source` omitted** (we always use `OsRng`).
6. **"Naughty word" filter omitted** (forward-review candidate).
7. **`pwgen-alias` PATH-collision warning** — when installed via the optional Cargo feature, the `pwgen` binary may collide with upstream pwgen on the same PATH.

## Exit-code matrix

| Scenario | Default | Strict | Upstream |
|---|---|---|---|
| Normal success | 0 | 0 | 0 |
| Conflicting flags | 2 (parse error) | 0 (last-wins) | 0 (last-wins) |
| Unknown flag | 2 (clap) | non-zero (first-error stderr) | non-zero (multi-error stderr) |
| `-H <file>` not found | 1 | 1 | 1 |

## Security caveats

- **`-H` reproducible mode is NOT cryptographically appropriate for high-value secrets.** The output is deterministic from the seed file; anyone with the same file produces the same password.
- **Pronounceable mode trades entropy for memorability.** ≈30-32 bits at length 8 (default) vs ≈48 bits for `-s` at the same length.
- **`rusty-pwgen` produces general-purpose passwords**, not key material. For long-lived cryptographic keys, use a dedicated crypto library.

## Known limitations at v0.1.0

- See [`CHANGELOG.md`](../CHANGELOG.md) § "Known limitations at v0.1.0".