Hash de senhas

Nenhuma linguagem deveria ter uma implementação de hash de senha escrita à mão no seu projeto. Os exemplos usam a biblioteca mais adotada em cada uma e mostram as três operações que todo sistema precisa: gerar o hash, conferir a senha e saber quando refazer o hash.

Gerar, conferir e atualizar

import argon2 from "argon2";

const PARAMETROS = {
  type: argon2.argon2id,
  memoryCost: 19456, // KiB = 19 MiB
  timeCost: 2,
  parallelism: 1,
};

export function gerarHash(senha: string) {
  return argon2.hash(senha, PARAMETROS);
}

export function conferir(hash: string, senha: string) {
  return argon2.verify(hash, senha);
}

export function precisaRefazer(hash: string) {
  return argon2.needsRehash(hash, PARAMETROS);
}

from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError

hasher = PasswordHasher(
    memory_cost=19456,  # KiB = 19 MiB
    time_cost=2,
    parallelism=1,
)


def gerar_hash(senha: str) -> str:
    return hasher.hash(senha)


def conferir(hash_: str, senha: str) -> bool:
    try:
        return hasher.verify(hash_, senha)
    except VerifyMismatchError:
        return False


def precisa_refazer(hash_: str) -> bool:
    return hasher.check_needs_rehash(hash_)

package senhas

import "golang.org/x/crypto/bcrypt"

const custo = 12

func GerarHash(senha string) (string, error) {
	// Retorna erro para senhas com mais de 72 bytes
	hash, err := bcrypt.GenerateFromPassword([]byte(senha), custo)
	return string(hash), err
}

func Conferir(hash, senha string) bool {
	err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(senha))
	return err == nil
}

func PrecisaRefazer(hash string) bool {
	atual, err := bcrypt.Cost([]byte(hash))
	return err != nil || atual < custo
}

import org.springframework.security.crypto.argon2.Argon2PasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

public class Senhas {
    // Requer a dependência org.bouncycastle:bcprov
    private static final PasswordEncoder ENCODER =
        Argon2PasswordEncoder.defaultsForSpringSecurity_v5_8();

    public static String gerarHash(String senha) {
        return ENCODER.encode(senha);
    }

    public static boolean conferir(String hash, String senha) {
        return ENCODER.matches(senha, hash);
    }

    public static boolean precisaRefazer(String hash) {
        return ENCODER.upgradeEncoding(hash);
    }
}

using Microsoft.AspNetCore.Identity;

public class Senhas
{
    private static readonly PasswordHasher<Usuario> Hasher = new();

    public static string GerarHash(Usuario usuario, string senha) =>
        Hasher.HashPassword(usuario, senha);

    // Success, SuccessRehashNeeded ou Failed
    public static PasswordVerificationResult Conferir(
        Usuario usuario, string hash, string senha) =>
        Hasher.VerifyHashedPassword(usuario, hash, senha);
}

public record Usuario(string Id, string Email);

O que muda de uma linguagem para outra

	Biblioteca do exemplo	Algoritmo	Como sabe que precisa refazer
Node	`argon2`	Argon2id	`needsRehash` compara com os parâmetros atuais
Python	`argon2-cffi`	Argon2id	`check_needs_rehash`
Go	`x/crypto/bcrypt`	bcrypt	Compare o custo do hash com o atual
Java	Spring Security	Argon2id	`upgradeEncoding`
C#	ASP.NET Core Identity	PBKDF2-HMAC-SHA512	O resultado `SuccessRehashNeeded`

Três observações sobre a tabela:

Go tem Argon2 em x/crypto/argon2, mas só a função de baixo nível: gerar o sal, montar a string e comparar ficam por sua conta. Por isso o bcrypt é a escolha mais segura para quem não quer escrever esse código.
C#: o PasswordHasher do Identity usa PBKDF2 com um número de iterações que sobe entre versões do .NET. Ao atualizar o .NET, os hashes antigos passam a voltar SuccessRehashNeeded.
Java: o DelegatingPasswordEncoder do Spring guarda o algoritmo como prefixo ({bcrypt}, {argon2}) e confere hashes de algoritmos diferentes, o que facilita migrar.

Conferir a senha é só uma parte. O login precisa responder no mesmo tempo quando o usuário não existe e aproveitar o momento para atualizar o hash.

// Hash de uma senha qualquer, calculado uma vez na inicialização
const HASH_FALSO = await gerarHash("senha-que-ninguem-usa");

export async function login(email: string, senha: string) {
  const usuario = await usuarios.buscarPorEmail(email);

  // Mesmo trabalho com e sem usuário: o tempo não revela quem existe
  const hash = usuario?.hashSenha ?? HASH_FALSO;
  const confere = await conferir(hash, senha);

  if (!usuario || !confere) {
    throw new CredenciaisInvalidas(); // mesma mensagem nos dois casos
  }

  if (precisaRefazer(usuario.hashSenha)) {
    await usuarios.atualizarHash(usuario.id, await gerarHash(senha));
  }

  return usuario;
}

Detalhe	Por que existe
`HASH_FALSO`	Sem ele, o login de um e-mail inexistente responde em milissegundos e o de um existente em centenas. O tempo de resposta revela quais e-mails estão cadastrados
Mesma mensagem de erro	"Usuário não encontrado" e "senha errada" contam ao atacante quais contas existem
Refazer depois de conferir	É o único momento em que o sistema tem a senha original em mãos

Lista de revisão

Armazenamento

O algoritmo é Argon2id, scrypt, bcrypt ou PBKDF2, de uma biblioteca mantida?
Os parâmetros são iguais ou maiores que os mínimos atuais da OWASP?
A coluna guarda a string completa da biblioteca, com tamanho suficiente para ela?
Com bcrypt, senhas acima de 72 bytes são tratadas?

Login

A conferência usa a função verify da biblioteca?
O tempo de resposta é o mesmo para e-mail existente e inexistente?
A mensagem de erro é a mesma nos dois casos?
O hash é refeito quando os parâmetros mudam?
Há limite de tentativas por conta e por endereço?

Em volta

A senha nunca aparece em logs, mensagens de erro ou ferramentas de monitoramento?
Senhas vazadas conhecidas são recusadas no cadastro e na troca?
Existe um plano para os hashes legados mais fracos?

Gerar, conferir e atualizar

O que muda de uma linguagem para outra

Lista de revisão

Prompts para aprofundar

Implementar cadastro e login seguros

Medir o custo do hash no meu servidor

Revisar o armazenamento de senhas

Gerar, conferir e atualizar

O que muda de uma linguagem para outra

O login completo

Lista de revisão

Prompts para aprofundar

Implementar cadastro e login seguros

Medir o custo do hash no meu servidor

Revisar o armazenamento de senhas