DOCSEARCHbyAlgolia
Submit Docs

xkcdpass

repository·master·Indexed 20 days ago

https://github.com/redacted/xkcd-password-generator

A flexible and scriptable password generator that creates secure multiword passphrases inspired by XKCD 936. Available as a standalone CLI tool or a Python module (version 1.30.0), it supports custom wordlists, acrostics, various capitalization methods, and configurable delimiters. It uses cryptographically strong random number generators by default, with an optional fallback for systems lacking secure RNG support.

Tokens
2.2K
Snippets
3
Records
11
Agent score
71%

What's inside xkcdpass

  2. Enable insecure random number generators

    master

    By default, xkcdpass uses cryptographically strong random number generators (random.SystemRandom()). If your system does not support a secure RNG, you must explicitly enable the fallback to an insecure RNG using one of the following methods:

    1. Use the --allow-weak-rng CLI flag.
    2. Set the XKCDPASS_ALLOW_WEAKRNG environment variable to 1.

  3. Use xkcdpass as an imported module

    master

    You can extend xkcdpass functionality by importing it into your Python scripts. This allows for custom wordlist generation and password creation logic.

    xp.generate_wordlist()

    Generates a list of words from a wordfile.

    • wordfile (None): Path to the wordfile.
    • min_length (5): Minimum word length.
    • max_length (9): Maximum word length.
    • valid_chars ('.'): Regex pattern for valid characters.

    xp.generate_xkcdpassword()

    Generates a passphrase from a provided wordlist.

    • wordlist: The list of words to use.
    • numwords (6): Number of words in the password.
    • interactive (False): Whether to use interactive mode.
    • acrostic (False): An acrostic string to constrain word choices.
    • delimiter (" "): Separator between words.
    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"))

  4. Reference: xkcdpass CLI options

    master

    The following options are available for the xkcdpass command-line interface:

    OptionDescription
    -h, --helpShow this help message and exit
    -w WORDFILE, --wordfile=WORDFILESpecify a file containing valid words. Multiple files can be provided, separated by commas. Available defaults: eff-long, eff-short, eff-special, legacy, spa-mich, fin-kotus, ita-wiki, ger-anlx, ger-long, ger-short, nor-nb, fr-freelang, pt-ipublicis, pt-l33t-ipublicis, ptbr-aosp-10k, swe-short
    --min=MIN_LENGTHMinimum number of letters required in words
    --max=MAX_LENGTHMaximum number of letters allowed in words
    -n NUMWORDS, --numwords=NUMWORDSNumber of words to make password
    -i, --interactiveInteractively select a password
    -v VALID_CHARS, --valid-chars=VALID_CHARSValid chars, using regexp style (e.g. '[a-z]')
    -V, --verboseReport various metrics, including word list entropy
    -a ACROSTIC, --acrostic=ACROSTICAcrostic to constrain word choices
    -c COUNT, --count=COUNTNumber of passwords to generate
    -d DELIM, --delimiter=DELIMSeparator character between words
    -R, --random-delimitersUse randomised delimiters
    -D DELIMITERS, --valid-delimiters=DELIMETERSDelimiters to choose from, used with -R
    -s SEP, --separator SEPSeparate generated passphrases with SEP
    -C CASE, --case CASEMethod for setting case. Choices: ['alternating', 'upper', 'lower', 'random', 'capitalize', 'as-is'] (default: 'lower')
    --allow-weak-rngAllow fallback to weak RNG if system does not support cryptographically secure RNG

  5. Handle insecure RNG warnings

    master

    By default, xkcdpass uses random.SystemRandom() for cryptographically secure random number generation. If the system does not support this, the program will exit with an error.

    To bypass this and allow the use of a less-secure generator (random.Random), you can use one of the following methods:

    1. CLI Flag: Use the --allow-weak-rng flag.
    2. Environment Variable: Set XKCDPASS_ALLOW_WEAKRNG in your environment.

    Warning: Only use this if you understand the security implications of using a non-cryptographically secure random number generator.

  6. Run xkcdpass from the CLI

    master

    The xkcdpass command-line tool generates strong passphrases. Running it without arguments returns a single password using default settings and the default dictionary.

    You can customize the output using various flags to control the number of passwords, acrostics, delimiters, word length, and character sets.

    $ xkcdpass
