在 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，則該方法應使 password 再執行 10,000 次 PBKDF2 迭代。

如果您的雜湊器沒有工作因子，請將該方法實作為空操作 (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 只會拒絕與屬性值相同的密碼。

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH)[原始碼]¶

驗證密碼不是常用密碼。這會將密碼轉換為小寫（進行不區分大小寫的比較），並根據 Royce Williams 建立的 20,000 個常用密碼的列表進行檢查。

password_list_path 可以設定為常用密碼的自訂檔案路徑。此檔案應包含每行一個小寫密碼，並且可以是純文字或 gzip 壓縮的。

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() 時，密碼欄位將被標記為「已變更」，這會在使用者儲存後觸發對 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()：提供幫助文字，向使用者說明要求。

在 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)，這會在密碼成功變更後呼叫。例如，這可以用來防止密碼重複使用。但是，如果您決定儲存使用者的先前密碼，則絕不應以明文形式儲存。