Configuring the KMS Clients

DSN Schemes

Each backend has its own scheme. The package providing it must be installed, or the DSN is reported as an unsupported scheme:

KMS Backends documents the options each one takes. Bridges reject any query option they do not know, so a typo is an error rather than a setting silently ignored. The local schemes don't check their options, though.

Percent-encode the credentials and the option values of a DSN when they contain characters that have a meaning in a URL, such as the / that AWS secret keys often contain.

service://<id> is the odd one out. It names a service you registered yourself, so a backend Symfony does not ship is declared like any other client: it gets the tag the encrypt, decrypt and data key commands look clients up by, an envelope encrypter of its own and the profiler decoration, none of which a plain alias would give it. Because the service has to be known while the container is built, this scheme is the only one that cannot come from an environment variable.

The AWS, Azure, Google Cloud, Vault and Scaleway clients send their requests through the http_client service of the application, with the timeouts of that service. Without one, they use an HTTP client with a 5-second idle timeout and a 10-second maximum duration. Their timeout and max_duration options, in seconds, override the timeouts of either client. Requests never follow redirects, since a redirect to another host would send the credentials and the payload again.

Local backends need their PHP extension at runtime: ext-openssl for the openssl schemes, ext-sodium for the sodium and sealed-box ones. Envelope encryption itself always needs ext-openssl, since the local step is AES-256-GCM. The Flysystem bridge also needs ext-fileinfo, which league/mime-type-detection uses.

Multiple Clients

Declare several clients when different parts of the system have different providers, regions or rotation schedules. One of them is then the default, which is the one autowiring injects:

1
2
3
4
5
6

# config/packages/key_management.yaml
key_management:
    default_client: app
    clients:
        app: '%env(KMS_APP_DSN)%'
        pii: '%env(KMS_PII_DSN)%'

1
2
3
4
5
6
7
8
9
10
11
12

// config/packages/key_management.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'key_management' => [
        'default_client' => 'app',
        'clients' => [
            'app' => env('KMS_APP_DSN'),
            'pii' => env('KMS_PII_DSN'),
        ],
    ],
]);

With a single client, default_client is inferred and can be left out. With several clients and no default_client, autowiring needs the name of a client.

Wrapping Under Several Providers

Everything above comes down to one master key. A provider that is unreachable stops every decryption, and one that is lost permanently takes every payload with it.

A client declared by its members instead of a DSN is a composite client, which prevents both. It encrypts everything under each member and reads it back through the first member that answers. Each member names a client declared alongside it and the master key it wraps under; use null to reuse the key id passed to the call:

1
2
3
4
5
6
7
8
9
10
11
12

# config/packages/key_management.yaml
key_management:
    default_client: app
    clients:
        aws: '%env(AWS_KMS_DSN)%'
        azure: '%env(AZURE_KEY_VAULT_DSN)%'
        app:
            members:
                # the first member creates the data keys and is read first
                aws: ~
                # a key name, optionally followed by /<version>
                azure: 'app-key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// config/packages/key_management.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'key_management' => [
        'default_client' => 'app',
        'clients' => [
            'aws' => env('AWS_KMS_DSN'),
            'azure' => env('AZURE_KEY_VAULT_DSN'),
            'app' => [
                'members' => [
                    // creates the data keys and is read first
                    'aws' => null,
                    // a key name, optionally followed by /<version>
                    'azure' => 'app-key',
                ],
            ],
        ],
    ],
]);

A composite client is a client like any other: same service ids, same autowiring aliases, traced by the profiler, and it can be the default one. A member must itself be a declared client, which includes one you registered yourself through a service:// DSN, and it cannot be composite in turn.

Writing goes through every member, and a member that cannot wrap fails the whole call: a ciphertext missing one wrapping would be less redundant than the configuration claims. Reading needs only one member to answer. Each member that fails is skipped and logged on the key_management channel, since nothing else tells the caller.

The authenticated data of a direct call goes to every member, so a single member that cannot authenticate data, such as a sealed box, makes every such call fail and rules out bind_wrapping_context. Only the first member creates the data keys, and it also wraps the ones that key-management:rewrap-data-keys moves. The other members wrap them through their encryption operation and read them back through their decryption one, which their credentials must allow: kms:Encrypt and kms:Decrypt on AWS, or encrypt and decrypt under the algorithm option on Azure Key Vault, rather than wrapKey and unwrapKey under wrap_algorithm.

Since one member is enough to read a ciphertext, anyone who can encrypt for one member can write a ciphertext that the composite reads. With a sealed box member, its public key is enough.

Because it sits at the client level, a composite client covers every path without a change of format: direct ciphertexts, both envelope shapes, stored data keys and blind index keys.

1

$ php bin/console key-management:rewrap-data-keys

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# config/packages/key_management.yaml
key_management:
    default_client: app
    clients:
        aws: '%env(AWS_KMS_DSN)%'
        azure: '%env(AZURE_KEY_VAULT_DSN)%'
        gcp: '%env(GCP_KMS_DSN)%'
        app:
            members:
                aws: ~
                azure: 'app-key'
            # read, never written to; kept until nothing needs it
            retired:
                - gcp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// config/packages/key_management.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'key_management' => [
        'default_client' => 'app',
        'clients' => [
            'aws' => env('AWS_KMS_DSN'),
            'azure' => env('AZURE_KEY_VAULT_DSN'),
            'gcp' => env('GCP_KMS_DSN'),
            'app' => [
                'members' => [
                    'aws' => null,
                    'azure' => 'app-key',
                ],
                // read, never written to; kept until nothing needs it
                'retired' => ['gcp'],
            ],
        ],
    ],
]);