Download the PHP package sneakyx/laravel-dynamic-encryption without Composer

sneakyx/laravel-dynamic-encryption

A minimalist Laravel package that replaces the default Encrypter with a dynamic key system. The application encryption key is not taken from APP_KEY, but resolved at runtime from a volatile store (cache) and/or derived from a password using a KDF. This enables ephemeral key management and straightforward rotation. Read more in: Why does this exist?

Installation

Local Development (Monorepo)

1. The package is already located at: packages/only-local/laravel-dynamic-encryption
2. Update autoloading:

Standalone Project (Packagist/GitHub)

The package uses Laravel’s auto-discovery and binds the service provider automatically.

Configuration

Add environment variables and publish/adjust the config if needed.

Relevant .env variables (examples):

See config/dynamic-encryption.php for all options.

Key size is taken from config('app.cipher'):

• aes-256-cbc / aes-256-gcm → 32 bytes
• aes-128-cbc / aes-128-gcm → 16 bytes

Key material: two supported formats

• Base64-derived key: base64:<...> that decodes to the required key length.
• Plain password: any string; the package derives the correct-length key using the configured KDF and salt from .env.

Behavior when the key bundle is missing

• The package keeps the framework operational (sessions/cookies) by providing a core encrypter from APP_KEY.
• A runtime flag is set (dynamic-encryption.missing_bundle by default). Application code should NOT try decrypting data with a fallback key. Instead, use the cast below to surface a "locked" value in the UI until the user unlocks their data (Variante A).
• Policies when saving while the bundle is missing:
  • block (default): Saving models with changed encryptable fields throws a validation error. Unchanged fields are untouched. Reading remains tolerant.
  • plaintext: Encryption is skipped for changed encryptable fields (they are stored as plaintext). Use only in exceptional cases.
  • fail: Provider throws during boot; the application will error.

Usage

The package replaces Laravel’s default Encrypter. Use the Crypt facade as usual:

Usage

Use the EncryptedNullableCast or EncryptedNullableJsonCast in your model's $casts array:

Migration from v0.3.x

Replace the DynamicEncryptable trait and $encryptable property with casts:

Please migrate to the Cast-based approach above. The trait will log deprecation warnings.

Cast-based "Locked" Flow

Instead of using a cryptographic fallback (e.g., APP_KEY), the following cast returns a LockedEncryptedValue placeholder object when the key is missing—no exception is thrown. This allows the UI to display an "unlock" dialog without breaking the rendering flow. If you have also (legacy) unencrypted fields for some entities, you also can use the .env value:

(There are also the values null and fail for the policy.)

1) Use Cast:

2) Check in the UI:

3) When saving:

• If the bundle key is available, encryption proceeds normally.
• If the key is missing, the policy dynamic-encryption.on_missing_bundle applies:
  • block (default): Throws a ValidationException.
  • plaintext: Stores the value in plaintext (use only temporarily or in exceptional cases!).

Note: LockedEncryptedValue is string-/JSON-serializable (returns an empty string or null) and contains no plaintext data.

Where is the key/password stored?

The package expects a key bundle (array) in your cache under DYNAMIC_ENCRYPTION_CACHE_KEY. Read more: Where is the key?

Data Prefixing (Versioned Encryption)

Starting with version 0.2.0, encrypted values are stored with a versioned prefix (default: dynenc:v1:). This allows the system to reliably distinguish between:

1. Encrypted ciphertext: Values starting with the prefix.
2. Legacy plaintext: Values without the prefix (e.g., from before the encryption was enabled).

Why use a prefix?

Without a prefix, it's difficult to know if a string in the database is already encrypted or if it's still plaintext. Attempting to decrypt plaintext usually results in a decryption error. With the prefix, the EncryptedNullableCast can safely return the raw value if no prefix is found, preventing errors during migration or partial rollouts.

Migration Command

If you have data that was encrypted with an older version of this package (without a prefix) or using different encryption parameters, you can use the migrate-legacy command to re-encrypt your data with the current settings:

The command decrypts legacy values (without prefix, encrypted with an old key/salt) and re-encrypts them using the current encrypter and adds the versioned prefix.

By default, it automatically attempts multiple decryption strategies:

• Current KDF password + current salt
• Current KDF password + empty salt (for environments that previously had no DYNAMIC_ENCRYPTION_SALT)
• Laravel APP_KEY
• Old password from cache (if available)

Options:

• --model=FQCN: Process specific models (can be repeated).
• --all: Process all models using encryption.
• --from="2025-01-01 00:00:00": Only process records updated after this date.
• --to="2025-12-31 23:59:59": Only process records updated before this date.
• --old-password=PASSWORD: Explicitly provide the legacy password.
• --old-salt=SALT: Explicitly provide the legacy salt.
• --old-kdf-iters=ITERS: Explicitly provide legacy KDF iterations.
• --skip-app-key: Do not attempt decryption with the Laravel APP_KEY.
• --skip-no-salt: Do not attempt decryption with an empty salt.
• --dry-run: Show what would be updated without changing the database.
• --debug-first: Useful if records cannot be decrypted. It stops at the first failed record and prints detailed diagnostic information (payload structure, tried encrypters, and error messages).

The command only processes values that:

1. Do not already have the current prefix.
2. Appear to be encrypted (e.g., valid JSON structure with iv, value, and mac).

But be careful, there is a theoretical possibility that unencrypted Data is misinterpreted.

Decrypt encrypted fields and store plaintext

Use this if you need to permanently decrypt encrypted values in your database for specific models/fields:

• Decrypts values that are recognized as encrypted (with the configured prefix) and writes back the plaintext.
• Supports --model (repeatable), --field (repeatable), --all, and --dry-run.

Encrypt any still-plaintext values in bulk

Use this when you have legacy plaintext in encryptable fields and want to encrypt them in one go:

• Encrypts values that do not start with the configured prefix and are not already legacy-structured ciphertexts.
• Writes back with the current prefix and current dynamic encrypter.
• Supports --model (repeatable), --field (repeatable), --all, and --dry-run.

Key Rotation

Re-encrypt existing data from an old password to a new one (interactive):

Options:

• --model=FQCN Can be repeated.
• --all Rotate for all models using encryption (be careful on large datasets).
• --dry-run Do not write changes.

How it works (since v0.5.1):

• The command reads the current password from the configured cache bundle (field password). If none is present, it aborts with a clear error (server must be unlocked first).
• It prompts for the old password (default = cached password; press Enter to use it) and for the new password (secret input).
• Before writing, it shows a short summary (affected models, dry-run status) and asks for explicit confirmation.
• Then it decrypts each field with the old encrypter and re-encrypts with the new one, in chunks (dynamic-encryption.chunk).
• In dry-run mode, no writes are performed.
• After success, if the entered new password differs from the cached password, the cache is updated and a reminder is printed to also update the external source used for unlocking.

Testing

If you are writing Feature tests for your application, you need to ensure that a valid encryption key is present in the cache. Otherwise, models using DynamicEncryptable might throw exceptions or fail to save.

This package ships with a helper trait DynamicEncryptionTestLoader. Use it in your base TestCase to automatically inject a temporary key into the cache for the duration of the tests.

Security notes

• No key/password is written to logs.
• KDF parameters and salt live in .env/secrets; the password/key material lives in cache (bundle).
• Use a non-persistent cache store shared by your PHP workers (memcached/redis). Avoid the array driver.

Compatibility

Tested with Laravel 10.

License

MIT