Class ClientEncryption

The public interface for explicit in-use encryption

Constructors

  • Create a new encryption instance

    Parameters

    Returns ClientEncryption

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

Accessors

Methods

  • 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).

    Parameters

    • _id: Binary

      The id of the document to update.

    • keyAltName: string

      a keyAltName to search for a key

    Returns Promise<null | WithId<DataKey>>

    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.

    // 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
    }
  • Creates a data key used for explicit encryption and inserts it into the key vault namespace

    Parameters

    Returns Promise<UUID>

    // Using async/await to create a local key
    const dataKeyId = await clientEncryption.createDataKey('local');
    // Using async/await to create an aws key
    const dataKeyId = await clientEncryption.createDataKey('aws', {
    masterKey: {
    region: 'us-east-1',
    key: 'xxxxxxxxxxxxxx' // CMK ARN here
    }
    });
    // 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' ]
    });
  • Explicitly decrypt a provided encrypted value

    Type Parameters

    • T = any

    Parameters

    • value: Binary

      An encrypted value

    Returns Promise<T>

    a Promise that either resolves with the decrypted value, or rejects with an error

    // Decrypting value with async/await API
    async function decryptMyValue(value) {
    return clientEncryption.decrypt(value);
    }
  • Deletes the key with the provided id from the keyvault, if it exists.

    Parameters

    Returns Promise<DeleteResult>

    // 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
    }
  • 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.

    Parameters

    Returns Promise<Binary>

    a Promise that either resolves with the encrypted value, or rejects with an error.

    // 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' });
    }
    // 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' });
    }
  • Encrypts a Match Expression or Aggregate Expression to query a range index.

    Only supported when queryType is "range" and algorithm is "Range".

    Parameters

    • expression: Document

      a BSON document of one of the following forms:

      1. A Match Expression of this form: {$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}
      2. An Aggregate Expression of this form: {$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]}

      $gt may also be $gte. $lt may also be $lte.

    • options: ClientEncryptionEncryptOptions

    Returns Promise<Binary>

    Returns a Promise that either resolves with the encrypted value or rejects with an error.

  • 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.

    Parameters

    Returns Promise<null | DataKey>

    // 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
    }
  • Finds a key in the keyvault which has the specified keyAltName.

    Parameters

    • keyAltName: string

      a keyAltName to search for a key

    Returns Promise<null | WithId<DataKey>>

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

    // 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
    }
  • 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.

    Parameters

    • _id: Binary

      The id of the document to update.

    • keyAltName: string

      a keyAltName to search for a key

    Returns Promise<null | WithId<DataKey>>

    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.

    // 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
    }
  • 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.

    Returns Promise<{
        bulkWriteResult?: BulkWriteResult;
    }>

    // 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.
    }
    // 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
    }