Encrypting Data with a KMS

Binding a Ciphertext to Its Context

The third argument of encrypt(), and the second of decrypt(), is the Additional Authenticated Data (AAD): bytes that are authenticated but not encrypted, and that must be supplied again, identical, to decrypt:

1
2
3
4

$aad = 'user.email:tenant=acme';

$ciphertext = $this->encrypter->encrypt('app-key', $payload, $aad);
$plaintext = $this->decrypter->decrypt($ciphertext, $aad);

Put in the AAD everything the value must belong to, here the column and the tenant. A ciphertext copied to another column or another tenant then fails to decrypt, rather than quietly succeeding. Compute the AAD from what you are reading, such as the row or the request, and never from the ciphertext itself.

AAD is opaque bytes. Structured context has to be serialized to a stable form first, such as JSON with sorted keys, or two equal contexts will not produce equal bytes. A backend that cannot enforce AAD throws UnsupportedOperationException on a non-empty value when you call it directly, rather than ignoring it.

In envelope mode, the local cipher authenticates the AAD and the KMS never sees it. A mismatch is therefore refused on every backend, including the ones that cannot authenticate data.

For the same reason, a self-contained envelope cannot rely on a KMS policy conditioned on the AAD, such as the kms:EncryptionContext condition of AWS KMS. A data key store with bind_wrapping_context does pass a context to the KMS, but it is the reference and the scope of the stored key, not your AAD.

Choosing a Client

To inject a client other than the default one, name it with the #[Target] attribute:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\KeyManagement\EncrypterInterface;

final class PiiVault
{
    public function __construct(
        #[Target('pii')]
        private EncrypterInterface $encrypter,
    ) {
    }
}

Each client is also aliased to an argument named after it: $piiKms for the client itself and $piiEnvelopeEncrypter for its envelope encrypter, which autowiring honors without the attribute.

When a store is configured, the envelope interfaces resolve to the store-backed encrypter. #[Target('stored')] and the argument name $storedEnvelopeEncrypter both name it explicitly. The store itself is autowired through DataKeyStoreInterface, or through RewrappableDataKeyStoreInterface for the administrative half: listing the keys, re-wrapping them and replacing them.

Service IDs

Beyond autowiring, the bundle registers service ids you can reference by hand in a YAML or PHP service definition:

key_management.<name>

A configured client. Implements EncrypterInterface and DecrypterInterface, plus DataKeyGeneratorInterface when the backend can create data keys. Tagged key_management.client.

key_management.envelope_encrypter.<name>

The envelope encrypter of that client, which writes payloads carrying their own data key.

key_management.store

The data key store, registered only when store is configured.

key_management.stored_envelope_encrypter

The encrypter built on that store, which writes payloads carrying a reference instead.

key_management.doctrine_dbal.encrypted_types

Contains the encrypted Doctrine types. A DoctrineBundle connection registers these types when the connection is created, so they can wrap the types of doctrine.dbal.types. Without DoctrineBundle, the types are registered when the kernel boots. Registered only when some types are declared, in the configuration or through an #[Encrypted] column with an explicit key.

key_management.factory

Turns a DSN into a backend. Used by the bundle itself.

Four tags are meant for services of your own. key_management.client adds a client to the ones that the profiler and the encrypt, decrypt and data key commands know about, under the name given by its key attribute or, without that attribute, under its service id. key_management.factory, which autoconfiguration adds to every KmsFactoryInterface, makes a DSN scheme of your own available. key_management.flysystem is covered in KMS Backends and key_management.blind_index in Searching Encrypted Data. The data key store doesn't use tagged clients. It only trusts the client and allowed_clients options of its configuration.