[Cache] Document cache encryption using SodiumMarshaller

Author: pableu

cache.rst

@@ -714,3 +714,119 @@ Clear all caches everywhere:
 .. code-block:: terminal
 
     $ php bin/console cache:pool:clear cache.global_clearer
+
+Encrypting the Cache
+--------------------
+
+To encrypt the cache using ``libsodium``, you can use the
+:class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`.
+
+Generate a key:
+
+.. code-block:: terminal
+
+    $ php -r 'echo base64_encode(sodium_crypto_box_keypair());'
+
+And add it to your :doc:`secret store </configuration/secrets>` as
+``CACHE_DECRYPTION_KEY`` and enable the ``SodiumMarshaller``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        services:
+            Symfony\Component\Cache\Marshaller\SodiumMarshaller:
+            decorates: cache.default_marshaller
+            arguments:
+                - ['%env(base64:CACHE_DECRYPTION_KEY)%']
+                - '@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <services>
+                <service id="Symfony\Component\Cache\Marshaller\SodiumMarshaller">
+                    <factory class="Symfony\Component\Cache\Adapter\RedisAdapter" method="createConnection"/>
+                    <argument>redis://localhost</argument>
+                    <argument type="collection">
+                        <argument>env(base64:CACHE_DECRYPTION_KEY)</argument>
+                    </argument>
+                    <argument type="service" id="@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        use Symfony\Component\Cache\Marshaller\SodiumMarshaller;
+
+        $container->register(SodiumMarshaller::class)
+            ->addArgument(['env(base64:CACHE_DECRYPTION_KEY)'])
+            ->addArgument(service('@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'));
+
+Rotating the encryption key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To rotate your encryption keys but still be able to read existing cache entries,
+add the old encryption key to the service arguments. The first key will be used
+for reading and writing, and the additional key(s) will only be used for reading.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+        services:
+            Symfony\Component\Cache\Marshaller\SodiumMarshaller:
+            decorates: cache.default_marshaller
+            arguments:
+                - ['%env(base64:CACHE_DECRYPTION_KEY)%', '%env(base64:OLD_CACHE_DECRYPTION_KEY)%']
+                - '@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <services>
+                <service id="Symfony\Component\Cache\Marshaller\SodiumMarshaller">
+                    <factory class="Symfony\Component\Cache\Adapter\RedisAdapter" method="createConnection"/>
+                    <argument>redis://localhost</argument>
+                    <argument type="collection">
+                        <argument>env(base64:CACHE_DECRYPTION_KEY)</argument>
+                        <argument>env(base64:OLD_CACHE_DECRYPTION_KEY)</argument>
+                    </argument>
+                    <argument type="service" id="@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        use Symfony\Component\Cache\Marshaller\SodiumMarshaller;
+
+        $container->register(SodiumMarshaller::class)
+            ->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)'])
+            ->addArgument(service('@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'));
+
+Once all cache entries encrypted with the old key have expired, you can remove
+`OLD_CACHE_DECRYPTION_KEY` completely.