---
title: "Laboratório: guardar palavras-passe e construir códigos TOTP"
domain: cybersecurity
level: beginner
duration: "45 min"
cost: "gratuito"
environment: "o seu próprio computador (Linux, macOS ou Windows com WSL2) com Python 3.9 ou posterior; uma aplicação de autenticação no telemóvel é opcional"
lang: pt
source_hash: c069a4b1d609
---

# Laboratório: guardar palavras-passe e construir códigos TOTP

## Objetivo
Ver com os seus próprios olhos porque é que um hash simples é uma má forma de guardar palavras-passe, guardar palavras-passe da forma segura com um sal e um hash lento, e construir o código de seis dígitos de uma aplicação de autenticação em cerca de 20 linhas de Python. Depois, confirma o seu código com os valores de teste oficiais da RFC 6238.

## Objetivos
- Mostrar que um hash SHA-256 simples dá o mesmo valor para a mesma palavra-passe e que uma palavra-passe comum pode ser procurada.
- Guardar palavras-passe com um sal aleatório e `hashlib.scrypt`, e verificá-las com uma comparação em tempo constante.
- Gerar códigos TOTP e confirmá-los com os vetores de teste do Apêndice B da RFC 6238.
- Dizer que segundo fator travaria um site de phishing que retransmite códigos em tempo real.

## Pré-requisitos
- Python 3.9 ou posterior (`python3 --version`). Cola scripts curtos e executa-os; não precisa de ser programador.
- Um terminal e um sítio onde colar texto (os comandos abaixo criam os ficheiros por si).
- Opcional (passo 4): uma aplicação de autenticação no telemóvel que permita adicionar uma conta escrevendo uma chave (a maioria permite).
- [A lição de Autenticação e MFA](lesson.pt.md) deste módulo.
- Sem contas, sem rede e sem dados de pagamento.

> [!WARNING]
> Tudo isto corre no seu próprio computador, com utilizadores e palavras-passe inventados. Nunca use uma palavra-passe que utilize realmente e nunca cole o segredo TOTP de uma conta real em nenhum script. O segredo que cria no passo 4 é **apenas para este laboratório**: remova-o da aplicação do telemóvel na secção Limpeza.

## Arquitetura
![À esquerda, uma zona para o seu computador, pasta ~/auth-lab, com quatro passos: o passo 1 plain_hash.py mostra a mesma palavra-passe a dar o mesmo SHA-256; o passo 2 store.py guarda com um sal e scrypt, pelo que os valores diferem; o passo 3 totp.py verifica os vetores de teste da RFC 6238; o passo 4 show_code.py imprime um segredo aleatório e um código em tempo real. À direita, uma zona opcional do telemóvel com uma aplicação de autenticação onde escreve à mão o segredo do laboratório. Uma seta liga o passo 4 à aplicação e compara se ambos mostram os mesmos seis dígitos. Uma nota diz para remover o segredo do telemóvel na limpeza.](../../../assets/diagrams/auth-lab-architecture.pt.svg)

*Figura 1. Quatro pequenos scripts numa pasta. Só o passo 4 toca no seu telemóvel, e apenas se quiser.*

## Passos

### Passo 1 — Ver porque é que os hashes simples são maus (8 min)
Um hash transforma uma palavra-passe numa impressão digital de comprimento fixo que não pode ser revertida. Guardar `SHA-256(password)` parece seguro. Vejamos o que pode fazer um atacante que roube uma tabela destas. Crie a pasta e um script:

```bash
mkdir ~/auth-lab
cd ~/auth-lab
cat > plain_hash.py <<'EOF2'
import hashlib

def sha256(text):
    return hashlib.sha256(text.encode()).hexdigest()

# A pretend user table where passwords are stored as a plain SHA-256 hash.
users = {"alice": sha256("sunshine1"), "bob": sha256("sunshine1"), "carol": sha256("c0rrect horse battery")}
for name, stored in users.items():
    print(name, stored)

# An attacker who stole the table tries a short list of common passwords.
common = ["123456", "password", "qwerty", "letmein", "sunshine1"]
lookup = {sha256(word): word for word in common}
print()
for name, stored in users.items():
    print(name, "->", lookup.get(stored, "not in my list"))
EOF2
python3 plain_hash.py
```

