Laravel CipherSweet: Searchable Encrypted Attributes

Laravel CipherSweet is a Laravel implementation of Paragon Initiative Enterprises CipherSweet searchable field level encryption.

Make sure you have some basic understanding of CipherSweet before continuing.

Installation

Install the package using composer:

composer require bjornvoesten/laravel-ciphersweet

Publish configuration file:

php artisan vendor:publish --tag=ciphersweet-config

Generate an encryption key:

php artisan ciphersweet:key

Watch out! All encrypted columns depend on this key. If the key changes, the already encrypted columns can not be decrypted anymore!

Configuration

Algorithm

You can change the encryption algorithm by defining the crypto:

ENCRYPTION_CRYPTO=modern/fips

For more information about the encryption index algorithms see the documentation.

Usage

Defining encryption

Add the Bjornvoesten\CipherSweet\Traits\HasEncryption trait to the model.

    use HasEncryption;

Define the attributes that should ben encrypted.

    /**
     * The attributes that can be encrypted.
     *
     * @var array
     */
    protected $encrypted = [
        'social_security_number',
    ];

By default the index column name is generated using the name and suffixing it with _index.

So the social_security_number attribute will use the default index column social_security_number_index.

Alternatively you can define multiple indexes per attribute and and define more options.

    /**
     * Set the social security number attribute encryption.
     *
     * @param \Bjornvoesten\CipherSweet\Contracts\Attribute $attribute
     * @return void
     */
    public function socialSecurityNumberAttributeEncryption($attribute): void
    {
        $attribute
            ->index('social_security_number_full_index', function (Index $index) {
                $index
                    ->bits(32)
                    ->slow();
            })
            ->index('social_security_number_last_four_index', function (Index $index) {
                $index
                    ->bits(16)
                    ->transform(
                        new LastFourDigits()
                    );
            });
    }

For more information about the index options see the documentation.

And make sure you have created the index columns in the database table!

Searching models

You can search encrypted attributes by using the default where clause on the query builder or with the whereEncrypted method.

 \App\User::query()
    ->where('social_security_number', '=', $number)
    ->get();

By using the whereEncrypted method you can also define the indexes which can be searched.

 \App\User::query()
    ->whereEncrypted('social_security_number', '=', $number, [
        'social_security_number_last_four_index',
    ])
    ->get();

Note When searching with the equal to operator models will be returned when the value is found in one of all available or defined indexes. When searching with the not equal to operator all models where the value is not found in any of the available or the defined indexes are returned.

Caveat

Because of the limited search possibilities in CipherSweet only the = and != operators are available when searching encrypted attributes.

Testing

$ composer test

To be done.

License

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