Encryptable Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Seamless Eloquent Integration: Leverages Laravel’s native Eloquent ORM, requiring minimal architectural changes. Ideal for applications already using Laravel’s model-layer abstractions.
  • Field-Level Granularity: Encrypts only specified fields ($encryptable), preserving flexibility for mixed-sensitive/non-sensitive data.
  • Transparency: Decryption happens automatically during attribute access, abstracting encryption logic from business layers.
  • Composability: Works alongside Laravel’s built-in encryption (e.g., encrypt()/decrypt()) or other packages (e.g., Laravel Cashier for payment data).

• Cons:

  • Tight Coupling to Eloquent: Not suitable for non-ORM data layers (e.g., raw database queries, API responses requiring manual encryption).
  • No Query-Level Encryption: Encrypts data at rest but doesn’t support encrypted queries (e.g., WHERE encrypted_column = ?).
  • Legacy Laravel Version: Targets Laravel 5.x; may require polyfills or updates for Laravel 8/9+ (e.g., dependency injection, helper changes).

Integration Feasibility

• Low Effort for Basic Use Cases:
  • Drop-in replacement for manual encrypt() calls in setAttribute() or boot().
  • Example: Replace User::creating(fn ($model) => $model->password = bcrypt($model->password)) with $encryptable = ['password'].
• Complex Scenarios:
  • Custom Accessors/Mutators: May conflict with existing logic (e.g., getPasswordAttribute() vs. automatic decryption).
  • API Responses: Requires explicit handling to avoid leaking encrypted data in JSON responses (e.g., hidden or appends arrays).
  • Database Migrations: Existing encrypted data won’t auto-migrate; requires manual re-encryption or schema changes.

Technical Risk

• Security Risks:
  • Key Management: Relies on APP_KEY; improper key rotation or exposure (e.g., .env leaks) compromises all encrypted data.
  • Side-Channel Attacks: Automatic decryption during attribute access could expose timing attacks if not mitigated (e.g., constant-time comparisons).
  • No Field-Level Key Rotation: Re-encrypting data on key changes requires full table scans or application downtime.
• Compatibility Risks:
  • Laravel Version Drift: Unmaintained since 2020; may break with newer Laravel versions (e.g., dependency changes, query builder updates).
  • Database-Specific Behavior: Assumes standard SQL encryption support; edge cases (e.g., JSON columns, PostgreSQL pgcrypto) untested.
• Performance Risks:
  • Decryption Overhead: Every attribute access triggers decryption, which may impact read-heavy workloads (mitigate with caching or selective encryption).

Key Questions

1. Compliance Requirements:
   • Does the application need field-level audit logs for encrypted data (e.g., GDPR right to erasure)?
   • Are there regulatory mandates for encryption (e.g., HIPAA, PCI-DSS) that require additional controls (e.g., key escrow, hardware security modules)?
2. Data Lifecycle:
   • How often does encrypted data change or expire? (Affects key rotation strategy.)
   • Are there legacy systems that need to read encrypted data without decryption keys?
3. Architecture Constraints:
   • Will this package coexist with other encryption layers (e.g., database-level TDE, application-level TLS)?
   • Are there non-Eloquent data sources (e.g., API payloads, external databases) requiring encryption?
4. Operational Trade-offs:
   • What’s the acceptable latency for decryption (e.g., 1ms vs. 10ms per field)?
   • How will key management scale (e.g., multi-tenant keys, dynamic key derivation)?

Integration Approach

Stack Fit

• Ideal For:
  • Laravel Monoliths: Applications where Eloquent models dominate data access (e.g., SaaS platforms, CRM systems).
  • Sensitive Field Isolation: Use cases like PII (SSN, email), payment tokens, or health records where only specific fields need encryption.
  • Legacy Migration: Gradually encrypting sensitive data in existing Laravel apps without rewriting business logic.
