# `passlib.pwd` – Password generation helpers

Added in version 1.7.

## Password Generation

Warning

Before using these routines, make sure your system’s RNG entropy pool is secure and full. Also make sure that `genword()` or `genphrase()` is called with a sufficiently high `entropy` parameter the intended purpose of the password.

passlib.pwd.genword(entropy=None, length=None, charset='ascii_62', chars=None, returns=None)

  Generate one or more random passwords.

  This function uses `random.SystemRandom` to generate one or more passwords using various character sets. The complexity of the password can be specified by size, or by the desired amount of entropy.

  Usage Example:

      >>> # generate a random alphanumeric string with 48 bits of entropy (the default)
      >>> from passlib import pwd
      >>> pwd.genword()
      'DnBHvDjMK6'

      >>> # generate a random hexadecimal string with 52 bits of entropy
      >>> pwd.genword(entropy=52, charset="hex")
      '310f1a7ac793f'

  Parameters:

    - entropy –

      Strength of resulting password, measured in ‘guessing entropy’ bits. An appropriate length value will be calculated based on the requested entropy amount, and the size of the character set.

      This can be a positive integer, or one of the following preset strings: `"weak"` (24), `"fair"` (36), `"strong"` (48), and `"secure"` (56).

      If neither this or length is specified, entropy will default to `"strong"` (48).

    - length –

      Size of resulting password, measured in characters. If omitted, the size is auto-calculated based on the entropy parameter.

      If both entropy and length are specified, the stronger value will be used.

    - returns –

      Controls what this function returns:

      - If `None` (the default), this function will generate a single password.

      - If an integer, this function will return a list containing that many passwords.

      - If the `iter` constant, will return an iterator that yields passwords.

    - chars – Optionally specify custom string of characters to use when randomly generating a password. This option cannot be combined with charset.

    - charset –

      The predefined character set to draw from (if not specified by chars). There are currently four presets available:

      - `"ascii_62"` (the default) – all digits and ascii upper & lowercase letters. Provides ~5.95 entropy per character.

      - `"ascii_50"` – subset which excludes visually similar characters (`1IiLl0Oo5S8B`). Provides ~5.64 entropy per character.

      - `"ascii_72"` – all digits and ascii upper & lowercase letters, as well as some punctuation. Provides ~6.17 entropy per character.

      - `"hex"` – Lower case hexadecimal. Providers 4 bits of entropy per character.

  Returns:

    `str` string containing randomly generated password; or list of 1+ passwords if `returns=int` is specified.

passlib.pwd.genphrase(entropy=None, length=None, wordset='eff_long', words=None, sep=' ', returns=None)

  Generate one or more random password / passphrases.

  This function uses `random.SystemRandom` to generate one or more passwords; it can be configured to generate alphanumeric passwords, or full english phrases. The complexity of the password can be specified by size, or by the desired amount of entropy.

  Usage Example:

      >>> # generate random phrase with 48 bits of entropy
      >>> from passlib import pwd
      >>> pwd.genphrase()
      'gangly robbing salt shove'

      >>> # generate a random phrase with 52 bits of entropy
      >>> # using a particular wordset
      >>> pwd.genword(entropy=52, wordset="bip39")
      'wheat dilemma reward rescue diary'

  Parameters:

    - entropy –

      Strength of resulting password, measured in ‘guessing entropy’ bits. An appropriate length value will be calculated based on the requested entropy amount, and the size of the word set.

      This can be a positive integer, or one of the following preset strings: `"weak"` (24), `"fair"` (36), `"strong"` (48), and `"secure"` (56).

      If neither this or length is specified, entropy will default to `"strong"` (48).

    - length –

      Length of resulting password, measured in words. If omitted, the size is auto-calculated based on the entropy parameter.

      If both entropy and length are specified, the stronger value will be used.

    - returns –

      Controls what this function returns:

      - If `None` (the default), this function will generate a single password.

      - If an integer, this function will return a list containing that many passwords.

      - If the `iter` builtin, will return an iterator that yields passwords.

    - words – Optionally specifies a list/set of words to use when randomly generating a passphrase. This option cannot be combined with wordset.

    - wordset –

      The predefined word set to draw from (if not specified by words). There are currently four presets available:

      `"eff_long"` (the default)

      > Wordset containing 7776 english words of ~7 letters. Constructed by the EFF, it offers ~12.9 bits of entropy per word.

      > This wordset (and the other `"eff_"` wordsets) were created by the EFF to aid in generating passwords. See their announcement page for more details about the design & properties of these wordsets.

      `"eff_short"`

      > Wordset containing 1296 english words of ~4.5 letters. Constructed by the EFF, it offers ~10.3 bits of entropy per word.

      `"eff_prefixed"`

      > Wordset containing 1296 english words of ~8 letters, selected so that they each have a unique 3-character prefix. Constructed by the EFF, it offers ~10.3 bits of entropy per word.

      `"bip39"`

      > Wordset of 2048 english words of ~5 letters, selected so that they each have a unique 4-character prefix. Published as part of Bitcoin’s BIP 39, this wordset has exactly 11 bits of entropy per word.

      > This list offers words that are typically shorter than `"eff_long"` (at the cost of slightly less entropy); and much shorter than `"eff_prefixed"` (at the cost of a longer unique prefix).

    - sep – Optional separator to use when joining words. Defaults to `" "` (a space), but can be an empty string, a hyphen, etc.

  Returns:

    `str` containing randomly generated passphrase; or list of 1+ passphrases if `returns=int` is specified.

## Predefined Symbol Sets

The following predefined sets are used by the generation functions above, but are exported by this module for general use:

default_charsets

  Dictionary mapping charset name -> string of characters, used by `genword()`. See that function for a list of predefined charsets present in this dict.

default_wordsets

  Dictionary mapping wordset name -> tuple of words, used by `genphrase()`. See that function for a list of predefined wordsets present in this dict.

  (Note that this is actually a special object which will lazy-load wordsets from disk on-demand)

## Password Strength Estimation

Passlib does not currently offer any password strength estimation routines. However, the (javascript-based) zxcvbn project is a very good choice.

Though there are a few different python ports of ZXCVBN library, as of 2019-11-13, zxcvbn (@ pypi) is the most up-to-date, and is endorsed by the upstream zxcvbn developers.