Create a new encryption instance
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
}
}
});
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).
The id of the document to update.
a keyAltName to search for a key
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
// 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' ]
});
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.
A Node.js driver Db object with which to create the collection
The name of the collection to be created
Options for createDataKey and for createCollection
Optional
mastercreated collection and generated encryptedFields
MongoCryptCreateDataKeyError - If part way through the process a createDataKey invocation fails, an error will be rejected that has the partial encryptedFields
that were created.
MongoCryptCreateEncryptedCollectionError - If creating the collection fails, an error will be rejected that has the entire encryptedFields
that were created.
Deletes the key with the provided id from the keyvault, if it exists.
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.
The value that you wish to serialize. Must be of a type that can be serialized into BSON
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".
a BSON document of one of the following forms:
{$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]}
{$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}]}
$gt
may also be $gte
. $lt
may also be $lte
.
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.
Finds a key in the keyvault which has the specified keyAltName.
a keyAltName to search for a key
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.
Finds all the keys currently stored in the keyvault.
This method will not throw.
a FindCursor over all keys in the keyvault.
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.
The id of the document to update.
a keyAltName to search for a key
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.
// 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
}
The public interface for explicit in-use encryption