Encrypted Fields Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Doctrine-Centric Design: Aligns perfectly with Symfony’s Doctrine ORM, requiring minimal architectural changes. The attribute-based approach (#[EncryptedField]) integrates seamlessly with existing entity structures, reducing cognitive load for developers.
  • Per-Field Granularity: Enables selective encryption of sensitive fields (e.g., credit_card_number, ssn) without over-encrypting non-sensitive data, optimizing performance and storage.
  • Key Hierarchy: Uses a master key to encrypt per-record keys, adhering to security best practices (e.g., NIST SP 800-57). This design limits blast radius if the master key is compromised.
  • Transparency: Encryption/decryption occurs automatically during Doctrine lifecycle events (prePersist, preUpdate, postLoad), abstracting cryptographic complexity from business logic.
  • Audit Trail: The encryption_key table provides a centralized repository for keys, aiding compliance audits (e.g., GDPR Article 32).

• Cons:

  • Doctrine Dependency: Tight coupling to Doctrine ORM excludes Laravel/Eloquent users without significant refactoring. This limits adoption in non-Symfony stacks.
  • Performance Trade-offs: Per-record key generation and AES-GCM operations introduce latency, particularly for high-throughput systems (e.g., >10K QPS). Benchmarking is critical.
  • Schema Impact: Requires a dedicated encryption_key table, adding complexity to migrations and database backups. Schema changes may conflict with existing CI/CD pipelines.
  • Key Management Gaps: Lacks native support for key rotation policies, HSM integration, or automated key revocation, requiring custom solutions for regulated environments.
  • OpenSSL Dependency: Relies on PHP’s OpenSSL extension, which may not be available in all hosting environments (e.g., shared servers, legacy systems).

Integration Feasibility

• Symfony Ecosystem:
  • Seamless: Designed for Symfony, with native support for Symfony Flex, Doctrine, and console commands. Minimal integration effort beyond configuration.
  • Tooling: Compatible with Symfony’s dependency injection, event system, and migration tools (e.g., make:migration).
• Laravel/Eloquent:
  • Challenging: Requires bridging Doctrine ORM (e.g., laravel-doctrine/orm) and adapting Symfony-specific components (e.g., console commands, config files). Not recommended unless Doctrine is already in use.
• Database Compatibility:
  • Wide Support: Works with PostgreSQL, MySQL, SQLite, and others via Doctrine. However, performance may vary (e.g., PostgreSQL’s pgcrypto could offer better throughput).
  • Binary Data: Encrypted fields are stored as binary blobs, which may require adjustments to existing queries or indexes.

Technical Risk

• Security Risks:
  • Master Key Exposure: Compromise of the master key (stored in ENCRYPTED_FIELDS_KEY) grants access to all per-record keys. Mitigation: Use a secrets manager (e.g., AWS Secrets Manager) and restrict access via IAM policies.
  • Side-Channel Attacks: AES-GCM is secure, but improper implementation (e.g., key reuse) could introduce vulnerabilities. Validate with tools like PHPStan or manual code reviews.
  • Key Rotation Complexity: The rotate-key command decrypts/re-encrypts all data, which may be impractical for large datasets. Plan for offline backups or incremental rotation strategies.
• Operational Risks:
  • Downtime During Migration: Adding the encryption_key table requires a migration, which may cause downtime in production. Use blue-green deployments or zero-downtime migration tools (e.g., Laravel’s migrate:refresh).
  • Backup/Restore: Encrypted data cannot be restored without the master key. Document key backup procedures and test restores in staging.
  • Monitoring Gaps: No built-in logging or alerts for encryption failures (e.g., corrupted keys, decryption errors). Integrate with APM tools (e.g., New Relic) to monitor latency spikes.
• Performance Risks:
  • Latency: AES-GCM operations add ~1–5ms per field (varies by hardware). Test with production-like data volumes to identify bottlenecks.
  • Memory Usage: Per-record key storage increases database size. Monitor storage growth, especially for high-cardinality tables.
• Maintenance Risks:
  • Package Maturity: Low adoption (6 stars, 0 dependents) suggests limited community support. Monitor GitHub issues for unresolved bugs or security vulnerabilities.
  • PHP Version Support: Ensure compatibility with your PHP version (e.g., PHP 8.1+ for attributes). Check the package’s composer.json for supported versions.

Key Questions

1. Compliance Alignment:
   • Does the package meet specific compliance requirements (e.g., HIPAA’s "addressable" implementation specifications, PCI DSS 3.5)?
   • Are there gaps in audit logging (e.g., tracking who accesses encrypted fields)?
2. Key Management:
   • How will master keys be rotated without decrypting all data? (Consider a phased approach or offline backups.)
   • What’s the process for revoking compromised keys? (No native support; may require custom scripts.)
3. Performance:
   • What’s the acceptable latency threshold for encrypted fields? Benchmark with 10x production load.
   • Can encrypted fields be cached (e.g., Redis) to reduce decryption overhead?
4. Disaster Recovery:
   • How will encrypted data be restored if the master key is lost? (Test with a staging database.)
   • Are database backups encrypted separately (e.g., with AWS KMS)?
5. Alternatives:
   • Would application-level encryption (e.g., Laravel’s encrypt()) or database-native encryption (e.g., PostgreSQL TDE) be more suitable?
   • Are there higher-maturity packages (e.g., spatie/laravel-encryption) with broader adoption?
6. Multi-Tenancy:
   • How will tenant-specific keys be managed? (Current design uses a single master key; may need extension.)
7. Testing:
   • Are there unit/integration tests for edge cases (e.g., corrupted keys, large binary fields, concurrent writes)?
   • How will encryption correctness be verified (e.g., unit tests vs. manual inspection)?

Integration Approach

Stack Fit

• Symfony (Primary Fit):

  • ORM: Doctrine 2+ (required). Leverage existing entity structures with minimal changes.
  • Configuration:
    • Use Symfony Flex for zero-config installation (add Flex recipe to composer.json).
    • Store master key in .env (e.g., ENCRYPTED_FIELDS_KEY=%env(ENCRYPTED_FIELDS_KEY)%).
    • Configure gebler_encrypted_fields.yaml with cipher and key paths.
  • Tooling:
    • Replace make:migration with Symfony’s make:entity or doctrine:migrations:generate.
    • Use Symfony’s console for key rotation (php bin/console gebler:encryption:rotate-key).
  • Caching:
    • Optional: Cache decrypted values with Symfony’s Cache component to reduce DB load.
    • Example: Cache encrypted fields for read-heavy endpoints (e.g., user profiles).

• Laravel (Partial Fit):

  • Prerequisites:
    • Install Doctrine ORM (e.g., laravel-doctrine/orm).
    • Bridge Symfony components (e.g., symfony/console, symfony/dependency-injection).
  • Adaptations:
    • Replace YAML config with Laravel’s .env and a service provider.
    • Override Symfony console commands with Laravel Artisan commands.
    • Example: Create a custom Artisan command for key rotation:

      // app/Console/Commands/RotateEncryptionKey.php
      use Gebler\EncryptedFieldsBundle\Command\RotateKeyCommand;
      use Symfony\Component\Console\Application;
      
      class RotateEncryptionKey extends Command {
          protected $signature = 'gebler:rotate-key {--generate-new-key} {--database-key=} {--database-key-file=}';
          public function handle() {
              $app = new Application();
              $app->add(new RotateKeyCommand());
              $app->run(new ArrayInput($this->option('generate-new-key') ? ['command' => 'gebler:encryption:rotate-key', '--generate-new-key' => true] : []));
          }
      }
      

  • Alternatives: If Doctrine integration is prohibitive, consider Laravel-specific packages (e.g., spatie/laravel-encryption).

• Database Layer:

  • Compatibility: Works with PostgreSQL, MySQL, SQLite, etc., via Doctrine.
  • Performance: Test with your database’s encryption extensions (e.g., PostgreSQL’s pgcrypto for bulk operations).
  • Indexes: Ensure indexes on encrypted fields are handled (e.g., avoid indexing encrypted blobs).

Migration Path

1. Preparation Phase:
   • Audit: Ident