xkcdpass
========
.. image:: https://badges.gitter.im/Join%20Chat.svg
:alt: Join the chat at https://gitter.im/redacted/XKCD-password-generator
:target: https://gitter.im/redacted/XKCD-password-generator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
A flexible and scriptable password generator which generates strong passphrases, inspired by `XKCD 936 <http://xkcd.com/936/>`_::
$ xkcdpass
> correct horse battery staple
.. image:: http://imgs.xkcd.com/comics/password_strength.png
Install
=======
``xkcdpass`` can be easily installed using pip::
pip install xkcdpass
or manually::
python setup.py install
Source
~~~~~~
The latest development version can be found on github: https://github.com/redacted/XKCD-password-generator
Contributions welcome and gratefully appreciated!
Requirements
============
Python 2 (version 2.7 or later), or Python 3 (version 3.4 or later). Running module unit tests on Python 2 requires ``mock`` to be installed.
Running ``xkcdpass``
====================
``xkcdpass`` can be called with no arguments::
$ xkcdpass
> pinball previous deprive militancy bereaved numeric
which returns a single password, using the default dictionary and default settings. Or you can mix whatever arguments you want::
$ xkcdpass --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid-chars='[a-z]'
> collar|highly|asset|ovoid|sultan
> caper|hangup|addle|oboist|scroll
> couple|honcho|abbot|obtain|simple
> cutler|hotly|aortae|outset|stool
> cradle|helot|axial|ordure|shale
which returns
* ``--count=5`` 5 passwords to choose from
* ``--acrostic='chaos'`` the first letters of which spell 'chaos'
* ``--delimiter='|'`` joined using '|'
* ``--min=5 --max=6`` with words between 5 and 6 characters long
* ``--valid-chars='[a-z]'`` using only lower-case letters (via regex).
A concise overview of the available ``xkcdpass`` options can be accessed via::
xkcdpass --help
Usage: xkcdpass [options]
Options:
-h, --help
show this help message and exit
-w WORDFILE, --wordfile=WORDFILE
Specify that the file WORDFILE contains the list of
valid words from which to generate passphrases. Multiple
wordfiles can be provided, separated by commas.
Provided wordfiles: eff-long (default), eff-short,
eff-special, legacy, spa-mich (Spanish), fin-kotus (Finnish)
ita-wiki (Italian), ger-anlx (German), nor-nb (Norwegian),
fr-freelang (French), pt-ipublicis / pt-l33t-ipublicis (Portuguese)
swe-short (Swedish)
--min=MIN_LENGTH
Minimum length of words to make password
--max=MAX_LENGTH
Maximum length of words to make password
-n NUMWORDS, --numwords=NUMWORDS
Number of words to make password
-i, --interactive
Interactively select a password
-v VALID_CHARS, --valid-chars=VALID_CHARS
Valid chars, using regexp style (e.g. '[a-z]')
-V, --verbose
Report various metrics for given options, including word list entropy
-a ACROSTIC, --acrostic=ACROSTIC
Acrostic to constrain word choices
-c COUNT, --count=COUNT
number of passwords to generate
-d DELIM, --delimiter=DELIM
separator character between words
-R, --random-delimiters
use randomised delimiters
-D DELIMITERS, --valid-delimiters=DELIMETERS
delimeters to choose from, used with -
-s SEP, --separator SEP
Separate generated passphrases with SEP.
-C CASE, --case CASE
Choose the method for setting the case of each word in
the passphrase. Choices: ['alternating', 'upper',
'lower', 'random', 'capitalize', 'as-is'] (default: 'lower').
--allow-weak-rng
Allow fallback to weak RNG if the system does not
support cryptographically secure RNG. Only use this if
you know what you are doing.
Word lists
==========
Several word lists are provided with the package. The default, `eff-long`, was specifically designed by the EFF for `passphrase generation <https://www.eff.org/deeplinks/2016/07/new-wordlists-random-passphrases>`_ and is licensed under `CC BY 3.0 <https://creativecommons.org/licenses/by/3.0/us/>`_. As it was originally intended for use with Diceware ensure that the number of words in your passphrase is at least six when using it. Two shorter variants of that list, `eff-short` and `eff-special`, are also included. Please refer to the EFF documentation linked above for more information.
The original word list from `xkcdpass` versions earlier than 1.10.0 is also provided as a convenience, and is available under `legacy`. This word list is derived mechanically from `12Dicts <http://wordlist.aspell.net/12dicts/>`_ by Alan Beale. It is the understanding of the author of ``xkcdpass`` that purely mechanical transformation does not imbue copyright in the resulting work. The documentation for the 12Dicts project at
http://wordlist.aspell.net/12dicts/ contains the following dedication:
..
The 12dicts lists were compiled by Alan Beale. I explicitly release them to the public domain, but request acknowledgment of their use.
Note that the generator can be used with any word file of the correct format: a file containing one 'word' per line.
Additional languages
~~~~~~~~~~~~~~~~~~~~
- Spanish: a modifed version of archive.umich.edu in the `/linguistics` directory. It includes ~80k words. Less than 5 char. and latin-like words were deleted using regex. This list is public domain, see `here <http://www.umich.edu/~archive/linguistics/00readme.txt>`_.
- Finnish: a modified version of the Institute for the Languages of Finland `XML word list <http://kaino.kotus.fi/sanat/nykysuomi/>`_. Profanities and expressions containing spaces were removed using regex. The resulting list contains ~93k words. The list is published under GNU LGPL, EUPL 1.1 and CC-BY 3.0 licenses.
- Italian: generated from dumps of the Italian-language Wikipedia, which is released under the Creative Commons Attribution-Share-Alike 3.0 licence.
- German (ger-anlx): based on `this GPL v3 list <https://github.com/dassencio/langcmp/blob/master/wordlists/top10000de.txt>`_. Single and double character words have been removed.
- German (eff_large_de_sample.wordlist): based on `this public domain dictionary <https://sourceforge.net/projects/germandict/>`_. Converted to UTF-8 and randomly sampled to reduce file size.
- Norwegian: a modified version of `Norsk Ordbank in Norwegian Bokmål 2005 <https://www.nb.no/sprakbanken/show?serial=oai%3Anb.no%3Asbr-5&lang=en>`_, 2018-06-28 update, which is released under the `CC-BY 4.0 license <https://creativecommons.org/licenses/by/4.0/>`_. Regex has been used to alter the list for cleanup and removal of words with impractical characters. The resulting list contains ~137k words.
- French: One cleaned version of `this list <https://packetstormsecurity.com/files/download/32007/french.gz>`_ (public domain), and one filtered to remove potentially offensive words.
- Portuguese: Converted variant of the LibreOffice / Firefox Portuguese dictionary (from `this link <https://raw.githubusercontent.com/titoBouzout/Dictionaries/master/Portuguese%20(European).dic>`_. GPL and BSD licenced.
- Swedish: a modified version of `Martin Lindhe's Swedish word list <https://github.com/martinlindhe/wordlist_swedish>`_ (MIT license). Modifications also released under MIT license.
Additional language word lists are always welcome!
Using xkcdpass as an imported module
====================================
The built-in functionality of ``xkcdpass`` can be extended by importing the module into python scripts. An example of this usage is provided in `example_import.py <https://github.com/redacted/XKCD-password-generator/blob/master/examples/example_import.py>`_, which randomly capitalises the letters in a generated password. `example_json.py` demonstrates integration of xkcdpass into a Django project, generating password suggestions as JSON to be consumed by a Javascript front-end.
A simple use of import::
from xkcdpass import xkcd_password as xp
# create a wordlist from the default wordfile
# use words between 5 and 8 letters long
wordfile = xp.locate_wordfile()
mywords = xp.generate_wordlist(wordfile=wordfile, min_length=5, max_length=8)
# create a password with the acrostic "face"
print(xp.generate_xkcdpassword(mywords, acrostic="face"))
When used as an imported module, `generate_wordlist()` takes the following args (defaults shown)::
wordfile=None,
min_length=5,
max_length=9,
valid_chars='.'
While `generate_xkcdpassword()` takes::
wordlist,
numwords=6,
interactive=False,
acrostic=False,
delimiter=" "
Insecure random number generators
=================================
`xkcdpass` uses crytographically strong random number generators where possible (provided by `random.SystemRandom()` on most modern operating systems). From version 1.7.0 falling back to an insecure RNG must be explicitly enabled, either by using a new command line variable before running the script::
xkcdpass --allow-weak-rng
or setting the appropriate environment variable::
export XKCDPASS_ALLOW_WEAKRNG=1
Changelog
=========
- **1.19.9** Remove usage of deprecated `assertEquals` in tests
- **1.19.8** Enables `python -m xkcdpass` usage
- **1.19.7** Adds Swedish wordlist, improvements to test suite, improvements to setup.py (excludes examples from install)
- **1.19.6** Fixes randomly failing unit test
- **1.19.5** Adds "as-is" option for case
- **1.19.4** Makes randomised delimiters behavior consistent with fixed delimeters
- **1.19.3** Restore a randomly sampled version of eff_large_de wordlist
- **1.19.2** Reduction in install size
- **1.19.1** Improvements to help text, handle rare case where arguments lead to empty wordlist
- **1.19.0** Initial support for multiple wordfiles
- **1.18.2** fixes for README
- **1.18.0** Added randomised delimiters
- **1.17.6** Bugfixes
- **1.17.5** Bugfixes
- **1.17.4** Improvements to French dictionary
- **1.17.3** Updated license and supported versions
- **1.17.2** Compatibility fix for 2.x/3.x
- **1.17.1** Fix issue with README and unicode encoding
- **1.17.0** Add French, Norwegian, and Portuguese dictionaries. Bugfixes and improvements to tests (WIP).
License
=======
This is free software: you may copy, modify, and/or distribute this work under the terms of the BSD 3-Clause license.
See the file ``LICENSE.BSD`` for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/redacted/XKCD-password-generator",
"name": "xkcdpass",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Steven Tobin",
"author_email": "steventtobin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/31/f8/14f147b1c7407ce70000ccd1819295c5d3c328d8ebed0840bb461ba71655/xkcdpass-1.19.9.tar.gz",
"platform": null,
"description": "xkcdpass\n========\n\n.. image:: https://badges.gitter.im/Join%20Chat.svg\n :alt: Join the chat at https://gitter.im/redacted/XKCD-password-generator\n :target: https://gitter.im/redacted/XKCD-password-generator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n\nA flexible and scriptable password generator which generates strong passphrases, inspired by `XKCD 936 <http://xkcd.com/936/>`_::\n\n $ xkcdpass\n > correct horse battery staple\n\n.. image:: http://imgs.xkcd.com/comics/password_strength.png\n\n\n\nInstall\n=======\n\n``xkcdpass`` can be easily installed using pip::\n\n pip install xkcdpass\n\nor manually::\n\n python setup.py install\n\n\n\nSource\n~~~~~~\nThe latest development version can be found on github: https://github.com/redacted/XKCD-password-generator\n\nContributions welcome and gratefully appreciated!\n\n\n\nRequirements\n============\n\nPython 2 (version 2.7 or later), or Python 3 (version 3.4 or later). Running module unit tests on Python 2 requires ``mock`` to be installed.\n\n\n\nRunning ``xkcdpass``\n====================\n\n``xkcdpass`` can be called with no arguments::\n\n $ xkcdpass\n > pinball previous deprive militancy bereaved numeric\n\nwhich returns a single password, using the default dictionary and default settings. Or you can mix whatever arguments you want::\n\n $ xkcdpass --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid-chars='[a-z]'\n > collar|highly|asset|ovoid|sultan\n > caper|hangup|addle|oboist|scroll\n > couple|honcho|abbot|obtain|simple\n > cutler|hotly|aortae|outset|stool\n > cradle|helot|axial|ordure|shale\n\nwhich returns\n\n* ``--count=5`` 5 passwords to choose from\n* ``--acrostic='chaos'`` the first letters of which spell 'chaos'\n* ``--delimiter='|'`` joined using '|'\n* ``--min=5 --max=6`` with words between 5 and 6 characters long\n* ``--valid-chars='[a-z]'`` using only lower-case letters (via regex).\n\n\nA concise overview of the available ``xkcdpass`` options can be accessed via::\n\n xkcdpass --help\n\n Usage: xkcdpass [options]\n\n Options:\n -h, --help\n show this help message and exit\n -w WORDFILE, --wordfile=WORDFILE\n Specify that the file WORDFILE contains the list of\n valid words from which to generate passphrases. Multiple \n wordfiles can be provided, separated by commas.\n Provided wordfiles: eff-long (default), eff-short,\n eff-special, legacy, spa-mich (Spanish), fin-kotus (Finnish)\n ita-wiki (Italian), ger-anlx (German), nor-nb (Norwegian),\n fr-freelang (French), pt-ipublicis / pt-l33t-ipublicis (Portuguese)\n swe-short (Swedish)\n --min=MIN_LENGTH\n Minimum length of words to make password\n --max=MAX_LENGTH\n Maximum length of words to make password\n -n NUMWORDS, --numwords=NUMWORDS\n Number of words to make password\n -i, --interactive\n Interactively select a password\n -v VALID_CHARS, --valid-chars=VALID_CHARS\n Valid chars, using regexp style (e.g. '[a-z]')\n -V, --verbose\n Report various metrics for given options, including word list entropy\n -a ACROSTIC, --acrostic=ACROSTIC\n Acrostic to constrain word choices\n -c COUNT, --count=COUNT\n number of passwords to generate\n -d DELIM, --delimiter=DELIM\n separator character between words\n -R, --random-delimiters\n use randomised delimiters\n -D DELIMITERS, --valid-delimiters=DELIMETERS\n delimeters to choose from, used with -\n -s SEP, --separator SEP\n Separate generated passphrases with SEP.\n -C CASE, --case CASE \n Choose the method for setting the case of each word in\n the passphrase. Choices: ['alternating', 'upper',\n 'lower', 'random', 'capitalize', 'as-is'] (default: 'lower').\n --allow-weak-rng \n Allow fallback to weak RNG if the system does not\n support cryptographically secure RNG. Only use this if\n you know what you are doing.\n\n\nWord lists\n==========\n\nSeveral word lists are provided with the package. The default, `eff-long`, was specifically designed by the EFF for `passphrase generation <https://www.eff.org/deeplinks/2016/07/new-wordlists-random-passphrases>`_ and is licensed under `CC BY 3.0 <https://creativecommons.org/licenses/by/3.0/us/>`_. As it was originally intended for use with Diceware ensure that the number of words in your passphrase is at least six when using it. Two shorter variants of that list, `eff-short` and `eff-special`, are also included. Please refer to the EFF documentation linked above for more information.\n\nThe original word list from `xkcdpass` versions earlier than 1.10.0 is also provided as a convenience, and is available under `legacy`. This word list is derived mechanically from `12Dicts <http://wordlist.aspell.net/12dicts/>`_ by Alan Beale. It is the understanding of the author of ``xkcdpass`` that purely mechanical transformation does not imbue copyright in the resulting work. The documentation for the 12Dicts project at\nhttp://wordlist.aspell.net/12dicts/ contains the following dedication:\n\n..\n\n The 12dicts lists were compiled by Alan Beale. I explicitly release them to the public domain, but request acknowledgment of their use.\n\nNote that the generator can be used with any word file of the correct format: a file containing one 'word' per line. \n\nAdditional languages\n~~~~~~~~~~~~~~~~~~~~\n\n- Spanish: a modifed version of archive.umich.edu in the `/linguistics` directory. It includes ~80k words. Less than 5 char. and latin-like words were deleted using regex. This list is public domain, see `here <http://www.umich.edu/~archive/linguistics/00readme.txt>`_.\n- Finnish: a modified version of the Institute for the Languages of Finland `XML word list <http://kaino.kotus.fi/sanat/nykysuomi/>`_. Profanities and expressions containing spaces were removed using regex. The resulting list contains ~93k words. The list is published under GNU LGPL, EUPL 1.1 and CC-BY 3.0 licenses.\n- Italian: generated from dumps of the Italian-language Wikipedia, which is released under the Creative Commons Attribution-Share-Alike 3.0 licence.\n- German (ger-anlx): based on `this GPL v3 list <https://github.com/dassencio/langcmp/blob/master/wordlists/top10000de.txt>`_. Single and double character words have been removed.\n- German (eff_large_de_sample.wordlist): based on `this public domain dictionary <https://sourceforge.net/projects/germandict/>`_. Converted to UTF-8 and randomly sampled to reduce file size. \n- Norwegian: a modified version of `Norsk Ordbank in Norwegian Bokm\u00e5l 2005 <https://www.nb.no/sprakbanken/show?serial=oai%3Anb.no%3Asbr-5&lang=en>`_, 2018-06-28 update, which is released under the `CC-BY 4.0 license <https://creativecommons.org/licenses/by/4.0/>`_. Regex has been used to alter the list for cleanup and removal of words with impractical characters. The resulting list contains ~137k words.\n- French: One cleaned version of `this list <https://packetstormsecurity.com/files/download/32007/french.gz>`_ (public domain), and one filtered to remove potentially offensive words.\n- Portuguese: Converted variant of the LibreOffice / Firefox Portuguese dictionary (from `this link <https://raw.githubusercontent.com/titoBouzout/Dictionaries/master/Portuguese%20(European).dic>`_. GPL and BSD licenced.\n- Swedish: a modified version of `Martin Lindhe's Swedish word list <https://github.com/martinlindhe/wordlist_swedish>`_ (MIT license). Modifications also released under MIT license.\n\nAdditional language word lists are always welcome!\n\nUsing xkcdpass as an imported module\n====================================\n\nThe built-in functionality of ``xkcdpass`` can be extended by importing the module into python scripts. An example of this usage is provided in `example_import.py <https://github.com/redacted/XKCD-password-generator/blob/master/examples/example_import.py>`_, which randomly capitalises the letters in a generated password. `example_json.py` demonstrates integration of xkcdpass into a Django project, generating password suggestions as JSON to be consumed by a Javascript front-end.\n\nA simple use of import::\n\n from xkcdpass import xkcd_password as xp\n\n # create a wordlist from the default wordfile\n # use words between 5 and 8 letters long\n wordfile = xp.locate_wordfile()\n mywords = xp.generate_wordlist(wordfile=wordfile, min_length=5, max_length=8)\n\n # create a password with the acrostic \"face\"\n print(xp.generate_xkcdpassword(mywords, acrostic=\"face\"))\n\nWhen used as an imported module, `generate_wordlist()` takes the following args (defaults shown)::\n\n wordfile=None,\n min_length=5,\n max_length=9,\n valid_chars='.'\n\nWhile `generate_xkcdpassword()` takes::\n\n wordlist,\n numwords=6,\n interactive=False,\n acrostic=False,\n delimiter=\" \"\n\n\nInsecure random number generators\n=================================\n`xkcdpass` uses crytographically strong random number generators where possible (provided by `random.SystemRandom()` on most modern operating systems). From version 1.7.0 falling back to an insecure RNG must be explicitly enabled, either by using a new command line variable before running the script::\n\n xkcdpass --allow-weak-rng\n\nor setting the appropriate environment variable::\n\n export XKCDPASS_ALLOW_WEAKRNG=1\n\n\nChangelog\n=========\n- **1.19.9** Remove usage of deprecated `assertEquals` in tests\n- **1.19.8** Enables `python -m xkcdpass` usage\n- **1.19.7** Adds Swedish wordlist, improvements to test suite, improvements to setup.py (excludes examples from install) \n- **1.19.6** Fixes randomly failing unit test\n- **1.19.5** Adds \"as-is\" option for case\n- **1.19.4** Makes randomised delimiters behavior consistent with fixed delimeters\n- **1.19.3** Restore a randomly sampled version of eff_large_de wordlist \n- **1.19.2** Reduction in install size\n- **1.19.1** Improvements to help text, handle rare case where arguments lead to empty wordlist\n- **1.19.0** Initial support for multiple wordfiles\n- **1.18.2** fixes for README\n- **1.18.0** Added randomised delimiters\n- **1.17.6** Bugfixes\n- **1.17.5** Bugfixes\n- **1.17.4** Improvements to French dictionary\n- **1.17.3** Updated license and supported versions\n- **1.17.2** Compatibility fix for 2.x/3.x \n- **1.17.1** Fix issue with README and unicode encoding\n- **1.17.0** Add French, Norwegian, and Portuguese dictionaries. Bugfixes and improvements to tests (WIP).\n\nLicense\n=======\nThis is free software: you may copy, modify, and/or distribute this work under the terms of the BSD 3-Clause license.\nSee the file ``LICENSE.BSD`` for details.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Generate secure multiword passwords/passphrases, inspired by XKCD",
"version": "1.19.9",
"project_urls": {
"Homepage": "https://github.com/redacted/XKCD-password-generator"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31f814f147b1c7407ce70000ccd1819295c5d3c328d8ebed0840bb461ba71655",
"md5": "aeb8b2477355ad4c62de8b29596ebb8a",
"sha256": "a94f871bda870668e5c65eb84296e939600362df2cc036b91c5ca3815bd292d7"
},
"downloads": -1,
"filename": "xkcdpass-1.19.9.tar.gz",
"has_sig": false,
"md5_digest": "aeb8b2477355ad4c62de8b29596ebb8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2689919,
"upload_time": "2024-04-01T13:50:43",
"upload_time_iso_8601": "2024-04-01T13:50:43.499033Z",
"url": "https://files.pythonhosted.org/packages/31/f8/14f147b1c7407ce70000ccd1819295c5d3c328d8ebed0840bb461ba71655/xkcdpass-1.19.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-01 13:50:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "redacted",
"github_project": "XKCD-password-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xkcdpass"
}
JSON
