Initial setup - provides Hashing and Encryption via Adapters in Servi…

…ces and Subscribers. Subscribers are hooked into Doctrine Events and Services are available for separate instantiation.

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Robin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,110 @@
+# Zend Framework 3 & Doctrine Encrypt Module
+
+Provides a Zend Framework 3 & Doctrine 2 encryption module.
+
+# Installation
+
+    composer require rkeet/zf-doctrine-encrypt
+
+# Requirements
+
+ * PHP 7.2 or greater (must have Sodium extension enabled)
+
+If you're on Windows, using Xampp, the PHP 7.2 installation might not automatically enable the Sodium extension. If this
+the case, you'll get an error (`'This is not implemented, as it is not possible to securely wipe memory from PHP'`). 
+Enable Sodium for PHP by adding this to your `php.ini` file:
+
+    extension = C:\xampp\php\ext\php_sodium.dll
+
+This might also be applicable ot other local installations.  
+
+# Configuration
+
+## Zend Framework
+
+Make sure to add the module to you application configuration. In your `modules.config.php` make sure to include 
+`ZfDoctrineEncryptModule`.
+
+## Module
+
+`*.dist` files are provided. Copy these (remove extension) to your application and fill in the required key/salt values. 
+If these are filled in, it works out of the box using [Halite](https://github.com/paragonie/halite) for encryption. 
+
+However, must be said, at the moment of writing this ReadMe, the Halite module contains duplicate `const` declarations,
+as such, you must disable your `E_NOTICE` warnings in your PHP config :(
+
+## Annotation Examples
+
+### Encryption
+
+Simple, consider that you have an `Address` Entity, which under upcoming [EU GDPR regulation](https://www.eugdpr.org/)
+requires parts of the address, such as the street, to be encrypted. This uses the key & salt required for the config
+by default
+
+To encrypt a street name, add `@Encrypted` like so: 
+
+    /**
+     * @var string
+     * @ORM\Column(name="street", type="string", length=255, nullable=true)
+     * @Encrypted
+     */
+    protected $street;
+
+By default the Encryption service assumes that the data to be encrypted is of the type `string`. However, you could have
+a requirement to encrypt another type of data, such as a house number. Non-string types are supported, but the type of data
+must be provided if not a string. You can do this like so:
+
+    /**
+     * @var int
+     * @ORM\Column(name="house_number", type="integer", length=20, nullable=false)
+     * @Encrypted(type="int")
+     */
+    protected $houseNumber;
+
+Supported types are [found here](http://php.net/settype).
+
+### Hashing
+
+Say you'd like to store a password, it should work in much of the same way as the above. However, it is data that should
+not be de-cryptable (and there's no need for it to ever be decrypted), thus you should hash it instead.
+
+To hash something, like a password, add the `@Hashed` Annotation. See the example below.
+
+    /**
+     * @var string
+     * @ORM\Column(name="password", type="text", nullable=false)
+     * @Hashed
+     */
+    protected $password;
+
+**Note** that, unlike `@Encrypted`, there aren't options to give a type. As we can't decrypt the data (it's one-way), 
+there's no need to know what the original type was. The response will always be string value.
+
+ ## Controller Examples
+
+ ### Hashing
+
+ A `Hashmanager` service is provided. This manager also uses the `HaliteHashingAdapter` but provides functionality that 
+ can be used in Controllers and other classes, such as plugins. The service is registered under the alias 'hashing_service'.
+ You can override 'hasing_service' in your own project to provide your own implementation. 
+
+ The `HashManager` provides the ability to hash and verify strings. These are two separate operations, one one-way 
+ hashes a string. The other does the same (requires the hashed string) and then verifies that both strings are 
+ exactly the same (thus verifying).
+
+ In a Controller, to hash a string, simple do:
+
+     $secret = $this->getHashManager()->hash('correct horse battery staple')
+     
+ To verify that your dealing the same string a next time, for example to compare passwords on login, do:
+
+     $verified = $this->getHashManager()->verify('correct horse battery staple', $secret)
+     
+ `$verified` will be set to a boolean value. 
+
+ To not store any entered data longer than you must, you could compare directly from form data, like so:
+
+     if($form->isValid() && $this->getHashManager()->verify($form->getData()['password_field'], $user->getPassword()) {
+         // do other things
+     }
+     

composer.json

@@ -0,0 +1,39 @@
+{
+  "name": "rkeet/zf-doctrine-encrypt",
+  "description": "Provides property encryption and hashing for Doctrine Entities when used within Zend Framework 3.",
+  "keywords": [
+    "zf3",
+    "doctrine2",
+    "encrypt",
+    "module",
+    "zend framework 3",
+    "encryption"
+  ],
+  "homepage": "https://keet.me/",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Robin Keet",
+      "email": "robin@keet.me",
+      "homepage": "http://keet.me/"
+    }
+  ],
+  "require": {
+    "php": "^7.2",
+    "ext-sodium": "*",
+    "doctrine/annotations": "^1.6",
+    "doctrine/orm": "^2.6",
+    "paragonie/halite": "^4.4",
+    "zendframework/zend-modulemanager": "^2.8",
+    "zendframework/zend-servicemanager": "^2.7.8 || ^3.3",
+    "zendframework/zend-stdlib": "^3.2"
+  },
+  "autoload": {
+    "psr-4": {
+      "Keet\\Encrypt\\": "src/"
+    },
+    "classmap": [
+      "src/Module.php"
+    ]
+  }
+}

config/local.config.php.dist

@@ -0,0 +1,19 @@
+<?php
+
+namespace Encrypt;
+
+return [
+    'doctrine' => [
+        'encryption' => [
+            'orm_default' => [
+                'key' => '',        // Must be 32 characters - Halite requirement
+            ],
+        ],
+        'hashing' => [
+            'orm_default' => [
+                'pepper' => '',     // Must be 32 characters - Halite requirement
+                'key' => '',        // Must be 32 characters - Halite requirement
+            ],
+        ],
+    ],
+];

config/module.config.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Encrypt;
+
+use Doctrine\Common\Annotations\AnnotationReader;
+use Encrypt\Adapter\EncryptionAdapter;
+use Encrypt\Adapter\HashingAdapter;
+use Encrypt\Factory\Adapter\EncryptionAdapterFactory;
+use Encrypt\Factory\Adapter\HashingAdapterFactory;
+use Encrypt\Factory\Service\EncryptionServiceFactory;
+use Encrypt\Factory\Service\HashingServiceFactory;
+use Encrypt\Factory\Subscriber\EncryptionSubscriberFactory;
+use Encrypt\Factory\Subscriber\HashingSubscriberFactory;
+use Encrypt\Service\EncryptionService;
+use Encrypt\Service\HashingService;
+
+return [
+    'doctrine_factories' => [
+        'encryption' => EncryptionSubscriberFactory::class,
+        'hashing'    => HashingSubscriberFactory::class,
+    ],
+    'doctrine'           => [
+        'encryption'   => [
+            'orm_default' => [
+                'adapter' => 'encryption_adapter',
+                'reader'  => AnnotationReader::class,
+            ],
+        ],
+        'hashing'      => [
+            'orm_default' => [
+                'adapter' => 'hashing_adapter',
+                'reader'  => AnnotationReader::class,
+            ],
+        ],
+        'eventmanager' => [
+            'orm_default' => [
+                'subscribers' => [
+                    'doctrine.encryption.orm_default',
+                    'doctrine.hashing.orm_default',
+                ],
+            ],
+        ],
+    ],
+    'service_manager'    => [
+        'aliases'   => [
+            // Using aliases so someone else can use own adapter/factory
+            'encryption_adapter' => EncryptionAdapter::class,
+            'encryption_service' => EncryptionService::class,
+            'hashing_adapter'    => HashingAdapter::class,
+            'hashing_service'    => HashingService::class,
+        ],
+        'factories' => [
+            EncryptionAdapter::class => EncryptionAdapterFactory::class,
+            EncryptionService::class => EncryptionServiceFactory::class,
+            HashingAdapter::class    => HashingAdapterFactory::class,
+            HashingService::class    => HashingServiceFactory::class,
+        ],
+    ],
+];

src/Adapter/EncryptionAdapter.php

@@ -0,0 +1,91 @@
+<?php
+
+namespace Encrypt\Adapter;
+
+use Encrypt\Interfaces\EncryptionInterface;
+use ParagonIE\ConstantTime\Binary;
+use ParagonIE\Halite\Alerts\InvalidKey;
+use ParagonIE\Halite\HiddenString;
+use ParagonIE\Halite\Symmetric\Crypto;
+use ParagonIE\Halite\Symmetric\EncryptionKey;
+
+class EncryptionAdapter implements EncryptionInterface
+{
+    /**
+     * @var EncryptionKey
+     */
+    private $key;
+
+    /**
+     * HaliteAdapter constructor.
+     *
+     * @param $key
+     *
+     * @throws InvalidKey
+     * @throws \TypeError
+     */
+    public function __construct($key)
+    {
+        if (Binary::safeStrlen($key) !== \Sodium\CRYPTO_STREAM_KEYBYTES) {
+            throw new InvalidKey(
+                sprintf(
+                    'Encryption key used for %s::%s must be exactly %s characters long',
+                    __CLASS__,
+                    __FUNCTION__,
+                    \Sodium\CRYPTO_STREAM_KEYBYTES
+                )
+            );
+        }
+
+        $this->setKey(new EncryptionKey(new HiddenString($key)));
+    }
+
+    /**
+     * @param string $data
+     *
+     * @return string
+     * @throws \ParagonIE\Halite\Alerts\CannotPerformOperation
+     * @throws \ParagonIE\Halite\Alerts\InvalidDigestLength
+     * @throws \ParagonIE\Halite\Alerts\InvalidMessage
+     * @throws \ParagonIE\Halite\Alerts\InvalidType
+     */
+    public function encrypt(string $data) : string
+    {
+        return Crypto::encrypt(new HiddenString($data), $this->getKey());
+    }
+
+    /**
+     * @param string $data
+     *
+     * @return HiddenString|string
+     * @throws \ParagonIE\Halite\Alerts\CannotPerformOperation
+     * @throws \ParagonIE\Halite\Alerts\InvalidDigestLength
+     * @throws \ParagonIE\Halite\Alerts\InvalidMessage
+     * @throws \ParagonIE\Halite\Alerts\InvalidSignature
+     * @throws \ParagonIE\Halite\Alerts\InvalidType
+     */
+    public function decrypt(string $data) : string
+    {
+        return Crypto::decrypt($data, $this->getKey());
+    }
+
+    /**
+     * @return EncryptionKey
+     */
+    public function getKey() : EncryptionKey
+    {
+        return $this->key;
+    }
+
+    /**
+     * @param EncryptionKey $key
+     *
+     * @return EncryptionAdapter
+     */
+    public function setKey(EncryptionKey $key) : EncryptionAdapter
+    {
+        $this->key = $key;
+
+        return $this;
+    }
+}