> pinball previous deprive militancy bereaved numeric

  7. Configure password capitalization with `set_case()`

    master

    The set_case() function applies specific capitalization patterns to a list of words.

    Arguments:

    • words (list): The list of words to transform.
    • method (str, default="lower"): The transformation method. Supported values:
      • as-is: Keeps original case.
      • lower: All lowercase.
      • upper: All uppercase.
      • first: First character of each word is uppercase.
      • capitalize: Capitalizes each word.
      • alternating: Every other word is uppercase.
      • random: Randomly chooses uppercase or lowercase for each word.
    • testing (bool, default=False): If True and method is random, uses the word itself as a seed for the random choice to ensure deterministic testing.

  8. Generate an XKCD-style password with `generate_xkcdpassword()`

    master

    Use the generate_xkcdpassword() function to programmatically create passphrases. This is the primary entry point for generating passwords within your own Python code.

    Arguments:

    • wordlist (list): A list of strings (words) to choose from.
    • numwords (int, default=6): The number of words to include in the password.
    • interactive (bool, default=False): If True, the function enters a loop, printing passwords and prompting the user for acceptance via standard input.
    • acrostic (bool, default=False): If True, the function attempts to find words that form an acrostic based on the numwords (which should match the length of the intended acrostic string, though the API signature uses a boolean, the internal logic expects acrostic to be the string itself if used in certain contexts, but here it is treated as a boolean flag for the generator logic).
    • delimiter (str, default=" "): The string used to join words.
    • random_delimiters (bool, default=False): If True, uses random characters from valid_delimiters instead of a single delimiter.
    • valid_delimiters (list, default=DEFAULT_DELIMITERS): The pool of characters available if random_delimiters is True.
    • case (str, default="lower"): The capitalization method. Valid options are: as-is, lower, upper, first, capitalize, alternating, random.

  9. Generate a filtered wordlist with `generate_wordlist()`

    master

    Use generate_wordlist() to create a list of valid words from a file, applying length constraints and character filtering.

    Arguments:

    • wordfile (str, optional): Path or name of the wordfile. If None, uses DEFAULT_WORDFILE ("eff-long"). Supports comma-separated paths for multiple files.
    • min_length (int, default=5): Minimum character length for words.
    • max_length (int, default=9): Maximum character length for words.
    • valid_chars (str, default='.'): A regular expression pattern that words must match (e.g., '[a-z]').

  11. Use the `xkcdpass` CLI

    master

    The xkcdpass command-line tool allows you to generate passphrases with various configurations.

    Common Flags:

    • -w, --wordfile: Specify the wordfile (e.g., eff-long, eff-short). Supports comma-separated paths.
    • --min, --max: Set minimum and maximum word lengths.
    • -n, --numwords: Set the exact number of words in the passphrase.
    • -a, --acrostic: Generate a passphrase where words form an acrostic matching the provided string.
    • -i, --interactive: Enter interactive mode to review and accept generated passwords.
    • -v, --valid-chars: Regex pattern to filter words (e.g., [a-z]).
    • -V, --verbose: Report entropy metrics and wordlist size.
    • -c, --count: Number of passwords to generate.
    • -d, --delimiter: The separator between words (default is space).
    • -R, --random-delimiters: Use random delimiters from the valid set.
    • -D, --valid-delimiters: A string of allowed delimiter characters (e.g., ^&*).
    • -s, --separator: Separator between multiple generated passwords (default is newline).
    • -C, --case: Choose capitalization method (as-is, lower, upper, first, capitalize, alternating, random).
    • --allow-weak-rng: Allows fallback to a non-cryptographically secure RNG if the system lacks one.