Gerenciamento de senhas no Django

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.

Ver também

Mesmo que os usuários usem senha fortes, ataques podem ser capazes de bisbilhotar suas conexões. Use conexões HTTPS para evitar o envio de senhas (ou qualquer outro dado sensível) sobre conexões HTTP porque eles estarão vulneráveis a sequestros de senhas.

Como o Django armazena as senhas

O Django fornece um sistema flexível de armazenamento de senhas e usa PBKDF2 por padrão.

O atributo password de um objeto User é uma string nesse formato:

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

Estes 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.

Por 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.

Contudo, 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:

Django 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 = [
    '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',
]

Isso 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.

As próximas seções descreverão jeitos comuns que usuários avançados podem querer usar para modificar essas configurações.

Usando Argon2 com Django

New in Django 1.10.

Argon2 é 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.

Argon2 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.

Para usar Argon2 como seu algoritmo de armazenamento padrão, faça o seguinte:

  1. Instale o argon2-cffi library. Isso pode ser feito rodando pip install django[argon2], que é equivalente a pip install argon2-cffi (junto com quaisquer requerimentos do setup.py do Django).

  2. Modificar PASSWORD_HASHERS`para listar primeiro ``Argon2PasswordHasher. Ou seja, no seu arquivo de configurações, você colocaria:

    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',
    ]
    

    Mantenha ou adicione quaisquer entradas nessa lista se você precisa que o Django atualize senhas.

Usando bcrypt com Django

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.

Para utilizar Bcrypt como seu algoritmo de armazenamento padrão, faça o seguinte:

  1. Instale o bcrypt library Isso pode ser feito rodando pip install django[bcrypt], que é o equivalente a pip install bcrypt (junto com quaisquer requerimentos do setup.py do Django).

  2. Modifique PASSWORD_HASHERS para listar primeiro BCryptSHA256PasswordHasher. Ou seja, no seu arquivo de configurações, você colocará:

    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',
    ]
    

    Mantenha ou adicione quaisquer entradas nessa lista se você precisa que o Django atualize senhas.

É isso - agora a sua instalação do Django usará Bcrypt como o algoritmo de armazenamento padrão.

Truncamento de senhas com BCryptPasswordHasher

Os desenvolvedores do bcrypt limitaram todos as senhas em 72 caraceteres, o que significa que bcrypt(password_with_100_chars) == bcrypt(password_with_100_chars[:72]). O BCryptPasswordHasher original não tem nenhum tratamento especial e portanto também trata este limite escondido da senha. O BCryptSHA256PasswordHasher concerta isso utilizando um sha256 para fazer a encriptação. Isso evita a limitação de caracteres na senha e portanto deve ser preferível ao BCryptPasswordHasher. Na prática isso tudo é marginal já que o o usuário médio não tem uma senha maior que 72 caracteres e mesmo sendo truncado em 72 o poder computacional requerido para quebrar o bcrypt por força bruta requer uma quantidade de tempo astronômica. Independente de qualquer coisa, recomendamos que você use de qualquer forma o BCryptSHA256PasswordHasher dentro do princípio melhor prevenir do que remediar.

Outras implementações de bcrypt

Existem várias outras implementações que permitem utilizar o bcrypt como Django. O suporte do bcrypt para o Django não é diretamente compatível com isso. Para fazer a atualização você precisará modificar os “hashers” no seu banco de dados para que fique no formato bcrypt$(raw bcrypt output)`. Por exemplo: bcrypt$$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy.

Aumentando o fator de trabalho

PBKDF2 e bcrypt

Os algoritmos PBKDF2 e bcrypt usam um número de iterações ou rodadas de hashing. Isso intencionalmente atrasa atacantes, tornando mais difíceis ataques contra hashes de senha. Entretanto, como o poder computacional aumenta, o número de iterações precisa ser ampliado. Temos escolhido um valor padrão razoável (e o aumentaremos a cada lançamento do Django), mas você pode desejar ajusta-lo para mais ou para menos, dependendo das suas necessidades de segurança e poder de processamento disponível. Para tanto, você criará uma subclasse herdando o algoritmo apropriado e sobrescreverá o parâmetro iterations. Por exemplo, para aumentar o número de iterações usadas pelo algoritmo padrão PBKDF2:

  1. Criar uma subclasse de 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
    

    Salve isso em algum lugar no seu projeto. Por exemplo, você pode coloca-lo em um arquivo como meuprojeto/hashers.py.

  2. Adicione seu novo hasher como a primeira entrada em: setting: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',
    ]
    

É isso – agora seu Django install usará mais iterações ao armazenar senhas usando PBKDF2.

Argon2

Argon2 tem três atributos que podem ser personalizados:

  1. time_cost controla o número de iterações dentro do hash.
  2. memory_cost controla o tamanho da memória que deve ser usada durante a computação do hash.
  3. 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:

  1. Escolha parallelism para ser o número de threads que você pode disponibilizar para computar o hash.
  2. Escolha memory_cost para ser o quanto de memória em KiB que você pode disponibilizar.
  3. 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.

