NmureEncryptorBundle

A Symfony Bundle for the nmure/encryptor library.

Table of contents

• Introduction
• Installation
  • Step 1 : Download the Bundle
  • Step 2 : Enable the Bundle
  • Step 3 : Configure the Bundle
• Usage
• Configuration
• Formatters
• Informations
• License
• Issues / feature requests
• Changes

Introduction

This Bundle integrates the nmure/encryptor library into Symfony. It is recommended to read the lib's documentation before continuing here.

Installation

Step 1 : Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require nmure/encryptor-bundle "~2.0.0"

For Symfony < 4.0, run

$ composer require nmure/encryptor-bundle "~1.0.0"

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 2 : Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

// app/AppKernel.php
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Nmure\EncryptorBundle\NmureEncryptorBundle(),
            // ...
        );
    }
}

Step 3 : Configure the Bundle

Add the following configuration to your config.yml file :

# app/config/config.yml
nmure_encryptor:
    encryptors:
        my_encryptor:
            secret: 452F93C1A737722D8B4ED8DD58766D99 # should be a complex key defined in your parameters.yml file
        # you can add as many encryptors as you want
        my_other_encryptor:
            secret: 6A4E723D3F4AA81ACF776DCF2B6AEC45 # you should use one unique secret key by encryptor

Usage

You can access to the encryptors defined in the config.yml file by specifying your encryptor's name, e.g. : accessing to nmure_encryptor.my_encryptor will return the encryptor defined under the my_encryptor key.

All the encryptors are instances of the Nmure\Encryptor\Encryptor class. To use them, call the encrypt / decrypt functions :

// from a controller :
$encryptor = $this->get('nmure_encryptor.my_encryptor');
$encrypted = $encryptor->encrypt('hello world');
// ...
$decrypted = $encryptor->decrypt($encrypted);

Configuration

Here is the list of all the confifuration options that you can use in your app/config.yml file under the nmure_encryptor key:

• encryptors : array, required. The main array of encryptors. Must contain at least one encryptor.
  • my_encryptor : creates a new encryptor service named nmure_encryptor.my_encryptor.
    • secret : string, required. The secret encryption key.
    • cipher : string, optional. The cipher method (default to AES-256-CBC).
    • turn_hex_key_to_bin : boolean, optional. Indicates if the hex secret key given above should be converted to a binary key. This could be useful when sharing encrypted data with C# apps for instance.
    • formatter : string, optional. The service name of the formatter to use with this encryptor. You can create your own formatter, it has to implement the FormatterInterface.
    • disable_auto_iv_update : boolean, optional. Set it to true if you want to disable the automatic IV generation on the encryptor before each encryption. The automatic IV update is enabled by default.
  • second_encryptor : here comes an other encryptor ... :)

Formatters

The bundle wraps the lib's formatters into services that you can use when configuring your encryptors :

• Base64Formatter => nmure_encryptor.formatters.base64_formatter
• HexFormatter => nmure_encryptor.formatters.hex_formatter

Note : If you use Symfony >= 4.0, these services will be declared as private.

Informations

Useful informations about:

• PHP's openssl
• Initialization Vector usage

License

This Bundle is licensed under the MIT License. More informations in the LICENSE file.

Issues / feature requests

Please use this Github repository page to report issues and to ask / propose features.

Changes

See the changelog for more details.