Document encryption features

CHANGELOG.md

@@ -3,6 +3,10 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [1.3.1] - Unreleased
+### Added
+- Added encryption [documentation](http://jmspaymentcorebundle.readthedocs.io/en/stable/encryption.html)
+
 ## [1.3.0] - 2017-01-22
 ### Changed
 - `JMS\Payment\CoreBundle\Model\ExtendedDataInterface` has changed. If any of your classes implement this interface, you need to update them accordingly:

Form/ChoosePaymentMethodType.php

@@ -60,10 +60,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
 
         // To maintain BC, we instantiate a new ChoosePaymentMethodTransformer in
         // case it hasn't been supplied.
-        $transformer = $this->transformer
-            ? $this->transformer
-            : new ChoosePaymentMethodTransformer()
-        ;
+        $transformer = $this->transformer ?: new ChoosePaymentMethodTransformer();
 
         $transformer->setOptions($options);
         $builder->addModelTransformer($transformer);

Resources/doc/backends.rst

@@ -16,7 +16,7 @@ This is the list of currently supported payment backends, through community-crea
 - `Merchant e-Solutions (Trident) <https://github.com/immersivelabs/PaymentMeSBundle>`_
 - `Mollie <https://github.com/ruudk/PaymentMollieBundle>`_
 - `Multisafepay <https://github.com/ruudk/PaymentMultisafepayBundle>`_
-- `Paymill <https://github.com/memeoirs/paymill-bundle>`_
+- `Paymill <https://github.com/regularjack/paymill-bundle>`_
 - `Paypal <http://jmspaymentpaypalbundle.readthedocs.io>`_
 - `Qiwi <https://github.com/chewbacco/ChewbaccoPaymentQiwiWalletBundle>`_
 - `Robokassa <https://github.com/karser/RobokassaBundle>`_

Resources/doc/encryption.rst

@@ -0,0 +1,41 @@
+Encryption
+==========
+
+- What is encrypted
+- Migrating from mcrypt to defuse
+
+
+Enabling encryption
+-------------------
+The only thing you need to do to enable encryption is to configure an encryption key. You can generate a key with the following command:
+
+.. code-block :: bash
+
+    bin/console jms_payment_core:generate-key
+
+And then use it in your configuration:
+
+.. code-block :: yaml
+
+    # app/config/config.yml
+    jms_payment_core:
+        encryption:
+            secret: output_of_above_command
+
+.. warning ::
+
+    If you change ``encryption.secret`` and/or ``encryption.provider``, all encrypted data will become unreadable. See :ref:`encryption-reencrypt` for instructions on how to properly change the encryption key or provider.
+
+Selectively encrypting data
+---------------------------
+TODO - Usage (form)
+
+Using a custom encryption provider
+----------------------------------
+TODO (Not recommended)
+
+.. _encryption-reencrypt:
+
+Re-encrypting data
+------------------
+Coming soon

Resources/doc/index.rst

@@ -32,6 +32,7 @@ License
 
     setup
     payment_form
+    encryption
     events
     plugins
     model

Resources/doc/setup.rst

@@ -1,8 +1,8 @@
 Setup
 =====
 
-Installation
--------------
+Installing
+----------
 Install with composer:
 
 .. code-block :: bash
@@ -23,29 +23,8 @@ And register the bundle in your ``AppKernel.php``:
         );
     }
 
-Configuration
--------------
-The configuration is as simple as setting an encryption key which will be used for encrypting data. You can generate a random key with the following command:
-
-.. code-block :: bash
-
-    bin/console jms_payment_core:generate-key
-
-And then use it in your configuration:
-
-.. code-block :: yaml
-
-    # app/config/config.yml
-    jms_payment_core:
-        encryption:
-            secret: output_of_above_command
-
-.. warning ::
-
-    If you change the ``secret`` or the ``crypto`` provider, all encrypted data will become unreadable.
-
-Create database tables
-----------------------
+Creating database tables
+------------------------
 This bundle requires a few database tables, which you can create as follows.
 
 If you're not using database migrations:
@@ -84,8 +63,8 @@ Or, if you're using migrations:
 
 .. _setup-configure-plugin:
 
-Configure a payment backend
----------------------------
+Configuring a payment backend
+-----------------------------
 In addition to setting up this bundle, you will also need to install a *plugin* for each payment backend you intend to support. Plugins are simply bundles you add to your application, as you would with any other Symfony bundle.
 
 .. tip ::
@@ -128,6 +107,10 @@ And configure it:
 
     :doc:`Other plugins <backends>` will require different configuration. Take a look at their documentation for complete instructions.
 
+Encrypting sensitive data
+-------------------------
+This bundle can encrypt sensitive data before storing it in the database. However, this feature is disabled by default. See :doc:`encryption` for instructions on how to enable it.
+
 Next steps
 ----------
 If you have no prior experience with this bundle or payment processing in general, you should follow the :doc:`guides/accepting_payments` guide. Otherwise, proceed to the :doc:`payment_form` chapter.

Tests/Functional/PaymentWorkflow/BasePaymentWorkflowTest.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace JMS\Payment\CoreBundle\Tests\Functional\PaymentWorkflow;
+
+use JMS\Payment\CoreBundle\Tests\Functional\BaseTestCase;
+use JMS\Payment\CoreBundle\Tests\Functional\TestBundle\Entity\Order;
+
+abstract class BasePaymentWorkflowTest extends BaseTestCase
+{
+    protected function getRawExtendedData($order)
+    {
+        $em = self::$kernel->getContainer()->get('em');
+
+        $stmt = $em->getConnection()->prepare('
+            SELECT extended_data
+            FROM payment_instructions
+            WHERE id = '.$order->getPaymentInstruction()->getId()
+        );
+
+        $stmt->execute();
+        $result = $stmt->fetchAll();
+
+        return unserialize($result[0]['extended_data']);
+    }
+
+    protected function doRequest($order, $route)
+    {
+        $client = $this->createClient();
+        $this->importDatabaseSchema();
+
+        $em = self::$kernel->getContainer()->get('em');
+        $router = self::$kernel->getContainer()->get('router');
+
+        $em->persist($order);
+        $em->flush();
+
+        $crawler = $client->request('GET', $router->generate($route, array('id' => $order->getId())));
+        $form = $crawler->selectButton('submit_btn')->form();
+        $form['jms_choose_payment_method[method]']->select('paypal_express_checkout');
+        $client->submit($form);
+
+        return $client->getResponse();
+    }
+
+    protected function refreshOrder($order)
+    {
+        $em = self::$kernel->getContainer()->get('em');
+        $em->clear();
+
+        return $em->getRepository('TestBundle:Order')->find($order->getId());
+    }
+}

Tests/Functional/PaymentWorkflow/PaymentWorkflowMcryptTest.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace JMS\Payment\CoreBundle\Tests\Functional\PaymentWorkflow;
+
+use JMS\Payment\CoreBundle\Tests\Functional\TestBundle\Entity\Order;
+use JMS\Payment\CoreBundle\Util\Number;
+
+class PaymentWorkflowMcryptTest extends PaymentWorkflowTest
+{
+    protected static function createKernel(array $options = array())
+    {
+        return parent::createKernel(array('config' => 'config_mcrypt.yml'));
+    }
+
+    public function setUp()
+    {
+        if (version_compare(phpversion(), '7.1', '>=')) {
+            $this->markTestSkipped('mcrypt is deprecated since PHP 7.1');
+        }
+
+        parent::setUp();
+    }
+
+    /**
+     * @runInSeparateProcess
+     */
+    public function testPayment()
+    {
+        $amount = 123.45;
+        $order = new Order($amount);
+
+        $response = parent::doRequest($order, 'payment');
+        $order = $this->refreshOrder($order);
+
+        $this->assertSame(201, $response->getStatusCode(), substr($response, 0, 2000));
+        $this->assertTrue(Number::compare($amount, $order->getPaymentInstruction()->getAmount(), '=='));
+        $this->assertEquals('bar', $order->getPaymentInstruction()->getExtendedData()->get('foo'));
+
+        $extendedData = $this->getRawExtendedData($order);
+        $this->assertArrayHasKey('foo', $extendedData);
+        $this->assertNotEquals('bar', $extendedData['foo'][0]);
+    }
+}