Resultado esperado:
```text
alice 284fff3bd254b48cca05a8bfc4fad69e05cad0d086513a034a66a118829e6fa4
bob 284fff3bd254b48cca05a8bfc4fad69e05cad0d086513a034a66a118829e6fa4
carol af2de743ce77cb99a82cda058f8a04c158bf7f8109e06f302539ba2107320f8d

alice -> sunshine1
bob -> sunshine1
carol -> not in my list
```

Em termos simples:

- **A alice e o bob têm o mesmo valor guardado.** A mesma palavra-passe dá o mesmo hash. Quem ler a tabela vê que duas pessoas partilham uma palavra-passe, e quebrar uma quebra ambas.
- **A segunda metade é o atacante.** Calcula o hash de cada palavra-passe comum uma só vez, constrói uma tabela de pesquisa e compara-a com a tabela roubada. A alice e o bob caem numa só pesquisa. As listas reais têm milhares de milhões de entradas, e hashes rápidos como o SHA-256 permitem a uma placa gráfica testar milhares de milhões por segundo.
- **A carol só está a salvo porque a sua frase-passe não consta da lista.** Isso é sorte, não conceção.

<details>
<summary>Porque não simplesmente aplicar o hash duas vezes?</summary>

Aplicar o hash duas vezes com a mesma função rápida continua a ser rápido e continua a dar o mesmo valor para a mesma palavra-passe. As duas soluções são um **sal** (valor diferente por utilizador) e um hash **lento** (dispendioso a cada tentativa). O passo 2 usa ambos.

</details>

### Passo 2 — Guardar palavras-passe com um sal e scrypt (10 min)
Agora, a forma correta. Para cada utilizador, crie um **sal** aleatório e depois aplique o hash à palavra-passe e ao sal em conjunto com o **scrypt**, uma função deliberadamente lenta e com uso intensivo de memória. Guarde o sal junto ao resultado. Para iniciar sessão, repita o cálculo com o sal guardado e compare.

```bash
cat > store.py <<'EOF2'
import hashlib, hmac, os

def make_record(password):
    salt = os.urandom(16)  # random, different for every user
    digest = hashlib.scrypt(password.encode(), salt=salt, n=2**14, r=8, p=1, dklen=32)
    return salt, digest

def check(password, salt, digest):
    attempt = hashlib.scrypt(password.encode(), salt=salt, n=2**14, r=8, p=1, dklen=32)
    return hmac.compare_digest(attempt, digest)

alice = make_record("sunshine1")
bob = make_record("sunshine1")
print("alice salt:  ", alice[0].hex())
print("alice stored:", alice[1].hex())
print("bob salt:    ", bob[0].hex())
print("bob stored:  ", bob[1].hex())
print("same stored value?", alice[1] == bob[1])
print("alice, right password:", check("sunshine1", *alice))
print("alice, wrong password:", check("sunshine2", *alice))
EOF2
python3 store.py
```

Resultado esperado (os valores hexadecimais são aleatórios e **mudam em cada execução**; as últimas três linhas nunca mudam):
```text
alice salt:   193e9e110d6fa0c36ea40a17ebd745be
alice stored: a58c567800dd4b22ff91e798bf0d25af061a5bbb06988decd854e812ea7d7729
bob salt:     ecca3df25d21df01104b2ad8b5795727
bob stored:   a7e5da3f8effd62fda91f6dabfeadafe9511c49457f9a28ef35761d10a5b750c
same stored value? False
alice, right password: True
alice, wrong password: False
```

Em termos simples:

