Números aleatórios e tokens seguros em PHP com random_bytes

Em resumo: Em PHP, gera tokens seguros com random_bytes(), por exemplo 32 bytes, que converte em texto com bin2hex() ou Base64-URL. Para números aleatórios num intervalo existe random_int(), e para códigos a partir de um conjunto fixo de carateres, desde o PHP 8.3, Random\Randomizer::getBytesFromString(). Os tokens guardam-se como hash, com validade limitada, usam-se uma só vez e comparam-se com hash_equals().

Um link demasiado fácil de adivinhar

“Esqueceu-se da palavra-passe?” Um clique, e o sistema envia um link com um código longo. Quem conhecer o link pode definir a palavra-passe. É precisamente por isso que este código tem de ser imprevisível. Se não o for, um atacante não precisa nem da caixa de correio nem da palavra-passe antiga, apenas de tentativas suficientes.

Nas auditorias a aplicações PHP encontram-se surpreendentemente muitas vezes tokens construídos a partir da hora, do ID do utilizador ou de um gerador de números aleatórios simples. Parecem longos e aleatórios, mas não são. O mesmo vale para chaves de API, links de convite, links de partilha de documentos, códigos de confirmação e tokens CSRF.

O risco é concreto: um link de reposição previsível permite assumir o controlo de qualquer conta cujo endereço de correio eletrónico seja conhecido, sem que o titular dê por nada até já não conseguir iniciar sessão.

O PHP oferece, desde a versão 7.0, uma solução simples e segura. Só tem de ser usada de forma consequente.

random_bytes em PHP: de onde vêm os valores aleatórios seguros

Segundo o manual do PHP, o random_bytes() fornece bytes aleatórios criptograficamente seguros, adequados também para segredos duradouros como chaves. A função usa a fonte de aleatoriedade do sistema operativo, no Linux por exemplo o getrandom(), no Windows a interface CNG. Se não encontrar uma fonte adequada, lança, desde o PHP 8.2, uma Random\RandomException.

A visão geral mostra que funções servem para segredos:

Gerar tokens: comprimento e codificação

32 bytes aleatórios correspondem a 256 bits e são mais do que suficientes para quase qualquer finalidade. Para a transmissão em links ou cabeçalhos, o token tem de ser convertido em texto. São habituais duas variantes:

<?php
declare(strict_types=1);

// Hex: 64 carateres, apenas 0-9 e a-f
$tokenHex = bin2hex(random_bytes(32));

// Base64-URL: 43 carateres, seguro em URLs sem mais codificação
$tokenUrl = rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');

// Número aleatório num intervalo, por exemplo para uma seleção
$index = random_int(0, 9);

// A partir do PHP 8.3: código numérico de seis dígitos, p. ex. para uma confirmação por SMS
$randomizer = new \Random\Randomizer();
$code = $randomizer->getBytesFromString('0123456789', 6);

Os códigos numéricos curtos só são aceitáveis se o número de tentativas for estritamente limitado e o código expirar ao fim de poucos minutos. Para links enviados por correio eletrónico, use sempre o token longo.

Para chaves de API que parceiros ou sistemas próprios usam de forma duradoura, duas adições provaram ser úteis. Um prefixo curto e não secreto antes da parte aleatória, por exemplo para ambiente ou finalidade, facilita o reconhecimento em registos e em achados em repositórios de código. E a chave é mostrada apenas uma vez, na criação; depois, o sistema conhece apenas o seu hash. Se uma chave se perder, é substituída, não recuperada.

Cuidado com tokens construídos por si que contêm informação, por exemplo o ID do utilizador e o tempo de expiração em Base64. Codificar não é proteger: qualquer pessoa pode ler e alterar tais tokens. Se um token tiver de transportar dados, tem de ser assinado com uma chave secreta, por exemplo com hash_hmac('sha256', ...), e a assinatura é verificada com hash_equals(). Em casos mais exigentes, são preferíveis bibliotecas verificadas a construções próprias.

Guardar, verificar e fazer expirar tokens

Um token gerado em segurança é só metade do caminho. Pelo menos igualmente importante é a forma como a aplicação lida com ele. Um procedimento provado para links de reposição e de convite:

1. Guardar apenas o hash: na base de dados fica hash('sha256', $token); o token em si só vai por link para o utilizador.
2. Limitar a validade: guardar o tempo de expiração e verificá-lo ao resgatar.
3. Usar uma só vez: após a utilização bem-sucedida, apagar a entrada ou marcá-la como consumida.
4. Invalidar em caso de alterações: após uma alteração de palavra-passe, apagar todos os tokens de reposição abertos da conta.
5. Comparar em tempo constante: onde um token é comparado diretamente com um valor guardado, usar hash_equals(), com o valor guardado como primeiro parâmetro.

<?php
// Gerar
$token = bin2hex(random_bytes(32));
$eintrag = [
    'konto_id'   => $kontoId,
    'token_hash' => hash('sha256', $token),
    'gueltig_bis'=> (new DateTimeImmutable('+30 minutes'))->format('Y-m-d H:i:s'),
];
// enviar $token apenas no link, guardar $eintrag

// Resgatar
$gesucht = hash('sha256', (string) ($_GET['token'] ?? ''));
// procurar a entrada por token_hash com um prepared statement,
// verificar a expiração e apagar a entrada de imediato

Limite também o número de pedidos de reposição por conta e período, para que a função não possa ser abusada para o envio em massa de correio eletrónico. A resposta a um pedido de reposição não deve, além disso, revelar se o endereço indicado tem sequer uma conta.

Um hash rápido como o SHA-256 chega aqui, porque o próprio token já é longo e aleatório. Para palavras-passe escolhidas por pessoas isso não vale; aí são necessários procedimentos lentos, como explica Guardar palavras-passe em PHP com segurança.

Após um incidente: renovar tokens e chaves

Quem conseguiu executar código num servidor teve, em regra, também acesso a tokens, chaves de API e dados de sessão guardados. Se após o PHP2Shell ou outro incidente existir a suspeita de uma intrusão, deve por isso renovar não só as palavras-passe, mas também tokens e chaves duradouros: acessos de API, chaves de assinatura de cookies ou links, acessos a serviços de pagamento e de expedição.

As sessões são um caso especial: o PHP gera ele próprio os IDs de sessão. Como proteger as suas definições e terminar sessões após um incidente é descrito no guia Proteger sessões em PHP. Para tokens de formulário contra pedidos forjados, ver Proteção CSRF em aplicações PHP. Outras ferramentas incorporadas são apresentadas em Funções de segurança incorporadas no PHP.

Como ajuda concretamente a PHP SOS?

• Encontramos na sua aplicação todos os pontos em que tokens, códigos e chaves são gerados e substituímos fontes inseguras.
• Verificamos o armazenamento, a validade e a utilização única dos links de reposição, de convite e de partilha.
• Garantimos que os tokens não vão parar a registos, relatórios de erros ou ferramentas de análise.
• Após um incidente, planeamos consigo a substituição ordenada de tokens e chaves.

A verificação de software PHP próprio é oferecida por nós como auditoria de segurança e teste de intrusão.

Perguntas frequentes

Fontes

• Manual do PHP: random_bytes
• Manual do PHP: Random\Randomizer::getBytesFromString
• Manual do PHP: hash_equals
• OWASP Cheat Sheet Series