Implementando Autenticação de Dois Fatores (2FA) com PHP Puro: Um Guia Prático

A segurança de aplicações web é uma preocupação constante para desenvolvedores. Com o aumento da complexidade das ameaças digitais, apenas um par de usuário e senha já não é mais suficiente para garantir a proteção das contas de seus usuários. É nesse cenário que a Autenticação de Dois Fatores (2FA) se torna uma camada essencial de segurança.

Neste post, vamos explorar uma solução elegante e minimalista para implementar 2FA em projetos PHP: o repositório php-token. Criado por Yuri Martins, este projeto oferece uma implementação completa do algoritmo TOTP (Time-Based One-Time Password) em PHP puro, sem a necessidade de dependências externas como o Composer. É a ferramenta ideal para quem deseja adicionar uma camada extra de segurança de forma rápida, ou para aqueles que querem entender a fundo como o mecanismo de 2FA funciona.

O que é TOTP?

O Time-Based One-Time Password (TOTP) é um algoritmo padronizado pela RFC 6238 que gera um código numérico de curta duração, geralmente 6 dígitos, que muda a cada 30 ou 60 segundos. Este código é gerado a partir de dois componentes principais:

1. Uma Chave Secreta (Shared Secret): Uma chave única, compartilhada entre o servidor e o dispositivo do usuário (geralmente um aplicativo autenticador no smartphone).
2. Um Fator de Tempo (Time Factor): O tempo atual, sincronizado entre o servidor e o dispositivo do usuário.

Esses dois elementos são combinados usando um algoritmo de HMAC (Hash-based Message Authentication Code), resultando em um código que é válido apenas por um curto período. Aplicativos populares como Google Authenticator, Microsoft Authenticator e Authy são baseados neste padrão.

Apresentando o php-token

O php-token se destaca por sua simplicidade e eficácia. Suas principais características incluem:

• PHP Puro: Nenhuma dependência externa é necessária. Basta incluir o arquivo TOTP.php em seu projeto.
• Conformidade com RFC 6238: A implementação segue fielmente o padrão oficial, garantindo compatibilidade com os principais aplicativos autenticadores.
• Suporte a Múltiplos Algoritmos: Permite o uso de algoritmos de hash como SHA-1, SHA-256 e SHA-512.
• Geração de QR Code: Facilita a configuração para o usuário final, que pode simplesmente escanear um QR Code para adicionar a conta ao seu aplicativo autenticador.
• Proteção Contra Ataques de Timing: Utiliza a função hash_equals() para comparar os códigos, uma prática de segurança essencial para prevenir que um atacante consiga adivinhar o código através da análise do tempo de resposta do servidor.

Como Funciona na Prática: Um Passo a Passo

Integrar o php-token em seu projeto é um processo direto. Vamos ver os três passos fundamentais:

Passo 1: Geração da Chave Secreta

Primeiro, você precisa gerar uma chave secreta única para cada usuário e armazená-la de forma segura em seu banco de dados. O php-token simplifica isso com o método generateSecret().

require_once 'TOTP.php';

$totp = new TOTP();
$secret = $totp->generateSecret();

// Exemplo de output: JBSWY3DPEHPK3PXP
// Armazene esta chave de forma segura, associada ao usuário.

Passo 2: Geração do QR Code

Com a chave secreta em mãos, o próximo passo é apresentá-la ao usuário de uma forma fácil de configurar. A melhor maneira é através de um QR Code.

$qrCodeImageUrl = $totp->getQRCodeImageUrl($secret, 'usuario@exemplo.com', 'Minha App');

echo '<img src="' . $qrCodeImageUrl . '" alt="QR Code para 2FA">';

O usuário então escaneia este QR Code com seu aplicativo autenticador, que passará a gerar os códigos de 6 dígitos.

Passo 3: Verificação do Código

Finalmente, quando o usuário tentar fazer login ou executar uma ação protegida, ele deverá fornecer o código de 6 dígitos exibido em seu aplicativo. Seu sistema então verifica se o código é válido.

$userCode = '123456'; // Código fornecido pelo usuário
$isValid = $totp->verifyCode($secret, $userCode, 1);

if ($isValid) {
    echo "Código válido! Acesso concedido.";
} else {
    echo "Código inválido ou expirado.";
}

O terceiro parâmetro do método verifyCode() é a discrepância de tempo. Ele permite uma tolerância para pequenas diferenças de relógio entre o servidor e o dispositivo do usuário, verificando o código atual, o anterior e o próximo, o que torna o sistema mais robusto.

Análise do Código-Fonte (TOTP.php)

Uma das belezas do php-token é que ele permite um mergulho profundo no funcionamento do TOTP. Vamos analisar alguns trechos da classe TOTP.php.

O coração do algoritmo está no método getCode(). É aqui que a mágica acontece:

public function getCode($secret, $timestamp = null)
{
    $secretKey = $this->base32Decode($secret);
    $timeStep = $this->getTimeStep($timestamp);
    
    // Converte time step para binário de 64 bits (big-endian)
    $time = pack('N*', 0) . pack('N*', $timeStep);
    
    // Calcula HMAC
    $hash = hash_hmac($this->algorithm, $time, $secretKey, true);
    
    // Truncamento dinâmico (RFC 4226)
    $offset = ord($hash[strlen($hash) - 1]) & 0x0F;
    
    $truncatedHash = (
        ((ord($hash[$offset + 0]) & 0x7F) << 24) |
        ((ord($hash[$offset + 1]) & 0xFF) << 16) |
        ((ord($hash[$offset + 2]) & 0xFF) << 8) |
        (ord($hash[$offset + 3]) & 0xFF)
    );
    
    $code = $truncatedHash % (10 ** $this->codeLength);
    
    return str_pad($code, $this->codeLength, '0', STR_PAD_LEFT);
}

Este método executa os passos cruciais do TOTP: decodifica a chave, calcula o time step, gera o hash HMAC e, por fim, aplica o truncamento dinâmico para extrair o código numérico final.

Segurança em Primeiro Lugar

O repositório não apenas fornece o código, mas também um guia de boas práticas de segurança. É crucial seguir estas recomendações em um ambiente de produção:

• Armazene as chaves secretas de forma criptografada no banco de dados.
• Utilize HTTPS para todas as comunicações, protegendo os dados em trânsito.
• Implemente rate limiting para limitar o número de tentativas de verificação de código, prevenindo ataques de força bruta.
• Forneça códigos de backup para que os usuários possam recuperar o acesso às suas contas caso percam o dispositivo autenticador.

Conclusão

O php-token é uma excelente ferramenta para qualquer desenvolvedor PHP que busca implementar autenticação de dois fatores de maneira descomplicada e segura. Ele não só resolve um problema prático, mas também serve como um ótimo material de estudo para entender os detalhes de um dos mais importantes padrões de segurança da web moderna.

Convidamos você a explorar o repositório no GitHub, testar os exemplos e considerar contribuir para este projeto valioso. Adicionar 2FA à sua aplicação nunca foi tão simples.