LaravelAEAD: Advanced Encryption with Associated Data (XChacha20-Poly1305-IETF and others)

in #utopian-io6 years ago (edited)


LaravelAEAD provides a drop-in replacement for the Laravel's default encryption component.

Laravel by default provides encryption using OpenSSL, with two options of ciphers, which are both block ciphers: AES-256-CBC and AES-128-CBC.

This library provides AEAD ciphers/constructions based on libsodium, which has bindings and is available as a core PHP extension since PHP 7.2.0.

What is AEAD?

AEAD 's are encryption ciphers/constructors which provide at the same time:

  • Confidentiality
    A stream cipher is used to carry the encryption, given a 256-bit key and a random nonce/IV.

  • Integrity
    A MAC algorithm is used to perform the authentication of the data within the cipher itself.

  • Authenticity
    Associated, non-encrypted data can be appended, the MAC will sign both encrypted and decrypted parts, where both cannot be tampered with. (Useful for message headers).

Available Constructions:

There are two available constructions, including the original ChaCha20-Poly1305 and it's three variations.

The recommended, and default one is XChaCha20-Poly1305-IETF.

AEAD Contruction / CipherKey Size / Nonce Size
XChaCha20-Poly1305-IEFT256 bits / 192 bits
ChaCha20-Poly1305-IEFT256 bits / 96 bits
ChaCha20-Poly1305256 bits / 64 bits
AES-256-GCM256 bits / 96 bits

General Usage Instructions.

After installing and enabling this library, the Laravel application encryption functions will rely on the chosen cipher to carry the operations.

It means that cookies, session, and other encrypted information will switch to the given cipher automatically.

Installing & Enabling the Library:

Dependency Install:

composer require hernandev/laravel-aead

Package Provider:

// Disable the Default Encryption Provider.
// Illuminate\Encryption\EncryptionServiceProvider::class,
// Enable the Library Encryption Provider.

Chose a Cipher:

// alter the encryption cipher to one if the supported on this library.
'cipher' => 'XCHACHA20-POLY1305-IETF',
Encrypting & Decryption.

Now, if you have custom data to encrypt, you can use the encrypt() and decrypt() methods already available on Laravel, for example:

  • Encrypting a given value:
$cipherText = encrypt('Utopian Is Awesome!');
// eyJ2YWx1ZSI6ImxBUElkNTBpbX...
  • Decrypt the cipher text back into plain text.
$value = decrypt($cipherText);
// 'Utopian Is Awesome!'

As always, this is a important subject. Laravel generates a 256-bit random key for the application, but, if you want to encrypt user-level data, with a specific user secret key, you could do that just by:

// alias the encrypter class.
use LaravelAEAD\Ecrypter;
// chose a cipher.
$cipher = 'XCHACHA20-POLY1305-IETF';
// generate an encryption key.
$encryptionKey = Encrypter::generateKey($cipher);
// start an encrypter instance.
$encrypter = new LaravelAEAD\Encrypter($encryptionKey, $cipher);
// encrypt data.
$cipherText = $encrypter->encrypt('some data');
// encrypt object instances (auto serialization).
$cipherText = $encrypter->encrypt(User::find(1));
// additional, non-encrypter headers to compose the payload.
$cipherText = $encrypter->encrypt('some-encrypted-data', true, 'additional-plain-headers');
// all can be reverse on the same API.
$original = $encrypter->decrypt($cipherText);

Notice that when use pass a serializable object instance to encrypt, it will serialize and encrypt, and when decrypting, the values will be used to revert the data into a instance of the original object, identical to the one encrypted.

Technology Stack

This library is based upon libsodium which is a great security-first cryptography library written in C and available to PHP through a core extension.

This library, uses some concepts from libsodium, like constant-type safe Base64 encode / decode functions.


As of right now, the main objective is unit-test and perform a security-scrutiny on the implementation.

How to contribute?

  • Join the PHP discussions over the Discord PHP channel @ SteemDevs
  • Contact Telegram
  • Open an Issue
  • Engage on the post comments.

Posted on - Rewarding Open Source Contributors


Thank you for the contribution. It has been approved.

It unfortunate that you could not find an image to go with your post.

Need help? Write a ticket on
Chat with us on Discord.


Hey @helo, I just gave you a tip for your hard work on moderation. Upvote this comment to support the utopian moderators and increase your future rewards!

Hey @helo, it's a little bit hard to find a meaning illustration on AEAD, each cipher has a unique take on it's process and it's differnt from the encrypt-then-mac or mac-then-encrypt traiditional processes, like AES-CBC.

I'll try doing something on to illustrate it. Thank you!

At least, I've put a cover now :p

Friends aren't my steemit selection power. i'm commenting.
Genius may be a nice post, thus you unnumerable
Thank you most for fun, funny writing. i am a general steemit user. i need to follow the howling individuals such as you. Please provide Pine Tree State upvote and follow Pine Tree State.

Hey @hernandev! Thank you for the great work you've done!

We're already looking forward to your next contribution!

Fully Decentralized Rewards

We hope you will take the time to share your expertise and knowledge by rating contributions made by others on to help us reward the best contributions together.

Utopian Witness!

Vote for Utopian Witness! We are made of developers, system administrators, entrepreneurs, artists, content creators, thinkers. We embrace every nationality, mindset and belief.

Want to chat? Join us on Discord

Coin Marketplace

STEEM 0.29
TRX 0.11
JST 0.031
BTC 68293.69
ETH 3899.61
USDT 1.00
SBD 3.69