• Poor Fit:
  • Microservices: Encryption logic tied to Eloquent models complicates service boundaries.
  • Headless APIs: If responses require manual encryption/decryption control.
  • Non-Laravel Stacks: PHP applications using raw PDO or other ORMs.

Migration Path

1. Assessment Phase:
   • Audit models to identify candidate fields for encryption (e.g., password, credit_card, ssn).
   • Validate compatibility with existing accessors/mutators and observers.
2. Pilot Phase:
   • Start with low-risk models (e.g., User, Payment) in a staging environment.
   • Test CRUD operations, serialization (JSON/API responses), and database backups.
3. Rollout Strategy:
   • Option A: Big Bang:
     • Add trait to all target models simultaneously.
     • Re-encrypt existing data via a data migration (e.g., php artisan encryptable:migrate if available, or custom script).
   • Option B: Incremental:
     • Encrypt one model at a time, verifying no regressions.
     • Use feature flags to toggle encryption per environment.
4. Post-Migration:
   • Implement key rotation procedures (e.g., double-encrypt during transition).
   • Add monitoring for decryption failures (e.g., logs for EncryptionException).

Compatibility

• Laravel Versions:
  • Tested: Laravel 5.x. For Laravel 8/9:
    • Replace use Illuminate\Database\Eloquent\Model with use Illuminate\Database\Eloquent\Model as BaseModel.
    • Update composer.json to resolve dependencies (e.g., illuminate/support).
  • Workarounds: Use a compatibility layer (e.g., laravel-shift/laravel-5-to-8) if critical.
• Database Compatibility:
  • Supported: MySQL, PostgreSQL, SQLite (via PHP’s openssl_encrypt).
  • Unsupported: SQL Server (may need custom cipher configuration).
• Third-Party Conflicts:
  • Model Casting: Ensure no conflicts with attributeCast (e.g., protected $casts = ['encrypted_field' => 'encrypted']).
  • Serialization: Use hidden or appends to exclude encrypted fields from API responses.

Sequencing

1. Prerequisites:
   • Generate/apply APP_KEY (php artisan key:generate).
   • Backup databases before migration.
2. Core Implementation:
   • Add Encryptable trait to models.
   • Define $encryptable array per model.
3. Edge Cases:
   • Mass Assignment: Whitelist encrypted fields in $fillable if using fill().
   • Relationships: Ensure encrypted fields in related models don’t break eager loading.
4. Validation:
   • Test unit tests for model hydration/serialization.
   • Test integration tests for API endpoints and background jobs.

Operational Impact

Maintenance

• Proactive Tasks:
  • Key Rotation: Schedule periodic key changes (e.g., annually) with a re-encryption script.
  • Dependency Updates: Monitor for Laravel version compatibility (e.g., watch for illuminate/support updates).
  • Backup Validation: Verify encrypted data integrity in backups (e.g., restore test backups and decrypt).
• Reactive Tasks:
  • Decryption Failures: Log and alert on EncryptionException (e.g., corrupted data, key issues).
  • Schema Changes: Document encrypted field additions/removals in migration scripts.

Support

• Debugging Challenges:
  • Silent Failures: Decryption errors may not bubble up (e.g., returning null instead of throwing).
  • Key Management: Lost APP_KEY requires full data re-encryption.
• Tooling:
  • Logging: Add middleware to log decryption attempts (e.g., Sagalbot\Encryptable\Events\Decrypted if available).
  • Monitoring: Track decryption latency via APM tools (e.g., New Relic, Laravel Telescope).
• Documentation:
  • Update runbooks for:
    • Key recovery procedures.
    • Handling corrupted encrypted data.
    • Onboarding new developers to the encryption pattern.

Scaling

• Performance:
  • Read Scaling: Decryption overhead is constant per field; mitigate with:
    • Caching: Cache decrypted attributes (e.g., rememberProperty()).
    • Selective Encryption: Avoid encrypting frequently accessed non-sensitive fields.
  • Write Scaling: Encryption is CPU-bound; ensure sufficient resources for bulk inserts/updates.
• **