Управление паролями в Django

Использование Argon2 с Django

Argon2 — победитель конкурса 2015 года по хэшированию паролей Password Hashing Competition, организованного сообществом, для выбора алгоритма хэширования следующего поколения. Он разработан таким образом, чтобы его вычисление на специализированном оборудовании не было проще, чем на обычном процессоре. По умолчанию для хэшера паролей Argon2 используется вариант Argon2id.

Argon2 не является значением по умолчанию для Django, поскольку он требует сторонней библиотеки. Однако панель конкурса по хэшированию паролей рекомендует немедленное использование Argon2 вместо других поддерживаемых Django алгоритмов.

Чтобы использовать Argon2id в качестве алгоритма хранения по умолчанию, выполните следующие действия:

1. Установите пакет argon2-cffi. Это можно сделать, выполнив команду python -m pip install django[argon2], что эквивалентно python -m pip install argon2-cffi (вместе с любыми требованиями к версии из pyproject.toml Django).

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 обновлял пароли.

Использование bcrypt с Django

Bcrypt — популярный алгоритм хранения паролей, специально разработанный для долгосрочного хранения паролей. Он не является значением по умолчанию, используемым Django, так как требует использования сторонних библиотек, но так как многие пользователи могут захотеть его использовать, Django поддерживает bcrypt с минимальными усилиями.

Чтобы использовать Bcrypt в качестве алгоритма хранения по умолчанию, выполните следующие действия:

1. Установите пакет bcrypt. Это можно сделать, выполнив команду python -m pip install django[bcrypt], что эквивалентно python -m pip install bcrypt (вместе с любыми требованиями к версии из pyproject.toml Django).

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 в качестве алгоритма хранения по умолчанию.

Использование scrypt с Django

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 обновлял пароли.

Увеличение энтропии соли

Большинство хэшей паролей включают соль вместе с хэшем пароля для защиты от атак с использованием радужных таблиц. Сама соль — это случайное значение, которое увеличивает размер и, следовательно, стоимость радужной таблицы и в настоящее время установлена на 128 бит с значением salt_entropy в BasePasswordHasher. По мере снижения вычислительных и хранилищных затрат это значение следует повышать. При реализации собственного хэшера паролей вы можете переопределить это значение, чтобы использовать желаемый уровень энтропии для хэшей паролей. salt_entropy измеряется в битах.

Увеличение фактора работы алгоритма

work_factor * 2 * block_size * 64

Обновление паролей

При входе пользователей, если их пароли хранятся с использованием алгоритма отличного от предпочтительного, Django автоматически обновит алгоритм до предпочтительного. Это означает, что старые установки Django станут автоматически более безопасными при каждом входе пользователя, а также это означает, что вы можете переключиться на новые (и лучшие) алгоритмы хранения, по мере их изобретения.

Однако Django может обновлять только пароли, которые используют алгоритмы, упомянутые в PASSWORD_HASHERS, поэтому при обновлении до новых систем вам следует убедиться, что вы никогда не удаляете элементы из этого списка. Если вы это сделаете, пользователи, использующие неуказанные алгоритмы, не смогут обновить пароли. Хешированные пароли будут обновлены при увеличении (или уменьшении) количества итераций PBKDF2, раундов bcrypt или атрибутов argon2.

Обратите внимание, что если все пароли в вашей базе данных не закодированы в алгоритме хешера по умолчанию, вы можете быть уязвимы для атаки на перечисление пользователей с помощью тайминга из-за различия между продолжительностью запроса входа в систему для пользователя с паролем, закодированным в алгоритме, отличном от стандартного, и продолжительностью запроса входа в систему для несуществующего пользователя (который использует стандартный хешер). Вы можете смягчить это, обновив старые хеши паролей.

Обновление паролей без требования входа

Если у вас есть существующая база данных со старым, слабым хешем, таким как MD5, вы можете обновить эти хеши самостоятельно, вместо того, чтобы ждать обновления при входе пользователя (что может никогда не произойти, если пользователь не возвращается на ваш сайт). В этом случае вы можете использовать «обёрнутый» хешер паролей.

В этом примере мы мигрируем набор хешей MD5 для использования PBKDF2(MD5(пароль)) и добавим соответствующий хешер паролей для проверки, ввёл ли пользователь правильный пароль при входе. Мы предполагаем, что мы используем встроенную модель 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.

Если ваш хешер не имеет фактора работы, реализуйте метод как no-op (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.

get_error_message() [source]

Добавлен в Django 5.2.

Способ настройки сообщения об ошибке ValidationError. По умолчанию это "This password is too short. It must contain at least <min_length> characters.".

get_help_text() [source]

Способ настройки подсказки валидатора. По умолчанию это "Your password must contain at least <min_length> characters.".

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

Проверяет, что пароль достаточно отличается от определённых атрибутов пользователя.

Параметр user_attributes должен быть итерируемым списком имён атрибутов пользователя для сравнения. Если этот аргумент не указан, используется значение по умолчанию: 'username', 'first_name', 'last_name', 'email'. Несуществующие атрибуты игнорируются.

Максимально допустимое сходство паролей можно установить в диапазоне от 0,1 до 1,0 с помощью параметра max_similarity. Это сравнивается с результатом difflib.SequenceMatcher.quick_ratio(). Значение 0,1 отклоняет пароли, если они существенно отличаются от значения user_attributes, в то время как значение 1,0 отклоняет только пароли, идентичные значению атрибута.

get_error_message() [source]

Добавлен в Django 5.2.

Способ настройки сообщения об ошибке ValidationError. По умолчанию это "The password is too similar to the <user_attribute>.".

get_help_text() [source]

Способ настройки подсказки валидатора. По умолчанию это "Your password can’t be too similar to your other personal information.".

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH) [source]

Проверяет, что пароль не является общим паролем. Преобразует пароль в нижний регистр (для выполнения сравнения без учёта регистра) и проверяет его по списку из 20 000 общих паролей, созданных Royce Williams.

Параметр password_list_path может быть установлен на путь к пользовательскому файлу общих паролей. Этот файл должен содержать по одному паролю в нижнем регистре на строке и может быть текстовым или сжатым в формате gzip.

get_error_message() [source]

Добавлен в Django 5.2.

Способ настройки сообщения об ошибке ValidationError. По умолчанию это "This password is too common.".

get_help_text() [source]

Способ настройки подсказки валидатора. По умолчанию это "Your password can’t be a commonly used password.".

class NumericPasswordValidator [source]

Проверяет, что пароль не состоит целиком из цифр.

get_error_message() [source]

Добавлен в Django 5.2.

Способ настройки сообщения об ошибке ValidationError. По умолчанию это "This password is entirely numeric.".

get_help_text() [source]

Способ настройки подсказки валидатора. По умолчанию это "Your password can’t be entirely numeric.".

Интеграция валидации

В модуле 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(): предоставляет текст подсказки для объяснения требований пользователю.

Любые элементы в 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), который будет вызван после успешного изменения пароля. Это можно использовать, например, для предотвращения повторного использования паролей. Однако, если вы решите хранить предыдущие пароли пользователя, никогда не делайте этого в виде открытого текста.