- **A alice e o bob usam a mesma palavra-passe, mas os valores guardados diferem.** Os sais são diferentes, logo os hashes são diferentes. Uma tabela de pesquisa feita antecipadamente é inútil e o atacante tem de atacar cada conta em separado.
- **O sal é guardado em claro.** Não há problema: a sua função é ser único, não secreto.
- **A verificação** repete o scrypt com o sal guardado. `True` para a palavra-passe certa, `False` para a errada.
- **`hmac.compare_digest`** compara dois valores em tempo constante. Um `==` normal pode parar no primeiro byte diferente, e essa minúscula diferença de tempo pode revelar informação.
- **Lento de propósito.** Um scrypt demora aqui alguns centésimos de segundo. Ninguém nota no início de sessão, mas para um atacante multiplica o custo de cada tentativa.

> [!NOTE]
> `n=2**14` foi escolhido para que o laboratório corra depressa em qualquer computador. Os sistemas reais usam definições mais fortes, ou Argon2id. Consulte as recomendações atuais no OWASP Password Storage Cheat Sheet em vez de copiar números de um laboratório.

Execute-o uma segunda vez e observe os sais:

```bash
python3 store.py | head -2
```

O sal e o valor guardado voltam a ser diferentes, mesmo que a palavra-passe não tenha mudado.

### Passo 3 — Construir o TOTP e confirmá-lo com a RFC (12 min)
Um código TOTP é um cálculo sobre um segredo partilhado e o tempo. Vai escrevê-lo como um pequeno módulo que os passos seguintes reutilizam. Leia os comentários: cada linha corresponde a uma caixa da figura da lição.

```bash
cat > totp.py <<'EOF2'
import hashlib, hmac, struct, time

def totp(secret_bytes, t=None, digits=6, step=30):
    counter = int((time.time() if t is None else t) // step)  # the time step T
    mac = hmac.new(secret_bytes, struct.pack(">Q", counter), hashlib.sha1).digest()
    offset = mac[-1] & 0x0F                                   # dynamic truncation
    number = struct.unpack(">I", mac[offset:offset + 4])[0] & 0x7FFFFFFF
    return str(number % 10**digits).zfill(digits)

if __name__ == "__main__":
    secret = b"12345678901234567890"   # RFC 6238 test secret
    for t, expected in [(59, "94287082"), (1111111109, "07081804"), (1111111111, "14050471"),
                        (1234567890, "89005924"), (2000000000, "69279037")]:
        code = totp(secret, t, digits=8)
        print(t, code, expected, "OK" if code == expected else "WRONG")
EOF2
python3 totp.py
```

Resultado esperado:
```text
59 94287082 94287082 OK
1111111109 07081804 07081804 OK
1111111111 14050471 14050471 OK
1234567890 89005924 89005924 OK
2000000000 69279037 69279037 OK
```

Em termos simples:

- **Cada linha** indica um tempo Unix em segundos, o código que a sua função calculou, o código que a RFC diz ser o correto e OK ou WRONG.
- Os cinco tempos de teste e os códigos esperados de 8 dígitos vêm do **Apêndice B da RFC 6238** (a coluna SHA-1). Obter cinco linhas OK significa que o seu código faz exatamente o que fazem as aplicações de autenticação.
- As linhas da função correspondem à lição: `// step` é o intervalo de tempo, `hmac.new(...)` é o HMAC-SHA1, `& 0x0F` e a fatia são a truncagem dinâmica, `% 10**digits` dá os dígitos.
- As aplicações reais usam 6 dígitos, que é o valor por omissão (`digits=6`); os vetores da RFC usam 8.

Verificação rápida: a primeira linha é o tempo 59, ou seja, 59 segundos após 1 de janeiro de 1970. O intervalo de tempo `59 // 30` é 1. Que código de 6 dígitos mostraria então uma aplicação?

<details>
<summary>Mostrar a resposta</summary>

Os últimos seis dígitos do valor de 8 dígitos: `287082`. Pode confirmar:

```bash
python3 -c "from totp import totp; print(totp(b'12345678901234567890', 59))"
```

Resultado: `287082`. (O código de 6 dígitos é o mesmo número módulo um milhão, pelo que são os últimos seis dígitos de `94287082`.)

</details>

