> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hashing de Senhas no MySQL

> Por que as funções de hash embutidas do MySQL não são seguras para senhas, e como armazenar hashes de senha corretamente usando PBKDF2 com o VillageSQL.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

O MySQL tem `MD5()` e `SHA2()`. Desenvolvedores recorrem a elas ao fazer hash de senhas. Isso é um erro — essas funções foram projetadas para serem rápidas, que é exatamente a propriedade errada para o armazenamento de senhas.

## Por Que Hashes Rápidos São Errados para Senhas

Funções de hash criptográficas como MD5 e SHA-256 são otimizadas para velocidade. Uma GPU moderna consegue calcular bilhões de hashes SHA-256 por segundo. Isso é útil para checksums e integridade de dados. Para senhas, significa que um atacante que obtém a sua tabela de senhas com hash pode quebrá-la por força bruta em horas.

Algoritmos de hash de senha — bcrypt, Argon2, PBKDF2 — são intencionalmente lentos. Eles são projetados para que a verificação de uma senha leve dezenas de milissegundos, o que é aceitável para um login, mas torna ataques de força bruta impraticáveis.

```sql theme={null}
-- Don't do this
INSERT INTO users (email, password_hash)
VALUES ('user@example.com', SHA2('mypassword', 256));
```

## A Resposta Padrão: Hash no Código da Aplicação

A maioria das aplicações MySQL lida com isso corretamente fazendo o hash na camada da aplicação — usando `bcrypt` em PHP, Python, Node.js ou qualquer linguagem em que a aplicação roda. O banco de dados só vê o valor já com hash.

Isso funciona, mas cria uma divisão: a lógica de hashing vive no código da aplicação, enquanto os dados vivem no banco de dados. Migrações, operações em massa e importações de dados precisam passar pela aplicação para fazer o hash corretamente, ou precisam replicar a lógica de hashing em várias bases de código.

## Com o VillageSQL: PBKDF2 Diretamente em SQL

A extensão `vsql_crypto` do VillageSQL adiciona `crypt()` e `gen_salt()` — uma API de hashing de senhas baseada em PBKDF2, modelada no pgcrypto do PostgreSQL. Você pode fazer hash e verificar senhas em SQL sem passar pelo código da aplicação.

```sql theme={null}
INSTALL EXTENSION vsql_crypto;
```

### Armazenando uma senha

```sql theme={null}
CREATE TABLE users (
    user_id       INT PRIMARY KEY AUTO_INCREMENT,
    email         VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL
);

-- gen_salt generates a random salt; the second argument is iteration count
-- Higher iterations = slower hash = harder to brute-force
INSERT INTO users (email, password_hash)
VALUES ('user@example.com', crypt('mypassword', gen_salt('pbkdf2-sha256', 10000)));
```

`gen_salt` cobre somente a família PBKDF2 — `pbkdf2-sha256` e `pbkdf2-sha512`, mais os aliases curtos `pbkdf2`, `sha256` e `sha512`. Os tipos `bf` (bcrypt), `md5` e `des` do pgcrypto não são suportados: `gen_salt` retorna NULL para esses nomes.

### Verificando uma senha

`crypt()` extrai o salt e os parâmetros do hash armazenado automaticamente — você passa o hash armazenado como segundo argumento:

```sql theme={null}
-- Returns TRUE if the password matches, FALSE otherwise
SELECT crypt('mypassword', password_hash) = password_hash AS is_valid
FROM users
WHERE email = 'user@example.com';
```

### Escolhendo a contagem de iterações

A contagem de iterações controla quanto tempo o hash leva para ser calculado. Mais iterações = mais lento = mais difícil de quebrar por força bruta, mas também logins mais lentos.

| Iterações | Tempo aprox. por hash | Recomendação |
| :- | :- | :- |
| 1.000 | \< 1ms | Rápido demais — não use para senhas |
| 10.000 | \~5ms | Mínimo para produção |
| 100.000 | \~50ms | Melhor — recomendação do NIST para PBKDF2-SHA256 |
| 600.000 | \~300ms | Recomendação da OWASP de 2023 |

