在 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 的 pyproject.toml 中的任何版本要求）。

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 的 pyproject.toml 中的任何版本要求）。

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，则该方法应通过另外 10,000 次 PBKDF2 迭代运行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)[source]¶

验证密码是否达到最小长度。最小长度可以使用min_length参数自定义。

class UserAttributeSimilarityValidator(user_attributes=DEFAULT_USER_ATTRIBUTES, max_similarity=0.7)[source]¶

验证密码与用户的某些属性是否足够不同。

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

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

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH)[source]¶

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

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

class NumericPasswordValidator[source]¶

验证密码不是完全由数字组成。

集成验证¶

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

validate_password(password, user=None, password_validators=None)[source]¶

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

user对象是可选的：如果没有提供它，某些验证器可能无法执行任何验证，并将接受任何密码。

password_changed(password, user=None, password_validators=None)[source]¶

通知所有验证器密码已更改。这可用于防止密码重用的验证器等。密码成功更改后，应调用此函数一次。

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

password_validators_help_texts(password_validators=None)[source]¶

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

password_validators_help_text_html(password_validators=None)¶

返回一个HTML字符串，其中包含所有帮助文本，这些文本位于<ul>中。当向表单添加密码验证时，这非常有用，因为您可以将输出直接传递到表单字段的help_text参数。

get_password_validators(validator_config)[source]¶

根据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()：提供帮助文本以向用户解释要求。

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

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

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)，这将在密码成功更改后调用。例如，这可以用于防止密码重用。但是，如果您决定存储用户的先前密码，则决不应该以明文形式存储。