在 Django 中使用 Argon2¶

Argon2 是 2015 年密码哈希竞赛的获胜者，这是一场由社区组织的公开竞赛，旨在选择下一代哈希算法。它的设计初衷是，在定制硬件上计算它不会比在普通 CPU 上计算更容易。Argon2 密码哈希器的默认变体是 Argon2id。

Argon2 不是 Django 的默认选项，因为它需要第三方库。然而，密码哈希竞赛小组建议立即使用 Argon2，而不是 Django 支持的其他算法。

要将 Argon2id 用作默认存储算法，请执行以下操作

1. 安装argon2-cffi包。可以通过运行python -m pip install django[argon2]来完成此操作，这等同于python -m pip install argon2-cffi（以及 Django 的setup.cfg中的任何版本要求）。

2. 修改PASSWORD_HASHERS以首先列出Argon2PasswordHasher。也就是说，在你的设置文件中，你应该输入

   PASSWORD_HASHERS = [
       "django.contrib.auth.hashers.Argon2PasswordHasher",
       "django.contrib.auth.hashers.PBKDF2PasswordHasher",
       "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
       "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
       "django.contrib.auth.hashers.ScryptPasswordHasher",
   ]
   

   如果你需要 Django升级密码，请保留和/或添加此列表中的任何条目。

在 Django 中使用bcrypt¶

Bcrypt 是一种流行的密码存储算法，专门设计用于长期密码存储。由于它需要使用第三方库，所以它不是 Django 使用的默认算法，但由于许多人可能希望使用它，因此 Django 支持 bcrypt，且几乎不需要付出任何努力。

要将 Bcrypt 用作默认存储算法，请执行以下操作

1. 安装bcrypt包。可以通过运行python -m pip install django[bcrypt]来完成此操作，这等同于python -m pip install bcrypt（以及 Django 的setup.cfg中的任何版本要求）。

2. 修改 PASSWORD_HASHERS 将 BCryptSHA256PasswordHasher 列为第一位。也就是说，在你的设置文件中，你应该这样写

   PASSWORD_HASHERS = [
       "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
       "django.contrib.auth.hashers.PBKDF2PasswordHasher",
       "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
       "django.contrib.auth.hashers.Argon2PasswordHasher",
       "django.contrib.auth.hashers.ScryptPasswordHasher",
   ]
   

   如果你需要 Django升级密码，请保留和/或添加此列表中的任何条目。

就这样——现在你的 Django 安装将使用 Bcrypt 作为默认存储算法。

在 Django 中使用 scrypt¶

scrypt 与 PBKDF2 和 bcrypt 类似，使用一定数量的迭代来减缓暴力攻击。然而，由于 PBKDF2 和 bcrypt 不需要大量内存，因此拥有足够资源的攻击者可以发起大规模并行攻击，以加快攻击进程。 scrypt 专门设计为与其他基于密码的密钥派生函数相比使用更多内存，以限制攻击者可使用的并行性，有关更多详细信息，请参见 RFC 7914。

若要将 scrypt 用作默认存储算法，请执行以下操作

1. 修改 PASSWORD_HASHERS 将 ScryptPasswordHasher 列为第一位。也就是说，在你的设置文件中

   PASSWORD_HASHERS = [
       "django.contrib.auth.hashers.ScryptPasswordHasher",
       "django.contrib.auth.hashers.PBKDF2PasswordHasher",
       "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
       "django.contrib.auth.hashers.Argon2PasswordHasher",
       "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
   ]
   

   如果你需要 Django升级密码，请保留和/或添加此列表中的任何条目。

增加盐熵¶

为了防止彩虹表攻击，大多数密码哈希在其密码哈希中包含一个盐。盐本身是一个随机值，它增加了彩虹表的大小，从而增加了彩虹表的成本，并且目前在 BasePasswordHasher 中通过 salt_entropy 值设置为 128 位。随着计算和存储成本的降低，此值应该提高。在实现自己的密码哈希器时，你可以自由地覆盖此值，以使用所需的密码哈希熵级别。 salt_entropy 以比特为单位进行测量。

增加工作因子¶

work_factor * 2 * block_size * 64

密码升级¶

当用户登录时，如果其密码存储在首选算法之外的任何算法中，Django 会自动将算法升级为首选算法。这意味着 Django 的旧安装将随着用户登录而自动变得更加安全，并且还意味着您可以切换到新的（更好的）存储算法，因为它们会被发明出来。

但是，Django 只能升级 PASSWORD_HASHERS 中提到的算法使用的密码，因此在升级到新系统时，您应确保绝不从该列表中删除条目。如果您这样做，使用未提及算法的用户将无法升级。在增加（或减少）PBKDF2 迭代次数、bcrypt 轮数或 argon2 属性时，将更新哈希密码。

请注意，如果数据库中的所有密码未使用默认哈希算法进行编码，则由于使用非默认算法编码密码的用户登录请求持续时间与不存在用户（运行默认哈希）的登录请求持续时间不同，您可能会受到用户枚举时序攻击的攻击。您可以通过升级较旧的密码哈希来缓解此问题。

