laravel-ciphersweet

To use a custom encryption backend, set the ciphersweet.backend configuration value to custom. You must then provide an invokeable factory class in the ciphersweet.backend.custom configuration key. This factory must return an object implementing ParagonIE\CipherSweet\Contract\BackendInterface.

Your implementation of BackendInterface must define the logic for encryption, decryption, blind indexing (both fast and slow), key derivation, and streaming operations.

// 1. Define your backend implementation
class CustomBackend implements BackendInterface {
    public function encrypt(string $plaintext, SymmetricKey $key, string $aad = ''): string { /* ... */ }
    public function decrypt(string $ciphertext, SymmetricKey $key, string $aad = ''): string { /* ... */ }
    public function blindIndexFast(string $plaintext, SymmetricKey $key, ?int $bitLength = null): string { /* ... */ }
    public function blindIndexSlow(string $plaintext, SymmetricKey $key, ?int $bitLength = null, array $config = []): string { /* ... */ }
    public function getIndexTypeColumn(string $tableName, string $fieldName, string $indexName): string { /* ... */ }
    public function deriveKeyFromPassword(string $password, string $salt): SymmetricKey { /* ... */ }
    public function doStreamDecrypt($inputFP, $outputFP, SymmetricKey $key, int $chunkSize = 8192, ?AAD $aad = null): bool { /* ... */ }
    public function doStreamEncrypt($inputFP, $outputFP, SymmetricKey $key, int $chunkSize = 8192, string $salt = Constants::DUMMY_SALT, ?AAD $aad = null): bool { /* ... */ }
    public function getFileEncryptionSaltOffset(): int { /* ... */ }
    public function getPrefix(): string { /* ... */ }
}

// 2. Create the factory
class CustomBackendFactory {
    public function __invoke()
    {
        return new CustomBackend();
    }
}

// 3. In your config file:
// 'ciphersweet.backend' => 'custom',
// 'ciphersweet.backend.custom' => CustomBackendFactory::class,

To encrypt model attributes, your model must implement the Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted interface and use the Spatie\LaravelCipherSweet\Concerns\UsesCipherSweet trait.

You must implement the configureCipherSweet method to define which fields are encrypted and which have blind indexes for searching.

Field Types:

• addField('column_name'): Standard encrypted field.
• addBooleanField('column_name'), addIntegerField('column_name'), addTextField('column_name'): Type-specific encrypted fields.
• addOptional...('column_name'): Fields that remain unencrypted NULL if a NULL value is provided.
• addJsonField('column_name', $fieldMap): Encrypts a JSON array using a field map.
• addBlindIndex('column_name', new BlindIndex('index_name')): Creates a blind index for exact-match searching on the column.

Note: Database columns used for encrypted values should be of type text.

use Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted;
use Spatie\LaravelCipherSweet\Concerns\UsesCipherSweet;
use ParagonIE\CipherSweet\EncryptedRow;
use ParagonIE\CipherSweet\BlindIndex;
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'));
    }
}

To use a custom key provider, set the ciphersweet.provider configuration value to custom. You must then provide an invokeable factory class in the ciphersweet.providers.custom configuration key. This factory must return an object implementing ParagonIE\CipherSweet\Contract\KeyProviderInterface.

The provider must implement the getSymmetricKey() method, which returns a SymmetricKey instance used for encryption and decryption operations.

// 1. Define your key provider implementation
class CustomKeyProvider implements KeyProviderInterface {
    public function getSymmetricKey(): SymmetricKey
    {
        return new SymmetricKey('your-key-here');
    }
}

// 2. Create the factory
class CustomKeyProviderFactory {
    public function __invoke()
    {
        return new CustomKeyProvider();
    }
}

// 3. In your config file:
// 'ciphersweet.provider' => 'custom',
// 'ciphersweet.providers.custom' => CustomKeyProviderFactory::class,

You can publish the configuration file using the ciphersweet-config tag. The configuration allows you to define the cryptographic backend, the key provider, and provider-specific options like file paths or string keys.

Key configuration options:

• backend: The cryptographic backend to use. Recommended: nacl. Supported: boring, fips, nacl.
• provider: How the key is retrieved. Supported: file, random, string.
• providers: Settings for specific providers (e.g., path for file or key for string).
• permit_empty: Boolean determining if empty fields should throw an EmptyFieldException.

return [
    'backend' => env('CIPHERSWEET_BACKEND', 'nacl'),
    'provider' => env('CIPHERSWEET_PROVIDER', 'string'),
    'providers' => [
        'file' => [
            'path' => env('CIPHERSWEET_FILE_PATH'),
        ],
        'string' => [
            'key' => env('CIPHERSWEET_KEY'),
        ],
    ],
    'permit_empty' => env('CIPHERSWEET_PERMIT_EMPTY', FALSE)
];

The EncryptedUniqueRule allows you to perform unique validation on columns that are encrypted using CipherSweet. It works by querying the blind index associated with the column rather than the encrypted data itself.

To use it, you must provide the model class, the name of the blind index, and optionally the column name. The model being validated must implement the Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted interface.

Ignoring records during validation

When updating an existing record, you must ignore its current ID so the validation doesn't fail against itself. You can use the ignore() method with a raw ID or the ignoreModel() method with an Eloquent model instance.

use Spatie\LaravelCipherSweet\Rules\EncryptedUniqueRule;

// Basic usage
'email' => [new EncryptedUniqueRule(User::class, 'email_index')],

// Usage with ignoring an existing model (e.g., during an update)
'email' => [new EncryptedUniqueRule(User::class, 'email_index')->ignore($user)],

// Usage with ignoring a specific ID
'email' => [new EncryptedUniqueRule(User::class, 'email_index')->ignore(123)],