README

Laravel Crypto provides a simple and easy-to-use API for encrypting, decrypting, hashing, and signing data using modern cryptographic algorithms powered by libsodium.

Why Laravel Crypto?

• Modern Algorithms: Support for XChaCha20-Poly1305, AES-256-GCM, AEGIS-128L, AEGIS-256, XSalsa20-Poly1305, Blake2b, and EdDSA.
• Per-User Encryption: Secure data using keys derived from and unique to each user, ensuring data privacy even if the APP_KEY is compromised.
• Performance: High-performance cryptographic operations utilizing hardware acceleration where available.
• Drop-in Replacement: Seamlessly replaces Laravel's default EncryptionServiceProvider.
• Comprehensive: Includes support for hashing, signing (symmetric and asymmetric), file encryption, Eloquent casting for encrypted files, and various data encoders (JSON, MessagePack, Igbinary).

Requirements

• PHP: 8.4 or higher
• Extensions: ext-sodium
• Laravel: 10.x, 11.x, or 12.x

Getting Started

1. Installation

composer require codelieutenant/laravel-crypto

2. Service Provider Registration

In order to activate the package, you need to replace Laravel's default EncryptionServiceProvider with CodeLieutenant\LaravelCrypto\ServiceProvider.

Laravel 11.x & 12.x

In bootstrap/providers.php, replace the default provider:

return [
    App\Providers\AppServiceProvider::class,
    // Illuminate\Encryption\EncryptionServiceProvider::class, // Remove or comment out
    CodeLieutenant\LaravelCrypto\ServiceProvider::class,       // Add this
];

Laravel 10.x

In config/app.php, replace Illuminate\Encryption\EncryptionServiceProvider::class in the providers array:

'providers' => [
    // ...
    // Illuminate\Encryption\EncryptionServiceProvider::class,
    CodeLieutenant\LaravelCrypto\ServiceProvider::class,
    // ...
],

3. Configuration

Publish the configuration file:

php artisan vendor:publish --provider="CodeLieutenant\LaravelCrypto\ServiceProvider"

Update your cipher in config/app.php:

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

4. Generating Keys

Generate the necessary cryptographic keys:

php artisan crypto:keys

This will update your .env file with the required keys and generate an EdDSA key pair in storage/keys/.

Usage Overview

Encryption

Uses the standard Laravel Crypt facade but with Sodium algorithms.

use Illuminate\Support\Facades\Crypt;

$encrypted = Crypt::encryptString('Hello Sodium');
$decrypted = Crypt::decryptString($encrypted);

File Encryption

Securely encrypt large files using chunked streaming.

use Illuminate\Support\Facades\Crypt;

// Encrypt a file
Crypt::encryptFile('path/to/input.txt', 'path/to/output.enc');

// Decrypt a file
Crypt::decryptFile('path/to/output.enc', 'path/to/decrypted.txt');

Hashing

High-performance hashing using Blake2b.

use CodeLieutenant\LaravelCrypto\Facades\Hashing;

$hash = Hashing::hash('data');

Signing

Symmetric (HMAC) and Asymmetric (EdDSA) signing.

use CodeLieutenant\LaravelCrypto\Facades\Sign;

// HMAC
$sig = Sign::sign('message');

// EdDSA
$sig = Sign::eddsaSign('message');

Eloquent Casting

Store files securely by automatically encrypting and decrypting them on-the-fly via an Eloquent caster.

use CodeLieutenant\LaravelCrypto\Casts\EncryptedFileCast;
use Illuminate\Database\Eloquent\Model;

class Document extends Model
{
    protected $casts = [
        'file' => EncryptedFileCast::class,
    ];
}

// Accessing the file decrypts it to a temporary location
$content = $document->file->contents();

// Modifying the content and saving the model re-encrypts the file
$document->file->putContents('Secret Data');
$document->save();

User Encryption

Securely encrypt user data using their own unique encryption key.

use CodeLieutenant\LaravelCrypto\Casts\UserEncryptedWithIndex;
use Illuminate\Database\Eloquent\Model;

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

For more details on setting up and using per-user encryption, see the User Encryption documentation.

Performance

Benchmarks conducted on various data sizes (PHP 8.5.1, Sodium extension enabled) on a Macbook M4 Pro 48GB RAM.

1 KiB Payload

32 KiB Payload

1 MiB Payload

Sodium-based algorithms provide more consistent performance and are significantly faster for decryption of large payloads compared to Laravel's default implementations. AEGIS algorithms offer top-tier performance on modern hardware.

Documentation

For detailed information, please refer to the following documentation:

• Console Commands
• Encryption
• User Encryption
• Hashing
• Signing
• Utilities (Encoders, Base64, Random)

License

The MIT License (MIT). Please see License File for more information.