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

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

Argon2 is the winner of the 2015 Password Hashing Competition, a community organized open competition to select a next generation hashing algorithm. It’s designed not to be easier to compute on custom hardware than it is to compute on an ordinary CPU. The default variant for the Argon2 password hasher is Argon2id.

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

To use Argon2id as your default storage algorithm, do the following:

1. Установите argon2-cffi library. Это можно сделать, запустив 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 upgrade passwords.

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

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

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

1. Установите bcrypt library. Это можно сделать, запустив 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 upgrade passwords.

Вот и все - теперь ваша установка Django будет использовать Bcrypt в качестве алгоритма хранения по умолчанию.

Using scrypt with Django¶

scrypt похож на PBKDF2 и bcrypt тем, что использует заданное количество итераций для замедления атак методом перебора. Однако, поскольку PBKDF2 и bcrypt не требуют большого объема памяти, злоумышленники, обладающие достаточными ресурсами, могут проводить масштабные параллельные атаки, чтобы ускорить процесс атаки. scrypt специально разработан для использования большего объема памяти по сравнению с другими функциями выведения ключей на основе паролей, чтобы ограничить объем параллелизма, который может использовать злоумышленник.

To use scrypt as your default storage algorithm, do the following:

1. Modify PASSWORD_HASHERS to list ScryptPasswordHasher first. That is, in your settings file:

   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 upgrade passwords.

Increasing the salt entropy¶

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

Увеличение рабочего коэффициента¶

work_factor * 2 * block_size * 64

Обновление пароля¶

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

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

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

Обновление пароля без необходимости входа в систему¶

If you have an existing database with an older, weak hash such as MD5, you might want to upgrade those hashes yourself instead of waiting for the upgrade to happen when a user logs in (which may never happen if a user doesn’t return to your site). In this case, you can use a «wrapped» password hasher.

For this example, we’ll migrate a collection of MD5 hashes to use PBKDF2(SHA1(password)) and add the corresponding password hasher for checking if a user entered the correct password on login. We assume we’re using the built-in User model and that our project has an accounts app. You can modify the pattern to work with any algorithm or with a custom user model.

Сначала мы добавим пользовательский хэшер:

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)[исходный код]¶

Validates that the password is of a minimum length. The minimum length can be customized with the min_length parameter.

class UserAttributeSimilarityValidator(user_attributes=DEFAULT_USER_ATTRIBUTES, max_similarity=0.7)[исходный код]¶

Validates that the password is sufficiently different from certain attributes of the user.

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

The maximum allowed similarity of passwords can be set on a scale of 0.1 to 1.0 with the max_similarity parameter. This is compared to the result of difflib.SequenceMatcher.quick_ratio(). A value of 0.1 rejects passwords unless they are substantially different from the user_attributes, whereas a value of 1.0 rejects only passwords that are identical to an attribute’s value.

Changed in Django 2.2.26:

Параметр max_similarity был ограничен минимальным значением 0,1.

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH)[исходный код]¶

Validates that the password is not a common password. This converts the password to lowercase (to do a case-insensitive comparison) and checks it against a list of 20,000 common password created by Royce Williams.

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

Changed in Django 4.2:

Список из 20 000 распространенных паролей был обновлен до самой последней версии.

class NumericPasswordValidator[исходный код]¶

Validate that the password is not entirely numeric.

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

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

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