README.rst

   1 xkcdpass
   2 ========
   3
   4 .. image:: https://badges.gitter.im/Join%20Chat.svg
   5    :alt: Join the chat at https://gitter.im/redacted/XKCD-password-generator
   6    :target: https://gitter.im/redacted/XKCD-password-generator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
   7
   8 A flexible and scriptable password generator which generates strong passphrases, inspired by `XKCD 936 <http://xkcd.com/936/>`_::
   9
  10     $ xkcdpass
  11     > correct horse battery staple
  12
  13 .. image:: http://imgs.xkcd.com/comics/password_strength.png
  14
  15
  16
  17 Install
  18 =======
  19
  20 ``xkcdpass`` can be easily installed using pip::
  21
  22     pip install xkcdpass
  23
  24 or manually::
  25
  26     python setup.py install
  27
  28
  29
  30 Source
  31 ~~~~~~
  32 The latest development version can be found on github: https://github.com/redacted/XKCD-password-generator
  33
  34 Contributions welcome and gratefully appreciated!
  35
  36
  37
  38 Requirements
  39 ============
  40
  41 Python 2 (version 2.7 or later), or Python 3 (version 3.2 or later).
  42
  43
  44
  45 Running ``xkcdpass``
  46 ====================
  47
  48 ``xkcdpass`` can be called with no arguments::
  49
  50     $ xkcdpass
  51     > pinball previous deprive militancy bereaved numeric
  52
  53 which returns a single password, using the default dictionary and default settings. Or you can mix whatever arguments you want::
  54
  55     $ xkcdpass --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid_chars='[a-z]'
  56     > collar|highly|asset|ovoid|sultan
  57     > caper|hangup|addle|oboist|scroll
  58     > couple|honcho|abbot|obtain|simple
  59     > cutler|hotly|aortae|outset|stool
  60     > cradle|helot|axial|ordure|shale
  61
  62 which returns
  63
  64 * ``--count=5``   5 passwords to choose from
  65 * ``--acrostic='chaos'``   the first letters of which spell 'chaos'
  66 * ``--delimiter='|'``   joined using '|'
  67 * ``--min=5 --max=6``  with words between 5 and 6 characters long
  68 * ``--valid-chars='[a-z]'``   using only lower-case letters (via regex).
  69
  70
  71 A concise overview of the available ``xkcdpass`` options can be accessed via::
  72
  73     xkcdpass --help
  74
  75     Usage: xkcdpass [options]
  76
  77     Options:
  78         -h, --help
  79                                     show this help message and exit
  80         -w WORDFILE, --wordfile=WORDFILE
  81                                     List of valid words for password
  82         --min=MIN_LENGTH
  83                                     Minimum length of words to make password
  84         --max=MAX_LENGTH
  85                                     Maximum length of words to make password
  86         -n NUMWORDS, --numwords=NUMWORDS
  87                                     Number of words to make password
  88         -i, --interactive
  89                                     Interactively select a password
  90         -v VALID_CHARS, --valid-chars=VALID_CHARS
  91                                     Valid chars, using regexp style (e.g. '[a-z]')
  92         -V, --verbose
  93                                     Report various metrics for given options, including word list entropy
  94         -a ACROSTIC, --acrostic=ACROSTIC
  95                                     Acrostic to constrain word choices
  96         -c COUNT, --count=COUNT
  97                                     number of passwords to generate
  98         -d DELIM, --delimiter=DELIM
  99                                     separator character between words
 100
 101
 102 A large wordlist is provided for convenience, but the generator can be used with any word file of the correct format: a file containing one 'word' per line. The default word file can be found in ``xkcdpass/static/default.txt``.
 103
 104 The default 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
 105 http://wordlist.aspell.net/12dicts/ contains the following dedication:
 106
 107 ..
 108
 109     The 12dicts lists were compiled by Alan Beale. I explicitly release them to the public domain, but request acknowledgment of their use.
 110
 111
 112 Using xkcdpass as an imported module
 113 ====================================
 114
 115 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.
 116
 117 A simple use of import::
 118
 119     from xkcdpass import xkcd_password as xp
 120
 121     # create a wordlist from the default wordfile
 122     # use words between 5 and 8 letters long
 123     wordfile = xp.locate_wordfile()
 124     mywords = xp.generate_wordlist(wordfile=wordfile, min_length=5, max_length=8)
 125
 126     # create a password with the acrostic "face"
 127     print(xp.generate_xkcdpassword(mywords, acrostic="face"))
 128
 129 When used as an imported module, `generate_wordlist()` takes the following args (defaults shown)::
 130
 131     wordfile=None,
 132     min_length=5,
 133     max_length=9,
 134     valid_chars='.'
 135
 136 While `generate_xkcdpassword()` takes::
 137
 138     wordlist,
 139     numwords=6,
 140     interactive=False,
 141     acrostic=False,
 142     delimiter=" "
 143
 144
 145 Insecure random number generators
 146 =================================
 147 `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::
 148
 149     xkcdpass --allow-weak-rng
 150
 151 or setting the appropriate environment variable::
 152
 153     export XKCDPASS_ALLOW_WEAKRNG=1
 154
 155
 156 Filtered word list
 157 ===================
 158 While we recommend the standard word list for most purposes, we note that this list is uncensored and, as such, generated passwords could offend. For this reason, `a filtered word list can be found in the github repo <https://github.com/redacted/XKCD-password-generator/tree/master/contrib/office-safe.txt>`_ (filtered by Twig Nyugen and included here with permission).
 159
 160 An important caveat: due to the significant reduction in the size of the filtered word list when compared to the default, the strength of the corresponding passwords is also reduced. Users should expect approximately an *order of magnitude* reduction in the strength of a five word passphrase. This can be mitigated by increasing the length of generated passphrases.
 161
 162
 163 Changelog
 164 =========
 165 - **1.9.0** Improvements to interactive mode
 166 - **1.8.2** `generate_wordlist` behaviour didn't match doctring, fixed
 167 - **1.8.1** Fix typo in validation function
 168 - **1.8.0** Fix error in wordfile argument handling
 169 - **1.7.0** require explicit permission to fall back to insecure PRNG
 170 - **1.6.4** fix broken link in README
 171 - **1.6.3** ensure deduplication of wordlist
 172 - **1.6.2** move contributors to stand-alone CONTRIBUTORS file
 173 - **1.6.0** rename `--valid_chars` to `--valid-chars` for consistency
 174 - **1.5.0** migrate from deprecated `optparse` to `argparse`. Users on older python versions (below 2.7 or 3.2) will need to manually install `argparse`.
 175
 176
 177 License
 178 =======
 179 This is free software: you may copy, modify, and/or distribute this work under the terms of the BSD 3-Clause license.
 180 See the file ``LICENSE.BSD`` for details.
 181 -