from __future__ import annotations
|
|
import hashlib
|
import hmac
|
import os
|
import posixpath
|
import secrets
|
import warnings
|
|
SALT_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
|
DEFAULT_PBKDF2_ITERATIONS = 600000
|
|
_os_alt_seps: list[str] = list(
|
sep for sep in [os.sep, os.path.altsep] if sep is not None and sep != "/"
|
)
|
|
|
def gen_salt(length: int) -> str:
|
"""Generate a random string of SALT_CHARS with specified ``length``."""
|
if length <= 0:
|
raise ValueError("Salt length must be at least 1.")
|
|
return "".join(secrets.choice(SALT_CHARS) for _ in range(length))
|
|
|
def _hash_internal(method: str, salt: str, password: str) -> tuple[str, str]:
|
if method == "plain":
|
warnings.warn(
|
"The 'plain' password method is deprecated and will be removed in"
|
" Werkzeug 3.0. Migrate to the 'scrypt' method.",
|
stacklevel=3,
|
)
|
return password, method
|
|
method, *args = method.split(":")
|
salt = salt.encode("utf-8")
|
password = password.encode("utf-8")
|
|
if method == "scrypt":
|
if not args:
|
n = 2**15
|
r = 8
|
p = 1
|
else:
|
try:
|
n, r, p = map(int, args)
|
except ValueError:
|
raise ValueError("'scrypt' takes 3 arguments.") from None
|
|
maxmem = 132 * n * r * p # ideally 128, but some extra seems needed
|
return (
|
hashlib.scrypt(password, salt=salt, n=n, r=r, p=p, maxmem=maxmem).hex(),
|
f"scrypt:{n}:{r}:{p}",
|
)
|
elif method == "pbkdf2":
|
len_args = len(args)
|
|
if len_args == 0:
|
hash_name = "sha256"
|
iterations = DEFAULT_PBKDF2_ITERATIONS
|
elif len_args == 1:
|
hash_name = args[0]
|
iterations = DEFAULT_PBKDF2_ITERATIONS
|
elif len_args == 2:
|
hash_name = args[0]
|
iterations = int(args[1])
|
else:
|
raise ValueError("'pbkdf2' takes 2 arguments.")
|
|
return (
|
hashlib.pbkdf2_hmac(hash_name, password, salt, iterations).hex(),
|
f"pbkdf2:{hash_name}:{iterations}",
|
)
|
else:
|
warnings.warn(
|
f"The '{method}' password method is deprecated and will be removed in"
|
" Werkzeug 3.0. Migrate to the 'scrypt' method.",
|
stacklevel=3,
|
)
|
return hmac.new(salt, password, method).hexdigest(), method
|
|
|
def generate_password_hash(
|
password: str, method: str = "pbkdf2", salt_length: int = 16
|
) -> str:
|
"""Securely hash a password for storage. A password can be compared to a stored hash
|
using :func:`check_password_hash`.
|
|
The following methods are supported:
|
|
- ``scrypt``, more secure but not available on PyPy. The parameters are ``n``,
|
``r``, and ``p``, the default is ``scrypt:32768:8:1``. See
|
:func:`hashlib.scrypt`.
|
- ``pbkdf2``, the default. The parameters are ``hash_method`` and ``iterations``,
|
the default is ``pbkdf2:sha256:600000``. See :func:`hashlib.pbkdf2_hmac`.
|
|
Default parameters may be updated to reflect current guidelines, and methods may be
|
deprecated and removed if they are no longer considered secure. To migrate old
|
hashes, you may generate a new hash when checking an old hash, or you may contact
|
users with a link to reset their password.
|
|
:param password: The plaintext password.
|
:param method: The key derivation function and parameters.
|
:param salt_length: The number of characters to generate for the salt.
|
|
.. versionchanged:: 2.3
|
Scrypt support was added.
|
|
.. versionchanged:: 2.3
|
The default iterations for pbkdf2 was increased to 600,000.
|
|
.. versionchanged:: 2.3
|
All plain hashes are deprecated and will not be supported in Werkzeug 3.0.
|
"""
|
salt = gen_salt(salt_length)
|
h, actual_method = _hash_internal(method, salt, password)
|
return f"{actual_method}${salt}${h}"
|
|
|
def check_password_hash(pwhash: str, password: str) -> bool:
|
"""Securely check that the given stored password hash, previously generated using
|
:func:`generate_password_hash`, matches the given password.
|
|
Methods may be deprecated and removed if they are no longer considered secure. To
|
migrate old hashes, you may generate a new hash when checking an old hash, or you
|
may contact users with a link to reset their password.
|
|
:param pwhash: The hashed password.
|
:param password: The plaintext password.
|
|
.. versionchanged:: 2.3
|
All plain hashes are deprecated and will not be supported in Werkzeug 3.0.
|
"""
|
try:
|
method, salt, hashval = pwhash.split("$", 2)
|
except ValueError:
|
return False
|
|
return hmac.compare_digest(_hash_internal(method, salt, password)[0], hashval)
|
|
|
def safe_join(directory: str, *pathnames: str) -> str | None:
|
"""Safely join zero or more untrusted path components to a base
|
directory to avoid escaping the base directory.
|
|
:param directory: The trusted base directory.
|
:param pathnames: The untrusted path components relative to the
|
base directory.
|
:return: A safe path, otherwise ``None``.
|
"""
|
if not directory:
|
# Ensure we end up with ./path if directory="" is given,
|
# otherwise the first untrusted part could become trusted.
|
directory = "."
|
|
parts = [directory]
|
|
for filename in pathnames:
|
if filename != "":
|
filename = posixpath.normpath(filename)
|
|
if (
|
any(sep in filename for sep in _os_alt_seps)
|
or os.path.isabs(filename)
|
or filename == ".."
|
or filename.startswith("../")
|
):
|
return None
|
|
parts.append(filename)
|
|
return posixpath.join(*parts)
|
