argon2-cffi

Warnings

• breaking Python 2.7, 3.4, 3.5, and 3.7 are no longer supported. The minimum Python version is now 3.8.
  Fix: Upgrade to Python 3.8 or newer. Ensure your project's `requires_python` matches.
• breaking The legacy top-level functions `argon2.hash_password()`, `argon2.hash_password_raw()`, and `argon2.verify_password()` that were soft-deprecated since 2016 and hard-deprecated (raising `DeprecationWarning`) in 23.1.0 are now removed.
  Fix: Migrate to using the `argon2.PasswordHasher` class for all hashing and verification operations. For low-level APIs, use `argon2.low_level.hash_secret()` and `argon2.low_level.verify_secret()`.
• breaking Default hashing parameters for `PasswordHasher` changed in version 21.2.0 to align with RFC 9106's low-memory profile. While old hashes remain verifiable, new hashes will use the updated, more secure defaults.
  Fix: No immediate fix for existing hashes, but be aware of the change for new hashes. If you need to force old defaults for new hashes (not recommended), use `argon2.profiles.PRE_21_2`. It's recommended to re-hash passwords on user login if `ph.check_needs_rehash()` indicates a need.
• breaking Since version 21.2.0, the CFFI bindings were extracted into `argon2-cffi-bindings`. This is a breaking change for users attempting to use a system-wide installation of Argon2 with `--no-binary`, as the argument value changed. Most users relying on default `pip install` with vendored code are unaffected.
  Fix: If using a system-wide Argon2, consult the installation guide for updated `--no-binary` instructions (e.g., `pip install --no-binary=argon2-cffi-bindings argon2-cffi`). Otherwise, continue with default installation.
• gotcha Forgetting to specifically catch `argon2.exceptions.VerifyMismatchError` during password verification. This exception is raised when a submitted password does not match the stored hash, indicating a failed login attempt.
  Fix: Always include `except VerifyMismatchError:` in your `try...except` block when calling `ph.verify()` to handle incorrect passwords explicitly.
• gotcha The `salt` parameter was added to `argon2.PasswordHasher.hash()` in v23.1.0. While available, it's generally not recommended to provide your own salt unless you have a very specific, advanced use case. The library generates secure, random salts by default.
  Fix: Unless you explicitly know why you need to provide a custom salt, leave the `salt` parameter as `None` to let `argon2-cffi` handle salt generation automatically.

Install

• pip install argon2-cffi Install stable version

Imports

• PasswordHasher

  from argon2 import PasswordHasher

  This is the primary class for hashing and verifying passwords.
• VerifyMismatchError

  from argon2.exceptions import VerifyMismatchError

  When verifying a password, `VerifyMismatchError` is raised if the password does not match the hash. Catching this specific exception is best practice rather than a generic `Exception`.

Quickstart

This quickstart demonstrates how to initialize `PasswordHasher`, hash a password, verify it, and check if the hash needs to be updated due to changed parameters. Always catch `VerifyMismatchError` for password mismatches.

from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError

ph = PasswordHasher()

# Hash a password
password = "correct horse battery staple"
hashed_password = ph.hash(password)
print(f"Hashed: {hashed_password}")

# Verify a password
try:
    ph.verify(hashed_password, password)
    print("Verification successful!")
except VerifyMismatchError:
    print("Verification failed: Password does not match.")
except Exception as e:
    print(f"An unexpected error occurred during verification: {e}")

# Check if a rehash is needed (e.g., if parameters changed)
if ph.check_needs_rehash(hashed_password):
    print("Password needs re-hashing with new parameters.")
else:
    print("Password hash parameters are up-to-date.")