无需登录即可升级密码¶

如果您有使用 MD5 等较旧、较弱哈希的现有数据库，您可能希望自己升级这些哈希，而不是等到用户登录时再进行升级（如果用户未返回您的网站，则可能永远不会发生）。在这种情况下，您可以使用“包装”密码哈希。

对于此示例，我们将迁移一组 MD5 哈希以使用 PBKDF2(MD5(password))，并添加相应的密码哈希，以检查用户在登录时是否输入了正确的密码。我们假设我们正在使用内置的User模型，并且我们的项目有一个accounts应用程序。您可以修改模式以使用任何算法或自定义用户模型。

首先，我们将添加自定义哈希

from django.contrib.auth.hashers import (
    PBKDF2PasswordHasher,
    MD5PasswordHasher,
)


class PBKDF2WrappedMD5PasswordHasher(PBKDF2PasswordHasher):
    algorithm = "pbkdf2_wrapped_md5"

    def encode_md5_hash(self, md5_hash, salt, iterations=None):
        return super().encode(md5_hash, salt, iterations)

    def encode(self, password, salt, iterations=None):
        _, _, md5_hash = MD5PasswordHasher().encode(password, salt).split("$", 2)
        return self.encode_md5_hash(md5_hash, salt, iterations)

数据迁移可能如下所示

from django.db import migrations

from ..hashers import PBKDF2WrappedMD5PasswordHasher


def forwards_func(apps, schema_editor):
    User = apps.get_model("auth", "User")
    users = User.objects.filter(password__startswith="md5$")
    hasher = PBKDF2WrappedMD5PasswordHasher()
    for user in users:
        algorithm, salt, md5_hash = user.password.split("$", 2)
        user.password = hasher.encode_md5_hash(md5_hash, salt)
        user.save(update_fields=["password"])


class Migration(migrations.Migration):
    dependencies = [
        ("accounts", "0001_initial"),
        # replace this with the latest migration in contrib.auth
        ("auth", "####_migration_name"),
    ]

    operations = [
        migrations.RunPython(forwards_func),
    ]

请注意，此迁移将花费数分钟时间处理数千名用户，具体取决于您的硬件速度。

最后，我们将添加PASSWORD_HASHERS设置

PASSWORD_HASHERS = [
    "django.contrib.auth.hashers.PBKDF2PasswordHasher",
    "accounts.hashers.PBKDF2WrappedMD5PasswordHasher",
]

在此列表中包括您的网站使用的任何其他哈希。

包含的哈希¶

Django 中包含的哈希完整列表如下

[
    "django.contrib.auth.hashers.PBKDF2PasswordHasher",
    "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
    "django.contrib.auth.hashers.Argon2PasswordHasher",
    "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
    "django.contrib.auth.hashers.BCryptPasswordHasher",
    "django.contrib.auth.hashers.ScryptPasswordHasher",
    "django.contrib.auth.hashers.MD5PasswordHasher",
]

相应的算法名称如下

• pbkdf2_sha256
• pbkdf2_sha1
• argon2
• bcrypt_sha256
• bcrypt
• scrypt
• md5

编写您自己的哈希¶

如果您编写自己的密码哈希器，其中包含诸如迭代次数之类的作业因子，则应实现 harden_runtime(self, password, encoded) 方法，以弥合 encoded 密码中提供的作业因子与哈希器的默认作业因子之间的运行时差距。这可以防止由于使用较旧迭代次数对密码进行编码的用户登录请求与不存在的用户（运行默认哈希器的默认迭代次数）之间的差异而导致的用户枚举时序攻击。

以 PBKDF2 为例，如果 encoded 包含 20,000 次迭代，而哈希器的默认 iterations 为 30,000，则该方法应通过 PBKDF2 的另外 10,000 次迭代来运行 password。

如果您的哈希器没有作业因子，请将该方法实现为无操作（pass）。

启用密码验证¶

密码验证在 AUTH_PASSWORD_VALIDATORS 设置中配置

AUTH_PASSWORD_VALIDATORS = [
    {
        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
        "OPTIONS": {
            "min_length": 9,
        },
    },
    {
        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
    },
    {
        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
    },
]

此示例启用了所有四个包含的验证器

• UserAttributeSimilarityValidator，它检查密码与用户的一组属性之间的相似性。
• MinimumLengthValidator，它检查密码是否满足最小长度。此验证器配置了一个自定义选项：现在它要求最小长度为九个字符，而不是默认的八个字符。
• CommonPasswordValidator，它检查密码是否出现在常见密码列表中。默认情况下，它与包含 20,000 个常见密码的列表进行比较。
• NumericPasswordValidator，它检查密码是否完全不是数字。

对于 UserAttributeSimilarityValidator 和 CommonPasswordValidator，我们在本示例中使用默认设置。 NumericPasswordValidator 没有设置。

密码验证器的帮助文本和任何错误始终按它们在 AUTH_PASSWORD_VALIDATORS 中列出的顺序返回。

包含的验证器¶

Django 包含四个验证器

