O gerenciamento de senha é algo que não deve ser reinventado desnecessariamente, e o Django se esforça para fornecer um conjunto de ferramentas seguras e flexíveis para gerenciar senhas de usuários. Este documento descreve como o Django armazena senhas, como o armazenamento de “hashes” pode ser configurado, e algumas utilidade para trabalhar com senhas criptografadas.
\n\nO Django fornece um sistema flexível de armazenamento de senhas e usa PBKDF2 por padrão.
\nO atributo password de um objeto User é uma string nesse formato:
<algorithm>$<iterations>$<salt>$<hash>\nEstes são os componentes usados para armazenamento de senha do “User”, separados pelo caracter de sinal do dólar e consistem em: o algoritmo de “hash”, o número de iterações do algoritmo (fator de trabalho), o “salt” randômico, e o “hash” de senha resultante. O algoritmo é um dos vários algoritmos “hash” de via única ou de armazenamento de senha que o Django pode usar; veja abaixo. O iterações descreve o número de vezes que o algoritmo é executado sobre o “hash”. “Salt” é a string randômica inicial usada e o “hash” é o resultado da função de via única.
\nPor padrão, Django usa o algoritmo PBKDF2 com um hash SHA256, um mecanismo de elasticidade de senha recomendado pelo NIST. Isso deve ser suficiente para a maior parte dos usuários: é bastante seguro, e requer quantidades massivas de tempo computacional para quebrar.
\nContudo, dependendo das suas necessidades, você pode escolher um algoritmo diferente, ou até mesmo usar um algoritmo customizado para suprir suas necessidades específicas de segurança. Novamente, a maioria dos usuários não precisam disso – se você não tem certeza, provavelmente não precisa. Se você precisa, por favor, leia:
\nDjango escolhe o algoritmo para usar consultando a configuração :setting:’PASSWORD_HASHERS’. Essa é uma lista de classes de algoritmos hash que essa instalação Django suporta. A primeira entrada nessa lista (ou seja, settings.PASSWORD_HASHERS[0]) será usada para armazenar senhas, e todas as outras entradas são hashers válidos que podem ser usados para checar senhas existentes. Isso significa que, se você quiser usar um algoritmo diferente, precisará modificar PASSWORD_HASHERS para listar seu algoritmo preferido como primeira entrada na lista.
O padrão para PASSWORD_HASHERS é:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nIsso significa que o Django vai usar o PBKFD2 para armazenar todas as senhas, mas vai suportar a conferência de senhas armazenadas com PBKDF2SHA1, argon2, and bcrypt.
\nAs próximas seções descreverão jeitos comuns que usuários avançados podem querer usar para modificar essas configurações.
\nArgon2 é o campeão 2015 da ‘Competição de Senhas Hashing’_ uma competição aberta organizada organizada pela comunidade para eleger a próxima geração de algoritmo hashing. É um algoritmo projetado para não ser mais fácil de computar num hardware customizado do que é em um CPU normal.
\nArgon2 não é o padrão do Django porque precisa de uma biblioteca de terceiros. A equipe da Competição de Senhas Hashing, contudo, recomenda o uso imediato de Argon2 em vez de outros algoritmos suportados pelo Django.
\nPara usar Argon2 como seu algoritmo de armazenamento padrão, faça o seguinte:
\nInstall the argon2-cffi library. This can be done by running\npython -m pip install django[argon2], which is equivalent to\npython -m pip install argon2-cffi (along with any version requirement\nfrom Django’s setup.cfg).
Modificar PASSWORD_HASHERS`para listar primeiro ``Argon2PasswordHasher. Ou seja, no seu arquivo de configurações, você colocaria:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nMantenha ou adicione quaisquer entradas nessa lista se você precisa que o Django atualize senhas.
\nbcrypt com DjangoLink para este cabeçalho#Bcrypt é um algoritmo popular de armazenamento de senhas que é especificamente desenhado para armazenamento de senhas de longo prazo. Não é o padrão utilizado pelo Django porque requer uso de bibliotecas de terceiros, mas, já que muita gente pode querer usá-lo, Django suporta o o Bcrypt com mínimo esforço.
\nPara utilizar Bcrypt como seu algoritmo de armazenamento padrão, faça o seguinte:
\nInstall the bcrypt library. This can be done by running\npython -m pip install django[bcrypt], which is equivalent to\npython -m pip install bcrypt (along with any version requirement from\nDjango’s setup.cfg).
Modifique PASSWORD_HASHERS para listar primeiro BCryptSHA256PasswordHasher. Ou seja, no seu arquivo de configurações, você colocará:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nMantenha ou adicione quaisquer entradas nessa lista se você precisa que o Django atualize senhas.
\nÉ isso - agora a sua instalação do Django usará Bcrypt como o algoritmo de armazenamento padrão.
\nscrypt with DjangoLink para este cabeçalho#scrypt is similar to PBKDF2 and bcrypt in utilizing a set number of iterations\nto slow down brute-force attacks. However, because PBKDF2 and bcrypt do not\nrequire a lot of memory, attackers with sufficient resources can launch\nlarge-scale parallel attacks in order to speed up the attacking process.\nscrypt is specifically designed to use more memory compared to other\npassword-based key derivation functions in order to limit the amount of\nparallelism an attacker can use, see RFC 7914 for more details.
\nTo use scrypt as your default storage algorithm, do the following:
\nModify PASSWORD_HASHERS to list ScryptPasswordHasher first.\nThat is, in your settings file:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n]\nMantenha ou adicione quaisquer entradas nessa lista se você precisa que o Django atualize senhas.
\nMost password hashes include a salt along with their password hash in order to\nprotect against rainbow table attacks. The salt itself is a random value which\nincreases the size and thus the cost of the rainbow table and is currently set\nat 128 bits with the salt_entropy value in the BasePasswordHasher. As\ncomputing and storage costs decrease this value should be raised. When\nimplementing your own password hasher you are free to override this value in\norder to use a desired entropy level for your password hashes. salt_entropy\nis measured in bits.
The PBKDF2 and bcrypt algorithms use a number of iterations or rounds of\nhashing. This deliberately slows down attackers, making attacks against hashed\npasswords harder. However, as computing power increases, the number of\niterations needs to be increased. We’ve chosen a reasonable default (and will\nincrease it with each release of Django), but you may wish to tune it up or\ndown, depending on your security needs and available processing power. To do so,\nyou’ll subclass the appropriate algorithm and override the iterations\nparameter (use the rounds parameter when subclassing a bcrypt hasher). For\nexample, to increase the number of iterations used by the default PBKDF2\nalgorithm:
Criar uma subclasse de django.contrib.auth.hashers.PBKDF2PasswordHasher:
from django.contrib.auth.hashers import PBKDF2PasswordHasher\n\nclass MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):\n """\n A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.\n """\n iterations = PBKDF2PasswordHasher.iterations * 100\nSalve isso em algum lugar no seu projeto. Por exemplo, você pode coloca-lo em um arquivo como meuprojeto/hashers.py.
Adicione seu novo hasher como a primeira entrada em: setting:PASSWORD_HASHERS:
\nPASSWORD_HASHERS = [\n 'myproject.hashers.MyPBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nÉ isso – agora seu Django install usará mais iterações ao armazenar senhas usando PBKDF2.
\n\nArgon2 tem três atributos que podem ser personalizados:
\ntime_cost controla o número de iterações dentro do hash.
memory_cost controla o tamanho da memória que deve ser usada durante a computação do hash.
parallelism controla quantas CPUs podem ser paralelizadas na computação do hash.
Os valores padrão desses atributos provavelmente estarão bons para você. Se você determinar que o seu hash de senha está muito rápido ou muito lento, você pode ajusta-lo como segue:
\nEscolha parallelism para ser o número de threads que você pode disponibilizar para computar o hash.
Escolha memory_cost para ser o quanto de memória em KiB que você pode disponibilizar.
Ajuste time_cost e meça o tempo gasto para gerar o hash de uma senha. Escolha um time_cost que tome um tempo aceitável para você. Se time_cost configurado para 1 for inaceitavelmente lento para você, reduza time_cost.
scryptLink para este cabeçalho#scrypt has four attributes that can be customized:
\nwork_factor controls the number of iterations within the hash.
block_size
parallelism controls how many threads will run in parallel.
maxmem limits the maximum size of memory that can be used during the\ncomputation of the hash. Defaults to 0, which means the default\nlimitation from the OpenSSL library.
We’ve chosen reasonable defaults, but you may wish to tune it up or down,\ndepending on your security needs and available processing power.
\n\nQuando usuários entram, se suas senhas estão armazenadas com qualquer outra coisa que não o o algoritmo preferido, Django atualizará automaticamente o algoritmo para o preferido. Isto significa que instalações antigas de Django ficarão mais seguras a medida que os usuários entram, isso também significa que você pode mudar para novos (e melhores) algoritmos de armazenamento quando eles forem inventados.
\nHowever, Django can only upgrade passwords that use algorithms mentioned in\nPASSWORD_HASHERS, so as you upgrade to new systems you should make\nsure never to remove entries from this list. If you do, users using\nunmentioned algorithms won’t be able to upgrade. Hashed passwords will be\nupdated when increasing (or decreasing) the number of PBKDF2 iterations, bcrypt\nrounds, or argon2 attributes.
Esteja ciente que se nem todas as senhas armazenadas em seu banco de dados estiverem codificadas através do algoritmo padrão de hash, você pode estar vulnerável a ataques de enumeração de usuários baseado em tempo devido a uma diferença entre a duração do pedido de login para um usuário com uma senha codificada por um algoritmo não-padrão e a duração de um pedido de login para um usuário inexistente (o qual roda o hash padrão). Você pode ser capaz de mitigar isso:ref:atualizando hashes de senhas mais antigos <wrapping-password-hashers>.
\nSe você tem um banco de dados existente com um hash mais antigo e fraco, tal como MD5 ou SHA1, você pode desejar atualizar esses hashes você mesmo em vez de esperar que a atualização aconteça quando um usuário faça login (o que pode nunca acontecer se um usuário não voltar ao seu site). Neste caso você pode utilizar um hasher de senha “envolta”.
\nPara esse exemplo, vamos migrar a coleção de hashes SHA1 para usar PBKDF2(SHA1(password)) e adicionar o hasher de senha correspondente para checar se um usuário inserir a senha correta no login. Vamos assumir que estamos usando o modelo User padrão e o nosso projeto tem uma aplicação contas. Você pode modificar o padrão para trabalhar com qualquer algoritmo ou com um modelo de usuário customizado.
Primeiro, vamos adicionar um hasher customizado:
\naccounts/hashers.pyfrom django.contrib.auth.hashers import (\n PBKDF2PasswordHasher, SHA1PasswordHasher,\n)\n\n\nclass PBKDF2WrappedSHA1PasswordHasher(PBKDF2PasswordHasher):\n algorithm = 'pbkdf2_wrapped_sha1'\n\n def encode_sha1_hash(self, sha1_hash, salt, iterations=None):\n return super().encode(sha1_hash, salt, iterations)\n\n def encode(self, password, salt, iterations=None):\n _, _, sha1_hash = SHA1PasswordHasher().encode(password, salt).split('$', 2)\n return self.encode_sha1_hash(sha1_hash, salt, iterations)\nA migração pode parecer algo como:
\naccounts/migrations/0002_migrate_sha1_passwords.pyfrom django.db import migrations\n\nfrom ..hashers import PBKDF2WrappedSHA1PasswordHasher\n\n\ndef forwards_func(apps, schema_editor):\n User = apps.get_model('auth', 'User')\n users = User.objects.filter(password__startswith='sha1$')\n hasher = PBKDF2WrappedSHA1PasswordHasher()\n for user in users:\n algorithm, salt, sha1_hash = user.password.split('$', 2)\n user.password = hasher.encode_sha1_hash(sha1_hash, salt)\n user.save(update_fields=['password'])\n\n\nclass Migration(migrations.Migration):\n\n dependencies = [\n ('accounts', '0001_initial'),\n # replace this with the latest migration in contrib.auth\n ('auth', '####_migration_name'),\n ]\n\n operations = [\n migrations.RunPython(forwards_func),\n ]\nTenha cuidado que essa migração deve ser tomará uma ordem de vários minutos para milhares de usuários, dependendo da velocidade do seu hardware.
\nFinalmente, vamos adicionar a configuração PASSWORD_HASHERS:
mysite/settings.pyPASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'accounts.hashers.PBKDF2WrappedSHA1PasswordHasher',\n]\nInclua quaisquer outros hashers que seu site usa nessa lista.
\nA lista completa de hashers incluídas no Django são:
\n[\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n 'django.contrib.auth.hashers.SHA1PasswordHasher',\n 'django.contrib.auth.hashers.MD5PasswordHasher',\n 'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher',\n 'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',\n 'django.contrib.auth.hashers.CryptPasswordHasher',\n]\nOs nomes de algoritmos correspondentes são:
\npbkdf2_sha256
pbkdf2_sha1
argon2
bcrypt_sha256
bcrypt
scrypt
sha1
md5
unsalted_sha1
unsalted_md5
crypt
If you write your own password hasher that contains a work factor such as a\nnumber of iterations, you should implement a\nharden_runtime(self, password, encoded) method to bridge the runtime gap\nbetween the work factor supplied in the encoded password and the default\nwork factor of the hasher. This prevents a user enumeration timing attack due\nto difference between a login request for a user with a password encoded in an\nolder number of iterations and a nonexistent user (which runs the default\nhasher’s default number of iterations).
Taking PBKDF2 as example, if encoded contains 20,000 iterations and the\nhasher’s default iterations is 30,000, the method should run password\nthrough another 10,000 iterations of PBKDF2.
If your hasher doesn’t have a work factor, implement the method as a no-op\n(pass).
The django.contrib.auth.hashers module provides a set of functions\nto create and validate hashed passwords. You can use them independently\nfrom the User model.
If you’d like to manually authenticate a user by comparing a plain-text\npassword to the hashed password in the database, use the convenience\nfunction check_password(). It takes two arguments: the plain-text\npassword to check, and the full value of a user’s password field in the\ndatabase to check against, and returns True if they match, False\notherwise.
Creates a hashed password in the format used by this application. It takes\none mandatory argument: the password in plain-text (string or bytes).\nOptionally, you can provide a salt and a hashing algorithm to use, if you\ndon’t want to use the defaults (first entry of PASSWORD_HASHERS\nsetting). See Hashers incluídos for the algorithm name of each\nhasher. If the password argument is None, an unusable password is\nreturned (one that will never be accepted by check_password()).
Returns False if the password is a result of\nUser.set_unusable_password().
Users often choose poor passwords. To help mitigate this problem, Django\noffers pluggable password validation. You can configure multiple password\nvalidators at the same time. A few validators are included in Django, but you\ncan write your own as well.
\nEach password validator must provide a help text to explain the requirements to\nthe user, validate a given password and return an error message if it does not\nmeet the requirements, and optionally receive passwords that have been set.\nValidators can also have optional settings to fine tune their behavior.
\nValidation is controlled by the AUTH_PASSWORD_VALIDATORS setting.\nThe default for the setting is an empty list, which means no validators are\napplied. In new projects created with the default startproject\ntemplate, a set of validators is enabled by default.
By default, validators are used in the forms to reset or change passwords and\nin the createsuperuser and changepassword management\ncommands. Validators aren’t applied at the model level, for example in\nUser.objects.create_user() and create_superuser(), because we assume\nthat developers, not users, interact with Django at that level and also because\nmodel validation doesn’t automatically run as part of creating models.
A validação de senha é configurada utilizando a variável AUTH_PASSWORD_VALIDATORS:
AUTH_PASSWORD_VALIDATORS = [\n {\n 'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',\n 'OPTIONS': {\n 'min_length': 9,\n }\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',\n },\n]\nEste exemplo habilita todos os quatro validadores incluídos:
\nUserAttributeSimilarityValidator, que verifica a similaridade entre a senha e um conjunto de atributos do usuário.
MinimumLengthValidator, which checks whether the password meets a minimum\nlength. This validator is configured with a custom option: it now requires\nthe minimum length to be nine characters, instead of the default eight.
CommonPasswordValidator, which checks whether the password occurs in a\nlist of common passwords. By default, it compares to an included list of\n20,000 common passwords.
NumericPasswordValidator, que verifica se a senha não é completamente numérica.
For UserAttributeSimilarityValidator and CommonPasswordValidator,\nwe’re using the default settings in this example. NumericPasswordValidator\nhas no settings.
Os textos de ajuda e qualquer erro dos validadores de senha sempre retornam na ordem que eles foram listados no AUTH_PASSWORD_VALIDATORS.
Django inclui quatro validadores:
\nValida se a senha possui um tamanho mínimo. O tamanho mínimo pode ser customizado com o parâmetro min_length.
Valida se a senha é suficientemente diferente dos atributos do usuário.
\nO parâmetro user_attributes deve ser um iterável de nomes de atributos de usuário para serem comparados. Se este argumento não for fornecido, o padrão será utilizado: 'username', 'first_name', 'last_name', 'email'. Atributos que não existem são ignorados.
The maximum allowed similarity of passwords can be set on a scale of 0.1\nto 1.0 with the max_similarity parameter. This is compared to the\nresult of difflib.SequenceMatcher.quick_ratio(). A value of 0.1\nrejects passwords unless they are substantially different from the\nuser_attributes, whereas a value of 1.0 rejects only passwords that are\nidentical to an attribute’s value.
Validates whether the password is not a common password. This converts the\npassword to lowercase (to do a case-insensitive comparison) and checks it\nagainst a list of 20,000 common password created by Royce Williams.
\nThe password_list_path can be set to the path of a custom file of\ncommon passwords. This file should contain one lowercase password per line\nand may be plain text or gzipped.
Validates whether the password is not entirely numeric.
\nThere are a few functions in django.contrib.auth.password_validation that\nyou can call from your own forms or other code to integrate password\nvalidation. This can be useful if you use custom forms for password setting,\nor if you have API calls that allow passwords to be set, for example.
Validates a password. If all validators find the password valid, returns\nNone. If one or more validators reject the password, raises a\nValidationError with all the error messages\nfrom the validators.
The user object is optional: if it’s not provided, some validators may\nnot be able to perform any validation and will accept any password.
Informs all validators that the password has been changed. This can be used\nby validators such as one that prevents password reuse. This should be\ncalled once the password has been successfully changed.
\nFor subclasses of AbstractBaseUser,\nthe password field will be marked as “dirty” when calling\nset_password() which\ntriggers a call to password_changed() after the user is saved.
Returns a list of the help texts of all validators. These explain the\npassword requirements to the user.
\nReturns an HTML string with all help texts in an <ul>. This is\nhelpful when adding password validation to forms, as you can pass the\noutput directly to the help_text parameter of a form field.
Returns a set of validator objects based on the validator_config\nparameter. By default, all functions use the validators defined in\nAUTH_PASSWORD_VALIDATORS, but by calling this function with an\nalternate set of validators and then passing the result into the\npassword_validators parameter of the other functions, your custom set\nof validators will be used instead. This is useful when you have a typical\nset of validators to use for most scenarios, but also have a special\nsituation that requires a custom set. If you always use the same set\nof validators, there is no need to use this function, as the configuration\nfrom AUTH_PASSWORD_VALIDATORS is used by default.
The structure of validator_config is identical to the\nstructure of AUTH_PASSWORD_VALIDATORS. The return value of\nthis function can be passed into the password_validators parameter\nof the functions listed above.
Note that where the password is passed to one of these functions, this should\nalways be the clear text password - not a hashed password.
\nIf Django’s built-in validators are not sufficient, you can write your own\npassword validators. Validators have a fairly small interface. They must\nimplement two methods:
\nvalidate(self, password, user=None): validate a password. Return\nNone if the password is valid, or raise a\nValidationError with an error message if the\npassword is not valid. You must be able to deal with user being\nNone - if that means your validator can’t run, return None for no\nerror.
get_help_text(): provide a help text to explain the requirements to\nthe user.
Any items in the OPTIONS in AUTH_PASSWORD_VALIDATORS for your\nvalidator will be passed to the constructor. All constructor arguments should\nhave a default value.
Here’s a basic example of a validator, with one optional setting:
\nfrom django.core.exceptions import ValidationError\nfrom django.utils.translation import gettext as _\n\nclass MinimumLengthValidator:\n def __init__(self, min_length=8):\n self.min_length = min_length\n\n def validate(self, password, user=None):\n if len(password) < self.min_length:\n raise ValidationError(\n _("This password must contain at least %(min_length)d characters."),\n code='password_too_short',\n params={'min_length': self.min_length},\n )\n\n def get_help_text(self):\n return _(\n "Your password must contain at least %(min_length)d characters."\n % {'min_length': self.min_length}\n )\nYou can also implement password_changed(password, user=None), which will\nbe called after a successful password change. That can be used to prevent\npassword reuse, for example. However, if you decide to store a user’s previous\npasswords, you should never do so in clear text.