flask_imp.auth¶

This module contains the authentication utilities for a Flask application.

Functions:

authenticate_password: Authenticates a password against a hashed password.

encrypt_password: Encrypts a password with a salt and pepper.

generate_alphanumeric_validator: Generates a validator for alphanumeric strings.

generate_csrf_token: Generates a CSRF token.

generate_email_validator: Generates a validator for email addresses.

generate_numeric_validator: Generates a validator for numeric strings.

generate_password: Generates a password.

generate_private_key: Generates a private key.

generate_salt: Generates a salt.

is_email_address_valid: Validates an email address.

is_username_valid: Validates a username.

flask_imp.auth.is_email_address_valid(email_address)¶

Checks if email_address is a valid email address.

Is not completely RFC 5322 compliant, but it is good enough for most use cases.

Here are examples of mistakes that it will not catch:

VALID but fails:
- email@[123.123.123.123]
- “email”@example.com
- very.unusual.“@”.unusual.com@example.com
- very.“(),:;<>[]”.VERY.“very@\ "very”.unusual@strange.example.com

 INVALID but passes:
 - email@example.com (Joe Smith)
 - email@111.222.333.44444

Parameters:: email_address (str) – email address to validate
Returns:: True if email_address is valid, False otherwise
Return type:: bool

flask_imp.auth.is_username_valid(username, allowed=None)¶

Checks if a username is valid.

Valid usernames can only include letters, numbers, ., -, and _ but cannot begin or end with the last three mentioned.

Example use:

is_username_valid("username", allowed=["all"])

Passes: username, user.name, user-name, user_name
Fails: _user_name

is_username_valid("username", allowed=["dot", "dash"])

Passes: username, user.name, user-name, user-name.name
Fails: user_name, _user_name, .user.name

Parameters:

username (str) – username to validate
allowed (List[Literal['all', 'dot', 'dash', 'under']] | None) – [“all”, “dot”, “dash”, “under”] - defaults to [“all”]

Returns:

True if username is valid, False otherwise

Return type:

bool

flask_imp.auth.generate_csrf_token()¶

Generates a SHA1 using the current date and time.

For use in Cross-Site Request Forgery.

Returns:: sha1 hash of the current date and time
Return type:: str

flask_imp.auth.generate_private_key(hook)¶

Generates a sha256 private key from a passed in hook value.

If no hook is passed in, it will generate a hook using datetime.now() and a random number between 1 and 1000.

Parameters:: hook (str | None) – hook value to generate private key from
Returns:: digested sha256
Return type:: str

flask_imp.auth.generate_numeric_validator(length)¶

Generates random choice between 1 * (length) and 9 * (length).

Example return if length = 4: 5468

For use in MFA email, or unique filename generation.

Parameters:: length (int) – length of number to generate
Returns:: random integer of (length)
Return type:: int

flask_imp.auth.generate_alphanumeric_validator(length)¶

Generates (length) of alphanumeric.

For use in MFA email, or unique filename generation.

Example return of “F5R6” if length is 4

Parameters:: length (int) – length of alphanumeric to generate
Returns:: alphanumeric of length (length)
Return type:: str

flask_imp.auth.generate_email_validator()¶

Uses generate_alphanumeric_validator with a length of 8 to generate a random alphanumeric value for the specific use of validating accounts via email.

Returns:: alphanumeric of length 8
Return type:: str

flask_imp.auth.generate_salt(length=4)¶

Generates a string of (length) characters of punctuation.

The Default length is 4.

For use in password salting

Returns:: a salt of (length)
Parameters:: length (int)
Return type:: str

flask_imp.auth.encrypt_password(password, salt, encryption_level=512, pepper_length=1, pepper_position='end')¶

Takes the plain password, applies a pepper, salts it, then produces a digested sha512 or sha256 if specified.

Can set the encryption level to 256 or 512, defaults to 512.
Can set the pepper length, defaults to 1. Max is 3.
Can set the pepper position, “start” or “end”, defaults to “end”.

For use in password hashing.

You must inform the authenticate_password function of:

the pepper length used to hash the password.
the position of the pepper used to hash the password.
the encryption level used to hash the password.

Parameters:

password (str) – str - plain password
salt (str) – str - salt
encryption_level (int) – int - 256 or 512 - defaults to 512
pepper_length (int) – int - length of pepper
pepper_position (Literal['start', 'end']) – str - “start” or “end” - defaults to “end”

Return str:

hash:

Return type:

str

flask_imp.auth.authenticate_password(input_password, database_password, database_salt, encryption_level=512, pepper_length=1, pepper_position='end', use_multiprocessing=False)¶

Takes the plain input password, the stored hashed password along with the stored salt and will try every possible combination of pepper values to find a match.

Note: use_multiprocessing is not compatible with coroutine workers, e.g. eventlet/gevent commonly used with socketio.

You must know:

the length of the pepper used to hash the password.
the position of the pepper used to hash the password.
the encryption level used to hash the password.

Parameters:

input_password (str) – plain password
database_password (str) – hashed password from database
database_salt (str) – salt from database
encryption_level (int) – encryption used to generate database password
pepper_length (int) – length of pepper used to generate database password
pepper_position (Literal['start', 'end']) – “start” or “end” - position of pepper used to generate database password
use_multiprocessing (bool) – use multiprocessing to speed up the process (not compatible with eventlet/gevent)

Returns:

True if match, False if not

Return type:

bool

flask_imp.auth.generate_password(style='mixed', length=3)¶

Generates a plain text password based on choice of style and length.

(length) of random numbers are appended to the end of every generated password.

style options: “animals”, “colors”, “mixed” - defaults to “mixed”

Parameters:

style (Literal['animals', 'colors', 'mixed']) – “animals”, “colors”, “mixed” - defaults to “mixed”
length (int) – the number of words joined - defaults to 3

Returns:

a generated password

Return type:

str