Encryption Laravel Package

Getting Started

Install via Composer (typically via laravel/framework, but standalone possible): composer require illuminate/encryption. Start by verifying your APP_KEY in .env—it must be 32 bytes (256-bit), base64-encoded (e.g., base64:abc123...), and set via php artisan key:generate in Laravel. Begin encrypting with the helper: encrypt('confidential'), and decrypting with decrypt($encrypted). First use case: securing user contact info before persisting to the database.

Implementation Patterns

• Model attribute casting: Declare encrypted cast in Eloquent models ('api_token' => 'encrypted') for automatic encryption on save and decryption on access.
• Configuration via service container: Bind custom Encrypter instances for per-tenant or hybrid encryption (e.g., AES-256-GCM for authenticated encryption with AAD support).
• Encrypted config values: Store sensitive config keys (e.g., app.php → smtp_password) encrypted, and decrypt at runtime in service providers or config getters.
• Secure session extras: Encrypt non-session data stored in cookies (e.g., auth state tokens) using encrypt() before setCookie()—Laravel’s encrypt() includes a MAC and IV handling automatically.
• Testing with mock data: In tests, intercept encrypt() via Encrypter::fake() or override APP_KEY to a known test value to validate round-trip integrity.

Gotchas and Tips

• APP_KEY validation failure is silent but fatal: A malformed key (non-base64, wrong length) yields RuntimeException on first encrypt/decrypt call—add startup checks in AppServiceProvider (assert(config('app.key') !== null)).
• Serialization caveat: encrypt() auto-serializes complex types (arrays/objects), but non-serializable objects (e.g., closures, PDO connections) will fail—ensure objects are lean or use json_encode() manually for partial data.
• Key rotation risk: Rotating APP_KEY breaks all existing encrypted values; implement soft-rotation via a Decrypter facade that tries old keys first (store key ID in payload if needed).
• No integrity on partial decrypts: A DecryptException means either key mismatch, corrupted data, or tampering—always validate decrypted data (e.g., checksums) for critical workflows.
• GCM vs CBC: Prefer AES-256-GCM if available (via Laravel 8+ and PHP ≥7.2 with OpenSSL ≥1.0.1); it provides encryption + authentication in one step and rejects truncated payloads. CBC alone lacks built-in tamper detection (relies on HMAC via mac).