README

A Symfony Bundle for the nmure/encryptor library.

Introduction
Installation
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:

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.

nmure / encryptor-bundle

Maintainers

Details