# `pgen`(1) – Passphrase Generator

[![Crates.io](https://img.shields.io/crates/v/pgen?style=flat-square)](https://crates.io/crates/pgen)
[![Crates.io](https://img.shields.io/crates/d/pgen?style=flat-square)](https://crates.io/crates/pgen)
[![License](https://img.shields.io/badge/license-ISC-blue?style=flat-square)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ctsrc/Pgen?style=social)](https://github.com/ctsrc/Pgen#start-of-content)

Generate passphrases using any of the following wordlists:

* the [wordlists for random passphrases][EFFWL] made by the EFF
* [BIP39][BIP39]

The EFF wordlists consist of words that are easy to type and easy to remember.

By default, passphrases generated by `pgen` consist of twelve words
randomly selected from the autocomplete-optimized wordlist. Be sure to
[read the article][EFFWL] to learn about the difference between the
different wordlists provided by the EFF.

These are some examples of generated passphrases:

* gimmick saffron nirvana superstore voicemail dedicate guacamole oftentimes dwindling kingdom shuttle upright
* bobcat pulley yearbook nectar krypton pesticide relic sauna detergent amnesty dishcloth tapestry
* porcupine identical occupation oxidize avalanche celery vaporizer dastardly vicinity enlarged hatchling urethane

## Table of Contents

* [Usage](#usage)
    - [Options and arguments](#options-and-arguments)
* [How many bits of entropy does your passphrase need?](#how-many-bits-of-entropy-does-your-passphrase-need)
* [Is a CSPRNG really needed here?](#is-a-csprng-really-needed-here)
* [Installation](#installation)

## Usage

```
pgen [-d] [-w <USE_WLIST>] [-n <n>] [-k <k>] [-e]
pgen -h | --help
pgen -V | --version
```

### Options and arguments

`-w` Specify wordlist to use.

* `eff-autocomplete` (default): Use *EFF's Short Wordlist #2*

  Features:
    - Each word has a unique three-character prefix. This means that software could
      auto-complete words in the passphrase after the user has typed the first three characters.
    - All words are at least an edit distance of 3 apart. This means that software could
      correct any single typo in the user's passphrase (and in many cases more than one typo).

  Details:
    - [Deep Dive: EFF's New Wordlists for Random Passphrases][EFFWL] (2016)
    - <https://www.eff.org/dice>

* `eff-long`: Use *EFF's Long Wordlist*

  Recommended for the creation of memorable passphrases since the increased number of words,
  as well as the greater effective word length, allows for good entropy with a lower amount
  of words compared to for example the autocomplete-optimized short wordlist.

  Features:
    - Contains words that are easy to type and remember.
    - Built from a list of words that prioritizes the most recognized words
      and then the most concrete words.
    - Manually checked by EFF and attempted to remove as many profane, insulting, sensitive,
      or emotionally-charged words as possible, and also filtered based on several public
      lists of vulgar English words.

  Details:
    - [Deep Dive: EFF's New Wordlists for Random Passphrases][EFFWL] (2016)
    - <https://www.eff.org/dice>

* `eff-short`: Use *EFF's Short Wordlist #1*

  Features:
    - Designed to include the 1,296 most memorable and distinct words.

  Details:
    - [Deep Dive: EFF's New Wordlists for Random Passphrases][EFFWL] (2016)
    - <https://www.eff.org/dice>

* `bip39`: Use *BIP39* wordlist

  Details:
    - [BIP39][BIP39]
    - <https://en.bitcoin.it/wiki/Seed_phrase>

`-n` Specify the number of words to use *n*. Default value:

* Twelve (12) words if any of the short wordlists are being used.
* Ten (10) words if the large wordlist is being used.

Note: When BIP39 wordlist is used, the number of words to use must be one of:
12, 15, 18, 21, or 24.

`-k` Specify the number of passphrases to generate *k*. Default value: 1.

`-e` Calculate and print the entropy for the passphrase(s) that would be
generated with the given settings. What is password entropy?
[Entropy is a measure of what the password could have been, so it relates to the selection process](https://crypto.stackexchange.com/a/376).

`--dice` Use physical six-sided dice instead of letting the computer pick
words. Useful in case you distrust the ability or willingness of
your computer to generate "sufficiently random" numbers.

`-h`, `--help` Show help and exit.

`-V`, `--version` Print version information and exit.

## How many bits of entropy does your passphrase need?

How many bits of entropy should your passphrase consist of?

Looking at [the article about password strength on Wikipedia](https://en.wikipedia.org/wiki/Password_strength), you will
find that the following is said:

> The minimum number of bits of entropy needed for a password depends
> on the threat model for the given application. If
> [key stretching](https://en.wikipedia.org/wiki/Key_stretching)
> is not used, passwords with more entropy are needed.
> [RFC 4086](https://tools.ietf.org/html/rfc4086), "Randomness Requirements
> for Security", presents some example threat models and how to calculate
> the entropy desired for each one. Their answers vary between 29 bits
> of entropy needed if only online attacks are expected, and up to 128 bits
> of entropy needed for important cryptographic keys used in applications
> like encryption where the password or key needs to be secure for a long
> period of time and stretching isn't applicable.

In the case of web services such as webmail, social networks, etc.,
given that historically we have seen password databases leaked, where
weak hashing algorithms such as MD5 were used, it is the opinion of the
author that the neighbourhood of 128 bits of entropy is in fact
an appropriate default for such use.

When calculating the entropy of a password or a passphrase,
[one must assume that the password generation procedure is known to the attacker](https://crypto.stackexchange.com/a/376).
Hence with 12 words from either of the short wordlists, each of which
consist of 1296 words, we get a password entropy of log2(1296^12) ~=
124.08 bits. Similarily, with 10 words from the long wordlist (7776 words),
we get a password entropy of log2(7776^10) ~= 129.25 bits.

## Is a CSPRNG really needed here?

Using a CSPRNG ensures uniform distribution of probability. This in turn
ensures that the password entropy calculations are correct. Hence it makes
sense to use a CSPRNG.

## See also

* `lastresort`(1) on [crates.io](https://crates.io/crates/base256) / [GitHub](https://github.com/ctsrc/Base256)

## Installation

1. [Install Rust](https://www.rust-lang.org/en-US/install.html).
2. Run `cargo install -f pgen`

[EFFWL]: https://www.eff.org/deeplinks/2016/07/new-wordlists-random-passphrases

[BIP39]: https://en.bitcoin.it/wiki/BIP_0039