Doctrine Encryption Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Aligns with GDPR compliance requirements for sensitive data encryption at the Doctrine ORM layer, reducing manual encryption/decryption logic in business logic.
  • Leverages annotations for declarative encryption, improving developer experience and reducing boilerplate.
  • Supports Twig integration, enabling seamless decryption in templates without exposing raw data.
  • Symfony/Bundle structure ensures compatibility with existing Laravel (via Symfony components) or Symfony-based stacks.

• Cons:

  • Lack of Laravel-native support (Symfony bundle) may require adapters or workarounds for Laravel’s ecosystem (e.g., Eloquent, service container).
  • No postLoad event could lead to performance overhead if decryption happens repeatedly (e.g., in loops or complex queries).
  • Last release in 2018 raises concerns about security updates, PHP 8.x compatibility, and Doctrine 3.x+ support.
  • No active maintenance (0 stars, no contributors) introduces long-term risk for critical security patches.

Integration Feasibility

• Doctrine ORM Dependency:
  • Laravel uses Eloquent, not Doctrine, so direct integration is non-trivial but possible via:
    • Doctrine Bridge (e.g., doctrine/orm + doctrine/dbal for Laravel).
    • Custom Eloquent Events (retrieved, saved) to mirror Doctrine’s prePersist/preUpdate.
  • Risk: Eloquent’s event system may not perfectly replicate Doctrine’s lifecycle callbacks.
• Encryption Method:
  • Uses AES-256-CBC (default), which is secure but requires proper key management (e.g., environment variables, AWS KMS).
  • IV handling must be deterministic (e.g., per-record) to avoid decryption failures.
• Configuration:
  • Hardcoded key/IV in YAML is insecure—must be replaced with environment variables or a key management system.

Technical Risk

Key Questions

1. Is GDPR compliance the primary driver, or is this for broader sensitive data protection?
   • If the latter, consider Laravel-specific packages (e.g., spatie/laravel-encryption).
2. Can we use this bundle’s encryption logic without the Doctrine layer?
   • Extract the core encryptor class and integrate it directly into Eloquent.
3. What’s the migration path for existing encrypted data?
   • Will old data need re-encryption with new keys/IVs?
4. How will we handle key rotation?
   • The bundle doesn’t support it natively—custom logic may be required.
5. What’s the fallback if decryption fails (e.g., corrupted IV)?
   • Define a graceful degradation strategy (e.g., log errors, mask data).

Integration Approach

Stack Fit

• Target Stack:

  • Laravel 9.x/10.x (PHP 8.1+).
  • Doctrine ORM (via doctrine/dbal and doctrine/orm packages) for Doctrine compatibility.
  • Symfony Components (e.g., symfony/dependency-injection, symfony/config) for bundle integration.
  • Alternative: Use the bundle’s core encryptor class without Doctrine (if possible).

• Compatibility Matrix:

  Component	Laravel Native	Doctrine Bundle	Workaround Needed?
  Encryption Logic	❌	✅	Extract class or use Symfony
  Entity Annotations	❌ (Eloquent)	✅	Custom trait/event system
  Twig Decryption	✅ (via filters)	✅	Adapt bundle’s Twig extension
  Doctrine Events	❌	✅	Eloquent events or hybrid

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Install doctrine/orm and doctrine/dbal in Laravel.
   • Test the bundle’s core encryptor outside Doctrine (e.g., as a standalone service).
   • Verify PHP 8.1+ compatibility and patch if needed.

2. Phase 2: Hybrid Integration

   • Option A: Use Doctrine ORM alongside Eloquent (e.g., for specific encrypted entities).
     • Configure Doctrine to share the same connection as Eloquent’s DBAL.
     • Map Eloquent models to Doctrine entities for encrypted fields.
   • Option B: Replace Doctrine with Eloquent Events.
     • Create a custom trait to replicate @Encrypted behavior:

       trait Encryptable {
           protected static function booted() {
               static::saving(function ($model) {
                   $model->encryptSensitiveFields();
               });
               static::retrieved(function ($model) {
                   $model->decryptSensitiveFields();
               });
           }
       }
       

     • Use the bundle’s encryptor class for logic.

3. Phase 3: Full Adoption

   • Replace manual encryption in controllers/Twig with bundle services.
   • Deprecate old encrypted fields in favor of annotated fields.
   • Audit queries to ensure no raw data leaks (e.g., in toArray() or API responses).

Compatibility Considerations

• Doctrine vs. Eloquent:
  • Eloquent’s retrieved event fires after hydration, unlike Doctrine’s postLoad. This may cause N+1 decryption queries if not optimized.
  • Solution: Decrypt only when needed (e.g., lazy-load decrypted fields).
• Twig Integration:
  • The bundle’s Twig filter assumes Doctrine entities. For Eloquent:

    {{ user.firstname|app.decryptFilter }}  {# Custom filter #}
    

• Key Management:
  • Replace YAML keys with Laravel’s .env:

    # config/doctrine_encryption.yaml
    doctrine_encryption:
      key: '%env(ENCRYPTION_KEY)%'
      iv: '%env(ENCRYPTION_IV)%'
    

Sequencing

1. Step 1: Set up Doctrine ORM in Laravel (if using Option A).
2. Step 2: Integrate the encryptor service into Laravel’s container.
3. Step 3: Implement @Encrypted equivalent for Eloquent (Phase 2 Option B).
4. Step 4: Migrate existing encrypted data (if any).
5. Step 5: Replace manual encryption in business logic with the bundle’s services.
6. Step 6: Add monitoring for decryption failures.

Operational Impact

Maintenance

• Pros:
  • Centralized encryption logic reduces duplication.
  • Annotation-driven approach minimizes future changes.
• Cons:
  • No active maintenance means security patches must be backported or forked.
  • Key rotation requires custom logic (not supported out-of-the-box).
  • Doctrine dependency adds complexity if Laravel’s Eloquent is the primary ORM.

Support

• Debugging Challenges:
  • Decryption failures may be hard to trace (e.g., wrong IV, corrupted data).
  • No postLoad event could obscure issues where data isn’t decrypted in time.
• Monitoring:
  • Log decryption errors and failed events (e.g., prePersist/preUpdate).
  • Track encryption/decryption latency in performance-critical paths.
• Fallbacks:
  • Define graceful handling for encrypted data (e.g., mask with [REDACTED] if decryption fails).

Scaling

• Performance:
  • Pre-persist/update hooks add overhead. Benchmark with:
    • 10K records: ~50ms–200ms (depends on IV generation).
    • Optimization: Cache IVs or use deterministic generation.
  • Twig decryption: Avoid decrypting in loops (e.g., {% for user in users %}{{ user.firstname|decrypt }}{% endfor %}).
• Database:
  • Encrypted fields **cannot