% pwgen(1) 1.3 | Misc
% Pat Beirne <patb@pbeirne.com>
  
# Name

pwgen - a phrase-based password generator

Generate word-based passwords. Based on [XKCD/936](https://xkcd.com/936/), word-based passwords are easier to remember than a string of random letters/numbers/punctuation.

[TOC]

# Description

Password generators can be found all over the internet, but most generate random combinations of letters + numbers + punctuation. If a combination of those is long enough to be secure, it is also long enough to be difficult to remember, and possible difficult to type.

The XKCD comic #936 introduced the idea that a phrase of 3, 4 or 5 common words can be used as a password that is sufficiently difficult to crack in our lifetimes. The program **`pwgen`** is a locally hosted generator of these kinds of pass phrases.

This program runs locally on a UNIX/Linux based computer, and the passphrase never crosses the network, so you can be sure that you're the only one who has ever seen it.

Simply invoke the program, and the defaults will give you a usable password phrase:

    pwgen -S

returns

    boards.coziest.allure

as a potential pass phrase.


# Synopsis

    pwgen [-sSpPkKnNcCXMa] [-L <length>] [nummber of passwords]

# Options

       -s           pad with only spaces (default; for smartphone)
       -S           pad with period and comma (for smartphone)
       -p           pad with special characters
       -P           pad with numbers
       -k           connect the words as CamelCase
       -K           connect the words as snake_case
       -n           add a number at the beginning
       -N           add a number at the end
       -c           add a special character at the begnning
       -C           add a special character at the end
       -M           capitalize the words
       -a           connect the words with a conjuction filler
       -X           same as -MNCS (capital, periods & commas, extra number & char)
       -L <n>       make pass phrases at least this long; default=20
       num_phrases  make multiple pass phrases, one per line; default=1

By default, **`pwgen`** will build a pass phrase using words from the dictionary at **`/usr/share/dict/words`** and add punctuation to separate the words. 

    $ pwgen
    consequentlyi restraining

The **`-s`** and **`-S`** options add padding using spaces or periods/commas, making thease passphrases easy to type on a smartphone. Adding the **`-p`** option will padd the phrase using a "special characters"; the character will be one of ` !@#$%^&*()-_=+[{]}\\|;:/?.>,<~`. Similarly, the **`-P`** option uses a number.

    $ pwgen -s
    garments mazes queasy
    $ pwgen -S
    crufted.teeth.buy
    $ pwgen -p
    eating!rocks!outside
    $ pwgen -P
    bleeding5clusters5berries

The **`-L`** option allows you to specify a minimum length for the pass phrase, although the result may be a few characters longer than you requested, so that the words aren't chopped up.

    $ pwgen -L 30
    dittoed nonabrasive atomic exhaust

The **`-a`** option uses common English conjunctions to separate a pair of words. If the 2nd word starts with a vowel, the conjuntion "a" is changed to "an". I find these phrases much easier to remember than just a sequence of words.

    $ pwgen -c
    quick in a crowd

Part of the reason for using pass phrases is to make them easier to remember for us humans. Sometimes, the first phrases offered just doesn't seem memorable, so you can add a small integer after `pwgen` to get multiple offerings, and you can just choose the one that seems memorable to you.

    $ pwgen 6
    mechanisms..contempt
    windbreak\\knuckling
    pith$seconding$unkempt
    adore/anthems/welder
    firesides!!!spaceman
    wannest=tabloids=weighty

The **`-k`** and **`-K`** options will create CamelCase and snake_case respetively. You can use the **`-M`** option to capitalize all the dictionary words.

Some servers require numbers and "special characters" in the passwords, so the **`-n, -N, -c`** and **`-C`** allow you to add these characters at the beginning or the end of your passphrase. See the examples below.

The **`-X`** option is included to abbreviate a commonly used combination of **`-MNCS`**. 

# Examples

```
    -s    dog cat mouse        # default
    -S    dog.cat.mouse   
    -p    dog#cat#mouse  
    -P    dog4cat4mouse  
    -c    !dog cat mouse  
    -C    dog cat mouse#  
    -n    4dog cat mouse
    -N    dog cat mouse4
    -cnCN $4dog cat mouse4$
    -M    Dog Cat Mouse
    -k    DogCatMouse
    -kN   DogCatMouse2
    -K    dog_cat_mouse
    -KMN  Dog_Cat_Mouse3
    -a    dog and a cat with mouse
    -Sa   dog.and.a.cat.with.mouse
    -aMS  Dog.and.a.Cat.with.Mouse
    -pa   dog#and#a#cat#with#mouse
    -paCN dog^and^a^cat^with^mouse5%
    -X    Dog.Cat.Mouse6&
```

Just select a format that you find memorable.
 
# Files

**`/usr/share/dict/words`**:  a line separated list of words for the pass phrases

Words ending in `'s` are dropped by the import algorithm; this may need to be changed for other languages. 
 
# Notes

Don't bother trying the **`-ka`** combination....the results can be illegible.

This project is written in Python3 and duplicated in Rust. I wanted to learn Rust and compare the complexity of both.

# See Also

### Other implementations

<http://www.egansoft.com/password/index.php>

<https://passwords-generator.org/words>

<https://passwordcreator.org/commonwords.html>

<https://mdigi.tools/memorable-password/>

<https://www.mapletech.co.uk/tools/password-generator/>