> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# KeyVault.rewrapManyDataKey() (mongosh method)

Decrypts multiple Data Encryption Keys (DEK) and re-encrypts them with a new Customer Master Key (CMK). Use this method to rotate the CMK that encrypts your DEKs. To learn more about CMKs and DEKs, see [Encryption Keys and Key Vaults.](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/keys-key-vaults.md#std-label-qe-reference-keys-key-vaults)

You specify a CMK through the `masterKey` parameter. If you do not include a `masterKey` argument, the method decrypts and encrypts each DEK with the CMK referenced in that DEK's metadata. To learn more about the metadata of DEKs, see [Metadata Used for Decryption.](https://www.mongodb.com/docs/manual/core/csfle/reference/decryption.md#std-label-csfle-reference-decryption-metadata)

A [BulkWriteResult](https://www.mongodb.com/docs/manual/reference/method/bulkwriteresult.md#std-label-server-bulkwriteresult-method) object that reports how many data keys were affected.

**Warning: Back-Up Your Key Vault collection**

Before you rotate your Data Encryption Keys, ensure you create a backup of your Key Vault collection. If you lose access to your Data Encryption Keys, you will lose all your encrypted data.

To learn how to create a backup of a collection, see [Back Up and Restore with MongoDB Tools.](https://www.mongodb.com/docs/manual/tutorial/backup-and-restore-tools.md#std-label-manual-tutorial-backup-and-restore)

## Compatibility

This command is available in deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

* [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

* [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

`KeyVault.rewrapManyDataKey` has the following syntax:

```javascript
let keyVault = db.getMongo().getKeyVault()

keyVault.rewrapManyDataKey(
  <filter>,
  <options>
)
```

| Parameter | Type | Description |
| --- | --- | --- |
| `filter` | [query filter document](https://www.mongodb.com/docs/manual/core/documents-other-uses.md#std-label-document-query-filter) | The query filter for the keyvault collection |
| `options` | document | This document has two fields: `provider`: A [KMS provider](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/kms-providers.md#std-label-qe-fundamentals-kms-providers) (AWS KMS, Azure Key Vault, GCP KMS, the local provider, or KMIP); `masterKey`: A KMS-specific key used to encrypt the new data key |

**Important: Key Rotation Support**

To view your driver's dependencies for the key rotation API, see [Compatibility.](https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/compatibility.md#std-label-csfle-reference-compatibility-key-rotation)

## Behavior

This operation is not atomic and should not be run in parallel with other key management operations.

### Requires Configuring Client-Side Field Level Encryption on Database Connection

The [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) `ClientEncryption` methods require a database connection with in-use encryption enabled. If the current database connection was not initiated with in-use encryption enabled, either:

- Use the [`Mongo()`](https://www.mongodb.com/docs/manual/reference/method/mongo.md#mongodb-method-Mongo) constructor from the [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) to establish a connection with the required in-use encryption options. The [`Mongo()`](https://www.mongodb.com/docs/manual/reference/method/mongo.md#mongodb-method-Mongo) method supports the following Key Management Service (KMS) providers for Customer Master Key (CMK) management:

  - [Amazon Web Services KMS](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/kms-providers.md#std-label-qe-fundamentals-kms-providers-aws)

  - [Azure Key Vault](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/kms-providers.md#std-label-qe-fundamentals-kms-providers-azure)

  - [Google Cloud Platform KMS](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/kms-providers.md#std-label-qe-fundamentals-kms-providers-gcp)

  - [Locally Managed Key](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/kms-providers.md#std-label-qe-fundamentals-kms-providers-local)

  *or*

- Use the [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) [command line options](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-label-mongosh-client-side-field-level-encryption-options) to establish a connection with the required options. The command line options only support the [Amazon Web Services KMS](https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/kms-providers.md#std-label-qe-fundamentals-kms-providers-aws) provider for CMK management.

## Example

These examples allow you to rapidly evaluate client-side field level encryption. For specific examples using each supported KMS (Key Management Service) provider, see [Encryption Key Management.](https://www.mongodb.com/docs/manual/core/csfle/fundamentals/manage-keys.md#std-label-field-level-encryption-data-key-manage)

1. Start mongosh

   Start the `mongosh` client.

   ```bash
   mongosh --nodb
   ```

2. Generate Your Key

   To configure client-side field level encryption for a locally managed key, generate a base64-encoded 96-byte string with no line breaks.

   ```javascript
   const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
   ```

3. Create the Client-Side Field Level Encryption Options

   Create the client-side field level encryption options using the generated local key string:

   ```javascript
    let autoEncryptionOpts = {
      "keyVaultNamespace" : "encryption.__dataKeys",
      "kmsProviders" : {
        "local" : {
          "key" : BinData(0, TEST_LOCAL_KEY)
        }
      }
    }
   ```

4. Create Your Encrypted Client

   Use the [`Mongo()`](https://www.mongodb.com/docs/manual/reference/method/mongo.md#mongodb-method-Mongo) constructor with the client-side field level encryption options configured to create a database connection. Replace the `mongodb://myMongo.example.net` URI with the [connection string URI](https://www.mongodb.com/docs/manual/reference/connection-string.md#std-label-mongodb-uri) of the target cluster.

   ```javascript
   encryptedClient = Mongo(
     "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
      autoEncryptionOpts
   )
   ```

Retrieve the [`KeyVault`](https://www.mongodb.com/docs/manual/reference/method/getkeyvault.md#mongodb-method-getKeyVault) object and use the [`KeyVault.rewrapManyDataKey()`](https://www.mongodb.com/docs/manual/reference/method/keyvault.rewrapmanydatakey.md#mongodb-method-KeyVault.rewrapManyDataKey) method to rewrap the existing keys in a new `masterKey`. If no new `masterKey` is given, each data key retains its respective current `masterKey`.

### Rewrap Data Keys with the Current masterKey

The following example shows how you can rewrap each data key with its respective current `masterKey`:

```javascript
let keyVault = mongo.getKeyVault()

keyVault.rewrapManyDataKey()
```

### Rewrap Data Keys with a New masterKey

The following example shows how you can rewrap each data key with a new `masterKey`:

```javascript
let keyVault = mongo.getKeyVault()

keyVault.rewrapManyDataKey({}, {
  provider: 'aws',
  masterKey: {
    region: 'us-east-2',
    key: 'arn:aws:kms:us-east-2:...'
  }
})
```

### Rewrap Data Keys That Have Not Been Rewrapped Recently

The following example shows how to rewrap data keys that have not been rewrapped in the previous thirty days.

```javascript
let keyVault = mongo.getKeyVault()

const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

keyVault.rewrapManyDataKey({ updateDate: { $lt: thirtyDaysAgo } });
```

### Output

[`KeyVault.rewrapManyDataKey()`](https://www.mongodb.com/docs/manual/reference/method/keyvault.rewrapmanydatakey.md#mongodb-method-KeyVault.rewrapManyDataKey) returns a `BulkWriteResult` object detailing how many data keys were affected:

```json
{
  bulkWriteResult: BulkWriteResult {
    result: {
      ok: 1,
      writeErrors: [],
      writeConcernErrors: [],
      insertedIds: [],
      nInserted: 0,
      nUpserted: 0,
      nMatched: 3,
      nModified: 3,
      nRemoved: 0,
      upserted: [],
      opTime: { ts: Timestamp({ t: 1655840760, i: 3 }), t: 23 }
    }
  }
}
```