### Passo 4 — Um segredo real e um código em tempo real (10 min)
As aplicações de autenticação guardam o segredo como texto em **base32** (letras A-Z e algarismos 2-7). Vamos criar um aleatório e imprimir o código atual de cinco em cinco segundos.

```bash
cat > show_code.py <<'EOF2'
import base64, secrets, time
from totp import totp

secret_b32 = base64.b32encode(secrets.token_bytes(10)).decode()  # 80 random bits -> 16 letters
print("Secret (lab only):", secret_b32)
key = base64.b32decode(secret_b32)
for _ in range(6):
    left = 30 - int(time.time()) % 30
    print(time.strftime("%H:%M:%S"), totp(key), f"(changes in {left}s)")
    time.sleep(5)
EOF2
python3 show_code.py
```

Resultado esperado (o segredo, as horas e os códigos **são diferentes no seu caso**; a forma é a mesma):
```text
Secret (lab only): EM35V2C6LLWLHA47
20:35:52 297598 (changes in 8s)
20:35:57 297598 (changes in 3s)
20:36:02 434430 (changes in 28s)
20:36:07 434430 (changes in 23s)
20:36:12 434430 (changes in 18s)
20:36:17 434430 (changes in 13s)
```

Em termos simples: o código mantém-se igual durante 30 segundos (o mesmo intervalo de tempo) e depois muda. O contador «changes in» chega a zero quando começa o intervalo seguinte. O servidor e o seu telemóvel seguem o mesmo relógio, pelo que concordam sem comunicarem entre si.

**Opcional: comparar com o telemóvel.** Execute o script outra vez, para que o segredo fique no ecrã, e na sua aplicação de autenticação escolha «adicionar uma conta» e depois «introduzir uma chave de configuração» (a formulação varia consoante a aplicação):

1. Nome da conta: `auth-lab`.
2. Chave: as 16 letras impressas a seguir a `Secret (lab only):`.
3. Tipo de chave: **baseada no tempo**. Mantenha as predefinições (6 dígitos, 30 segundos, SHA-1).

Compare os seis dígitos da aplicação com os do terminal. Devem coincidir. Se o telemóvel mostrar um código mesmo antes de uma mudança e o terminal um instante depois, aguarde pelo seguinte.

Acabou de fazer o que faz a leitura de um código QR: um código QR é apenas este segredo, mais um nome, escrito como uma ligação `otpauth://` em forma de imagem.

### Passo 5 — Exercício de reflexão: quem trava a retransmissão? (5 min)
Um site de phishing mostra uma cópia da página de início de sessão da sua empresa. Escreve a sua palavra-passe e o código de seis dígitos da sua aplicação. Em segundo plano, o site envia ambos ao site verdadeiro em segundos e obtém um início de sessão em seu nome.

Pergunta: para cada método, travaria este ataque? Responda sim ou não e diga porquê: (a) uma palavra-passe isolada, (b) um código SMS, (c) o código TOTP que acabou de construir, (d) uma notificação push com correspondência de números, (e) uma chave de segurança FIDO2 ou uma chave de acesso.

<details>
<summary>Mostrar a resposta</summary>

| Método | Trava a retransmissão em tempo real? | Porquê |
|---|---|---|
| (a) Palavra-passe isolada | Não | A página de phishing recolhe-a diretamente. |
| (b) Código SMS | Não | Escreve o código na página falsa, que o retransmite. |
| (c) Código TOTP | Não | O código é válido durante 30 segundos e não está associado a um site. O seu script prova-o: a função recebe apenas um segredo e um tempo, nunca um endereço web. |
| (d) Push com correspondência de números | Parcialmente | É mais difícil, porque o utilizador tem de fazer corresponder o número mostrado no início de sessão verdadeiro. Mas uma retransmissão ainda pode mostrar esse número na página falsa, pelo que um utilizador cansado ou apressado pode ser enganado. |
| (e) Chave FIDO2 ou chave de acesso | **Sim** | A chave assina um desafio juntamente com o endereço web que o navegador vê. No site falso não há credencial correspondente, e uma assinatura para o endereço falso é inútil no site verdadeiro. |