Tests/Functional/PaymentWorkflow/PaymentWorkflowNoEncryptionTest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace JMS\Payment\CoreBundle\Tests\Functional\PaymentWorkflow;
+
+use JMS\Payment\CoreBundle\Tests\Functional\TestBundle\Entity\Order;
+use JMS\Payment\CoreBundle\Util\Number;
+
+class PaymentWorkflowNoEncryptionTest extends BasePaymentWorkflowTest
+{
+    /**
+     * Disable encryption globally.
+     */
+    protected static function createKernel(array $options = array())
+    {
+        return parent::createKernel(array('config' => 'config_no_encryption.yml'));
+    }
+
+    /**
+     * @runInSeparateProcess
+     */
+    public function testPayment()
+    {
+        $amount = 123.45;
+        $order = new Order($amount);
+
+        $response = parent::doRequest($order, 'payment');
+        $order = $this->refreshOrder($order);
+
+        $this->assertSame(201, $response->getStatusCode(), substr($response, 0, 2000));
+        $this->assertTrue(Number::compare($amount, $order->getPaymentInstruction()->getAmount(), '=='));
+        $this->assertEquals('bar', $order->getPaymentInstruction()->getExtendedData()->get('foo'));
+
+        $extendedData = $this->getRawExtendedData($order);
+        $this->assertArrayHasKey('foo', $extendedData);
+        $this->assertEquals('bar', $extendedData['foo'][0]);
+    }
+}

Tests/Functional/PaymentWorkflow/PaymentWorkflowTest.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace JMS\Payment\CoreBundle\Tests\Functional\PaymentWorkflow;
+
+use JMS\Payment\CoreBundle\Tests\Functional\TestBundle\Entity\Order;
+use JMS\Payment\CoreBundle\Util\Number;
+
+class PaymentWorkflowTest extends BasePaymentWorkflowTest
+{
+    /**
+     * @runInSeparateProcess
+     */
+    public function testPayment()
+    {
+        $amount = 123.45;
+        $order = new Order($amount);
+
+        $response = parent::doRequest($order, 'payment');
+        $order = $this->refreshOrder($order);
+
+        $this->assertSame(201, $response->getStatusCode(), substr($response, 0, 2000));
+        $this->assertTrue(Number::compare($amount, $order->getPaymentInstruction()->getAmount(), '=='));
+        $this->assertEquals('bar', $order->getPaymentInstruction()->getExtendedData()->get('foo'));
+
+        $extendedData = $this->getRawExtendedData($order);
+        $this->assertArrayHasKey('foo', $extendedData);
+        $this->assertNotEquals('bar', $extendedData['foo'][0]);
+    }
+
+    /**
+     * @runInSeparateProcess
+     */
+    public function testPaymentNoEncryption()
+    {
+        $amount = 123.45;
+        $order = new Order($amount);
+
+        $response = parent::doRequest($order, 'payment_no_encryption');
+        $order = $this->refreshOrder($order);
+
+        $this->assertSame(201, $response->getStatusCode(), substr($response, 0, 2000));
+        $this->assertTrue(Number::compare($amount, $order->getPaymentInstruction()->getAmount(), '=='));
+        $this->assertEquals('bar', $order->getPaymentInstruction()->getExtendedData()->get('foo'));
+
+        $extendedData = $this->getRawExtendedData($order);
+        $this->assertArrayHasKey('foo', $extendedData);
+        $this->assertNotEquals('bar', $extendedData['foo'][0]);
+    }
+}