passwdgen 0.4.0

Description:

passwdgen 0.4.0

passwdgen


Overview
passwdgen is a simple password generation utility with a couple of
powerful extra features (including password entropy calculation and
entropy-based password generation).
Installation
To use passwdgen, you will need to install Python 3.9+.
> pip install passwdgen

If you want passwdgen to be globally accessible, you'll need to
install it with sudo/root privileges:
> sudo pip install passwdgen

Usage
The simplest password generation command you can execute is:
> passwdgen generate
totems-representing-sachem-tarrier

Commands
To find out more detailed help about a particular command, simply
run:
> passwdgen <command> --help

# For example:
> passwdgen generate --help

info
Allows you to calculate the entropy of a particular password. For
example, on UNIX-like systems, you can simply pipe the password into
the info command:
> echo "some-password" | passwdgen info
> cat /path/to/password/file | passwdgen info

If you do not pipe text into passwdgen, it will prompt you to enter
the password on the command line:
> passwdgen info
Please enter the password to check: <type your password here>

For more information on password entropy, please see the section
on Entropy further on in this README.
generate
Generate a password. Two kinds of passwords can be generated:

dictionary-based passwords (the default), or
character-based passwords (see this XKCD
before you choose this mechanism).

Some examples of dictionary-based password generation:
# Generate a dictionary-based password 6 words long
> passwdgen generate -l 6

# Generate a dictionary-based password with minimum entropy 70 bits
> passwdgen generate -m 70

# Generate a dictionary-based password and copy it to the clipboard
> passwdgen generate -c

# Generate a dictionary-based password with colons (:) as a separator
> passwdgen generate -s colon

# Generate a dictionary-based password and display its entropy info
> passwdgen generate -i

# Generate a dictionary-based password based on the given starting letters
> passwdgen generate --starting-letters hello

Some examples of character-based password generation:
# Generate a password 15 characters long comprising numbers and letters
> passwdgen generate -t alpha-numeric -l 15

# Generate a password 18 characters long comprising numbers, letters and
# special characters
> passwdgen generate -t special -l 18

# Generate a password 12 characters long and display its entropy info
> passwdgen generate -t special -l 12 -i

# Generate a character-based password, copy it to the clipboard, and
# display its entropy info
> passwdgen generate -t special -c -i

rng
Runs a quick test of your OS' pseudorandom number generator (PRNG).
Computes a sample set (by default, 1 million entries) of random
numbers between 0 and 100 (inclusive)
For example:
> passwdgen rng
Testing OS RNG. Attempting to generate 1000000 samples between 0 and 100 (inclusive). Please wait...

Statistics
----------
Mean : 49.966455 (should approach 50.000 as the sample size increases; 0.067% difference)
Standard deviation : 29.151161 (should be as close to 29.154759 as possible; 0.012% difference)
Time taken : 2.083 seconds

The expected standard deviation for a random variable with a discrete
uniform random distribution is expected to be calculated as per
this Wikipedia entry.
wordlist
At present, this command has only one sub-command: clean. To take
an arbitrary word list (a text file with one word per line) and
clean it up, do the following:
> passwdgen wordlist clean /path/to/input/file.txt /path/to/output/file.txt

This command will:

