spencer14420/sp-anti-csrf

Can be used to generate and validate anti-CSRF tokens

1.0.0-beta1 2024-11-28 21:53 UTC

MIT

• spencer14420

README

SPAntiCSRF is a lightweight PHP package that secures web applications against CSRF attacks using token-based validation.

Features

• Session-based CSRF token management: Tokens are stored securely in PHP sessions.
• Token expiration: Tokens expire after a configurable duration for enhanced security.
• Validation and replay protection: Ensures tokens are valid and prevents token reuse.
• Session regeneration: Provides a method to regenerate session IDs, helping to mitigate session fixation attacks when used appropriately.
• One-time token usage: Tokens are invalidated after successful validation to prevent reuse.

Installation

You can install SPAntiCSRF using Composer:

composer require spencer14420/sp-anti-csrf

Usage

Generate a CSRF Token

Generate a token when rendering forms or making requests that require CSRF protection:

use spencer14420\SpAntiCsrf\AntiCsrf;

$csrf = new AntiCsrf();
$token = $csrf->generateToken();

Use the token in your HTML form:

<input
  type="hidden"
  id="csrf_token"
  name="csrf_token"
  value="<?php echo $token ?>"
/>

Validate the Token

Validate the token on the server side when processing the form submission:

use spencer14420\SpAntiCsrf\AntiCsrf;

$csrf = new AntiCsrf();

try {
    $token = $_POST['csrf_token'] ?? '';
    if (!$csrf->tokenIsValid($token)) {
        throw new Exception('Invalid CSRF token.');
    }
    // Proceed with processing the form
} catch (Exception $e) {
    // Handle invalid or expired token
    echo 'Error: ' . $e->getMessage();
}

Regenerate the Session

For added security, you can regenerate the session ID periodically or after certain actions:

$csrf->regenerateSession();

• Consider calling regenerateSession() after sensitive actions like user login, logout, or privilege escalation to protect against session fixation attacks.

API Reference

generateToken(int $expirySeconds = 3600): string

Generates a new CSRF token, and stores it in a session variable with an expiry time (default: 1 hour).

• Parameters:
  • $expirySeconds: The token's lifetime in seconds.
• Returns: The generated token as a string.

tokenIsValid(string $tokenToCheck): bool

Validates a CSRF token.

• Parameters
  • $tokenToCheck: The token to validate.
• Returns: true if the token is valid and has not expired; false otherwise.

regenerateSession(): void

Regenerates the PHP session ID to mitigate session fixation attacks.

tokenIsNotExpired(): bool

Checks if the stored token has expired.

• Returns: true if the token has not expired; false otherwise.