Skip to content

README.md

Latest commit

 

History

History
80 lines (51 loc) · 3.89 KB

README.md

File metadata and controls

80 lines (51 loc) · 3.89 KB
Raw

Exemplo de Uso - everton3x/csrf

Este diretório contém uma aplicação de demonstração prática para testar e compreender o funcionamento da biblioteca de proteção CSRF (everton3x/csrf).

📋 Pré-requisitos

Para executar o exemplo, certifique-se de ter:

  1. PHP 8.5.7 ou superior instalado no ambiente.
  2. Dependências do projeto instaladas via Composer. Caso ainda não tenha instalado, execute no diretório raiz do projeto:
composer install

🚀 Como Executar o Exemplo

A forma mais simples e rápida de rodar o exemplo é utilizando o servidor embutido do PHP (PHP Built-in Web Server).

Opção 1: Executando a partir do diretório do exemplo (Recomendado)

Abra o terminal no diretório example/ e execute:

php -S localhost:8000

Em seguida, acesse no navegador: http://localhost:8000

Opção 2: Executando a partir da raiz do projeto

Abra o terminal na raiz do projeto e execute:

php -S localhost:8000 -t example

Em seguida, acesse no navegador: http://localhost:8000

🧪 Cenários Demonstrados no Exemplo

A página inicial (index.php) apresenta três formulários interativos que demonstram o comportamento do validador CSRF:

1. Teste com Token Válido (Sucesso)

  • Formulário: Inclui a tag gerada dinamicamente pelo método Csrf::token().
  • Comportamento: Ao clicar em "Testar", o formulário envia o token correspondente à sessão do usuário para login.php.
  • Resultado: Csrf::check() valida o token com sucesso usando hash_equals(), rotaciona o token para a próxima requisição e exibe a mensagem de sucesso: "Se você vê esta mensagem, então o teste CSRF passou.".

2. Teste sem Token CSRF (Falha)

  • Formulário: Submete o formulário POST sem nenhum campo csrf_token.
  • Comportamento: Ao clicar em "Testar", a requisição chega a login.php desprovida de token.
  • Resultado: Csrf::check() identifica a ausência do token, define o código de resposta como HTTP 409 Conflict (header('HTTP/1.1 409 Conflict')) e interrompe imediatamente a execução da página. O navegador exibirá a tela de erro de requisição conflitante.

3. Teste com Token CSRF Inválido (Falha)

  • Formulário: Submete um campo oculto com valor manipulado/falso (value="invalid_token").
  • Comportamento: Ao clicar em "Testar", a requisição envia uma credencial forjada ou incorreta.
  • Resultado: Csrf::check() compara o token enviado com o token gravado na sessão do usuário através de hash_equals(). Detectando a divergência (de forma segura contra timing attacks), emite a resposta HTTP 409 Conflict e encerra o processamento.

📂 Estrutura dos Arquivos de Exemplo

Arquivo Descrição
index.php Interface visual com os formulários de teste, inicializando a sessão e demonstrando o uso de Csrf::token().
login.php Endpoint de destino do formulário POST, inicializando a sessão e executando Csrf::check() para proteção do endpoint.

💡 Como Funciona o Ciclo de Vida do Token

  1. Inicialização da Sessão: Toda página que lida com CSRF deve iniciar a sessão do PHP antes de qualquer operação (session_start()).
  2. Geração e Injeção: Ao chamar Csrf::token(), caso a sessão ainda não possua $_SESSION['csrf_token'], um token criptograficamente seguro (32 bytes em hexadecimal via random_bytes) é criado. Uma tag <input type="hidden" name="csrf_token" value="..."> sanitizada é retornada.
  3. Validação e Rotação: No script receptor (login.php), Csrf::check() inspeciona requisições POST. Se o token for válido, o método gera automaticamente um novo token na sessão (rotação) para garantir proteção contra reutilização.