8000 [Cache] Document cache encryption using SodiumMarshaller · symfony/symfony-docs@4e4924e · GitHub
[go: up one dir, main page]

Skip to content

Commit 4e4924e

Browse files
pableuwouterj
authored andcommitted
[Cache] Document cache encryption using SodiumMarshaller
1 parent 84fb7fa commit 4e4924e

File tree

1 file changed

+83
-0
lines changed

1 file changed

+83
-0
lines changed

cache.rst

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -714,3 +714,86 @@ Clear all caches everywhere:
714714
.. code-block:: terminal
715715
716716
$ php bin/console cache:pool:clear cache.global_clearer
717+
718+
Encrypting the Cache
719+
--------------------
720+
721+
.. versionadded:: 5.1
722+
723+
:class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller` has been
724+
introduced in Symfony 5.1.
725+
726+
To encrypt the cache using ``libsodium``, you can use the
727+
:class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`.
728+
729+
.. note::
730+
731+
This will encrypt the values of the cache items, but not the cache keys. Be
732+
careful not the leak sensitive data in the keys.
733+
734+
Generate a key:
735+
736+
.. code-block:: terminal
737+
738+
$ php -r 'echo base64_encode(sodium_crypto_box_keypair());'
739+
740+
And add it to your :doc:`secret store </configuration/secrets>` as
741+
``CACHE_DECRYPTION_KEY`` and enable the ``SodiumMarshaller``:
742+
743+
.. configuration-block::
744+
745+
.. code-block:: yaml
746+
747+
# config/packages/cache.yaml
748+
services:
749+
Symfony\Component\Cache\Marshaller\SodiumMarshaller:
750+
decorates: cache.default_marshaller
751+
arguments:
752+
- ['%env(base64:CACHE_DECRYPTION_KEY)%']
753+
# use multiple keys in order to rotate them
754+
#- ['%env(base64:CACHE_DECRYPTION_KEY)%', '%env(base64:OLD_CACHE_DECRYPTION_KEY)%']
755+
- '@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'
756+
757+
.. code-block:: xml
758+
759+
<!-- config/packages/cache.xml -->
760+
<?xml version="1.0" encoding="UTF-8" ?>
761+
<container xmlns="http://symfony.com/schema/dic/services"
762+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
763+
xmlns:framework="http://symfony.com/schema/dic/symfony"
764+
xsi:schemaLocation="http://symfony.com/schema/dic/services
765+
https://symfony.com/schema/dic/services/services-1.0.xsd
766+
http://symfony.com/schema/dic/symfony
767+
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
768+
769+
<services>
770+
<service id="Symfony\Component\Cache\Marshaller\SodiumMarshaller" decorates="cache.default_marshaller">
771+
<argument>redis://localhost</argument>
772+
<argument type="collection">
773+
<argument>env(base64:CACHE_DECRYPTION_KEY)</argument>
774+
<!-- use multiple keys in order to rotate them -->
775+
<!-- argument>env(base64:OLD_CACHE_DECRYPTION_KEY)</argument -->
776+
</argument>
777+
<argument type="service" id="Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner"/>
778+
</service>
779+
</services>
780+
</container>
781+
782+
.. code-block:: php
783+
784+
// config/packages/cache.php
785+
use Symfony\Component\Cache\Marshaller\SodiumMarshaller;
786+
787+
$container->register(SodiumMarshaller::class)
788+
->decorate('cache.default_marshaller')
789+
->addArgument(['env(base64:CACHE_DECRYPTION_KEY)'])
790+
// use multiple keys in order to rotate them
791+
// ->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)'])
792+
->addArgument(service('@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'));
793+
794+
To rotate your encryption keys but still be able to read existing cache entries,
795+
add the old encryption key to the service arguments. The first key will be used
796+
for reading and writing, and the additional key(s) will only be used for reading.
797+
798+
Once all cache items encrypted with the old key have expired, you can remove
799+
`OLD_CACHE_DECRYPTION_KEY` completely.

0 commit comments

Comments
 (0)
0