memory_cost interpretação

O utilitário de linha de comando argon2 e algumas outras bibliotecas interpretam o parâmetro memory_cost diferentemente do valor que Django usa. A conversão é dada por memory_cost == 2 ** memory_cost_commandline.

Atualização de senha

Quando 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.

Entretanto, Django só é capaz de atualizar senhas que utilizam os algoritmos mencionados em: setting:PASSWORD_HASHERS, portanto quando atualizar para novos sistemas você deve certificar-se de nunca remover entradas dessa lista. Se você o fizer, usuários utilizando algoritmos não mencionados não estarão aptos a atualizar. Hashes de senhas serão atualizados ao incrementar (ou decrementar) o número de iterações PBKDF2 ou rodadas bcrypt.

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

Atualização de senha sem exigência de login

Se 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”.

Para 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:

accounts/hashers.py
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(PBKDF2WrappedSHA1PasswordHasher, self).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)

A migração pode parecer algo como:

accounts/migrations/0002_migrate_sha1_passwords.py
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),
    ]

Tenha 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.

Finalmente, vamos adicionar a configuração PASSWORD_HASHERS:

mysite/settings.py
PASSWORD_HASHERS = [
    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
    'accounts.hashers.PBKDF2WrappedSHA1PasswordHasher',
]

Inclua quaisquer outros hashers que seu site usa nessa lista.

Hashers incluídos

A lista completa de hashers incluídas no Django são:

[
    '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',
]

Os nomes de algoritmos correspondentes são:

  • pbkdf2_sha256
  • pbkdf2_sha1
  • argon2
  • bcrypt_sha256
  • bcrypt
  • sha1
  • md5
  • unsalted_sha1
  • unsalted_md5
  • crypt

Escrevendo seu próprio hasher

If you write your own password hasher that contains a work factor such as a number of iterations, you should implement a harden_runtime(self, password, encoded) method to bridge the runtime gap between the work factor supplied in the encoded password and the default work factor of the hasher. This prevents a user enumeration timing attack due to difference between a login request for a user with a password encoded in an older number of iterations and a nonexistent user (which runs the default hasher’s default number of iterations).

Taking PBKDF2 as example, if encoded contains 20,000 iterations and the hasher’s default iterations is 30,000, the method should run password through another 10,000 iterations of PBKDF2.

If your hasher doesn’t have a work factor, implement the method as a no-op (pass).

Manually managing a user’s password

The django.contrib.auth.hashers module provides a set of functions to create and validate hashed password. You can use them independently from the User model.

check_password(password, encoded)[código fonte]

If you’d like to manually authenticate a user by comparing a plain-text password to the hashed password in the database, use the convenience function check_password(). It takes two arguments: the plain-text password to check, and the full value of a user’s password field in the database to check against, and returns True if they match, False otherwise.

make_password(password, salt=None, hasher='default')[código fonte]

Creates a hashed password in the format used by this application. It takes one mandatory argument: the password in plain-text. Optionally, you can provide a salt and a hashing algorithm to use, if you don’t want to use the defaults (first entry of PASSWORD_HASHERS setting). See Hashers incluídos for the algorithm name of each hasher. If the password argument is None, an unusable password is returned (a one that will be never accepted by check_password()).

is_password_usable(encoded_password)[código fonte]

Checks if the given string is a hashed password that has a chance of being verified against check_password().

Validação de senha

Users often choose poor passwords. To help mitigate this problem, Django offers pluggable password validation. You can configure multiple password validators at the same time. A few validators are included in Django, but it’s simple to write your own as well.

Each password validator must provide a help text to explain the requirements to the user, validate a given password and return an error message if it does not meet the requirements, and optionally receive passwords that have been set. Validators can also have optional settings to fine tune their behavior.

Validation is controlled by the AUTH_PASSWORD_VALIDATORS setting. The default for the setting is an empty list, which means no validators are applied. In new projects created with the default startproject template, a simple set of validators is enabled.

By default, validators are used in the forms to reset or change passwords and in the createsuperuser and changepassword management commands. Validators aren’t applied at the model level, for example in User.objects.create_user() and create_superuser(), because we assume that developers, not users, interact with Django at that level and also because model validation doesn’t automatically run as part of creating models.

Nota

Validação de senha pode previnir que o usuário utilize muitos tipos de senhas fracas. No entanto, o fato de uma senha passar em todos os validadores não garante que a senha é forte. Existem muitos outros fatores que podem enfraquecer uma senha que não é detectado nem mesmo pelos validadores de senha mais avançados.

Habilitando validação de senha

A validação de senha é configurada utilizando a variável 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',
    },
]

