Elocryptfive Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require delatbabel/elocryptfive
   

   Add to config/app.php under providers:

   Delatbabel\EloquentEncrypt\ServiceProvider::class,
   

2. Publish Config:

   php artisan vendor:publish --provider="Delatbabel\EloquentEncrypt\ServiceProvider"
   

   Configure encryption key in .env:

   ELOCRYPT_KEY=your-32-byte-base64-encoded-key
   

3. First Use Case: Define an encrypted attribute in your model:

   use Delatbabel\EloquentEncrypt\Encryptable;
   
   class User extends Model
   {
       use Encryptable;
   
       protected $encryptable = ['credit_card', 'ssn'];
   }
   

   Now credit_card and ssn will auto-encrypt on save and decrypt on retrieval.

Implementation Patterns

Core Workflows

1. Attribute-Level Encryption:

   • Declare fields in $encryptable array:

     protected $encryptable = ['api_key', 'password_hash'];
     

   • Supports mixed encrypted/non-encrypted columns in the same table.

2. Dynamic Encryption:

   • Use encrypt()/decrypt() methods manually:

     $user->encrypt('ssn', '123-45-6789'); // Force encrypt
     $plaintext = $user->decrypt('ssn');    // Force decrypt
     

3. Querying Encrypted Fields:

   • Use whereEncrypted() for encrypted column queries:

     User::whereEncrypted('ssn', '123-45-6789')->get();
     

4. Mass Assignment:

   • Encryption works seamlessly with fill()/create():

     User::create(['name' => 'John', 'ssn' => '123-45-6789']);
     

Integration Tips

• Database Schema: Extend column sizes (e.g., TEXT/LONGTEXT) for encrypted fields.
• Migrations: Use doctrine/dbal for dynamic column type adjustments:

  Schema::table('users', function (Blueprint $table) {
      $table->text('ssn')->change(); // If upgrading from VARCHAR
  });
  

• API Responses: Exclude encrypted fields from JSON responses:

  protected $hidden = ['ssn', 'credit_card'];
  

Gotchas and Tips

Pitfalls

1. Key Management:

   • Never hardcode keys in config. Use environment variables or Laravel’s config/cache.
   • Rotate keys carefully: encrypted data becomes unreadable if the key changes.

2. Column Size Limits:

   • Encrypted data can grow 2-3x in size. Test with VARCHAR(255) → TEXT upgrades.
   • Example: A 64-char ssn may encrypt to 128+ chars.

3. Query Performance:

   • whereEncrypted() requires plaintext comparison (decrypts internally). Avoid on large datasets.
   • Use indexed columns for encrypted fields if possible (though encryption breaks index usability).

4. Serialization:

   • Encrypted attributes won’t serialize correctly in sessions/cache. Exclude them:

     protected $dontEncryptInCache = ['ssn'];
     

Debugging

• Check Encryption Tags:

  • Encrypted values are prefixed with __ELOCRYPT__:. If missing, the field wasn’t encrypted.
  • Debug with:

    dd($user->getAttribute('ssn')); // Inspect raw value
    

• Key Validation:

  • Test decryption manually:

    $encrypted = $user->ssn;
    $decrypted = \Delatbabel\EloquentEncrypt\Encryptor::decrypt($encrypted);
    

Extension Points

1. Custom Encryptors:

   • Implement Delatbabel\EloquentEncrypt\Contracts\Encryptor for alternative algorithms (e.g., AES-256):

     class CustomEncryptor implements Encryptor {
         public function encrypt($value) { ... }
         public function decrypt($value) { ... }
     }
     

   • Bind in ServiceProvider:

     $this->app->bind('encryptor', function () {
         return new CustomEncryptor();
     });
     

2. Event Hooks:

   • Listen for eloquent.encrypting/eloquent.decrypting events to log or modify behavior:

     Event::listen('eloquent.encrypting', function ($model, $attribute) {
         if ($attribute === 'ssn') {
             // Pre-process sensitive data
         }
     });
     

3. Conditional Encryption:

   • Dynamically set $encryptable based on user roles:

     public function getEncryptable()
     {
         if (auth()->user()->isAdmin()) {
             return ['api_key', 'ssn'];
         }
         return ['ssn'];
     }