Comece em 10.000 e aumente conforme o seu hardware permitir. O seu endpoint de login tolera 100ms; um atacante tentando bilhões de palpites, não.

```sql theme={null}
-- More secure: 100,000 iterations
INSERT INTO users (email, password_hash)
VALUES ('user@example.com', crypt('mypassword', gen_salt('pbkdf2-sha256', 100000)));
```

## Quando Fazer Hash em SQL vs. no Código da Aplicação

Fazer hash em SQL nem sempre é a escolha certa. Use quando:

* Você está fazendo inserções em massa ou migrações em que passar pela aplicação não é prático
* Você quer a lógica de hashing centralizada na camada do banco de dados
* Você está construindo ferramentas administrativas ou scripts de seed orientados a SQL

Faça hash no código da aplicação quando:

* O seu framework de aplicação já tem uma biblioteca bcrypt/Argon2 bem testada
* Você usa uma linguagem em que o ecossistema de criptografia é maduro (a maioria é)
* Você quer trocar de algoritmo de hashing sem uma migração de esquema

As duas abordagens produzem hashes seguros. O essencial é usar um algoritmo lento — PBKDF2, bcrypt ou Argon2 — e não SHA2 puro.

## Perguntas Frequentes

#### O PBKDF2 é tão forte quanto o bcrypt?

Com contagens de iterações equivalentes, o bcrypt tem uma leve vantagem porque é memory-hard (mais difícil de paralelizar em GPUs). O PBKDF2 com contagens de iterações altas (100.000+) continua forte e é amplamente usado. A diferença importa em cenários adversariais; os dois são muito melhores que SHA2.

#### Posso migrar hashes SHA2 existentes?

Sim. Adicione uma flag `needs_rehash`. Em um login bem-sucedido, verifique se o hash está no formato SHA2 antigo e refaça o hash com `crypt()`. Remova os hashes antigos quando todos os usuários ativos tiverem feito login.

#### Posso migrar hashes bcrypt existentes do PostgreSQL?

Não diretamente. `crypt()` retorna NULL para qualquer salt ou hash que não esteja no formato PBKDF2, então hashes bcrypt do pgcrypto não podem ser verificados aqui. Mantenha-os na coluna existente e refaça o hash de cada usuário no próximo login bem-sucedido, da mesma forma que os hashes SHA2 acima. O [guia de migração do PostgreSQL para o MySQL](https://villagesql.com/docs/pt-BR/guides/postgres-to-mysql.md) tem o mapeamento completo de extensões.

#### O hash armazenado inclui o salt?

Sim. A saída de `crypt()` codifica o algoritmo, a contagem de iterações, o salt e o hash em uma única string. Você não gerencia o salt separadamente.

## Solução de Problemas

| Problema | Solução |
| :- | :- |
| `FUNCTION <database>.crypt does not exist` | Execute `INSTALL EXTENSION vsql_crypto` |
| A verificação sempre retorna FALSE | Confirme que você está passando o hash armazenado como segundo argumento de `crypt()`, e não um salt novo |
| A saída do hash é NULL | Verifique se nenhum argumento de `crypt()` é NULL, e se o argumento de salt é um salt ou hash PBKDF2 — `crypt()` retorna NULL para valores bcrypt, `md5` e `des` |

## Veja também

* [Hashing de Dados no MySQL](https://villagesql.com/docs/pt-BR/guides/hashing-data.md) — hashing que não é de senhas, para verificações de integridade e deduplicação
* [Criptografia Simétrica no MySQL](https://villagesql.com/docs/pt-BR/guides/symmetric-encryption.md) — quando criptografia (e não hashing) é a escolha certa
* [Gerando Dados Aleatórios no MySQL](https://villagesql.com/docs/pt-BR/guides/random-data-mysql.md) — gerando salts e tokens criptograficamente seguros


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.