Class ClientEncryption

Create a new encryption instance

Example

new ClientEncryption(mongoClient, {
  keyVaultNamespace: 'client.encryption',
  kmsProviders: {
    local: {
      key: masterKey // The master key used for encryption/decryption. A 96-byte long Buffer
    }
  }
});
Copy

Example

new ClientEncryption(mongoClient, {
  keyVaultNamespace: 'client.encryption',
  kmsProviders: {
    aws: {
      accessKeyId: AWS_ACCESS_KEY,
      secretAccessKey: AWS_SECRET_KEY
    }
  }
});
Copy

Adds a keyAltName to a key identified by the provided _id.

This method resolves to/returns the old key value (prior to adding the new altKeyName).

Example

// adding an keyAltName to a data key
const id = new Binary();  // id is a bson binary subtype 4 object
const keyAltName = 'keyAltName';
const oldKey = await clientEncryption.addKeyAltName(id, keyAltName);
if (!oldKey) {
 // null is returned if there is no matching document with an id matching the supplied id
}
Copy

Creates a data key used for explicit encryption and inserts it into the key vault namespace

Example

// Using async/await to create a local key
const dataKeyId = await clientEncryption.createDataKey('local');
Copy

Example

// Using async/await to create an aws key
const dataKeyId = await clientEncryption.createDataKey('aws', {
  masterKey: {
    region: 'us-east-1',
    key: 'xxxxxxxxxxxxxx' // CMK ARN here
  }
});
Copy

Example

// Using async/await to create an aws key with a keyAltName
const dataKeyId = await clientEncryption.createDataKey('aws', {
  masterKey: {
    region: 'us-east-1',
    key: 'xxxxxxxxxxxxxx' // CMK ARN here
  },
  keyAltNames: [ 'mySpecialKey' ]
});
Copy

A convenience method for creating an encrypted collection. This method will create data keys for any encryptedFields that do not have a keyId defined and then create a new collection with the full set of encryptedFields.

Throws

MongoCryptCreateDataKeyError - If part way through the process a createDataKey invocation fails, an error will be rejected that has the partial encryptedFields that were created.

Throws

MongoCryptCreateEncryptedCollectionError - If creating the collection fails, an error will be rejected that has the entire encryptedFields that were created.

Explicitly decrypt a provided encrypted value

Example

// Decrypting value with async/await API
async function decryptMyValue(value) {
  return clientEncryption.decrypt(value);
}
Copy

Deletes the key with the provided id from the keyvault, if it exists.

Example

// delete a key by _id
const id = new Binary(); // id is a bson binary subtype 4 object
const { deletedCount } = await clientEncryption.deleteKey(id);

if (deletedCount != null && deletedCount > 0) {
  // successful deletion
}
Copy

Explicitly encrypt a provided value. Note that either options.keyId or options.keyAltName must be specified. Specifying both options.keyId and options.keyAltName is considered an error.

Example

// Encryption with async/await api
async function encryptMyData(value) {
  const keyId = await clientEncryption.createDataKey('local');
  return clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
}
Copy

Example

// Encryption using a keyAltName
async function encryptMyData(value) {
  await clientEncryption.createDataKey('local', { keyAltNames: 'mySpecialKey' });
  return clientEncryption.encrypt(value, { keyAltName: 'mySpecialKey', algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' });
}
Copy

Encrypts a Match Expression or Aggregate Expression to query a range index.

Only supported when queryType is "rangePreview" and algorithm is "RangePreview".

The Range algorithm is experimental only. It is not intended for production use. It is subject to breaking changes.

Finds a key in the keyvault with the specified _id.

Returns a promise that either resolves to a DataKey if a document matches the key or null if no documents match the id. The promise rejects with an error if an error is thrown.

Example

// getting a key by id
const id = new Binary(); // id is a bson binary subtype 4 object
const key = await clientEncryption.getKey(id);
if (!key) {
 // key is null if there was no matching key
}
Copy

Finds a key in the keyvault which has the specified keyAltName.

Example

// get a key by alt name
const keyAltName = 'keyAltName';
const key = await clientEncryption.getKeyByAltName(keyAltName);
if (!key) {
 // key is null if there is no matching key
}
Copy

Finds all the keys currently stored in the keyvault.

This method will not throw.

Example

// fetching all keys
const keys = await clientEncryption.getKeys().toArray();
Copy

Adds a keyAltName to a key identified by the provided _id.

This method resolves to/returns the old key value (prior to removing the new altKeyName).

If the removed keyAltName is the last keyAltName for that key, the altKeyNames property is unset from the document.

Example

// removing a key alt name from a data key
const id = new Binary();  // id is a bson binary subtype 4 object
const keyAltName = 'keyAltName';
const oldKey = await clientEncryption.removeKeyAltName(id, keyAltName);

if (!oldKey) {
 // null is returned if there is no matching document with an id matching the supplied id
}
Copy

Searches the keyvault for any data keys matching the provided filter. If there are matches, rewrapManyDataKey then attempts to re-wrap the data keys using the provided options.

If no matches are found, then no bulk write is performed.

Example

// rewrapping all data data keys (using a filter that matches all documents)
const filter = {};

const result = await clientEncryption.rewrapManyDataKey(filter);
if (result.bulkWriteResult != null) {
 // keys were re-wrapped, results will be available in the bulkWrite object.
}
Copy

Example

// attempting to rewrap all data keys with no matches
const filter = { _id: new Binary() } // assume _id matches no documents in the database
const result = await clientEncryption.rewrapManyDataKey(filter);

if (result.bulkWriteResult == null) {
 // no keys matched, `bulkWriteResult` does not exist on the result object
}
Copy