Php Encryption Laravel Package

Getting Started

1. Install via Composer: composer require defuse/php-encryption.
2. Generate a secure key once (using the included CLI tool or via code) and store it outside your codebase (e.g., environment variable, config file with restricted access):

   vendor/bin/generate-defuse-key
   

3. Use the FileEncryption and EnvironmentEncryption classes for common cases. For in-memory data, use Encryption::encrypt() and Encryption::decrypt() with Key objects.
4. First use case: Encrypt a sensitive config value at runtime using an environment variable key:

   $key = Key::loadFromJsonString(getenv('DEFUSE_KEY')); // key as JSON string from env
   $encrypted = Encryption::encrypt('my_secret_password', $key);
   

Implementation Patterns

• Configuration Value Protection: Encrypt secrets (e.g., API keys, DB passwords) and store only ciphertext. Decrypt at runtime on cache warm-up or request startup:

  $key = Key::loadFromJsonString($secretKeyJson);
  $decrypted = Encryption::decrypt($encryptedConfigValue, $key);
  

• Session/Data Integrity: Combine encryption with HMAC via EncryptThenMac (used internally) to prevent tampering. Avoid manual MAC handling—rely on the library’s defaults.
• File-level Encryption: Use FileEncryption::encryptFile($plaintextFile, $ciphertextFile, $key) for large data without loading into memory.
• Per-User Keys: Generate a unique key per user (e.g., derived from a master key + user ID via HKDF) and cache securely in a keyring—avoid generating on each request.

Gotchas and Tips

• Never store keys in source control: Use environment variables, secret managers (e.g., Vault), or hardware-backed storage (HSM/KMS) where possible.
• Key format matters: The library uses JSON-wrapped keys. Ensure your deployment pipeline handles key rotation cleanly (e.g., store key ID + JSON in env, load with Key::loadFromJsonString($json)).
• Exception handling: Encryption::decrypt() throws CryptoException on invalid MAC/ciphertext or WrongKeyException on incorrect key. Always wrap decryption in try/catch with specific logging (avoid leaking info in exceptions).
• Key longevity: Keys can be rotated—encrypt with the new key, but decryption supports multiple keys via Encryption::decryptWithPossibleKeys($ciphertext, $possibleKeys).
• Avoid custom IVs: The library handles IVs securely by default. Never try to reuse or set custom IVs.
• Performance: Encryption/decryption is fast for typical payloads (<1MB), but avoid wrapping large DB queries in encrypt/decrypt loops—use column-level encryption only where necessary.