class MinimumLengthValidator(min_length=8)¶

验证密码是否达到最小长度。最小长度可以通过 min_length 参数进行定制。

class UserAttributeSimilarityValidator(user_attributes=DEFAULT_USER_ATTRIBUTES, max_similarity=0.7)¶

验证密码与用户的某些属性有足够的差异。

user_attributes 参数应为要比较的用户属性名称的可迭代对象。如果未提供此参数，则使用默认值： 'username', 'first_name', 'last_name', 'email'。不存在的属性将被忽略。

可以使用 max_similarity 参数在 0.1 到 1.0 的范围内设置允许的密码最大相似度。这与 difflib.SequenceMatcher.quick_ratio() 的结果进行比较。0.1 的值拒绝密码，除非它们与 user_attributes 存在很大差异，而 1.0 的值仅拒绝与属性值相同的密码。

在 Django 2.2.26 中更改

max_similarity 参数的最小值限制为 0.1。

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH)¶

验证密码不是常见密码。这会将密码转换为小写（执行不区分大小写的比较），并针对 Royce Williams 创建的 20,000 个常见密码列表进行检查。

password_list_path 可以设置为常见密码自定义文件的路径。此文件应包含每行一个密码小写，可以是纯文本或 gzip 压缩文件。

在 Django 4.2 中更改

20,000 个常见密码列表已更新为最新版本。

class NumericPasswordValidator¶

验证密码不是完全数字的。

集成验证¶

django.contrib.auth.password_validation 中有一些函数，你可以从自己的表单或其他代码中调用这些函数来集成密码验证。例如，如果你对密码设置使用自定义表单，或者如果你有允许设置密码的 API 调用，这会很有用。

validate_password(password, user=None, password_validators=None)¶

验证密码。如果所有验证器都发现密码有效，则返回 None。如果一个或多个验证器拒绝密码，则引发 ValidationError，其中包含来自验证器的所有错误消息。

user 对象是可选的：如果未提供，则某些验证器可能无法执行任何验证，并且会接受任何密码。

password_changed(password, user=None, password_validators=None)¶

通知所有验证器密码已更改。密码重用预防验证器等验证器可以使用此功能。应在成功更改密码后调用此功能。

对于 AbstractBaseUser 的子类，在调用 set_password() 时，密码字段将标记为“dirty”，这会在保存用户后触发对 password_changed() 的调用。

password_validators_help_texts(password_validators=None)¶

返回所有验证器的帮助文本列表。这些文本向用户解释密码要求。

password_validators_help_text_html(password_validators=None)¶

返回一个 HTML 字符串，其中包含 <ul> 中的所有帮助文本。在向表单添加密码验证时，此功能很有用，因为你可以将输出直接传递给表单字段的 help_text 参数。

get_password_validators(validator_config)¶

根据 validator_config 参数返回一组验证器对象。默认情况下，所有函数都使用在 AUTH_PASSWORD_VALIDATORS 中定义的验证器，但通过使用一组备用验证器调用此函数，然后将结果传递到其他函数的 password_validators 参数，将改为使用自定义验证器组。在大多数情况下，如果你有一组典型的验证器可供使用，但也有需要自定义组的特殊情况，此功能非常有用。如果你始终使用同一组验证器，则无需使用此函数，因为默认情况下会使用 AUTH_PASSWORD_VALIDATORS 中的配置。

validator_config 的结构与 AUTH_PASSWORD_VALIDATORS 的结构相同。此函数的返回值可以传递到上面列出的函数的 password_validators 参数。

请注意，将密码传递到其中一个函数的位置，应始终为明文密码 - 而不是哈希密码。

编写你自己的验证器¶

如果 Django 的内置验证器不够用，你可以编写自己的密码验证器。验证器的界面相当小。它们必须实现两个方法

• validate(self, password, user=None)：验证密码。如果密码有效，则返回 None，如果密码无效，则引发带有错误消息的 ValidationError。你必须能够处理 user 为 None 的情况 - 如果这意味着你的验证器无法运行，则返回 None 以表示没有错误。
• get_help_text()：提供帮助文本向用户解释要求。

验证器中的 OPTIONS 中的任何项目在 AUTH_PASSWORD_VALIDATORS 中会传递给构造函数。所有构造函数参数都应具有默认值。

下面是一个验证器的基本示例，带有一个可选设置

from django.core.exceptions import ValidationError
from django.utils.translation import gettext as _


class MinimumLengthValidator:
    def __init__(self, min_length=8):
        self.min_length = min_length

    def validate(self, password, user=None):
        if len(password) < self.min_length:
            raise ValidationError(
                _("This password must contain at least %(min_length)d characters."),
                code="password_too_short",
                params={"min_length": self.min_length},
            )

    def get_help_text(self):
        return _(
            "Your password must contain at least %(min_length)d characters."
            % {"min_length": self.min_length}
        )

您还可以实现 password_changed(password, user=None)，它将在成功更改密码后调用。例如，这可用于防止重复使用密码。但是，如果您决定存储用户的先前密码，则切勿以明文形式存储。