authnzerver.actions.passwords module

This contains functions for validating passwords.

authnzerver.actions.passwords.check_password_pwned(password: str, email: str, reqid: str, pii_salt: str, min_matches: int = 25) → tuple[source]

Checks the password against the haveibeenpwned.com API.

https://haveibeenpwned.com/API/v3#PwnedPasswords

Parameters:
  • password (str) – The password to check against the haveibeenpwned.com API.
  • email (str) – The email address of the user creating the account.
  • reqid (int or str) – The request ID associated with this password validation request. Used to track and correlate these requests in logs.
  • pii_salt (str) – The PII salt value passed in from a wrapping function. Used to censor personally identifying information in the logs emitted from this function.
  • min_matches (int) – The minimum number of matches required in the matching set returned by the API to consider a password as compromised.
Returns:

(status, msg, sha1_suffix, all_matches) – If the password is considered to be compromised, returns “bad”, msg for the first two elements in the tuple. Otherwise, returns “ok”, “”. If the API does not respond or there’s an error, returns “unknown”, “”.
Return type:

tuple
authnzerver.actions.passwords.validate_input_password(full_name: str, email: str, password: str, pii_salt: str, reqid: str, min_pass_length: int = 12, max_unsafe_similarity: int = 33, max_character_frequency: float = 0.3, min_pwned_matches: int = 25, config: types.SimpleNamespace = None) → tuple[source]

Validates user input passwords.

Password rules are:

  1. must be at least min_pass_length characters (we’ll truncate the password at 1024 characters since we don’t want to store entire novels)
  2. must not match within max_unsafe_similarity of their email or full_name
  3. must not match within max_unsafe_similarity of the site’s FQDN
  4. must not have a single case-folded character take up more than 20% of the length of the password
  5. must not be completely numeric
  6. must not be in the top 10k passwords list

If all of the above pass, one last check is done:

  1. must not be in the https://haveibeenpwned.com/Passwords database with at least min_pwned_matches matches
Parameters:
  • full_name (str) – The full name of the user creating the account.
  • email (str) – The email address of the user creating the account.
  • password (str) – The password of the user creating the account.
  • pii_salt (str) – The PII salt value passed in from a wrapping function. Used to censor personally identifying information in the logs emitted from this function.
  • reqid (int or str) – The request ID associated with this password validation request. Used to track and correlate these requests in logs.
  • min_pass_length (int) – The minimum required character length of the password. The value provided in this kwarg will be overriden by the passpolicy attribute in the config object if that is passed in as well.
  • max_unsafe_similarity (int) – The maximum ratio required to fuzzy-match the input password against the server’s domain name, the user’s email, or their name. The value provided in this kwarg will be overriden by the passpolicy attribute in the config object if that is passed in as well.
  • max_character_frequency (float) – The maximum number of times a character can appear in the password as a fraction of the total number of characters in the password. Upper and lower case characters are counted separately.
  • min_pwned_matches (int) – The minimum number of matches required in the matching set returned by the haveibeenpwned.com password compromise database API to consider a password as compromised.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

(password_ok, messages) – password_ok is True if the password is OK to use and meets all specification, False otherwise. messages is a list of strings containing helpful messages on why the password was rejected (if it was) that can be passed to an end-user.
Return type:

tuple
authnzerver.actions.passwords.validate_password(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, config: types.SimpleNamespace = None) → dict[source]

External interface to password validation.

Use this in a frontend server or client to validate any passwords sent by the end-user.

Parameters:
  • payload (dict) –

    This is a dict with the following required keys:

    • password: str
    • email: str
    • full_name: str

    The following keys are optional:

    • min_pass_length: int, default = 12
    • max_unsafe_similarity: int, default = 33
    • max_character_frequency: float, default = 0.3
    • min_pwned_matches: int, default = 25

    The email and full_name are required to check if the password is too similar to either of these items.

    min_pass_length is the minimum number of characters required for the password. All passwords are capped at 256 characters. This value will be overriden by a value in the config object’s min_pass_length attribute.

    max_unsafe_similarity is the maximum ratio required to fuzzy-match the input password against the server’s domain name, the user’s email, or their name. This value will be overriden by a value in the config object’s max_unsafe_similarity attribute.

    max_character_frequency is the maximum ratio required to fuzzy-match the input password against the server’s domain name, the user’s email, or their name. The value provided in this kwarg will be overriden by the passpolicy attribute in the config object if that is passed in as well.

    min_pwned_matches is the minimum number of matches required in the matching set returned by the haveibeenpwned.com password compromise database API to consider a password as compromised.

    In addition to these items received from an authnzerver client, the payload must also include the following keys (usually added in by a wrapping function):

    • reqid: int or str
    • pii_salt: str
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

Returns a dict containing a success key indicating if the user’s password is valid and can be used. If the password is invalid, the messages key will contain messages that inform the user why their password was rejected.
Return type:

dict