laravel-crypto: libsodium, no compromises, and per-user encryption

Laravel's default cipher is AES-256-CBC. That is a 25-year-old design with no built-in authentication — the MAC is bolted on separately by the framework, and the correctness of that construction depends on nobody ever reordering the operations.

I am not saying it is broken. I am saying PHP has shipped with libsodium since 7.2, and libsodium gives you authenticated encryption by construction. There was no reason to keep using AES-256-CBC as the default the moment sodium_crypto_aead_xchacha20poly1305_ietf_encrypt became available in every standard PHP install. I built laravel-crypto because I wanted to stop thinking about that gap every time I started a new project.

why libsodium

NaCl — and libsodium as its portable successor — was designed around one principle: remove the ways you can shoot yourself in the foot. Every algorithm choice is made for you. There is no ECB mode. There is no "pick your own MAC." XChaCha20-Poly1305 is authenticated by definition. AEGIS was designed specifically for high-throughput AEAD on hardware with AES acceleration, which includes every modern x86 and ARM chip. The API surface is small enough to understand fully.

PHP's mcrypt was the old answer. It was unmaintained, it supported ECB, it let you combine incompatible primitives, and it was removed in PHP 7.2. libsodium replaced it — but Laravel did not update its default cipher. AES-256-CBC stayed in config/app.php, a leftover from before the ecosystem had anything better. laravel-crypto picks up where mcrypt's removal should have taken things.

the drop-in

Swapping the provider is two lines:

// bootstrap/providers.php (Laravel 11+)
// Illuminate\Encryption\EncryptionServiceProvider::class,   // remove
CodeLieutenant\LaravelCrypto\ServiceProvider::class,         // add

After that, Crypt::encryptString() and Crypt::decryptString() still work exactly as before. All existing code calling the facade keeps working. The only change is what runs underneath.

Set the cipher in config/app.php:

'cipher' => 'Sodium_AEGIS256GCM',
// Options: Sodium_AES256GCM, Sodium_XChaCha20Poly1305, Sodium_AEGIS256GCM, Sodium_AEGIS128LGCM, Sodium_SecretBox

Generate keys:

php artisan crypto:keys

That is the full migration for most apps. If you already use AEAD via APP_PREVIOUS_KEYS, the library picks those up automatically for decryption during key rotation.

the numbers

Benchmarks from PHP 8.5.1 on a MacBook M4 Pro — Apple Silicon has hardware AES-NI and dedicated AEGIS acceleration:

AEGIS-128L decrypts a 1 MiB payload in 1.60 ms versus Laravel's AES-256-CBC at 7.57 ms. That is 4.7× faster, authenticated, on the same hardware. Sodium AES-256-GCM halves the decryption time compared to Laravel's own GCM implementation — same algorithm, better path through the Sodium extension than through OpenSSL via PHP's stream wrapper.

XChaCha20-Poly1305 is the conservative choice: well-analyzed, hardware-agnostic, fast on everything. Use it if you need consistent performance on older or constrained hardware without AES acceleration. On ARM or x86 with AES-NI, AEGIS is the right pick.

The point is not that the difference matters for a single request. It matters when you are decrypting a hundred fields per page load, or processing a batch job over encrypted rows, or streaming large files. AES-256-CBC at 7.57 ms per MiB is not a performance problem in isolation. As a default that never gets questioned, it adds up.

per-user encryption

The standard model — one APP_KEY encrypts everything — has a structural problem. Anyone with access to that key can decrypt every row in the database. That is the DBA, the sysadmin, the developer with a .env copy, and any process with access to the environment. If client data confidentiality is a real requirement, "we encrypted the database" is not a complete answer when a single key unlocks all of it.

Per-user encryption means each user's sensitive fields are encrypted with a key unique to that user. A 32-byte random key is generated at enrollment and wrapped in a self-contained blob stored in the encryption_key column. Two wrapping modes exist depending on what is available at enrollment time:

• Mode 1 — password-wrapped (0x01, 89 bytes): wrapping key derived via Argon2id from the user's plaintext password. APP_KEY is not involved. Unwrapping requires the password — no server-side secret alone can decrypt these fields.
• Mode 2 — server-wrapped (0x02, 73 bytes): wrapping key derived via BLAKE2b(appKey, userId). Used for auto-enrollment when the plaintext password is unavailable (e.g. OAuth users, Filament). The blob is promoted to Mode 1 transparently the next time the user provides their password.

The unwrapped key is never stored anywhere. It is base64url-encoded, sent to the client as X-Encryption-Token (header for SPA/API clients) or as an HTTP-only enc_token cookie (web clients), and re-sent on every subsequent request. The middleware reads it, loads it into the request-scoped context, then zeros it at the end of the response.

Setting it up:

// User model
use CodeLieutenant\LaravelCrypto\Traits\HasUserEncryption;

class User extends Authenticatable
{
    use HasUserEncryption;
}

At registration, return the token to the client:

