密码管理通常不应该被重新再设计，Django 努力提供了一个安全且灵活的管理用户密码的工具。这篇文档描述了 Django 如何存储密码，如何配置存储哈希，和一些使用哈希密码的工具。
\n\nDjango 提供灵活的密码存储系统，默认使用 PBKDF2。
\nUser 对象的 password 属性是一个以以下格式的字符串：
<algorithm>$<iterations>$<salt>$<hash>\nThose are the components used for storing a User's password, separated by the\ndollar-sign character and consist of: the hashing algorithm, the number of\nalgorithm iterations (work factor), the random salt, and the resulting password\nhash. The algorithm is one of a number of one-way hashing or password storage\nalgorithms Django can use; see below. Iterations describe the number of times\nthe algorithm is run over the hash. Salt is the random seed used and the hash\nis the result of the one-way function.
\n默认情况下，Django 使用带有 SHA256 哈希的 PBKDF2 算法，它是 NIST 推荐的密码延展机制。它足够安全，需要大量的运算时间才能破解，这对大部分用户来说足够了。
\nHowever, depending on your requirements, you may choose a different\nalgorithm, or even use a custom algorithm to match your specific\nsecurity situation. Again, most users shouldn't need to do this -- if\nyou're not sure, you probably don't. If you do, please read on:
\nDjango 通过查阅 PASSWORD_HASHERS 设置来选择要使用的算法。这是一个包含此 Django 安装支持的哈希算法类的列表。
对于存储密码，Django 将使用 PASSWORD_HASHERS 中的第一个哈希算法。要使用不同的算法存储新密码，请将您首选的算法放在 PASSWORD_HASHERS 中的第一位。
对于验证密码，Django 将在列表中查找与存储的密码中的算法名称匹配的哈希算法。如果存储的密码命名了在 PASSWORD_HASHERS 中找不到的算法，试图验证它将引发 ValueError。
PASSWORD_HASHERS 的默认值是：
PASSWORD_HASHERS = [\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",\n "django.contrib.auth.hashers.ScryptPasswordHasher",\n]\n这意味着 Django 除了使用 PBKDF2 来存储所有密码，也支持使用 PBKDF2SHA1 、argon2 和 bcrypt 来检测已存储的密码。
\n接下来的部分描述了高级用户修改这个配置的几个常见方法。
\nArgon2 是 2015 年 Password Hashing Competition 的获胜者，这是一个由社区组织的开放式竞赛，旨在选择下一代哈希算法。它的设计目标是在自定义硬件上计算不应该比在普通 CPU 上计算容易。Argon2 密码哈希器的默认变种是 Argon2id。
\nArgon2 并不是 Django 的默认首选，因为它依赖第三方库。尽管哈希密码竞赛主办方建议立即使用 Argon2 ，而不是 Django 提供的其他算法。
\n要将 Argon2id 用作默认的存储算法，请执行以下操作：
\n安装 argon2-cffi 包。可以通过运行 python -m pip install django[argon2] 来完成，这等同于 python -m pip install argon2-cffi``（以及 Django 的 ``pyproject.toml 中的任何版本要求）。
修改 PASSWORD_HASHERS 配置，把 Argon2PasswordHasher 放在首位。如下：
PASSWORD_HASHERS = [\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",\n "django.contrib.auth.hashers.ScryptPasswordHasher",\n]\n如果你需要 Django 升级密码（ upgrade passwords ），请保留或添加这个列表中的任何条目。
\nbcryptLink to this heading#Bcrypt 是一个非常流行的密码存储算法，尤其是为长期密码存储设计。Django 默认不使用它，因为它需要使用第三方库，但由于很多人想使用它，Django 只需要很少的努力就能支持 bcrypt。
\n使用 Bcrypt 作为你的默认存储算法，需要以下步骤：
\n安装 bcrypt 包。可以通过运行 python -m pip install django[bcrypt] 来完成，这等同于 python -m pip install bcrypt``（以及 Django 的 ``pyproject.toml 中的任何版本要求）。
修改 PASSWORD_HASHERS 配置，把 BCryptSHA256PasswordHasher 放在首位。如下：
PASSWORD_HASHERS = [\n "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.ScryptPasswordHasher",\n]\n如果你需要 Django 升级密码（ upgrade passwords ），请保留或添加这个列表中的任何条目。
\n现在 Django 将使用 Bcrypt 作为默认存储算法。
\nscryptLink to this heading#scrypt 类似于 PBKDF2 和 bcrypt，它们都利用一定数量的迭代来减慢暴力攻击的速度。然而，由于 PBKDF2 和 bcrypt 不需要大量内存，具有足够资源的攻击者可以发起大规模并行攻击以加快攻击过程。scrypt 特别设计用于使用比其他基于密码的密钥派生函数更多的内存，以限制攻击者可以使用的并行度，详细信息请参见 RFC 7914。
\n使用 scrypt 作为你的默认存储算法，需要以下步骤：
\n将 PASSWORD_HASHERS 修改为首先列出 ScryptPasswordHasher。在您的设置文件中，应如下所示：
PASSWORD_HASHERS = [\n "django.contrib.auth.hashers.ScryptPasswordHasher",\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",\n]\n如果你需要 Django 升级密码（ upgrade passwords ），请保留或添加这个列表中的任何条目。
\n大多数密码哈希值包括一个盐，与他们的密码哈希值一起，以防止彩虹表攻击。盐本身是一个随机值，它增加了彩虹表的大小和成本，目前在 BasePasswordHasher 中的 salt_entropy 值设置为 128 比特。随着计算和存储成本的降低，这个值应该被提高。当实现你自己的密码散列器时，你可以自由地覆盖这个值，以便为你的密码散列器使用一个理想的熵值。salt_entropy 是以比特为单位。
PBKDF2 和 bcrypt 算法使用一定数量的迭代或哈希轮次。这是有意为之的，它减慢了攻击者的速度，使对散列密码的攻击更加困难。然而，随着计算能力的增加，迭代次数也需要增加。我们选择了一个合理的默认值（并将在每个 Django 版本发布时逐渐增加），但您可以根据您的安全需求和可用的处理能力来调整它。要这样做，您需要子类化适当的算法并覆盖 iterations 参数（当子类化 bcrypt 哈希器时使用 rounds 参数）。例如，要增加默认 PBKDF2 算法使用的迭代次数：
创建一个 django.contrib.auth.hashers.PBKDF2PasswordHasher 的子类：
from django.contrib.auth.hashers import PBKDF2PasswordHasher\n\n\nclass MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):\n """\n A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.\n """\n\n iterations = PBKDF2PasswordHasher.iterations * 100\n在你的项目某些位置中保存。比如，你可以放在类似 myproject/hashers.py 里。
在 PASSWORD_HASHERS 中把新哈希放在首位：
PASSWORD_HASHERS = [\n "myproject.hashers.MyPBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",\n "django.contrib.auth.hashers.ScryptPasswordHasher",\n]\n现在 Django 使用 PBKDF2 存储密码时将会多次迭代。
\n\nArgon2 具有以下可自定义的属性：
\ntime_cost 控制哈希的次数。
memory_cost 控制被用来计算哈希时的内存大小。
parallelism 控制并行计算哈希的 CPU 数量。
这三个属性的默认值足够适合你。如果你确定密码哈希过快或过慢，可以按如下方式调整它：
\n选择 parallelism 你可以节省计算哈希的线程数。
选择 memory_cost 你可以节省内存的 KiB 。
调整 time_cost 和估计哈希一个密码所需的时间。挑选出你可以接受的 time_cost 。如果设置为1的 time_cost 慢的无法接受，则调低 memory_cost 。
scryptLink to this heading#scrypt 具有以下可自定义的属性：
\nwork_factor controls the number of iterations within the hash and the\nsize of memory for computation (N). It must be a power of 2.
block_size controls the internal block size (r), tuning the algorithm\nto memory latency.
parallelism controls how many independent computations may run in\nparallel (p).
maxmem 限制了在计算哈希过程中可以使用的最大内存大小。默认值为 0，表示使用 OpenSSL 库的默认限制。
We've chosen reasonable defaults, but you may wish to tune it up or down,\ndepending on your security needs and available processing power and memory.
\n\n当用户登录时，如果用户的密码使用首选算法以外的算法保存，Django 会自动升级这个算法成为首选算法。这意味着旧的 Django 安装会在用户登录时自动得到更多的安全，并且当它们创建时你可以切换到新的更好的存储算法。
\n然而，Django 只会使用 PASSWORD_HASHERS 提到的算法升级密码，因此当你升级到新系统时你要确保你从没有删除过这个列表的条目。如果你删除过，那么使用的没有列出的算法的用户将不会升级。当增加（或减少） PBKDF2 迭代的次数、bcrypt 的轮次或者 argon2 属性，哈希过的密码将被更新。
注意，如果数据库内的所有密码没有在默认哈希算法里编码，则由于非默认算法的密码编码的用户登录请求持续时间和不存在用户（运行过默认哈希）的登录请求持续时间的不同，你可能会受到用户枚举时间攻击。你可以使用 升级旧密码的哈希值 来缓解此问题。
\n如果你有一个使用较旧、较弱的哈希算法（如 MD5）的现有数据库，你可能希望自己升级这些哈希值，而不是等待用户登录时进行升级（如果用户不返回你的网站，可能永远不会发生）。在这种情况下，你可以使用一个“包装”的密码哈希器。
\n在这个示例中，我们将迁移一组 MD5 哈希值，以使用 PBKDF2(MD5(password))，并添加相应的密码哈希器，用于在登录时检查用户输入的正确密码。我们假设我们正在使用内置的“User”模型，并且我们的项目有一个“accounts”应用程序。您可以根据需要修改模式，以适应任何算法或自定义用户模型。
\n首先，我们添加一个自定义的哈希：
\naccounts/hashers.pyfrom django.contrib.auth.hashers import (\n PBKDF2PasswordHasher,\n MD5PasswordHasher,\n)\n\n\nclass PBKDF2WrappedMD5PasswordHasher(PBKDF2PasswordHasher):\n algorithm = "pbkdf2_wrapped_md5"\n\n def encode_md5_hash(self, md5_hash, salt, iterations=None):\n return super().encode(md5_hash, salt, iterations)\n\n def encode(self, password, salt, iterations=None):\n _, _, md5_hash = MD5PasswordHasher().encode(password, salt).split("$", 2)\n return self.encode_md5_hash(md5_hash, salt, iterations)\n数据迁移可能类似于这样：
\naccounts/migrations/0002_migrate_md5_passwords.pyfrom django.db import migrations\n\nfrom ..hashers import PBKDF2WrappedMD5PasswordHasher\n\n\ndef forwards_func(apps, schema_editor):\n User = apps.get_model("auth", "User")\n users = User.objects.filter(password__startswith="md5$")\n hasher = PBKDF2WrappedMD5PasswordHasher()\n for user in users:\n algorithm, salt, md5_hash = user.password.split("$", 2)\n user.password = hasher.encode_md5_hash(md5_hash, salt)\n user.save(update_fields=["password"])\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("accounts", "0001_initial"),\n # replace this with the latest migration in contrib.auth\n ("auth", "####_migration_name"),\n ]\n\n operations = [\n migrations.RunPython(forwards_func),\n ]\n注意，迁移将对上千名用户花费大约数十分钟，这取决于你的硬件速度。
\n最后，我们在 PASSWORD_HASHERS 中添加配置：
mysite/settings.pyPASSWORD_HASHERS = [\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "accounts.hashers.PBKDF2WrappedMD5PasswordHasher",\n]\n包含你的站点使用的此列表中的其他算法。
\n在 Django 中的所有列出的哈希是：
\n[\n "django.contrib.auth.hashers.PBKDF2PasswordHasher",\n "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",\n "django.contrib.auth.hashers.Argon2PasswordHasher",\n "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",\n "django.contrib.auth.hashers.BCryptPasswordHasher",\n "django.contrib.auth.hashers.ScryptPasswordHasher",\n "django.contrib.auth.hashers.MD5PasswordHasher",\n]\n相应的算法名是：
\npbkdf2_sha256
pbkdf2_sha1
argon2
bcrypt_sha256
bcrypt
scrypt
md5
如果你编写自己的密码哈希包含工作因子，比如迭代数量。你应该实现一个 harden_runtime(self, password, encoded) 方法来消除编码密码时提供的工作因子和默认的哈希工作因子之间的运行时间差。这样可以防止用户枚举时间攻击，因为旧的迭代次数中对密码编码的用户与不存在的用户（运行默认哈希的默认迭代次数）在登录时存在差异。
以 PDKDF2 为例，如果编码包含20000次迭代，并且默认哈希迭代是30000，那么该方法应该通过另外的10000次迭代的 PBKDF2 运行密码。
\n如果你的哈希没有工作因子，可以将该方法实现为 no-op (pass) 。
\nThe django.contrib.auth.hashers module provides a set of functions\nto create and validate hashed passwords. You can use them independently\nfrom the User model.
异步版本：acheck_password()
If you'd like to manually authenticate a user by comparing a plaintext\npassword to the hashed password in the database, use the convenience\nfunction check_password(). It takes two mandatory arguments: the\nplaintext password to check, and the full value of a user's password\nfield in the database to check against. It returns True if they match,\nFalse otherwise. Optionally, you can pass a callable setter that\ntakes the password and will be called when you need to regenerate it. You\ncan also pass preferred to change a hashing algorithm if you don't want\nto use the default (first entry of PASSWORD_HASHERS setting). See\n已包含的哈希 for the algorithm name of each hasher.
Creates a hashed password in the format used by this application. It takes\none mandatory argument: the plaintext password (string or bytes).\nOptionally, you can provide a salt and a hashing algorithm to use, if you\ndon't want to use the defaults (first entry of PASSWORD_HASHERS\nsetting). See 已包含的哈希 for the algorithm name of each\nhasher. If the password argument is None, an unusable password is\nreturned (one that will never be accepted by check_password()).
如果密码是 User.set_unusable_password() 的结果，则返回 False 。
用户经常会选择弱密码。为了缓解这个问题，Django 提供可插拔的密码验证。你可以同时配置多个密码验证。Django 已经包含了一些验证，但你也可以编写你自己的验证。
\n每个密码验证器必须提供帮助文本以解释要求给用户，验证给定的密码，如果不符合要求则返回错误消息，并可选择定义一个回调函数，以在用户密码更改时进行通知。验证器还可以具有可选的设置，以微调其行为。
\n验证由 AUTH_PASSWORD_VALIDATORS 控制。默认的设置是一个空列表，这意味着默认是不验证的。在使用默认的 startproject 创建的新项目中，默认启用了验证器集合。
默认情况下，验证器在重置或修改密码的表单中使用，也可以在 createsuperuser 和 changepassword 命令中使用。验证器不能应用在模型层，比如 User.objects.create_user() 和 create_superuser() ，因为我们假设开发者（非用户）会在模型层与 Django 进行交互，也因为模型验证不会在创建模型时自动运行。
在 AUTH_PASSWORD_VALIDATORS 中设置密码验证：
AUTH_PASSWORD_VALIDATORS = [\n {\n "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",\n },\n {\n "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",\n "OPTIONS": {\n "min_length": 9,\n },\n },\n {\n "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",\n },\n {\n "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",\n },\n]\n这个例子启用了所有包含的验证器：
\nUserAttributeSimilarityValidator 检查密码和一组用户属性集合之间的相似性。
MinimumLengthValidator 用来检查密码是否符合最小长度。这个验证器可以自定义设置：它现在需要最短9位字符，而不是默认的8个字符。
CommonPasswordValidator 检查密码是否在常用密码列表中。默认情况下，它会与列表中的2000个常用密码作比较。
NumericPasswordValidator 检查密码是否是完全是数字的。
对于 UserAttributeSimilarityValidator 和 CommonPasswordValidator ，我们在这个例子里使用默认配置。NumericPasswordValidator 不需要设置。
帮助文本和来自密码验证器的任何错误信息始终按照 AUTH_PASSWORD_VALIDATORS 列出的顺序返回。
Django 包含了四种验证器：
\n验证密码是否达到最小长度要求。最小长度可以使用 min_length 参数进行自定义。
A hook for customizing the ValidationError error message. Defaults\nto "This password is too short. It must contain at least <min_length>\ncharacters.".
A hook for customizing the validator's help text. Defaults to "Your\npassword must contain at least <min_length> characters.".
验证密码与用户的某些属性足够不同。
\nuser_attributes 参数应该是可比较的用户属性名的可迭代参数。如果没有提供这个参数，默认使用：'username', 'first_name', 'last_name', 'email' 。不存在的属性会被忽略。
最大允许的密码相似度可以通过 max_similarity 参数设置在 0.1 到 1.0 的范围内。这将与 difflib.SequenceMatcher.quick_ratio() 的结果进行比较。0.1 的值会拒绝与 user_attributes 非常不同的密码，而 1.0 的值只会拒绝与属性值相同的密码。
A hook for customizing the ValidationError error message. Defaults\nto "The password is too similar to the <user_attribute>.".
A hook for customizing the validator's help text. Defaults to "Your\npassword can’t be too similar to your other personal information.".
Validates that the password is not a common password. This converts the\npassword to lowercase (to do a case-insensitive comparison) and checks it\nagainst a list of 20,000 common passwords created by Royce Williams.
\npassword_list_path 用来设置自定义的常用密码列表文件的路径。这个文件应该每行包含一个小写密码，并且文件是纯文本或 gzip 压缩过的。
A hook for customizing the ValidationError error message. Defaults\nto "This password is too common.".
A hook for customizing the validator's help text. Defaults to "Your\npassword can’t be a commonly used password.".
验证密码不是完全由数字组成。
\nA hook for customizing the ValidationError error message. Defaults\nto "This password is entirely numeric.".
A hook for customizing the validator's help text. Defaults to "Your\npassword can’t be entirely numeric.".
django.contrib.auth.password_validation 包含一些你可以在表单或其他地方调用的函数，用来集成密码检查。如果你使用自定义表单来进行密码设置或者你有允许密码设置的 API 调用，此功能会很有用。
验证密码。如果所有验证器验证密码有效，则返回 None 。如果一个或多个验证器拒绝此密码，将会引发 ValidationError 和验证器的错误信息。
user 对象是可选的：如果不提供用户对象，一些验证器将不能执行验证，并将接受所有密码。
通知所有验证器密码已经更改。这可以由验证器使用，例如防止密码重用。一旦密码更改成功，则调用此方法。
\n对于 AbstractBaseUser 子类，当调用 set_password() 是会将密码字段标记为 "dirty" ，这会在用户保存后调用 password_changed() 。
返回一个所有验证器帮助文案的列表。这些向用户解释了密码要求。
\n返回一个``<ul>`` ，包含所有帮助文案的 HTML 字符串。这在表单中添加密码验证时有帮助，因为你可以直接将输出传递到表单字段的 help_text 参数。
返回一个基于 validator_config 的验证器对象的集合。默认情况下，所有函数使用 AUTH_PASSWORD_VALIDATORS 定义的验证器，但通过一个验证器替代集合来调用此函数，然后向其他函数传递的密码验证器参数传递结果，将使用你自定义的验证器集合。当你有一个应用于大多数场景的通用的验证器集合时，需要一个自定义的集合来用于特殊情况。当你始终使用同一个验证器集合时，则不需要这个函数，因为默认使用是 AUTH_PASSWORD_VALIDATORS 的配置。
validator_config 的结构和 AUTH_PASSWORD_VALIDATORS 的结构相同。这个函数的返回值可以传递给上述函数列表的``password_validators`` 参数。
注意，如果将密码传递给其中一个函数，应该始终是明文密码，而不是哈希过的密码。
\n如果 Django 内置的验证器不满足你的需求，你可以编写自定义的验证器。验证器的接口很小。它们必须实现两个方法：
\nvalidate(self, password, user=None) ：验证密码。如果密码有效，返回 None ，否则引发 ValidationError 错误。你必须能够处理 user 为 None 的情况，如果这样会让验证器无法运行，只需返回 None 即可。
get_help_text() ：提供一个帮助文本向用户解释密码要求。
验证器的 AUTH_PASSWORD_VALIDATORS 中， OPTIONS 里的任何条目将会传递到构造器中。所有构造器参数应该有一个默认值。
这里是一个验证器的基本示例，其中包含一个可选的设置：
\nfrom django.core.exceptions import ValidationError\nfrom django.utils.translation import gettext as _\n\n\nclass MinimumLengthValidator:\n def __init__(self, min_length=8):\n self.min_length = min_length\n\n def validate(self, password, user=None):\n if len(password) < self.min_length:\n raise ValidationError(\n _("This password must contain at least %(min_length)d characters."),\n code="password_too_short",\n params={"min_length": self.min_length},\n )\n\n def get_help_text(self):\n return _(\n "Your password must contain at least %(min_length)d characters."\n % {"min_length": self.min_length}\n )\n你也可以实现 password_changed(password, user=None) ，在密码修改成功后调用。比如说用来防止密码重用。但是，如果你决定存储用户之前的密码，则不应该以明文形式存储。