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

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 / Cipher	Key Size / Nonce Size
XChaCha20-Poly1305-IEFT	256 bits / 192 bits
ChaCha20-Poly1305-IEFT	256 bits / 96 bits
ChaCha20-Poly1305	256 bits / 64 bits
AES-256-GCM	256 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.
LaravelAEAD\Providers\EncryptionServiceProvider::class,

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.

Roadmap.

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 Utopian.io - Rewarding Open Source Contributors

---