ExportXMLWordPrintableJSON

    • Type: New Feature
    • Resolution: Fixed
    • Priority: Major - P3
    • 5.12.0
    • Affects Version/s: None
    • None
    • Needed
    • Hide

      1. What to communicate to the user about this feature?

      • The command rotates the master key, not the data keys. It re-encrypts the data encryption keys (DEKs) stored in the key vault under a new master key. The DEKs keep their id and key material, so no document is read, decrypted or rewritten, and encrypted data stays readable.
      • Both the old and the new KMS credentials must be present in driver_options.autoEncryption.kmsProviders while the command runs: a DEK is unwrapped with the old master key before being wrapped with the new one.
      • The new credentials must stay in the configuration afterwards. Without them, every DEK, and so every encrypted document, becomes undecryptable.
      • The provider and master key default to the connection configuration, so a rotation can be driven from config/database.php alone. --provider and --master-key override them.
      • --provider must be one of the configured kmsProviders. Otherwise the command fails with exit code 1 and lists the configured providers.
      • A local KMS holds a single key, so rotating between two local keys needs a named provider, for example local and local:rotated.
      • --filter narrows which DEKs are rewrapped, as a JSON key vault query.
      • In production the command asks for confirmation. --force skips it.
      • This is not a way to replace the data keys themselves. That is a different, far more expensive operation, since every document has to be read, decrypted and rewritten.

      2. Examples of syntax and output?

      1. Rotate using the connection configuration as-is
        php artisan mongodb:encryption:rewrap-data-keys
      2. Rotate to a second local key configured as "local:rotated"
        php artisan mongodb:encryption:rewrap-data-keys --provider=local:rotated
      3. Rotate to a cloud KMS provider
        php artisan mongodb:encryption:rewrap-data-keys --provider=aws \
          --master-key='{"region":"eu-west-1","key":"arn:aws:kms:eu-west-1:111122223333:key/abcd-1234"}'
      4. Only the keys matching a key vault query, and skip the production prompt
        php artisan mongodb:encryption:rewrap-data-keys \
          --filter='{"keyAltNames":"laravel_qe.patients/ssn"}' --force

      Output:

      Rewrapped 1 data key(s) in "encryption.__keyVault" under the "local:rotated" master key.

      No key matched:

      No data key in "encryption.__keyVault" matched the filter. Nothing was rewrapped.

      Unconfigured provider (exit code 1):

      The "aws" KMS provider is not configured. Configured providers: "local", "local:rotated".

      Configuration for two local keys:

      'autoEncryption' => [
          'keyVaultNamespace' => 'encryption.__keyVault',
          'kmsProviders' => [
              'local' => ['key' => env('MONGODB_LOCAL_MASTER_KEY')],
              'local:rotated' => ['key' => env('MONGODB_ROTATED_MASTER_KEY')],
          ],
      ],

       

      Show
      1. What to communicate to the user about this feature? The command rotates the master key, not the data keys. It re-encrypts the data encryption keys (DEKs) stored in the key vault under a new master key. The DEKs keep their id and key material, so no document is read, decrypted or rewritten, and encrypted data stays readable. Both the old and the new KMS credentials must be present in driver_options.autoEncryption.kmsProviders while the command runs: a DEK is unwrapped with the old master key before being wrapped with the new one. The new credentials must stay in the configuration afterwards. Without them, every DEK, and so every encrypted document, becomes undecryptable. The provider and master key default to the connection configuration, so a rotation can be driven from config/database.php alone. --provider and --master-key override them. --provider must be one of the configured kmsProviders. Otherwise the command fails with exit code 1 and lists the configured providers. A local KMS holds a single key, so rotating between two local keys needs a named provider, for example local and local:rotated. --filter narrows which DEKs are rewrapped, as a JSON key vault query. In production the command asks for confirmation. --force skips it. This is not a way to replace the data keys themselves. That is a different, far more expensive operation, since every document has to be read, decrypted and rewritten. 2. Examples of syntax and output? Rotate using the connection configuration as-is php artisan mongodb:encryption:rewrap-data-keys Rotate to a second local key configured as "local:rotated" php artisan mongodb:encryption:rewrap-data-keys --provider=local:rotated Rotate to a cloud KMS provider php artisan mongodb:encryption:rewrap-data-keys --provider=aws \   --master-key='{"region":"eu-west-1","key":"arn:aws:kms:eu-west-1:111122223333:key/abcd-1234"}' Only the keys matching a key vault query, and skip the production prompt php artisan mongodb:encryption:rewrap-data-keys \   --filter='{"keyAltNames":"laravel_qe.patients/ssn"}' --force Output: Rewrapped 1 data key(s) in "encryption.__keyVault" under the "local:rotated" master key. No key matched: No data key in "encryption.__keyVault" matched the filter. Nothing was rewrapped. Unconfigured provider (exit code 1): The "aws" KMS provider is not configured. Configured providers: "local", "local:rotated". Configuration for two local keys: 'autoEncryption' => [     'keyVaultNamespace' => 'encryption.__keyVault',     'kmsProviders' => [         'local' => ['key' => env('MONGODB_LOCAL_MASTER_KEY')] ,         'local:rotated' => ['key' => env('MONGODB_ROTATED_MASTER_KEY')] ,     ], ],  
    • None
    • None
    • None
    • None
    • None
    • None

      Summary

      Add a command to re-encrypt the Data Encryption Keys (DEKs) under a new master key from a different KMS provider, so applications can rotate their master key.

      Proposal mongodb:encrypted:rewrap-deks iterates the key vault with ClientEncryption::rewrapManyDataKey(), re-encrypting each DEK under the new master key.

      • Used to change the master encryption key (local or a cloud KMS provider).
      • Key rotation was previously out of scope in the Queryable Encryption work; this is a planned follow-up. Equivalent of PHPORM-376.

              Assignee:
              Pauline Vos
              Reporter:
              Jérôme Tamarelle
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Created:
                Updated:
                Resolved: