Security

This module provides security related helpers such as secure password hashing tools and a random string generator.

webapp2_extras.security.generate_random_string(length=0, entropy=0, pool='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')

Generates a random string using the given sequence pool.

To generate stronger passwords, use ASCII_PRINTABLE as pool.

Entropy is:

H = log2(N**L)

where:

• H is the entropy in bits.
• N is the possible symbol count
• L is length of string of symbols

Entropy chart:

-----------------------------------------------------------------
Symbol set              Symbol Count (N)  Entropy per symbol (H)
-----------------------------------------------------------------
HEXADECIMAL_DIGITS      16                4.0000 bits
DIGITS                  10                3.3219 bits
LOWERCASE_ALPHA         26                4.7004 bits
UPPERCASE_ALPHA         26                4.7004 bits
PUNCTUATION             32                5.0000 bits
LOWERCASE_ALPHANUMERIC  36                5.1699 bits
UPPERCASE_ALPHANUMERIC  36                5.1699 bits
ALPHA                   52                5.7004 bits
ALPHANUMERIC            62                5.9542 bits
ASCII_PRINTABLE         94                6.5546 bits
ALL_PRINTABLE           100               6.6438 bits

Parameters:

• length – The length of the random sequence. Use this or entropy, not both.
• entropy – Desired entropy in bits. Use this or length, not both. Use this to generate passwords based on entropy: http://en.wikipedia.org/wiki/Password_strength
• pool – A sequence of characters from which random characters are chosen. Default to case-sensitive alpha-numeric characters.

Returns:

A string with characters randomly chosen from the pool.

webapp2_extras.security.generate_password_hash(password, method='sha1', length=22, pepper=None)

Hashes a password.

The format of the string returned includes the method that was used so that check_password_hash() can check the hash.

This method can not generate unsalted passwords but it is possible to set the method to plain to enforce plaintext passwords. If a salt is used, hmac is used internally to salt the password.

Parameters:

• password – The password to hash.
• method – The hash method to use ('md5' or 'sha1').
• length – Length of the salt to be created.
• pepper – A secret constant stored in the application code.

Returns:

A formatted hashed string that looks like this:

method$salt$hash

This function was ported and adapted from Werkzeug.

webapp2_extras.security.check_password_hash(password, pwhash, pepper=None)

Checks a password against a given salted and hashed password value.

In order to support unsalted legacy passwords this method supports plain text passwords, md5 and sha1 hashes (both salted and unsalted).

Parameters:

• password – The plaintext password to compare against the hash.
• pwhash – A hashed string like returned by generate_password_hash().
• pepper – A secret constant stored in the application code.

Returns:

True if the password matched, False otherwise.

This function was ported and adapted from Werkzeug.

webapp2_extras.security.hash_password(password, method, salt=None, pepper=None)

Hashes a password.

Supports plaintext without salt, unsalted and salted passwords. In case salted passwords are used hmac is used.

Parameters:

• password – The password to be hashed.
• method – A method from hashlib, e.g., sha1 or md5, or plain.
• salt – A random salt string.
• pepper – A secret constant stored in the application code.

Returns:

A hashed password.

This function was ported and adapted from Werkzeug.

webapp2_extras.security.compare_hashes(a, b)

Checks if two hash strings are identical.

The intention is to make the running time be less dependant on the size of the string.

Parameters:

• a – String 1.
• b – String 2.

Returns:

True if both strings are equal, False otherwise.