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.4+ (Python 3.x compatible)
  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
  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/xkcdpass/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 License
 145 =======
 146 This is free software: you may copy, modify, and/or distribute this work under the terms of the BSD 3-Clause license.
 147 See the file ``LICENSE.BSD`` for details.
 148 -