Skip to content

Latest commit

 

History

History
143 lines (98 loc) · 7.13 KB

README.md

File metadata and controls

143 lines (98 loc) · 7.13 KB
Raw

dicewarepy

dicewarepy is a minimalist Python library designed for the random selection of words from cryptographic wordlists, utilizing the Diceware method.

About

Many scenarios require the manual input and memorization of passwords, such as the master password for a password manager or the encryption password for a device.

Two key considerations emerge in this context:

  • The password must be difficult to guess.
  • The password should be easy to remember.

The Diceware method (archived), created by Arnold G. Reinhold, addresses both of these considerations. Instead of relying on a hard-to-remember string of characters, which often suffers from a lack of randomness and therefore security when thought up by humans, Diceware uses dice and a special wordlist to generate secure passphrases.

The process for creating a Diceware passphrase can be broken down into the following four steps:

  1. A six-sided dice is rolled five times, with the resulting numbers recorded after each roll.
  2. For instance, if the rolls come up with 4-3-6-4-4, one would look through a Diceware wordlist to find the word corresponding to the number 43644.
  3. In this case, the word “password” would be identified and written down.
  4. This process is repeated until the desired number of words is gathered for the passphrase, with each word separated by a space.

dicewarepy provides a compact simulation of the steps described above.

Installation

pip install dicewarepy

Or if you have multiple Python / pip versions installed, use pip3:

pip3 install dicewarepy

Usage

dicewarepy.diceware(n=6, language='en')

Returns a list of n words selected from a Diceware wordlist specified by language.

  • n: int
    • The desired number of words to generate.
    • Default: 6
  • language: str
    • The language tag of the wordlist to select from.
    • Default: en

Example

Import the diceware function:

from dicewarepy import diceware

Assign a list of six randomly selected words to the variable words:

words = diceware()

Print the list to the terminal:

print(words)

Output: ['dainty', 'swimmable', 'thimble', 'stuffing', 'armrest', 'little']

Use the previously selected words to build a passphrase string:

# Define a space as delimiter.
delimiter = " "

# Build the passphrase string.
passphrase = delimiter.join(words)

Print the passphrase to the terminal:

print(passphrase)

Output: dainty swimmable thimble stuffing armrest little

Wordlists

Language Tag Wordlist File
English en EFF Large Word List eff_large_wordlist.txt
German de Mnemonische deutsche Wortliste de-7776-v1-diceware.txt
... ... ... ...

Security

Entropy

Entropy measures the unpredictability of a given element. A passphrase with higher entropy is more challenging to guess, making entropy a useful metric for assessing passphrase strength.

The word lists included in this package are standard Diceware word lists, featuring $7,776$ unique words. The total number of possible passphrases from such a word list can be calculated using the formula $7,776^n$, where $n$ represents the number of words in the passphrase.

The entropy is determined by taking the base-2 logarithm of the number of possible passphrases, leading to the formula: $E_{pass} = \log_2(7,776^n)$.

As shown in the following table, each word in the passphrase contributes an additional $12.925$ bits of entropy. Given the time required to guess the correct combination, it is recommended to use Diceware passphrases that consist of at least 6 words.

Words Possible Passphrases Entropy Time to guess*
$1$ $7,776$ $12.925$ $\lt 1 \textrm{ second}$
$2$ $\approx 6.04e^7$ $25.85$ $\lt 1 \textrm{ second}$
$3$ $\approx 4.7e^{11}$ $38.774$ $\lt 1 \textrm{ second}$
$4$ $\approx 3.65e^{15}$ $51.7$ $\approx 30 \text{ minutes}$
$5$ $\approx 2.84e^{19}$ $64.62$ $\approx 165 \text{ days}$
$6$ $\approx 2.21e^{23}$ $77.55$ $\approx 3,505 \text{ years}$
$7$ $\approx 1.71e^{27}$ $90.47$ $\approx 27,256 \text{ millenia}$
$8$ $\approx 1.33e^{31}$ $103.4$ ...

*Assuming an average of attempting 50% of possible combinations to successfully guess the correct passphrase, and considering an adversary capable of making one trillion (1,000,000,000,000) guesses per second.

Randomness

The strength of random passphrases relies heavily on the randomness of the underlying number generator.

The Diceware FAQ (archived) states that for most users, using dice is by far the better method for selecting passphrase words than relying on a computer, as the random number generators provided by most programming libraries are nowhere near good enough.

For this reason, Python's random library, which produces cryptographically weak pseudo-random numbers, was not utilized in this implementation. Instead, this implementation relies on Python's secrets library, specifically designed for generating cryptographically strong random numbers suitable for passwords, account authentication, security tokens, and other sensitive information.

Credits