Field Encryption Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Doctrine Alignment: The bundle is designed for Symfony 6.4+/7.x and Doctrine ORM 2.14+/3.x, making it a strong fit for applications already using this stack. It leverages Doctrine’s event system (e.g., prePersist, preUpdate) for transparent encryption/decryption, minimizing invasive changes to business logic.
• Layered Encryption: Supports two distinct encryption modes (AES-256-CBC for strings, AES-256-GCM for binaries) with HMAC-SHA256 for integrity, aligning with modern cryptographic best practices. The use of HKDF for key derivation ensures cryptographic separation of concerns.
• Attribute-Driven: The #[Encrypted] and #[EncryptedFile] attributes enable declarative security, reducing boilerplate and improving maintainability. This is particularly valuable for large codebases where encryption logic might otherwise be scattered.

Integration Feasibility

• Minimal Code Changes: Encryption is transparent to application logic—no manual encrypt()/decrypt() calls required. Existing queries (e.g., findBy) work as-is due to HMAC-based searchability for strings.
• Doctrine Compatibility: Works with Doctrine’s lifecycle callbacks, but may require custom DQL functions for encrypted fields in complex queries (e.g., WHERE clauses on encrypted strings). The bundle provides a FieldEncryptionExtension for basic support.
• Binary File Handling: Encrypts files in-place (e.g., OneToMany/ManyToOne relations with BinaryBlobType or StringType for base64). Metadata (MIME type, filename) is stored separately, which is critical for file uploads/downloads.

Technical Risk

• Key Management: The bundle does not include a key storage solution (e.g., AWS KMS, HashiCorp Vault, or environment variables). Misconfiguration (e.g., hardcoded keys) could lead to data loss or exposure. Requires external integration or custom key storage logic.
• Performance Overhead:
  • String Fields: AES-256-CBC + HMAC adds ~5–10ms latency per field (benchmarks needed for production workloads).
  • Binary Files: AES-256-GCM + optional Gzip compression increases I/O overhead. Large files (e.g., videos) may require streaming encryption (not natively supported).
• Query Limitations:
  • Encrypted strings cannot be indexed in traditional ways (e.g., LIKE, ILIKE). The bundle provides HMAC-based partial matching, but complex searches may require application-layer filtering.
  • Doctrine Criteria API or native SQL queries on encrypted fields may fail without workarounds.
• Key Rotation Complexity: While the bundle supports rotation, migrating existing encrypted data requires careful planning (e.g., downtime, backup validation). The console wizard helps but assumes manual coordination.
• Dependency Maturity: The package has no stars/dependents, indicating unproven adoption. Lack of documentation (despite README) and no CI/CD pipeline (e.g., GitHub Actions) raises maintenance risk.

Key Questions

1. Key Storage Strategy:
   • How will encryption keys be stored/retrieved? (e.g., environment variables, secrets manager, database?)
   • What’s the key rotation strategy for existing data? (e.g., dual-write during transition?)
2. Performance Impact:
   • Have load tests been run on encrypted endpoints? What’s the acceptable latency threshold?
   • For binary files, is streaming encryption (e.g., chunked uploads) required for large files?
3. Query Requirements:
   • Are there complex searches (e.g., full-text, range queries) on encrypted fields? If so, how will they be handled?
   • Will Doctrine’s QueryBuilder or native SQL need custom extensions?
4. Compliance:
   • Does the encryption meet regulatory requirements (e.g., GDPR, HIPAA)? Are audit logs needed for key access?
5. Backup/Disaster Recovery:
   • How will encrypted backups be handled? (e.g., database dumps, S3 exports)
   • What’s the data recovery process if keys are lost?
6. Migration Path:
   • How will existing unencrypted data be migrated? (e.g., batch job, downtime)
   • Are there schema changes required (e.g., new columns for metadata)?

Integration Approach

Stack Fit

• Symfony Ecosystem: Ideal for Symfony 6.4+/7.x applications using Doctrine ORM. Leverages Symfony’s dependency injection, event system, and attribute system for seamless integration.
• PHP 8.2+: Requires named arguments, attributes, and modern Doctrine features (e.g., Collection changes in 2.14+). May need polyfills for older PHP versions.
• Database Compatibility:
  • Works with any Doctrine-supported database (MySQL, PostgreSQL, SQLite, etc.).
  • Binary file storage: Assumes BLOB/BYTEA types for encrypted binaries. May need adjustments for object storage (e.g., S3).
• File Uploads: Best suited for small-to-medium files (e.g., documents, images). Large files (e.g., videos) may require hybrid storage (e.g., encrypt metadata in DB, store files in S3 with pre-signed URLs).

Migration Path

1. Pre-Integration:
   • Audit dependencies: Ensure Doctrine ORM and PHP versions meet requirements.
   • Key infrastructure: Set up a key management system (e.g., AWS KMS, HashiCorp Vault) or secure storage (e.g., encrypted env vars).
   • Backup existing data: Encrypted data cannot be decrypted without the current key. Plan for dual-write during migration if needed.
2. Installation:
   • Composer: composer require caeligo/field-encryption-bundle
   • Register bundle in config/bundles.php.
   • Configure config/packages/field_encryption.yaml (e.g., key paths, compression settings).
3. Attribute-Based Setup:
   • Add #[Encrypted] to sensitive string fields (e.g., password, creditCardNumber).
   • Add #[EncryptedFile] to file upload fields (e.g., profilePicture, resume).
   • Example:

     #[ORM\Entity]
     class User {
         #[ORM\Column]
         #[Encrypted]
         private string $ssn;
     
         #[ORM\Column(type: 'string', length: 255)]
         #[EncryptedFile]
         private string $filePath;
     }
     

4. Key Generation:
   • Run php bin/console field-encryption:generate-key to create a master key.
   • Store the key securely (e.g., secrets manager) and configure field_encryption.key_path.
5. Data Migration:
   • For new applications: Start with encrypted fields from day one.
   • For existing data:
     • Option 1: Re-encrypt during write (e.g., add a #[Encrypted] attribute and let Doctrine handle it on next update).
     • Option 2: Batch migration using the field-encryption:migrate command (if available).
     • Option 3: Dual-write (store both encrypted and unencrypted until migration completes).
6. Testing:
   • Unit tests: Verify encryption/decryption of entities.
   • Integration tests: Test file uploads/downloads, queries, and edge cases (e.g., malformed data).
   • Performance tests: Measure latency impact on critical paths.

Compatibility

• Doctrine Extensions: May conflict with other Doctrine listeners or behavior extensions (e.g., StoDoctrineExtensions). Test for priority conflicts.
• Symfony Forms: File uploads via FileType will work, but custom validation may be needed for encrypted metadata.
• API Platform: If using API Platform, ensure serialization/deserialization of encrypted fields doesn’t break (e.g., #[ApiProperty] compatibility).
• Legacy Code: Existing raw SQL queries or native queries may fail on encrypted fields. Use the bundle’s FieldEncryptionExtension for basic support.

Sequencing

1. Phase 1: Non-Production Validation
   • Set up in a staging environment.
   • Test with non-critical data first.
   • Validate key rotation and backup/restore.
2. Phase 2: Critical Path Integration
   • Start with high-sensitivity fields (e.g., PII).
   • Gradually add less critical fields.
3. Phase 3: File Uploads
   • Test file encryption/decryption with various formats (PDF, images, etc.).