symfony · wouterj · Dec 6, 2020 · Dec 5, 2020
diff --git a/cache.rst b/cache.rst
@@ -714,3 +714,86 @@ Clear all caches everywhere:
 .. code-block:: terminal
 
     $ php bin/console cache:pool:clear cache.global_clearer
+
+Encrypting the Cache
+--------------------
+
+.. versionadded:: 5.1
+
+    :class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller` has been
+    introduced in Symfony 5.1.
+
+To encrypt the cache using ``libsodium``, you can use the
+:class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`.
+
+.. note::
+
+    This will encrypt the values of the cache items, but not the cache keys. Be
+    careful not the leak sensitive data in the keys.
+
+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)%']
+                    # use multiple keys in order to rotate them
+                    #- ['%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" decorates="cache.default_marshaller">
+                    <argument>redis://localhost</argument>
+                    <argument type="collection">
+                        <argument>env(base64:CACHE_DECRYPTION_KEY)</argument>
+                        <!-- use multiple keys in order to rotate them -->
+                        <!-- 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)
+            ->decorate('cache.default_marshaller')
+            ->addArgument(['env(base64:CACHE_DECRYPTION_KEY)'])
+            // use multiple keys in order to rotate them
+            // ->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)'])
+            ->addArgument(service('@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'));
+
+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.
+
+Once all cache items encrypted with the old key have expired, you can remove
+`OLD_CACHE_DECRYPTION_KEY` completely.