Package: passutil
Python Password UtilityCryptographically secure, easy-to-use, password generatorMost password generators written in Python make use of Python's
secrets module to generate random values.Python Password Utilitygoes a step further: it chains together
a keyed version of the SHA-512 (or SHA3-512) hash function
to create a password which is computationally infeasible to guess, even for someone
who knows the internal state of the secrets module.Python Password Utilitycan berun directly from the command line,
orcalled through a Python API.This software requires Python 3.6 or later.
Major versions of Python after Python 3 are not supported.IndexDescriptionInstallationRunning from the Command LineCharacter SetsAdvanced Examples of Character SetsGetting the Size of a Character SetDetermining which Hashing Algorithm is being usedCalling from Pythongenerate_passwordcharset_sizeSHA512_numberDescriptionThe algorithm operates in a loop; at each iteration of the loop one character
is added to the password. The program takes the "output state" of the previous iteration,
and hashes it alongside the current time, 64 random bytes from Python's secrets module,
a unique counter value, and the key. The result of this operation is the "output state"
that will be used by the next iteration of the loop.Each of the "output states" is then hashed again along with the time, a different 64 random bytes,
and a different unique counter value. One byte is selected randomly
from each of the resulting "candidate states"
and is transformed into a password character.The power of this technique comes from the keyed hash functions. For an attacker to have any hope
of guessing a password generated in this way, they must first know the key which was used.
If the user creates a new somewhat-random key for each password, and then removes all record of the key,
it eliminates any chance of retroactively recovering the password.
This holds true even in the absurdly unlikely case that an attacker knows both the time when the
password was generated and the internal state of Python's secrets module.Drawing randomness from multiple sources, and passing it through a SHA hash,
guarantees that the resulting passwords will be patternless: knowing any part
of the password will not give an attacker any information about the rest of the password.
Passwords generated fromPython Password Utilitywill have the maximum possible
entropy for a password of their length and character set.Installationpip install passutilNote:
This software requires Python 3.6 or later.
Major versions of Python after Python 3 are not supported.Running from the Command Linepython -m passutil <valid_chars> <length> <random keyboard smashing, optional><valid_chars>tells the program which characters are permitted in your password.
The format of this parameter is described below.zis generally the best option, unless there are restrictions on which
characters may appear in the password.
This parameter may not correspond to an empty set;
to be able to generate a password, at least one character must be
allowed to exist in the password.
This parameter is case sensitive.<length>is the desired length of the password. This can be any nonnegative integer.<random keyboard smashing>is an optional parameter. The entire command is taken as the key
for the hash function, so going wild on the keyboard after the<length>will
increase the randomness of the generated password.Character SetsThe basic character sets include:uorc-> uppercase/capital:A-Z(26 characters)l-> lowercase:a-z(26 characters)n-> numeral:0-9(10 characters)p-> ASCII punctuation:`~!@#$%^&*()-_=+[]{}\|;:'",<.>/?(32 characters)r-> subset ofp, some systems prohibit which punctuation
characters may be used in a password,romits those characters
which are most likely to be banned, leaving:!@#$%&*()-_+[]{};:,.?(21 characters)s-> the space character (1 character)H-> uppercase hexadecimal characters:0123456789ABCDEF(16 characters)h-> lowercase hexadecimal characters:0123456789abcdef(16 characters)The names of the basic character sets are case sensitive;
they must all be lowercase, other thanH.Example:The command below will generate a password of length 4,
only containing the numerals0-9.
It does this by specifying the character setnfor numerals,
and the length4.
The output might look like:7014.python -m passutil n 4Example:The command below will generate a password of length 25,
only containing ASCII punctuation characters.
It does this by specifying the character setpfor punctuation,
and the length25.
The output might look like:$/:<"/\~(+#/=";-:^(*)+'?-.python -m passutil p 25If we want to use characters from multiple character sets, we can perform a union on the sets simply by concatenating their names in the command.Example:The command below will generate a password of length 10,
only containing numerals, spaces, and lowercase letters.
It does this by combining then,s, andlsets,
to get thenslset.
The output might look like:p ltaj0k3p.python -m passutil nsl 10It is also possible to combine many character sets at once using shorthands:a=ulnps, all the characters (95 characters)ar=ulnrs, all the characters, except those which are likely to be banned (84 characters)z=ulnp, all the characters, except spaces (94 characters)zr=ulnr, all the characters, except spaces, and those which are likely to be banned (83 characters)The shorthands are case sensitive; they must all be lowercase.Example:The command below will generate a password of length 16,
containing any of the ASCII printable characters. It does this by using theashorthand. The output may look like:~VJ &FhC[_K8wu:+.python -m passutil a 16Note that the above command is fully equivalent to:python -m passutil ulnps 16Example:The command below will generate a password of length 7,
only containing uppercase letters, lowercase letters, numerals,
restricted punctuation characters, and spaces.
It does this by combining thezrshorthand with thescharacter set.
The output may look like:1A #T-x.python -m passutil zrs 7Note:zrs=szr=ulnrs=ar(zris expanded to its definition, and then merged withs)However:zsr=ulnpsr=a(zis expanded to its definition, the lastris ignored because it is already included inp)Individual characters may be included withior excluded withe.Example:The command below will generate a password of length 20,
only containing numerals,Acharacters andbcharacters.
It does this by first declaring the base set:n,
indicating numerals, then modifying it
withi. TheAbafter theisignals thatAcharacters
andbcharacters are allowed in the password.
The output may look like:24b749b71A1669586098.python -m passutil niAb 20This feature is case sensitive;
using uppercaseIwould not work here.Example:The command below will generate a password of length 18,
only containing capital letters and ASCII punctuation.
However, it will not contain the charactersC,A,T,., or/.
It does this by first declaring the base set:cp,
indicating capitals and punctuation, then modifying it
withe. TheCAT./after theesignals that these
characters may not appear in the password.
The output may look like:[W*[*;{(UM@QL,_$XR.python -m passutil cpeCAT./ 18This feature is case sensitive;
using uppercaseEwould not work here.Some characters may need to be enclosed in parenthesis or prefixed with an escape backslash.
See:https://www.shellscript.sh/escape.htmlTo include/exclude lowercaseiore, escape them with a..prefix.Example:The command below will generate a password of length 14,
only containing consonants in the English alphabet.
It does this by first declaring the base set:l,
indicating lowercase letters, then modifying it
witheto exclude the vowel characters.
Notice that in the exclusion,eandiare prefixed with..to prevent them
from being interpreted as the beginning
of an exclusion or inclusion.
The output may look like:hgydslgfzpsqft.python -m passutil lea..e..iou 14iandemay be used togetherExample:The command below will generate a password of length 26,
only containing even numerals,acharacters, andmcharacters.
It does this by first declaring the base set:n,
indicating numerals, then modifying it
withito includeaandmcharacters.
The followingewill then exclude
the1,3,5,7, and9characters from
the password.
The output may look like:m6am6a264m6m4m884m40aa6ma2.python -m passutil niame13579 26Example:The command below will generate a password of length 7,
only containing numerals,echaracters,
and excluding the numeral5.
It does this by first declaring the base set:n,
indicating numerals, then modifying it withito includee. Note that the firsteis escaped with a..,
and is therefore included by the precedingi, while the secondeis not escaped, and so signals the start of an exclusion.5is excluded by the seconde.
The output may look like:97739e8.python -m passutil ni..ee5 7Advanced ExamplesExample:IN:  python -m passutil li234 30
OUT: ppkksclllnihfghmrmxqklvcleiroeWhere's the234in the output?The<valid_chars>parameter controls which
characters may appear in the password,
not which characters will appear in the password.Example:IN:  python -m passutil aen 30
OUT: x&deJD.PHG\]-5]0d\&!CX\wRwHyNlI wanted to generate a password using
all the characters, except for numerals.
What's that5doing in there?After aniorestarts an inclusion or exclusion,
all subsequent characters (except foriande)
are interpreted literally.Before any inclusions or exclusions,u,c,l,n,p,r,s,H, andhrefer to sets of characters.
(Definitions given above)Within inclusions and exclusions, these same characters
are interpreted as individual Latin alphabet
letters to be included or excluded.So,aenwill generate a password using all available characters
except for the lowercase lettern, which will be excluded.
To generate a password using all the available characters
except numerals, useulpsor more inconvenientlyae0123456789.Example:IN:  python -m passutil iATCG 12
OUT: CACCCCCGTCTGDeclaring a base set is not required.
The<valid_chars>parameter may begin with ani,
followed by the characters to include.Example:IN:  python -m passutil ipeck 10
OUT: ppppppppppWhat's going on here?
I wanted a password using the lettersp,e,c, andk, but I only get a bunch ofpcharacters.Because theeis not escaped, it is treated as the beginning
of an exclusion.candkare excluded, leaving onlypin the character set.To create a character set with the charactersp,e,c, andk, theeneeds to be
escaped:ip..eck.Example:IN:  python -m passutil lebig 10
OUT: wdaozsgputWhy is there agin the output? I wanted to exclude
the charactersb,i, andg.Same thing as the previous example.iis not escaped.
The correct character set will be produced with:leb..ig.Example:IN:  python -m passutil i..i 10
OUT: iiiiiiiiiiWait, what?The firstistarts an inclusion.
The escaped secondiis the sole character
that is included into the set.Example:IN:  python -m passutil e..e 10
OUT: valid_chars parameter has minimum size 1Wait, what?The firstestarts an exclusion.
No characters are added into the character set.
The program needs at least one valid character
to be able to produce a password.Example:IN:  python -m passutil ixiyey 10
OUT: xxxxxxxxxx

IN:  python -m passutil ixeyiy 10
OUT: xyyyxyyyxyWhat's going on here?
Why do such similar inputs produce such different outputs?The generation of the character set operates from left to right.In the first case:ixwill addxto the set.iywill addyto the set.
But then,eywill removeyfrom the set,
leaving onlyx.In the second case:ixwill addxto the set.eywill try to removeyfrom the set, but as
there is noyin the set, it will do nothing.
Then, the program reachesiy, addingyto the set,
resulting in a set containing bothxandy.Example:Adding pseudorandomly generated keystrokes
(e.g. pretending to type without actually making words)
after the core of the command can help increase the randomness
of the generated password.
It is recommended that users make use of this feature
to fully utilize the capacities of this software.IN:  python -m passutil n 30 ju2ikntu i g rhtuirehtui3wh8r73hfsdnrrhtrthui
OUT: 834040642994017327433140007821

IN:  python -m passutil Hixyz 20 njfkern 4tio54n28r4 gmfd dginrekngtiosei8ufh
OUT: 18C29C2A9Az472BC1D27

IN:  python -m passutil zeI..i 5 min3w 12ji44tnf 4hNUFIWE 3U4ITR8H4RH283W7 fhu
OUT: Ss#oLGetting the Size of a Character SetSometimes it is useful to know how many characters
are in a character set before the character set
is used.Python Password Utilityallows
one to do this from the command line.python -m passutil --size <valid_chars><valid_chars>has the same format as above.
However, unlike when generating a password,valid_charsmay correspond to an empty set.
In such a case,0is returned.Example:IN:  python -m passutil --size une5
OUT: 35uhas 26 characters.nhas 10.e5removes one character, leaving 35.Hashing AlgorithmsPython Password Utilitygenerates passwords using either
the SHA-2 512 algorithm or the SHA-3 512 algorithm.To determine which algorithm is being used:python -m passutil --hashCalling from PythonPython Password Utilityprovides three publicly accessible objects.generate_passwordcharset_sizeSHA512_numbergenerate_passwordgenerate_passwordis a function. As the name suggests,
it generates passwords in the same way that the
command line interface does.importpassutilpassword=passutil.generate_password(length,key,valid_chars)lengthis a nonnegativeintrepresenting the desired number of characters in the password.keyis of typebytesorstr. Its length cannot be zero. This value will be used to key the
SHA hash function.
For best results, use a differentkeyvalue on each call togenerate_password.valid_charsindicates which characters may appear in the output password. It may be astrof the same
format as the<valid_chars>parameter in the command line interface.
Alternatively,valid_charsmay be aset,list, ortuplecontaining permitted
characters, encoded as single-character strings.
Alternatively,valid_charsmay be aset,list, ortuplecontaining
codepoints for permitted characters. Only ASCII printable characters,
or their codepoints, may exist invalid_chars.valid_charsmay not correspond to
an empty set.The function will output astrcontaining the password.RaisesTypeErroriflengthis not anint.
Or ifkeyis not abytesorstrobject.
Or ifvalid_charsis not astr,set,list, ortuple. Or if the contained elements are neitherstrnorint.RaisesValueErroriflengthis negative.
Or ifkeyhas length zero.
Or if the format is incorrect.
Or if non-ASCII-printable
characters are given invalid_chars.Example:importpassutilpassword=passutil.generate_password(4,"hello world","n")print(type(password))# strprint(password)# 7014This is analogous to the very first example given in this document.Example:importpassutilpassword=passutil.generate_password(12,b'\xf0\x9f\x98\x84',{"A","T",67,71})# ASCII value 67 is "C", ASCII value 71 is "G"print(password)# CACCCCCGTCTGThis is analogous to one of the advanced examples above.charset_sizecharset_sizeis the analog of--sizein the command line interface.
It is a function called in the following way:importpassutilsize=passutil.charset_size(valid_chars)It returns anint.valid_charshas the same format as ingenerate_password.
Unlike ingenerate_password, an input corresponding to an
empty character set will not cause an exception; instead, the function
will simply return0, indicating a character set of size zero.RaisesTypeErrorifvalid_charsis not astr,set,list, ortuple. Or if the contained elements are neitherstrnorint.RaisesValueErrorif the format is incorrect or if non-ASCII-printable
characters are given invalid_chars.SHA512_numberSHA512_numberis the analog of--hashin the command line interface.
It is anintconstant.
A value of2indicates that SHA-2 512 will be used for hashing.
A value of3indicates that SHA-3 512 will be used for hashing.importpassutilalgorithm_version=passutil.SHA512_number