$rawKey = $user->initUserEncryption($request->password);
$user->save();
return response()->json([...])->header('X-Encryption-Token', $user->encodeEncryptionToken($rawKey));

At login, re-derive the token from the password and hand it back:

if (Auth::attempt($credentials)) {
    $token = Auth::user()->issueEncryptionToken($credentials['password']);
    return response()->json([...])->header('X-Encryption-Token', $token);
}

After that, model casts handle the rest transparently:

class UserSecret extends Model
{
    protected function casts(): array
    {
        return [
            'ssn' => UserEncryptedWithIndex::class . ':ssn_index',
        ];
    }
}

Reading $secret->ssn decrypts using the key currently in the request context. Saving writes ciphertext. Nothing else in the application changes.

the key in memory

The key lives in a scoped container — one instance per HTTP request. The BootPerUserEncryption middleware loads it from the incoming header or cookie, sets it on the context, then clears it in a finally block:

// src/Encryption/UserKey/UserEncryptionContext.php
public function clear(): void
{
    if ($this->key !== null) {
        sodium_memzero($this->key);
        $this->key = null;
    }
}

public function __destruct()
{
    $this->clear();
}

Setting a variable to null in PHP does not zero the memory — the garbage collector might hold the reference, and even when it collects, it does not overwrite the bytes. sodium_memzero does. The key is gone, not just unreferenced.

For Mode 1 blobs the wrapped blob in the database is useless without the user's password. Compromising APP_KEY does not help. For Mode 2 blobs, APP_KEY + userId is enough to re-derive the wrapping key — that is the acknowledged trade-off for the auto-enrollment path. The moment the user sets a password, issueEncryptionToken() promotes the blob to Mode 1 automatically.

blind indexes for searchable fields

Encrypting a column means you can no longer query it. WHERE ssn = ? stops working when ssn is ciphertext. The standard solution is a blind index: a deterministic MAC of the plaintext stored alongside the ciphertext, used only for equality lookups.

The derivation:

// src/Encryption/UserKey/BlindIndex.php — compute
public function compute(
    #[SensitiveParameter] string $value,
    string $column,
    bool $normalise = true,
): string {
    $userKey = $this->context->get();
    $subKey  = $this->deriveColumnSubKey($userKey, $column);

    $input = $normalise ? mb_strtolower(trim($value)) : $value;

    return sodium_crypto_generichash($input, $subKey, self::INDEX_BYTES);
}

// src/Encryption/UserKey/BlindIndex.php — column sub-key
private function deriveColumnSubKey(string $userKey, string $column): string
{
    $hash = sodium_crypto_generichash($column, '', SODIUM_CRYPTO_GENERICHASH_BYTES_MIN);
    $ctx  = substr($hash, 0, 8);

    return sodium_crypto_kdf_derive_from_key(
        self::INDEX_BYTES,
        self::KDF_SUBKEY_ID,
        $ctx,
        $userKey,
    );
}

Each column gets a distinct sub-key derived from the user's key via libsodium's official KDF. The index for ssn is cryptographically separated from the index for email, even though both come from the same user key. Two users with identical SSNs produce different indexes. Querying:

UserSecret::where('ssn_index', UserCrypt::blindIndex('123-45-6789', 'ssn'))->first();

The leakage is explicit: blind indexes leak equality. An attacker with database read access can tell that two rows share a value — they learn nothing about what that value is. Do not put a blind index on a low-cardinality field. gender, country, boolean flags — no. SSN, passport number, phone, email — yes.

what it isn't

• It is not a replacement for proper key management. Mode 1 blobs are only as safe as the user's password — weak passwords mean weak wrapping. Mode 2 blobs are only as safe as APP_KEY. Treat APP_KEY accordingly: secrets manager, rotation policy, backup.
• It does not protect against runtime compromise. If an attacker can execute arbitrary PHP in your process, they can read the key from the request context during a live request. Encryption protects data at rest, not running code.
• Per-user encryption is not transparent key rotation. Changing a user's password requires rewrapUserEncryption($old, $new). Rotating APP_KEY requires re-wrapping every user's key. Neither is automatic.
• Blind indexes leak equality. Two rows with the same value in the same column for the same user produce the same index. On fields with a small set of possible values, that is dangerous enough to skip the index entirely.
• It is not end-to-end encryption. The raw key is derived server-side and then handed to the client as a token. The server sees it. True E2E requires the key to never reach the server — that is a different architecture and a different threat model entirely.

where to start

composer require codelieutenant/laravel-crypto
php artisan vendor:publish --provider="CodeLieutenant\LaravelCrypto\ServiceProvider"
php artisan crypto:keys

Set 'cipher' => 'Sodium_AEGIS256GCM' in config/app.php, swap the service provider, run your test suite. For most apps the migration takes twenty minutes.

Per-user encryption takes longer — you need to decide which columns are sensitive enough to warrant it, wire up the middleware, and handle the password-change re-wrap flow. The docs in docs/UserEncryption.md cover the full setup. I use it in every project where the question "can your team read this user's data?" has an answer I would be uncomfortable defending.