README

A Symfony bundle for transparent Doctrine entity field encryption using AES-256-CBC for string fields and AES-256-GCM for binary files.

Features

• 🔐 Automatic encryption/decryption - Transparent for your application code
• 📝 String field encryption - AES-256-CBC with HMAC-SHA256 hash for searching
• 📁 Binary file encryption - AES-256-GCM for documents, images, etc.
• 🔑 HKDF key derivation - Cryptographic key separation for different purposes
• 🛡️ Timing-safe comparison - Protection against timing attacks on hash verification
• 🏷️ Attribute-based configuration - Simple #[Encrypted] and #[EncryptedFile] attributes
• 🔄 Key rotation support - Safely rotate keys with progress tracking
• 🗜️ Optional compression - Gzip compression for binary files
• 📋 Metadata storage - Store MIME type, filename, size alongside encrypted content
• 🛠️ Console commands - Key generation, rotation wizard, data migration

Requirements

• PHP 8.2+
• Symfony 6.4+ or 7.x
• Doctrine ORM 2.14+ or 3.x

Installation

composer require caeligo/field-encryption-bundle

Register the bundle in config/bundles.php:

return [
    // ...
    Caeligo\FieldEncryptionBundle\FieldEncryptionBundle::class => ['all' => true],
];

Quick Start

1. Generate Encryption Key

php bin/console field-encryption:generate-key --append-to-env

2. Configure the Bundle

# config/packages/field_encryption.yaml
field_encryption:
    encryption_key: '%env(FIELD_ENCRYPTION_KEY)%'

3. Add Attributes to Your Entity

use Caeligo\FieldEncryptionBundle\Attribute\Encrypted;
use Caeligo\FieldEncryptionBundle\Attribute\EncryptedEntity;

#[ORM\Entity]
#[EncryptedEntity]
class User
{
    #[ORM\Column(type: Types::TEXT, nullable: true)]
    #[Encrypted(hashField: true, hashProperty: 'emailHash')]
    private ?string $email = null;

    #[ORM\Column(type: Types::TEXT, nullable: true, unique: true)]
    private ?string $emailHash = null;

    private ?string $plainEmail = null;  // Transient, auto-populated

    public function getEmail(): ?string
    {
        return $this->plainEmail;
    }

    public function setEmail(?string $email): self
    {
        $this->plainEmail = $email;
        return $this;
    }
}

That's it! The bundle automatically encrypts on save and decrypts on load.

Documentation

Basic Examples

Encrypted String Field

#[Encrypted(hashField: true)]
private ?string $email = null;

private ?string $plainEmail = null;
private ?string $emailHash = null;

Encrypted File Field

use Caeligo\FieldEncryptionBundle\Attribute\EncryptedFile;
use Caeligo\FieldEncryptionBundle\Model\EncryptedFileData;

#[EncryptedFile(mimeTypeProperty: 'mimeType', originalNameProperty: 'fileName')]
private $document;

private ?EncryptedFileData $plainDocument = null;
private ?string $mimeType = null;
private ?string $fileName = null;

Working with Files

// From upload
$fileData = EncryptedFileData::fromUploadedFile($uploadedFile);
$entity->setPlainDocument($fileData);

// To download
$content = $entity->getPlainDocument()->getContent();
$mimeType = $entity->getPlainDocument()->getMimeType();

Console Commands

# Generate new encryption key
php bin/console field-encryption:generate-key

# Rotate encryption keys (interactive wizard)
php bin/console field-encryption:rotate-keys --wizard

# Encrypt existing unencrypted data
php bin/console field-encryption:encrypt-existing --dry-run

Security Considerations

• ⚠️ Never commit encryption keys - Use environment variables
• 💾 Backup your keys - Key loss = data loss
• 🔄 Plan key rotation - Use the wizard for safe rotation
• 🔍 Use hashes for search - Enable hashField for searchable fields
• 🆔 Use ULID/UUID - Don't use sequential integers for key derivation
• 🌶️ Consider hash pepper - Use hash_pepper config for extra key separation

Database Compromise Protection

This bundle provides strong protection if only your database is compromised:

Key requirement: The encryption key must NOT be stored in the database.

License

MIT License - see LICENSE

Author

Bíró Gábor (@biga156)

Repository

• GitHub: https://github.com/biga156/field-encryption-bundle
• Packagist: https://packagist.org/packages/caeligo/field-encryption-bundle