Encrypted Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require crudly/encrypted
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Crudly\Encrypted\EncryptedServiceProvider::class,
   ],
   

2. Basic Usage Define an encrypted attribute in your Eloquent model:

   use Crudly\Encrypted\Encrypted;
   
   class User extends Model
   {
       protected $casts = [
           'credit_card' => Encrypted::class,
       ];
   }
   

3. First Use Case

   // Encrypt on set
   $user = new User();
   $user->credit_card = '4111111111111111'; // Automatically encrypted
   
   // Decrypt on get
   $card = $user->credit_card; // Returns decrypted value
   

Key Files to Review

• config/encrypted.php (default encryption settings)
• app/Models/User.php (model-level configuration)
• database/migrations/ (ensure encrypted fields are stored as text or longtext)

Implementation Patterns

Common Workflows

1. Selective Encryption

   // Encrypt only specific fields
   protected $casts = [
       'ssn' => Encrypted::class,
       'medical_history' => Encrypted::class,
   ];
   

2. Custom Encryption Keys Override the default key in config/encrypted.php:

   'key' => env('ENCRYPTION_KEY', 'default-key-32-characters-long'),
   

3. Querying Encrypted Fields Use whereRaw for encrypted comparisons:

   User::whereRaw('encrypted(credit_card) = ?', ['4111111111111111'])->get();
   

4. Mass Assignment

   $user = User::create([
       'name' => 'John Doe',
       'credit_card' => '4242424242424242', // Encrypted automatically
   ]);
   

Integration Tips

• API Responses: Use $user->only(['id', 'name']) to exclude encrypted fields from JSON responses.
• Form Requests: Validate encrypted fields as strings (they’re stored encrypted in the DB).
• Testing: Mock the encryption service in unit tests:

  $this->app->instance(Encrypted::class, MockEncrypted::class);
  

Gotchas and Tips

Pitfalls

1. Field Type Mismatch

   • Encrypted fields must be text or longtext in MySQL (or equivalent in other DBs). Using varchar will corrupt data.

2. Key Management

   • The encryption key is not stored in the database. Use environment variables:

     ENCRYPTION_KEY=your-32-byte-key-here
     

   • Rotate keys carefully—old keys must decrypt existing data.

3. Query Limitations

   • Encrypted fields cannot be used in where(), orderBy(), or groupBy(). Use whereRaw instead.

4. Serialization Issues

   • Avoid serializing/deserializing models with encrypted fields (e.g., session()->put('user', $user)). Use ->toArray() first.

Debugging

• Decryption Failures: Check config/encrypted.php for correct key length (must be 32 bytes for AES-256).
• Silent Failures: Enable Laravel’s debug mode (APP_DEBUG=true) to catch encryption errors.
• Database Dumps: Use DB::enableQueryLog() to verify raw SQL queries when debugging whereRaw.

Extension Points

1. Custom Encryption Algorithm Bind a custom encryptor in AppServiceProvider:

   $this->app->bind(Encrypted::class, function () {
       return new CustomEncrypted();
   });
   

2. Attribute-Level Configuration Pass options to Encrypted:

   protected $casts = [
       'api_key' => [Encrypted::class, 'algorithm' => 'AES-128'],
   ];
   

3. Global Exclusions Exclude models from encryption entirely in EncryptedServiceProvider:

   protected $except = [
       'App\Models\AuditLog',
   ];