The Passlib documentation has moved to https://passlib.readthedocs.io

passlib.pwd – Password generation helpers

New 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:

unicode 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:

unicode string 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 current offer any password strength estimation routines. However, the (javascript-based) zxcvbn project is a very good choice. There are a few python ports of ZCVBN library, though as of 2016-11, none of them seem active and up to date.

The following is a list of known ZCVBN python ports, though it’s not clear which of these is active and/or official: