Encryption

Learn how to encrypt and decrypt values using Laravel’s Crypt facade and AES-256-CBC. Covers generating APP_KEY, model casts, and safely storing personal data.

What is the Crypt facade

Laravel’s encryption service provides a simple interface for encrypting and decrypting values using OpenSSL with AES-256-CBC (or AES-128-CBC).

All values encrypted by Laravel are signed with a message authentication code (MAC). This ensures that any tampering with the encrypted value will prevent it from being decrypted.

---

Configuration

Generating the APP_KEY

Before using encryption, you need to set the key value in config/app.php. This value is loaded from the APP_KEY environment variable.

Use the php artisan key:generate command to generate a secure key. It generates a cryptographically secure key using PHP’s secure random number generator.

php artisan key:generate

It’s typically generated automatically when you install Laravel. The generated key is stored in the .env file.

APP_KEY=base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY=

Never expose APP_KEY. If this key leaks, all encrypted data can be decrypted.

Rotating the encryption key

When you change the encryption key, all authenticated user sessions are logged out. This is because Laravel encrypts all cookies, including session cookies.

Also, data encrypted with the previous key can no longer be decrypted.

To mitigate this, you can list old keys separated by commas in APP_PREVIOUS_KEYS.

APP_KEY="base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY="
APP_PREVIOUS_KEYS="base64:2nLsGFGzyoae2ax3EF2Lyq/hH6QghBGLIq5uL+Gp8/w="

Laravel always uses the current key to encrypt, but when decrypting, if it fails with the current key it tries the previous keys in order. This allows users to continue using the application during key rotation.

---

Encryption

Use the encryptString method on the Crypt facade to encrypt a value. The encrypted value uses OpenSSL with AES-256-CBC and is signed with a MAC.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Crypt;

class DigitalOceanTokenController extends Controller
{
    /**
     * Store the user's API token.
     */
    public function store(Request $request): RedirectResponse
    {
        $request->user()->fill([
            'token' => Crypt::encryptString($request->token),
        ])->save();

        return redirect('/secrets');
    }
}

encryptString encrypts a string without serialization. To encrypt objects or arrays, use encrypt.

Method	Purpose
Crypt::encryptString($value)	Encrypts a string as-is
Crypt::encrypt($value)	Serializes the value and then encrypts it (supports arrays and objects)

---

Decryption

Use the decryptString method on the Crypt facade to decrypt an encrypted value. If decryption fails (for example, if the MAC is invalid), a DecryptException is thrown.

use Illuminate\Contracts\Encryption\DecryptException;
use Illuminate\Support\Facades\Crypt;

try {
    $decrypted = Crypt::decryptString($encryptedValue);
} catch (DecryptException $e) {
    // Handle decryption failure
    abort(400, 'Invalid data.');
}

Method	Purpose
Crypt::decryptString($value)	Decrypts as a string
Crypt::decrypt($value)	Decrypts and unserializes (supports arrays and objects)

---

Model casts

Using the encrypted cast on an Eloquent model, an attribute is automatically encrypted and decrypted.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected function casts(): array
    {
        return [
            'secret_note'    => 'encrypted',           // String encryption
            'profile_data'   => 'encrypted:array',     // Encrypt and store an array
            'preferences'    => 'encrypted:collection',// Encrypt and store a collection
            'metadata'       => 'encrypted:object',    // Encrypt and store an object
            'settings'       => 'encrypted:json',      // Encrypt and store as JSON
        ];
    }
}

Once the cast is set up, values are automatically encrypted and decrypted when assigning to or reading from the model.

// Automatically encrypted and stored in the DB
$user->secret_note = 'Secret note';
$user->save();

// Automatically decrypted on retrieval
echo $user->secret_note; // 'Secret note'

The encrypted:* casts internally use Crypt::encrypt and Crypt::decrypt. A text or longText database column type is recommended.

---

Practical example: encrypting personal information

A typical pattern for securely storing personal information (national ID numbers, credit card numbers, etc.) in the database.

Migration

Schema::create('profiles', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->text('my_number')->nullable();     // Store encrypted values in text
    $table->text('bank_account')->nullable();
    $table->timestamps();
});

Model

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Profile extends Model
{
    protected $fillable = ['user_id', 'my_number', 'bank_account'];

    protected function casts(): array
    {
        return [
            'my_number'    => 'encrypted',
            'bank_account' => 'encrypted',
        ];
    }
}

Controller

use App\Models\Profile;
use Illuminate\Http\Request;

class ProfileController extends Controller
{
    public function store(Request $request)
    {
        $request->validate([
            'my_number'    => ['required', 'string'],
            'bank_account' => ['required', 'string'],
        ]);

        // The model automatically encrypts and stores the values
        Profile::create([
            'user_id'      => $request->user()->id,
            'my_number'    => $request->my_number,
            'bank_account' => $request->bank_account,
        ]);

        return redirect('/profile');
    }

    public function show(Request $request)
    {
        $profile = $request->user()->profile;

        // The model automatically decrypts on return
        return view('profile.show', ['profile' => $profile]);
    }
}

---

Summary

What you want to do	How
Generate APP_KEY	php artisan key:generate
Encrypt a string	Crypt::encryptString($value)
Decrypt a string	Crypt::decryptString($value)
Encrypt an array/object	Crypt::encrypt($value)
Auto-encrypt a model attribute	'column' => 'encrypted' cast
Key rotation	List old keys in APP_PREVIOUS_KEYS

Next steps

Hashing

Learn how to securely hash and verify passwords.

Authorization

Learn about access control using policies and gates.