# dicewarepy
_dicewarepy_ is a minimalist Python library designed for the random selection of words from cryptographic wordlists, utilizing the Diceware method.
- [About](#about)
- [Installation](#installation)
- [Usage](#usage)
- [Example](#example)
- [Wordlists](#wordlists)
- [Security](#security)
- [Entropy](#entropy)
- [Randomness](#randomness)
- [Credits](#credits)
## 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](https://theworld.com/~reinhold/diceware.html) [(archived)](https://web.archive.org/web/20240913072907/https://theworld.com/~reinhold/diceware.html), 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
```shell
pip install dicewarepy
```
Or if you have multiple Python / pip versions installed, use `pip3`:
```shell
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:
```python
from dicewarepy import diceware
```
Assign a list of six randomly selected words to the variable `words`:
```python
words = diceware()
```
Print the list to the terminal:
```python
print(words)
```
Output: `['dainty', 'swimmable', 'thimble', 'stuffing', 'armrest', 'little']`
Use the previously selected words to build a passphrase string:
```python
# Define a space as delimiter.
delimiter = " "
# Build the passphrase string.
passphrase = delimiter.join(words)
```
Print the passphrase to the terminal:
```python
print(passphrase)
```
Output: `dainty swimmable thimble stuffing armrest little`
### Wordlists
| Language | Tag | Wordlist | File |
|----------|------|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| English | `en` | [EFF Large Word List](https://www.eff.org/document/passphrase-wordlists) | [eff_large_wordlist.txt](https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt) |
| German | `de` | [Mnemonische deutsche Wortliste](https://github.com/dys2p/wordlists-de) | [de-7776-v1-diceware.txt](https://raw.githubusercontent.com/dys2p/wordlists-de/main/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](https://theworld.com/~reinhold/dicewarefaq.html#computer) [(archived)](https://web.archive.org/web/20240912113815/https://theworld.com/~reinhold/dicewarefaq.html#computer) 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](https://docs.python.org/3/library/random.html), which produces cryptographically weak pseudo-random numbers, was not utilized in this implementation. Instead, this implementation relies on Python's [secrets library](https://docs.python.org/3/library/secrets.html), specifically designed for generating cryptographically strong random numbers suitable for passwords, account authentication, security tokens, and other sensitive information.
## Credits
- [Diceware](https://theworld.com/~reinhold/diceware.html) [(archived)](https://web.archive.org/web/20240913072907/https://theworld.com/~reinhold/diceware.html) by Arnold G. Reinhold
- [EFF Large Word List](https://www.eff.org/document/passphrase-wordlists) by Electronic Frontier Foundation
- [Mnemonische deutsche Wortliste](https://github.com/dys2p/wordlists-de) by dys2p
Raw data
{
"_id": null,
"home_page": "https://github.com/inwerk/dicewarepy",
"name": "dicewarepy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "dicewarepy, diceware, dice, die, passphrase, passphrases, password, passwords",
"author": "inwerk",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a8/22/df93bf780c5c86181373e2e8f9d7d7112f75fff9ae147263539223d2afe3/dicewarepy-1.0.3.tar.gz",
"platform": null,
"description": "# dicewarepy\n\n_dicewarepy_ is a minimalist Python library designed for the random selection of words from cryptographic wordlists, utilizing the Diceware method.\n\n- [About](#about)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Example](#example)\n - [Wordlists](#wordlists)\n- [Security](#security)\n - [Entropy](#entropy)\n - [Randomness](#randomness)\n- [Credits](#credits)\n\n## About\n\nMany 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.\n\nTwo key considerations emerge in this context:\n- The password must be difficult to guess.\n- The password should be easy to remember.\n\nThe [Diceware method](https://theworld.com/~reinhold/diceware.html) [(archived)](https://web.archive.org/web/20240913072907/https://theworld.com/~reinhold/diceware.html), created by Arnold G. Reinhold, addresses both of these considerations.\nInstead 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.\n\nThe process for creating a Diceware passphrase can be broken down into the following four steps:\n1. A six-sided dice is rolled five times, with the resulting numbers recorded after each roll.\n2. 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`.\n3. In this case, the word \u201cpassword\u201d would be identified and written down.\n4. This process is repeated until the desired number of words is gathered for the passphrase, with each word separated by a space.\n\n_dicewarepy_ provides a compact simulation of the steps described above.\n\n## Installation\n\n```shell\npip install dicewarepy\n```\n\nOr if you have multiple Python / pip versions installed, use `pip3`:\n\n```shell\npip3 install dicewarepy\n```\n\n## Usage\n\n**dicewarepy.diceware(n=6, language='en')**\n\nReturns a list of `n` words selected from a Diceware wordlist specified by `language`.\n\n- `n`: `int`\n - The desired number of words to generate.\n - Default: `6`\n- `language`: `str`\n - The language tag of the wordlist to select from. \n - Default: `en`\n\n### Example\n\nImport the `diceware` function:\n\n```python\nfrom dicewarepy import diceware\n```\n\nAssign a list of six randomly selected words to the variable `words`:\n\n```python\nwords = diceware()\n```\n\nPrint the list to the terminal:\n\n```python\nprint(words)\n```\n\nOutput: `['dainty', 'swimmable', 'thimble', 'stuffing', 'armrest', 'little']`\n\nUse the previously selected words to build a passphrase string:\n\n```python\n# Define a space as delimiter.\ndelimiter = \" \"\n\n# Build the passphrase string.\npassphrase = delimiter.join(words)\n```\n\nPrint the passphrase to the terminal:\n\n```python\nprint(passphrase)\n```\n\nOutput: `dainty swimmable thimble stuffing armrest little`\n\n### Wordlists\n\n| Language | Tag | Wordlist | File |\n|----------|------|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|\n| English | `en` | [EFF Large Word List](https://www.eff.org/document/passphrase-wordlists) | [eff_large_wordlist.txt](https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt) |\n| German | `de` | [Mnemonische deutsche Wortliste](https://github.com/dys2p/wordlists-de) | [de-7776-v1-diceware.txt](https://raw.githubusercontent.com/dys2p/wordlists-de/main/de-7776-v1-diceware.txt) |\n| ... | ... | ... | ... |\n\n## Security\n\n### Entropy\n\nEntropy 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.\n\nThe 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.\n\nThe 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)$.\n\nAs 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.\n\n| Words | Possible Passphrases | Entropy | Time to guess* |\n|-------|----------------------|----------|-----------------------------------|\n| $1$ | $7,776$ | $12.925$ | $\\lt 1 \\textrm{ second}$ |\n| $2$ | $\\approx 6.04e^7$ | $25.85$ | $\\lt 1 \\textrm{ second}$ |\n| $3$ | $\\approx 4.7e^{11}$ | $38.774$ | $\\lt 1 \\textrm{ second}$ |\n| $4$ | $\\approx 3.65e^{15}$ | $51.7$ | $\\approx 30 \\text{ minutes}$ |\n| $5$ | $\\approx 2.84e^{19}$ | $64.62$ | $\\approx 165 \\text{ days}$ |\n| $6$ | $\\approx 2.21e^{23}$ | $77.55$ | $\\approx 3,505 \\text{ years}$ |\n| $7$ | $\\approx 1.71e^{27}$ | $90.47$ | $\\approx 27,256 \\text{ millenia}$ |\n| $8$ | $\\approx 1.33e^{31}$ | $103.4$ | ... |\n\n*_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._\n\n### Randomness\n\nThe strength of random passphrases relies heavily on the randomness of the underlying number generator.\n\nThe [Diceware FAQ](https://theworld.com/~reinhold/dicewarefaq.html#computer) [(archived)](https://web.archive.org/web/20240912113815/https://theworld.com/~reinhold/dicewarefaq.html#computer) 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.\n\nFor this reason, Python's [random library](https://docs.python.org/3/library/random.html), which produces cryptographically weak pseudo-random numbers, was not utilized in this implementation. Instead, this implementation relies on Python's [secrets library](https://docs.python.org/3/library/secrets.html), specifically designed for generating cryptographically strong random numbers suitable for passwords, account authentication, security tokens, and other sensitive information.\n\n## Credits\n- [Diceware](https://theworld.com/~reinhold/diceware.html) [(archived)](https://web.archive.org/web/20240913072907/https://theworld.com/~reinhold/diceware.html) by Arnold G. Reinhold\n- [EFF Large Word List](https://www.eff.org/document/passphrase-wordlists) by Electronic Frontier Foundation\n- [Mnemonische deutsche Wortliste](https://github.com/dys2p/wordlists-de) by dys2p\n",
"bugtrack_url": null,
"license": null,
"summary": "Minimalist Python library designed for the random selection of words from cryptographic wordlists, utilizing the Diceware method.",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/inwerk/dicewarepy"
},
"split_keywords": [
"dicewarepy",
" diceware",
" dice",
" die",
" passphrase",
" passphrases",
" password",
" passwords"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "36e8c80e506980444a2c7bbebf4e2d368120fde9b825c6c4ea89231577e6d4b4",
"md5": "d38d4aff42bc517daeb20e81f9d2ff17",
"sha256": "16b9a588973072f41e6ca0c1310f7cdc837cb5c33b2c6d11b8ea395f9dccf5f6"
},
"downloads": -1,
"filename": "dicewarepy-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d38d4aff42bc517daeb20e81f9d2ff17",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 101153,
"upload_time": "2024-09-25T20:55:53",
"upload_time_iso_8601": "2024-09-25T20:55:53.476340Z",
"url": "https://files.pythonhosted.org/packages/36/e8/c80e506980444a2c7bbebf4e2d368120fde9b825c6c4ea89231577e6d4b4/dicewarepy-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a822df93bf780c5c86181373e2e8f9d7d7112f75fff9ae147263539223d2afe3",
"md5": "57159a0c4466efc18339809569ea14cc",
"sha256": "82f9ba2161fd74bf01906d6ec386dcbe2631b9b34dd83c1884f83c561b4afbbc"
},
"downloads": -1,
"filename": "dicewarepy-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "57159a0c4466efc18339809569ea14cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 103090,
"upload_time": "2024-09-25T20:55:54",
"upload_time_iso_8601": "2024-09-25T20:55:54.658710Z",
"url": "https://files.pythonhosted.org/packages/a8/22/df93bf780c5c86181373e2e8f9d7d7112f75fff9ae147263539223d2afe3/dicewarepy-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-25 20:55:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "inwerk",
"github_project": "dicewarepy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dicewarepy"
}
JSON
