DOCSEARCHbyAlgolia
Submit Docs

PHP-Secure-Session

repository·master·Indexed 18 days ago

https://github.com/ezimuel/php-secure-session

A library that provides an encryption and authentication layer for PHP's internal session save handlers. It uses AES-256 and HMAC-SHA-256 via the OpenSSL extension to secure session data stored by standard handlers such as files, SQLite, memcache, or memcached. The SecureHandler manages encryption keys via cookies and requires the openssl and mbstring extensions.

Tokens
1K
Snippets
5
Records
6
Agent score
64%

What's inside php-secure-session

  1. How PHP-Secure-Session works

    master

    PHP-Secure-Session adds an encryption layer to existing PHP session handlers (like 'file', 'sqlite', 'memcache', or 'memcached') using the OpenSSL extension.

    It provides:

    • Encryption: AES-256
    • Authentication: HMAC-SHA-256

    Key Management: Session data is encrypted using a random key and a random authentication key. These keys are stored in a cookie variable prefixed with KEY_. The value in the KEY_ cookie is the Base64 representation of the encryption key concatenated with the authentication key. The keys are generated using random_bytes() (or the paragonie/random_compat polyfill for PHP 5).

  2. Install PHP-Secure-Session via Composer

    master

    Install the library using Composer to add an encryption layer to your PHP session handlers. Once installed, the SecureHandler is automatically registered with session_set_save_handler() when you include your project's vendor/autoload.php file.

    composer require ezimuel/php-secure-session

  3. Register the secure session handler via PHP

    master

    To register the PHPSecureSession\\SecureHandler as the global session handler for your application, call session_set_save_handler() passing a new instance of the handler. Setting the second parameter to true ensures that the handler is also used for session read/write operations.

    <?php
// Register the secure session handler
session_set_save_handler(new \PHPSecureSession\SecureHandler(), true);

  5. Use SecureHandler to encrypt PHP sessions

    master

    The PHPSecureSession\SecureHandler class extends the native PHP SessionHandler to add an encryption and authentication layer to session data. It uses AES-256-CBC for encryption and HMAC with SHA256 for authentication.

    To use it, instantiate SecureHandler and register it using session_set_save_handler().

    Requirements:

    • The openssl extension must be loaded.
    • The mbstring extension must be loaded.

    Key Behavior:

    • Key Management: The handler automatically manages encryption and authentication keys by storing them in a cookie named KEY_ followed by your session name (e.g., KEY_PHPSESSID).
    • Security: If the key cookie is missing, a new 64-byte key is generated and sent to the client via a cookie that respects your existing session cookie parameters (path, domain, secure, httponly, and lifetime).
    <?php

use PHPSecureSession\SecureHandler;

// 1. Instantiate the secure handler
$handler = new SecureHandler();

// 2. Register it as the session save handler
session_set_save_handler($handler, true);

// 3. Start the session
session_start();

// Now, any data written to $_SESSION will be encrypted before being saved to the storage backend
$_SESSION['user_id'] = 123;

  6. Handle authentication failures with AuthenticationFailedException

    master

    When using php-secure-session, an AuthenticationFailedException is thrown if session authentication fails. This exception extends \[RuntimeException](https://www.php.net/manual/en/class.runtimeexception.php). You should catch this exception to handle unauthorized access attempts or session invalidation gracefully in your application logic.

    try {
    // Code that triggers session authentication
} catch (\PHPSecureSession\Exception\AuthenticationFailedException $e) {
    // Handle the authentication failure (e.g., redirect to login, show error)
}