remove empty lines,
strip out any plurals ('s at the end of strings),
convert all words to lowercase,
deduplicate entries, and
sort everything alphabetically.

API
Using passwdgen from your own Python project is easy:
import passwdgen

# Generate a dictionary-based password using the built-in dictionary
my_password = passwdgen.words()

# Generate a character-based password
my_password = passwdgen.chars()

# Generate a dictionary-based password with 6 words
long_password = passwdgen.words(word_count=6)

# Generate a dictionary-based password with minimum entropy 80
difficult_password = passwdgen.words(min_entropy=80)

# Generate a dictionary-based password with a custom dictionary
my_dictionary = passwdgen.load_word_list("/path/to/my/dict.txt")
password = passwdgen.words(my_dictionary)

passwdgen.words(dict_set, separator, word_count, min_entropy, starting_letters)
Generates a dictionary-based password. All arguments are keyword
arguments and are optional:

dict_set: A set containing all of the possible words from which to
generate a password. If not supplied, this will default to the
built-in dictionary.
separator: The separator character to use between the words.
Default value: - (hyphen)
word_count: The number of words to use when generating the password.
If not specified, and min_entropy is not specified, this defaults
to 4.
min_entropy: The minimum required entropy of the generated
password. If word_count is specified, this parameter is ignored.
starting_letters: A string containing the desired starting letters
of each word in the generated password. Note: if word_count or
min_entropy are specified, this string must contain at least
the relevant number of characters to match the number of generated
words. Otherwise the generated password will have exactly the same
number of words as this string has characters.

Returns a string.
passwdgen.chars(charset, length, min_entropy)
Generates a character-based password. All arguments are keyword
arguments and are optional:

charset: The ID of the character set from which to source characters
for the generated password. Default: special. See the
section on Character Sets below.
length: The required number of characters in the generated password.
If neither length nor min_entropy are specified, this defaults
to 12.
min_entropy: The minimum required entropy of the generated
password. If length is specified, this parameter is ignored.

Returns a string.
passwdgen.load_word_list(filename, encoding)
Loads a word list into memory. All arguments are keyword arguments
and are optional:

filename: The path to the file from which to load the words. This
file must be a plain text file containing one word per line. If
not specified, this loads the built-in dictionary into memory.
encoding: The character encoding to use when reading the file.

Returns a set containing the loaded words.
passwdgen.secure_random(a, b)
Securely generates a random number using the given limits.

a (required): If b is specified, a represents the lower limit
(inclusive) of the resulting random number. If b is not specified,
a represents the upper limit (exclusive) of the generated number,
and the lower limit defaults to 0.
b (optional): The upper limit (exclusive) of the generated random
number.

Returns a securely generated random number with a <= result < b if
b is specified, or 0 <= result < a if b is not specified.
passwdgen.calculate_entropy(password, dict_set)
Attempts to calculate the entropy of the given password based on
the preconfigured character sets and the dictionary.

password (required): The password whose entropy is to be calculated.
dict_set (optional): A set of words comprising the dictionary
for which to perform the dictionary-based entropy calculation.

Returns a dict whose keys represent the IDs of the different character
sets tested, and values represent the corresponding entropies.
Character Sets
The following character sets are available at present (for use with the
generate --charset <charset> command).

dict: Dictionary-based password generation.
alpha-lower: Lowercase alphabetical letters (a-z).
alpha-upper: Uppercase alphabetical letters (A-Z).
alpha: Alphabetical (a-z, A-Z).
alpha-numeric: Alphanumeric characters (a-z, A-Z, 0-9).
alpha-numeric-spaced: Alphanumeric characters and spaces (a-z,
A-Z, 0-9, ).
numeric: Numeric characters (0-9).
alpha-lower-sep: Lowercase alphabetical letters and separators
(a-z, -_. ,;:).
alpha-upper-sep: Uppercase alphabetical letters and separators
(A-Z, -_. ,;:).
special: Alphanumeric characters and special characters
(a-z, A-Z, 0-9, -_. ,;:!@#$%^&*()+={}[]'\"\\/?<>`~).

Entropy
Entropy, in the context of information theory, provides a convenient
way to quantify the amount of information in a particular set of
data. With regard to password strength, the higher the entropy of
a password, the more difficult it is for an attacker to guess.
From the perspective of the generator, the password strength is measured
by way of the information source. From the perspective of an attacker,
the more information is known about the information source that
generated the password (e.g. the kind of random number generator used,
the character set to which the password belongs), the lower the entropy
of that password.
Secure random number generation
Entropy calculations are based on the assumption that the random number
source is of good quality (see CSPRNG)
and generates uniformly distributed
random numbers. The random number generator (RNG) used in passwd
is provided by the os.urandom() function, which uses /dev/urandom
on POSIX systems and CryptGenRandom() on Windows systems.
Character-based calculation
This password generator uses the following definition for entropy: a
single character c from a character set of size n characters has
an entropy of log2(n) bits (per character). Entropy adds up as the
length of the password increases, i.e. two characters from the character
set of size n will have a combined overall entropy of 2 x log2(n).
For example, if the lowercase alphabet a..z is used as the character
set, it has n=26. Each character would have an entropy of
log2(26) = 4.700439718141093 bits per character. A password string,
therefore, such as mysuperweakpassword of length 19 characters, will
have a total entropy of 19 x log2(26) = 89.31 bits.
As the size of the character set increases, so does the entropy of the
password of a certain length, as an attacker attempting a brute force
attack would have to search a much larger set of possibilities to
find the password.
Dictionary-based calculation
The dictionary-based method of entropy calculation assumes that an
attacker has prior knowledge that the password was generated using a
dictionary of words, and even knows which dictionary was used. This
would obviously be the case if you personally used passwdgen to
generate a dictionary-based password, as all the code and the dictionary
are out in the open.
In this case, instead of assuming a character set (which would mean
a far higher entropy in passwords with 2 or more words), a
dictionary-based attack could be performed much quicker.
For example, the password dog-far-nightly-can is 19 characters long
and makes use of the lowercase alphabet and hyphens (resulting in a
character set of 27 possible characters). This means that a
brute force attacker using the full lowercase alphabet and hyphens
would be faced with a potential password entropy of
19 x log2(27) = 90.34 bits.
If, however, the attacker knows that the password is dictionary-based
and that the words are separated by hyphens, the attacker would only
have to guess the 4 words from the dictionary making up the password.
This results in a potential entropy from the perspective of the
attacker of 4 x log2(275,185) = 72.28 bits (assuming dictionary
size of 275,185 words). This is still a pretty strong password, but
it is still easier to crack than a password where the attacker does not
know that it is dictionary-based.
How much entropy is enough?
So how does one select an appropriate entropy for trying to prevent
brute force attacks? This is difficult to estimate, because it depends
entirely on the resources available to an attacker. Usually it's cheaper
and easier to perform social engineering attacks if someone wants to
obtain your password, but if you're paranoid about security and want to
cover all your bases, you have to think about the kinds of computing
power available to attackers.
Assuming that whichever service stores your password does not store the
clear password itself, but a SHA-256
hash of the password (common practice today), and an attacker manages
to get hold of this SHA-256 hash, they will have to try many possible
permutations of input passwords that will eventually match to that
SHA-256 hash.
In general, GPU-based hash attacks are much faster
than CPU-based hash attacks. At the time of this writing, it would seem
as though high-end GPUs have the ability to perform around 1,000
megahashes per second (that's 1,000,000,000 hashes per second, or
10^9 hashes per second).
Let's assume you generate a dictionary-based password, where the
source dictionary size is 71,188 words. Let's also assume that the
attacker has the same source dictionary, and knows which character you
use to separate the words in your password (in this case, a hyphen).



Words
Permutations
Time to Crack
Entropy




2
5,067,660,156
5.07 seconds
32.24 bits


3
360,746,455,865,016
4.175 days
48.36 bits


4
25,679,736,460,751,163,960
814 years
64.47 bits


5
1,827,986,360,222,110,855,328,640
57,965,067 years
80.6 bits



Of course, if an attacker splits the work up evenly across multiple
GPUs, the time to crack goes down linearly, so a 4-word password being
brute-force cracked by 2 GPUs would take 407 years, 3 GPUs would take
203.5 years, 10 GPUs 81.4 years, 100 GPUs 8.1 years, 1,000 GPUs
would take about 9.5 months, and 10,000 GPUs would take 29.7 days.
So, as you see, it really depends on the resources available to an
attacker. In general though, right now, a password with entropy
80 bits and upwards, from the perspective of an attacker, is pretty
much infeasible to crack (so a 5-word password from a significantly
sized source dictionary and a good quality PRNG). This will, of course,
possibly change in the age of quantum computers.
Dictionary
The included dictionary is a "cleaned out" (see the wordlist clean
command provided by passwdgen) version of a dictionary created
through SCOWL (And Friends), using their
word list generator.
At present, the embedded dictionary contains 71,188 words, ensuring
an entropy of log2(71,188) = 16.119 bits per word.
Legal
Copyright 2000-2014 by Kevin Atkinson

Permission to use, copy, modify, distribute and sell these word
lists, the associated scripts, the output created from the scripts,
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appears in all copies and
that both that copyright notice and this permission notice appear in
supporting documentation. Kevin Atkinson makes no representations
about the suitability of this array for any purpose. It is provided
"as is" without express or implied warranty.

Copyright (c) J Ross Beresford 1993-1999. All Rights Reserved.

The following restriction is placed on the use of this publication:
if The UK Advanced Cryptics Dictionary is used in a software package
or redistributed in any form, the copyright notice must be
prominently displayed and the text of this document must be included
verbatim.
There are no other restrictions: I would like to see the list
distributed as widely as possible.

Many sources were used in the creation of SCOWL, most of them were in
the public domain or used indirectly. For a full list please see the
SCOWL readme.
http://wordlist.aspell.net/
References
The following sources were consulted in building the password generator:

Entropy (information theory) ~ Wikipedia
How should I calculate the entropy of a password? ~ Cryptography StackExchange
How to calculate password entropy
Permutation ~ Wikipedia

License
The MIT License (MIT)
Copyright (c) 2016-2019 Thane Thomson
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.