README

English | 中文

A Symfony Bundle for automatically encrypting and decrypting specific cookies, particularly useful for deployment environments with strict WAF (Web Application Firewall) rules, such as Azure.

Features

Automatic encryption of specified cookies in responses
Automatic decryption of specified cookies in requests
Uses XOR encryption algorithm with base64 encoding
Zero configuration after initial setup
Seamless integration with Symfony's event system

Requirements

PHP 8.1 or higher
Symfony 6.4 or higher

Installation

Install via Composer:

composer require tourze/cookie-encrypt-bundle

Configuration

1. Set Encryption Key

Add the encryption key to your .env file:

COOKIE_XOR_SECURITY_KEY=your_secure_key_here

⚠️ Important:

Use a strong, random encryption key
Keep the key secret and never commit it to version control
Consider using different keys for different environments

2. Register the Bundle

If not using Symfony Flex, register the bundle in config/bundles.php:

return [
    // ...other bundles
    Tourze\CookieEncryptBundle\CookieEncryptBundle::class => ['all' => true],
];

Usage

Once installed and configured, the bundle automatically handles encryption/decryption for the following cookies:

sf_redirect - Symfony's redirect cookie

The bundle works transparently:

On Request: Automatically decrypts encrypted cookies before your application processes them
On Response: Automatically encrypts cookies before sending them to the client

How It Works

When a request arrives, the CookieEncryptSubscriber checks for encrypted cookies
If found, it decrypts them using the XOR algorithm and replaces the encrypted values
Your application works with the decrypted values normally
Before sending the response, the subscriber encrypts the cookie values again

Advanced Configuration

Custom Cookie Names

To encrypt additional cookies, extend the CookieEncryptSubscriber class:

namespace App\EventSubscriber;

use Tourze\CookieEncryptBundle\EventSubscriber\CookieEncryptSubscriber;

class CustomCookieEncryptSubscriber extends CookieEncryptSubscriber
{
    protected array $names = [
        'sf_redirect',
        'my_custom_cookie',
        'another_cookie',
    ];
}

Then override the service definition in your config/services.yaml:

services:
    Tourze\CookieEncryptBundle\EventSubscriber\CookieEncryptSubscriber:
        class: App\EventSubscriber\CustomCookieEncryptSubscriber

Security Considerations

The XOR encryption is designed for WAF bypass, not cryptographic security
Always use HTTPS in production to prevent man-in-the-middle attacks
Rotate encryption keys periodically
Store encryption keys securely (use Symfony secrets management)

Testing

Run the test suite:

# From the monorepo root
./vendor/bin/phpunit packages/cookie-encrypt-bundle/tests

# Run with PHPStan
php -d memory_limit=2G ./vendor/bin/phpstan analyse packages/cookie-encrypt-bundle

Troubleshooting

InvalidEncryptionKeyException

This exception is thrown when:

The COOKIE_XOR_SECURITY_KEY environment variable is not set
The encryption key is empty or contains only whitespace

Solution: Ensure you have set a valid encryption key in your .env file.

Cookies Not Being Encrypted

Check that:

The bundle is properly registered
The encryption key is set
The cookie name is in the list of cookies to encrypt

Contributing

Please see the main monorepo README for contribution guidelines.

License

MIT

tourze / cookie-encrypt-bundle

Maintainers

Details