É por isso que as orientações privilegiam agora os métodos resistentes ao phishing para administradores e contas de elevado valor.

</details>

## Verificação
Verifique o seguinte, por ordem:

```bash
cd ~/auth-lab
python3 totp.py
python3 store.py | tail -3
```

Está aprovado se:
- `totp.py` imprimir cinco linhas que terminam todas em `OK`.
- `store.py` imprimir `same stored value? False`, depois `True` para a palavra-passe certa e `False` para a errada.
- No passo 1, a alice e o bob mostraram o mesmo SHA-256 e uma pesquisa recuperou `sunshine1`.
- (Opcional) O seu telemóvel e o `show_code.py` mostraram os mesmos seis dígitos.

## Resolução de problemas
| Sintoma | Causa provável | Solução |
|---|---|---|
| `AttributeError: module 'hashlib' has no attribute 'scrypt'` | Este Python foi compilado sem suporte para scrypt do OpenSSL | Use um Python 3.9 ou posterior padrão, do seu sistema ou de python.org; num contentor mínimo, instale o pacote `python3` completo |
| `ModuleNotFoundError: No module named 'totp'` | Não está em `~/auth-lab`, ou o `totp.py` não existe ou foi renomeado | Execute `cd ~/auth-lab`, verifique com `ls` e volte a executar o bloco do passo 3 |
| `SyntaxError` ou `IndentationError` | A colagem perdeu linhas ou espaços | Elimine esse ficheiro e cole novamente o bloco inteiro, incluindo a última linha `EOF2` |
| `totp.py` imprime `WRONG` | Um erro de escrita no código, num valor da RFC ou no segredo | Compare o ficheiro com o bloco; o segredo tem de ser exatamente `12345678901234567890` |
| O telemóvel mostra um código diferente | Erro de escrita no segredo; a aplicação não está definida como baseada no tempo; o relógio do telemóvel está desfasado mais do que alguns segundos | Volte a introduzir a chave, verifique se o tipo é baseado no tempo, ative a data e hora automáticas no telemóvel |
| `mkdir: cannot create directory ... File exists` | Já executou o passo 1 | Não faz mal: execute `cd ~/auth-lab` e continue |

## Desafio (opcional)
1. Escreva `verify(secret, code)` que aceite o código do intervalo atual e dos intervalos imediatamente antes e depois (uma janela de um intervalo, como num servidor real). Teste-a passando o código de há 30 segundos e o código de há 90 segundos.
2. Meça o tempo de `make_record` com `n=2**14` e com `n=2**17` (para o valor maior, acrescente `maxmem=2**28` à chamada `hashlib.scrypt`, ou o Python recusa-se a usar tanta memória). Quanto mais lenta fica a verificação de uma palavra-passe? O que significa isso para um atacante?
3. Passe uma frase-passe longa por `check` com e sem um carater alterado. O valor guardado parece semelhante? Porque não?

## Limpeza
Remova a pasta e o segredo do laboratório do seu telemóvel:

```bash
cd ~
rm -r ~/auth-lab
```

No telemóvel, abra a aplicação de autenticação e elimine a conta `auth-lab`, se a tiver adicionado. Nada mais foi instalado nem alterado.

## O que aprendeu
- Um hash simples dá o mesmo valor para a mesma palavra-passe e pode ser procurado, pelo que não é um armazenamento seguro de palavras-passe.
- Um sal aleatório por utilizador e um hash lento como o scrypt fazem com que palavras-passe idênticas pareçam diferentes e que cada tentativa seja dispendiosa. Compare em tempo constante.
- Um código TOTP é apenas o HMAC-SHA1 do intervalo de tempo de 30 segundos com um segredo partilhado, truncado em dígitos. Confirmou-o com a RFC 6238.
- Um código que escreve não está associado a um site, pelo que um site de phishing o pode retransmitir. Uma chave FIDO2 ou chave de acesso assina a origem, pelo que não pode ser retransmitida.
