/Pgen

Command-line passphrase generator

Primary LanguageRustISC LicenseISC

pgen(1) – Passphrase Generator

Crates.io Crates.io License GitHub stars

Generate passphrases using any of the following wordlists:

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 to learn about the difference between the different wordlists provided by the EFF.

Table of Contents

Examples of generated passphrases

Using the default wordlist

pgen

spyglass eruption sapphire wifeless thimble breath fossil thwarting sedative peroxide vagrancy earlobe

Using the EFF long wordlist

pgen -w eff-long

flashy tackle semifinal endowment trekker exhume citrus venus carload implant

Using BIP39 wordlist, and custom number of words

Note

In the current version, BIP39 wordlist is available but the BIP39 algorithm itself is not yet used. In the upcoming v3.0.0 release, the BIP39 algorithm will be implemented so that when you use the BIP39 wordlist it will generate mnemonics that can be used for generation of valid Bitcoin wallets.

pgen -w bip39 -n 24

sword relief this any peanut uncle supreme month impose learn rose ramp double auction course mutual bench elder unfair dizzy harbor use casino pledge

Latest version available

pgen --version
pgen 3.0.0-alpha.1

Installation

  1. Install Rust.
  2. Run cargo install -f pgen@3.0.0-alpha.1

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 (EFF's "short word list" with words that have unique three-character prefixes)

    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:

  • eff-long: Use EFF's Long Wordlist (EFF's "long word list")

    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:

  • eff-short: Use EFF's Short Wordlist #1 (EFF's "general short word list")

    Features:

    • Designed to include the 1,296 most memorable and distinct words.

    Details:

  • bip39: Use BIP39 English wordlist

    Details:

-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.

--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.

Calculation of entropy

When calculating the entropy of a password or a passphrase, one must assume that the password generation procedure is known to the attacker. As such, the strength of the passphrases that pgen generate are not weakened in and of itself by the fact that the wordlists we use are publicly known.

EFF wordlists

When one of the EFF wordlists is used, you have the following total number of distinct words to pick from the respective list:

  • 7776 words in EFF's "long word list" (eff-long)
  • 1296 words in EFF's "general short word list" (eff-short)
  • 1296 words in EFF's "short word list" with words that have unique three-character prefixes (eff-autocomplete)

The number of bits of entropy added by each randomly selected word from these EFF wordlists depends on the total number of words that are in the list we are selecting the words from.

To calculate the entropy added by each word, we take the binary logarithm of the number of words total in the wordlist:

  • log2(7776) ~= 12.92 bits of entropy added from each randomly selected word in the "long word list".
  • log2(1296) ~= 10.33 bits of entropy added from each randomly selected word in one of the EFF's short word lists.

Then:

  • Creating a passphrase consisting of 10 randomly selected words from the "long word list" gives a passphrase with log2(7776^10) ~= 129.25 bits of entropy.
  • Creating a passphrase consisting of 12 randomly selected words from one of the EFF's short word lists gives a passphrase with log2(1296^12) ~= 124.08 bits of entropy.

BIP39 English wordlist and BIP39 algorithm

When using the BIP39 algorithm, the passphrase is derived directly from a specific number of random bits, which are then padded with bits from a checksum at the end.

For example, for a BIP39 mnemonic sentence consisting of 12 words, one has to use 128 random bits appended by 4 bits of checksum bits.

The checksum bits do not add entropy, nor are any of the initial entropy bits discarded.

The entropy of a BIP39 mnemonic sentence is simply the number of random bits it was generated from in the first place.

Specifically, BIP39 has five different possible mnemonic sentence lengths, each with the following corresponding number of bits of entropy:

  • 128 bits of entropy for a BIP39 mnemonic sentence consisting of 12 words.
  • 160 bits of entropy for a BIP39 mnemonic sentence consisting of 15 words.
  • 192 bits of entropy for a BIP39 mnemonic sentence consisting of 18 words.
  • 224 bits of entropy for a BIP39 mnemonic sentence consisting of 21 words.
  • 256 bits of entropy for a BIP39 mnemonic sentence consisting of 24 words.

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, 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 is not used, passwords with more entropy are needed. RFC 4086, "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.

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