Использование bcrypt с 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.

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

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

1. Install the argon2-cffi library. This can be done by running python -m pip install django[argon2], which is equivalent to python -m pip install argon2-cffi (along with any version requirement from Django’s setup.cfg).

2. Измените PASSWORD_HASHERS так, чтобы BCryptSHA256PasswordHasher был указан первым. То есть, в файле конфигурации надо сделать так:

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

   Сохраните и/или добавьте любые записи в этот список, если вам нужно, чтобы Django обновил пароли.

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

Bcrypt является популярным алгоритмом для хранения паролей, который специально разработан для хранения «долгих» паролей. Данный алгоритм не выбран в качестве стандартного в Django так как он требует использования внешних библиотек, но раз он используется многими, то Django поддерживает его, требуя минимальных усилий по его установке.

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

1. Install the bcrypt library. This can be done by running python -m pip install django[bcrypt], which is equivalent to python -m pip install bcrypt (along with any version requirement from Django’s 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 обновил пароли.

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

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

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

Увеличение сложности хэша¶

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

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

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

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

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

If you have an existing database with an older, weak hash such as MD5 or SHA1, 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 SHA1 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, SHA1PasswordHasher,
)


class PBKDF2WrappedSHA1PasswordHasher(PBKDF2PasswordHasher):
    algorithm = 'pbkdf2_wrapped_sha1'

    def encode_sha1_hash(self, sha1_hash, salt, iterations=None):
        return super().encode(sha1_hash, salt, iterations)

    def encode(self, password, salt, iterations=None):
        _, _, sha1_hash = SHA1PasswordHasher().encode(password, salt).split('$', 2)
        return self.encode_sha1_hash(sha1_hash, salt, iterations)

Миграция данных может выглядеть примерно так:

from django.db import migrations

from ..hashers import PBKDF2WrappedSHA1PasswordHasher


def forwards_func(apps, schema_editor):
    User = apps.get_model('auth', 'User')
    users = User.objects.filter(password__startswith='sha1$')
    hasher = PBKDF2WrappedSHA1PasswordHasher()
    for user in users:
        algorithm, salt, sha1_hash = user.password.split('$', 2)
        user.password = hasher.encode_sha1_hash(sha1_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.PBKDF2WrappedSHA1PasswordHasher',
]

Включите в этот список любые другие хешеры, которые использует ваш сайт.

Включенные хешеры¶

Полный список хэшеров, включенных в 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.SHA1PasswordHasher',
    'django.contrib.auth.hashers.MD5PasswordHasher',
    'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher',
    'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',
    'django.contrib.auth.hashers.CryptPasswordHasher',
]

Соответствующие названия алгоритмов:

• pbkdf2_sha256

• pbkdf2_sha1

• аргон2

• bcrypt_sha256

• bcrypt

• sha1

• md5

• unsalted_sha1

• unsalted_md5

• crypt

Написание собственного хэшера¶

Если вы пишете свой собственный хэшер паролей, который содержит рабочий фактор, такой как количество итераций, вам следует реализовать метод Harden_runtime(self, пароль, закодированный) для устранения разрыва во время выполнения между рабочим фактором, указанным в «закодированном» пароле, и рабочим фактором хэшера по умолчанию. Это предотвращает атаку по времени перечисления пользователей из-за разницы между запросом на вход в систему для пользователя с паролем, закодированным в более старом количестве итераций, и несуществующим пользователем (который выполняет количество итераций хэшера по умолчанию).

Если взять в качестве примера PBKDF2, то если encoded содержит 20 000 итераций, а итерации по умолчанию для хэшера равны 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)¶

Validates whether the password meets 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 whether the password is sufficiently different from certain attributes of the user.

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

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

Changed in Django 2.2.26:

The max_similarity parameter was limited to a minimum value of 0.1.

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH)¶

Validates whether 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 можно указать путь к пользовательскому файлу общих паролей. Этот файл должен содержать один пароль в нижнем регистре в каждой строке и может быть в виде обычного текста или в формате gzip.

class NumericPasswordValidator¶

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