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

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

Как Django хранит пароли

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

Атрибут password объекта User представляет собой строку в этом формате:

<algorithm>$<iterations>$<salt>$<hash>

Это компоненты, используемые для хранения пароля пользователя, разделенные символом «доллар»: алгоритм хэширования, количество итераций алгоритма (фактор сложности), случайный соль и полученный хэш пароля. Алгоритм — это один из нескольких односторонних алгоритмов хэширования или хранения паролей, которые может использовать Django; см. ниже. Итерации описывают количество раз, когда алгоритм выполняется над хэшем. Соль — это случайное семя, используемое, а хэш — это результат односторонней функции.

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

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

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

Значение по умолчанию для PASSWORD_HASHERS:

PASSWORD_HASHERS = [
    '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 будет использовать PBKDF2 для хранения всех паролей, но будет поддерживать проверку паролей, хранящихся с помощью PBKDF2SHA1, argon2 и bcrypt.

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

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

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

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

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

1. Установите библиотеку argon2-cffi. Это можно сделать, выполнив pip install django[argon2], что эквивалентно pip install argon2-cffi, (вместе с любыми требованиями к версии из setup.py 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.BCryptPasswordHasher',
   ]
   

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

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

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

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

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

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

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

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

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

Увеличение фактора сложности алгоритма паролей

PBKDF2 и bcrypt

Алгоритмы PBKDF2 и bcrypt используют определенное количество итераций или циклов хэширования. Это преднамеренно замедляет злоумышленников, затрудняя атаки на хэшированные пароли. Однако с ростом вычислительной мощности количество итераций необходимо увеличивать. Мы выбрали разумное значение по умолчанию (и будем увеличивать его с каждым выпуском Django), но вы можете настроить его в зависимости от ваших потребностей в безопасности и доступной вычислительной мощности. Для этого вы создадите подкласс соответствующего алгоритма и переопределите параметры iterations. Например, чтобы увеличить количество итераций, используемых по умолчанию алгоритмом PBKDF2:

1. Создайте подкласс django.contrib.auth.hashers.PBKDF2PasswordHasher:

   from django.contrib.auth.hashers import PBKDF2PasswordHasher
   
   class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
       """
       A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.
       """
       iterations = PBKDF2PasswordHasher.iterations * 100
   

   Сохраните его где-нибудь в вашем проекте. Например, вы можете поместить его в файл, как myproject/hashers.py.

2. Добавьте ваш новый хэширователь в качестве первого элемента в PASSWORD_HASHERS:

   PASSWORD_HASHERS = [
       'myproject.hashers.MyPBKDF2PasswordHasher',
       '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 будет использовать больше итераций при хранении паролей с помощью PBKDF2.

Argon2

У Argon2 есть три атрибута, которые можно настроить:

1. time_cost контролирует количество итераций внутри хэша.
2. memory_cost контролирует размер памяти, который должен использоваться во время вычисления хэша.
3. parallelism контролирует, на скольких процессорах вычисление хэша можно распараллелить.

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

1. Выберите parallelism в качестве количества потоков, которые вы можете выделить для вычисления хэша.
2. Выберите memory_cost в качестве объёма памяти в KiB, которые вы можете выделить.
3. Настройте time_cost и измерьте время хэширования пароля. Выберите значение time_cost, которое займет приемлемое время для вас. Если time_cost установлено в 1, это слишком медленно, уменьшите memory_cost.

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

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

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

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

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

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

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

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

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
• argon2
• bcrypt_sha256
• bcrypt
• sha1
• md5
• unsalted_sha1
• unsalted_md5
• crypt

Написание собственного хешера паролей

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

Примером может служить PBKDF2. Если encoded содержит 20 000 итераций, а стандартное значение iterations хешера равно 30 000, метод должен выполнить password еще 10 000 итераций PBKDF2.

Если ваш хешер не имеет коэффициента сложности, реализуйте метод как недействующий (pass).

Ручное управление паролем пользователя

Модуль django.contrib.auth.hashers предоставляет набор функций для создания и проверки хешированных паролей. Вы можете использовать их независимо от модели User.

check_password(password, encoded) [source]

Если вы хотите вручную аутентифицировать пользователя, сравнив текстовый пароль с хешированным паролем в базе данных, используйте удобную функцию check_password(). Она принимает два аргумента: текстовый пароль для проверки и полное значение поля password пользователя в базе данных для проверки, и возвращает True, если они совпадают, и False в противном случае.

make_password(password, salt=None, hasher='default') [source]

Создаёт хешированный пароль в формате, используемом этим приложением. Он принимает один обязательный аргумент: пароль в текстовом формате. По желанию вы можете указать соль и алгоритм хеширования для использования, если не хотите использовать значения по умолчанию (первая запись в настройке PASSWORD_HASHERS). См. Включенные хешеры для имени алгоритма каждого хешера. Если аргумент password имеет значение None, возвращается непригодный пароль (который никогда не будет принят функцией check_password()).

is_password_usable(encoded_password) [source]

Проверяет, является ли заданная строка хешированным паролем, который может быть проверен с помощью check_password().

Проверка паролей

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

Каждый валидатор пароля должен предоставить подсказку для объяснения требований пользователю, проверить данный пароль и вернуть сообщение об ошибке, если он не соответствует требованиям, и необязательно получить пароли, которые были установлены. У валидаторов также могут быть необязательные настройки для тонкой настройки их поведения.

Проверка контролируется настройкой AUTH_PASSWORD_VALIDATORS. Значение по умолчанию для этой настройки — пустой список, что означает отсутствие применённых валидаторов. В новых проектах, созданных с помощью шаблона startproject по умолчанию, включён простой набор валидаторов.

По умолчанию валидаторы используются в формах для сброса или изменения паролей, а также в командной строке управления createsuperuser и changepassword. Валидаторы не применяются на уровне модели, например, в User.objects.create_user() и create_superuser(), потому что мы предполагаем, что разработчики, а не пользователи, взаимодействуют с Django на этом уровне, а также потому, что проверка модели не выполняется автоматически при создании моделей.

Включение проверки паролей

Проверка паролей настраивается в настройке 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, который проверяет, не встречается ли пароль в списке распространённых паролей. По умолчанию он сравнивается со списком из 1000 распространённых паролей.
• 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'. Атрибуты, которых нет, игнорируются.

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

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH) [source]

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

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

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