wizofgoz/cryptographer

An extensible encryption system for Laravel

v0.3 2019-10-01 19:24 UTC

Requires

• php: >=7.1.0
• ext-json: *
• ext-openssl: *
• illuminate/container: ^5.6|^6.0
• illuminate/support: ^5.6|^6.0

Requires (Dev)

• aws/aws-sdk-php: ^3.112
• guzzlehttp/guzzle: ^6.3
• mockery/mockery: ^1.0
• orchestra/testbench: ^3.1
• php-coveralls/php-coveralls: ^2.0
• phpunit/phpunit: ^6.0|^7.0|^8.0

Suggests

• ext-sodium: Required to use sodium engine
• aws/aws-sdk-php: Required to use AWS key driver
• aws/aws-sdk-php-laravel: Better integration of the AWS SDK with Laravel

MIT

• Jordan Gosney

• encryption
• laravel
• libsodium

README

Introduction

Cryptographer provides an extensible replacement for Laravel's encryption service. It also allows you to define multiple drivers that can be used for different areas of your application.

Installation

You may use Composer to install Cryptographer into your Laravel project:

composer require wizofgoz/cryptographer

After installing, publish the configuration:

php artisan vendor:publish --provider="Wizofgoz\Cryptographer\EncryptionServiceProvider"

Configuration

After publishing the configuration file, it will be located at config/cryptographer.php This file allows you to define the encryption drivers available to your application.

Defaults

These options allow you to define the default encryption driver and key to use when using the encryption service. If no default driver is set, the first entry in the drivers array will be used.

'default-driver' => 'default',
'default-key'    => 'default',

Available Drivers

This array allows for defining the encryption drivers available to your application. Each entry in the list MUST contain an engine, cipher, and key name for proper use.

'drivers' => [
    'default' => [
        'engine' => 'openssl',
        'cipher' => OpenSslEngine::CIPHER_AES_128,
        'key'    => 'default',
    ],
],

Keys

This array allows for defining multiple keys for use with your encryption drivers. Each key must have a unique name.

Local Driver

The simplest key implementation is one that is managed locally. With this driver, the key is visible locally in plaintext and is loaded directly into the encryption driver being used.

'default' => [
    'driver' => 'local',
    'value' => env('APP_KEY'),
],

AWS Driver

When it is unacceptable for the key to be stored in plaintext, the AWS driver is able to use a local key that has been encrypted with an AWS KMS consumer key.

This allows you to rotate the encryption of the key and not have to re-encrypt all the data the key was used to encrypt.

'kms' => [
    'driver'     => 'aws',
    'value'      => env('AWS_DATA_KEY'), // encrypted value of the local data key
    'region'     => 'us-west-2',
    'profile'    => 'default', // credentials to use from ~/.aws/credentials file
    'master-key' => 'key_id_for_making_data_key', // ARN or key ID of master key to use
    'context'    => [], // optional key/values for authenticating key material
],

Usage

This package integrates with Laravel's encryption system and either the built-in encrypt() and decrypt() helpers or the Crypt facade may be used when you want to utilize your default driver.

In order to use additional drivers, either the Crypt facade must be used as shown below:

use Illuminate\Support\Facades\Crypt;

$encrypted = Crypt::driver('something')->encrypt('Hello world.');

Or the ncrypt and dcrypt helper functions must be used:

$encrypted = ncrypt('some value', 'driver_name');

$plaintext = dcrypt($encrypted, 'driver_name');

Key Generation

Encryption keys can be generated using the command php artisan crypt:key:generate and there are the following options available:

• --driver the name of the driver from your configuration to use.
• --engine an override of the engine to use when generating a key.
• --cipher an override of the cipher to use when generating a key.
• --key-driver an override of the key driver to use when generating a key.
• --aws-master-key an override of the AWS CMK to use for encrypting a local data key (Only used for AWS key driver).
• --aws-region an override of the AWS region to use for making calls to the AWS API (Only used for AWS key driver).
• --aws-context an override of any custom context to use for encrypting the local data key (Only used for AWS key driver).
• --environment what environment variable to set in your .env file. Defaults to APP_KEY.
• --show to display the key instead of applying it to configuration and environment.
• --force force the operation to run when in production.

Available Engines

OpenSSL

The openssl engine is drop-in replacement for Laravel's encryption system that will work with existing keys assuming the cipher is set correctly.

Supported Ciphers

• OpenSslEngine::CIPHER_AES_128: AES-128-CBC - default
• OpenSslEngine::CIPHER_AES_256: AES-256-CBC

Sodium

The sodium engine depends on the Sodium PHP extension and will not be available if it is missing. In PHP 7.2+, the Sodium extension is part of the core and should always be available.

Supported Ciphers

• SodiumEngine::CIPHER_AES_256: AES-256-GCM - requires hardware support
• SodiumEngine::CIPHER_CHACHA: CHACHA-20-POLY-1305
• SodiumEngine::CIPHER_CHACHA_IETF: CHACHA-20-POLY-1305-IETF
• SodiumEngine::CIPHER_X_CHACHA_IETF: XCHACHA-20-POLY-1305-IETF - default

Extensions

Custom encryption engines are expected to implement the Wizofgoz\Cryptographer\Contracts\Engine contract and can be added by simply extending EncryptionManager:

public function register()
{
    $this->app->resolving('encrypter', function ($encrypter) {
        $encrypter->extend('engine_name', function ($config) {
            return new CustomEngine($config);
        });
    });
}

Custom key drivers are expected to implement the Wizofgoz\Cryptographer\Contracts\KeyDriver contract and can be added in a very similar manner by extending the KeyManager:

public function register()
{
    $this->app->resolving('key-manager', function ($km) {
        $km->extend('driver_name', function ($config) {
            return new CustomDriver($config);
        });
    });
}