Este exemplo habilita todos os quatro validadores incluídos:

  • UserAttributeSimilarityValidator, que verifica a similaridade entre a senha e um conjunto de atributos do usuário.
  • MinimumLengthValidator, que simplesmente verifica se a senha possui um tamanho mínimo. Este validador é configurado com uma opção personalizada: agora ela vem configurada com um tamanho mínimo de nove caracteres, ao invés do padrão de oito.
  • CommonPasswordValidator, que verifica se a senha está presente em uma lista de senhas comuns. Por padrão, ele compara com uma lista pré-definida com 1000 senhas comuns.
  • NumericPasswordValidator, que verifica se a senha não é completamente numérica.

Para os validadores UserAttributeSimilarityValidator e CommonPasswordValidator, nós estamos simplesmente utilizando as configurações padrão. O validador NumericPasswordValidator não possui nenhuma opção de configuração.

Os textos de ajuda e qualquer erro dos validadores de senha sempre retornam na ordem que eles foram listados no AUTH_PASSWORD_VALIDATORS.

Validadores incluídos

Django inclui quatro validadores:

class MinimumLengthValidator(min_length=8)[código fonte]

Valida se a senha possui um tamanho mínimo. O tamanho mínimo pode ser customizado com o parâmetro min_length.

class UserAttributeSimilarityValidator(user_attributes=DEFAULT_USER_ATTRIBUTES, max_similarity=0.7)[código fonte]

Valida se a senha é suficientemente diferente dos atributos do usuário.

O 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 minimum similarity of a rejected password can be set on a scale of 0 to 1 with the max_similarity parameter. A setting of 0 rejects all passwords, whereas a setting of 1 rejects only passwords that are identical to an attribute’s value.

class CommonPasswordValidator(password_list_path=DEFAULT_PASSWORD_LIST_PATH)[código fonte]

Validates whether the password is not a common password. By default, this checks against a list of 1000 common password created by Mark Burnett.

The password_list_path can be set to the path of a custom file of common passwords. This file should contain one password per line and may be plain text or gzipped.

class NumericPasswordValidator[código fonte]

Validates whether the password is not entirely numeric.

Integrating validation

There are a few functions in django.contrib.auth.password_validation that you can call from your own forms or other code to integrate password validation. This can be useful if you use custom forms for password setting, or if you have API calls that allow passwords to be set, for example.

validate_password(password, user=None, password_validators=None)[código fonte]

Validates a password. If all validators find the password valid, returns None. If one or more validators reject the password, raises a ValidationError with all the error messages from the validators.

The user object is optional: if it’s not provided, some validators may not be able to perform any validation and will accept any password.

password_changed(password, user=None, password_validators=None)[código fonte]

Informs all validators that the password has been changed. This can be used by validators such as one that prevents password reuse. This should be called once the password has been successfully changed.

For subclasses of AbstractBaseUser, the password field will be marked as “dirty” when calling set_password() which triggers a call to password_changed() after the user is saved.

password_validators_help_texts(password_validators=None)[código fonte]

Returns a list of the help texts of all validators. These explain the password requirements to the user.

password_validators_help_text_html(password_validators=None)

Returns an HTML string with all help texts in an <ul>. This is helpful when adding password validation to forms, as you can pass the output directly to the help_text parameter of a form field.

get_password_validators(validator_config)[código fonte]

Returns a set of validator objects based on the validator_config parameter. By default, all functions use the validators defined in AUTH_PASSWORD_VALIDATORS, but by calling this function with an alternate set of validators and then passing the result into the password_validators parameter of the other functions, your custom set of validators will be used instead. This is useful when you have a typical set of validators to use for most scenarios, but also have a special situation that requires a custom set. If you always use the same set of validators, there is no need to use this function, as the configuration from AUTH_PASSWORD_VALIDATORS is used by default.

The structure of validator_config is identical to the structure of AUTH_PASSWORD_VALIDATORS. The return value of this function can be passed into the password_validators parameter of the functions listed above.

Note that where the password is passed to one of these functions, this should always be the clear text password - not a hashed password.

Escrevendo seu próprio validador

If Django’s built-in validators are not sufficient, you can write your own password validators. Validators are fairly simple classes. They must implement two methods:

  • validate(self, password, user=None): validate a password. Return None if the password is valid, or raise a ValidationError with an error message if the password is not valid. You must be able to deal with user being None - if that means your validator can’t run, simply return None for no error.
  • get_help_text(): provide a help text to explain the requirements to the user.

Any items in the OPTIONS in AUTH_PASSWORD_VALIDATORS for your validator will be passed to the constructor. All constructor arguments should have a default value.

Here’s a basic example of a validator, with one optional setting:

from django.core.exceptions import ValidationError
from django.utils.translation import ugettext as _

class MinimumLengthValidator(object):
    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}
        )

You can also implement password_changed(password, user=None), which will be called after a successful password change. That can be used to prevent password reuse, for example. However, if you decide to store a user’s previous passwords, you should never do so in clear text.