Encrypting Laravel Eloquent models with CipherSweet

July 1st, 2022

CipherSweet is a backend library developed by Paragon Initiative Enterprises for implementing searchable field-level encryption. It can encrypt and decrypt values in a very secure way. It is also able to create blind indexes. A blind index can be used to perform some targeted searches on the encrypted data. The indexes themselves are unreadable by humans.

We’ve just released laravel-ciphersweet. This package is a wrapper over CipherSweet, which allows you to easily use it with Laravel’s Eloquent models.

Preparing your model and choosing the attributes that should be encrypted#

Add the CipherSweetEncrypted interface and UsesCipherSweet trait to the model that you want to add encrypted fields to.

You’ll need to implement the configureCipherSweet method to configure CipherSweet.

use Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted;
use Spatie\LaravelCipherSweet\Concerns\UsesCipherSweet;
use ParagonIE\CipherSweet\EncryptedRow;
use Illuminate\Database\Eloquent\Model;

class User extends Model implements CipherSweetEncrypted
{
    use UsesCipherSweet;
    
    public static function configureCipherSweet(EncryptedRow $encryptedRow): void
    {
        $encryptedRow
            ->addField('email')
            ->addBlindIndex('email', new BlindIndex('email_index'));
    }
}

Generating an encryption key#

We’ve also added a small helper command to the package that allows you to generate a new key in a way that is suggested by Paragon Initiative Enterprises.

This encryption key is used to encrypt your values.

php artisan ciphersweet:generate-key

Encrypting model attributes#

Once everything is set up, you can start encrypting your model values:

php artisan ciphersweet:encrypt <your-model-class> <generated-key>

The command will update all the encrypted fields and blind indexes of the model.

If you have a lot of rows, this process can take a long time since encryption is a resource intensive operation. Don’t worry if it times out for some reason, the command is always restartable and only tries to encrypt models when it’s needed.

Updating your .env file#

After the fields have been encrypted, you should add the generated CipherSweet key to your .env file.

CIPHERSWEET_KEY=<YOUR-KEY>

The key will be used by your application to read encrypted values.

Searching on blind indexes#

Even though values are encrypted, you can still search them using a blind index. The blind indexes will have been built up when you ran the command to encrypt the model values.

Our package provides a whereBlind and orWhereBlind scope to search on blind indexes.

The first parameter is the column, the second the index name you set up when calling ->addBlindIndex, the third is the raw value, the package will automatically apply any transformations and hash the value to search on the blind index.

In closing#

CipherSweet is a very powerful library, and our package makes it very approachable. Of course, be very sure about what columns actually need encrypting, and don’t overdo it, encryption is resource intensive and comes with some downsides.

We’ll be using this package sparingly in the development of our upcoming SaaS mailcoach.cloud to protect the personal information that will be stored by our users.

Of course, laravel-ciphersweet isn’t the first package that our team has built. On our company website, check out all of our open source packages in this long list. If you want to support us, consider picking up any of our paid products.

Laravel Ciphersweet is a package by Spatie to integrate searchable field-level encryption in Laravel applications. The package’s readme explains the problem Ciphersweet can help solve as follows:

In your project, you might store sensitive personal data in your database. Should an unauthorised person get access to your DB, all sensitive can be read which is obviously not good.

To solve this problem, you can encrypt the personal data. This way, unauthorized persons cannot read it, but your application can still decrypt it when you need to display or work with the data.

This package is a wrapper for Ciphersweet to integrate its features into Laravel models easily. Here’s an example of a model from the readme’s setup instructions that illustrates what a model looks like using Ciphersweet:

 1use Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted;
 2use Spatie\LaravelCipherSweet\Concerns\UsesCipherSweet;
 3use ParagonIE\CipherSweet\EncryptedRow;
 4use Illuminate\Database\Eloquent\Model;
 5 
 6class User extends Model implements CipherSweetEncrypted
 7{
 8    use UsesCipherSweet;
 9 
10    public static function configureCipherSweet(EncryptedRow $encryptedRow): void
11    {
12        $encryptedRow
13            ->addField('email')
14            ->addBlindIndex('email', new BlindIndex('email_index'));
15    }
16}

This allows you the encrypt a user’s email to keep it safe from unauthorized people reading the data, but give you the ability to decrypt the data to display it or work with it.

Once you have configured this package and set up a model, you can search encrypted data in the database using blind indexes:

1$user = User::whereBlind('email', 'email_index', 'rias@spatie.be');

This package also aids in generating encrypting keys and encrypting model attributes to speed up integration with Ciphersweet.

I want to point out that you should not use this package blindly without understanding the ins and outs of the use case you are trying to solve. You can learn more about CipherSweet on this page, which has many linked resources.

CipherSweet also has PHP-specific documentation to help get you up to speed with the underlying PHP package.

I would also recommend reading Rias’ post, Encrypting Laravel Eloquent models with CipherSweet.

To get started with this package, check it out on GitHub at spatie/laravel-ciphersweet.

1. Not knowing which datatype to use in MySQL

I once heard it’s better to use integers when handling financial data. You convert a price like €10 to its lowest unit (cents in this case). This way you end up using 1000 as the amount to work with. This way you avoid the floating-point problem. The floating-point problem is best shown by typing the following in your Google Chrome console:

0.1 + 0.2 > 0.30000000000000004

If you want to learn more about this problem visit this website. Working with integers is dramatic for readability (how much is 13310 in euros?). The disadvantage of working with integers is also that it has a limit of 2147483647 which is roughly € 21,474,836.47. Although with the euro you probably wouldn’t run into this issue quickly but with the Vietnamese Dong, this wouldn’t work. Learnings: use decimals (not floats!) in MySQL to store monetary values. Depending on how many decimals you need decimal(15,2) oftentimes is enough.

2. Not having something to fact-check the numbers

Imagine we have a shopping cart where there’s 1 product for € 100, the VAT of € 21 and a total of € 131. The first time you’re sharp and you immediately see your mistake. After the 100th time, you start to be blind to those mistakes.

That’s why you need something to fact-check the numbers if they’re correct. I’ve created a Google Sheet for me and my team where we can all fact-check this. Especially if you work with people who test your product but don’t have access to the code this is crucial. How should they know if the price displayed is the correct one?

3. Not splitting the price into all the components

Every part of a price should be stored separately. If not, there’s no way to reproduce the components if you need to later on. So save the VAT amount, the discount amount, the base price, and the total all separately. Big chance there are gonna be more price components in your app in the future.

4. Using foreign keys in the ‘orders’ table

One of my dumbest mistakes. I had an ‘orders’ table where all the orders of an e-commerce store were placed. Unfortunately, it had a reference to the actual products which I got the product price from. Everything was fine until one of the product prices changed and older orders were affected by it😅

I’ve made many mistakes even though I have been developing applications for years. But without resistance, there’s no growth, so I tend to share my mistakes so you might prevent them.

I’m planning on writing an ebook on developing applications where you work with money. If you’re interested you might wanna subscribe to get free access to the first chapter.

Subscribe here