Class: 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

}

}

});

Methods

createDataKey(provider, options, callback){Promise|void}

node_modules/mongodb-client-encryption/lib/clientEncryption.js, line 167

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

Name	Type	Description
provider	string	The KMS provider used for this data key. Must be 'aws', 'azure', 'gcp', or 'local'
options	object	optional Options for creating the data key Name Type Description masterKey AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions optional Idenfities a new KMS-specific key used to encrypt the new data key keyAltNames Array.<string> optional An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by _id.
callback	ClientEncryption~createDataKeyCallback	optional Optional callback to invoke when key is created

Returns:

no callback is provided, returns a Promise that either resolves with the id of the created data key, or rejects with an error. If a callback is provided, returns nothing.

Examples

// Using callbacks to create a local key

clientEncryption.createDataKey('local', (err, dataKey) => {

if (err) {

// This means creating the key failed.

} else {

// key creation succeeded

}

});

// 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' ]

});

decrypt(value, callback){Promise|void}

node_modules/mongodb-client-encryption/lib/clientEncryption.js, line 333

Explicitly decrypt a provided encrypted value

Name	Type	Description
value	Buffer	An encrypted value
callback	ClientEncryption~decryptCallback	Optional callback to invoke when value is decrypted

Returns:

no callback is provided, returns a Promise that either resolves with the decryped value, or rejects with an error. If a callback is provided, returns nothing.

Examples

// Decrypting value with callback API

function decryptMyValue(value, callback) {

clientEncryption.decrypt(value, callback);

}

// Decrypting value with async/await API

async function decryptMyValue(value) {

return clientEncryption.decrypt(value);

}

encrypt(value, options, callback){Promise|void}

node_modules/mongodb-client-encryption/lib/clientEncryption.js, line 271

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.

Name	Type	Description
value	*	The value that you wish to serialize. Must be of a type that can be serialized into BSON
options	object	Name Type Description keyId ClientEncryption~dataKeyId optional The id of the Binary dataKey to use for encryption keyAltName string optional A unique string name corresponding to an already existing dataKey. algorithm The algorithm to use for encryption. Must be either 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' or AEAD_AES_256_CBC_HMAC_SHA_512-Random'
callback	ClientEncryption~encryptCallback	optional Optional callback to invoke when value is encrypted

Returns:

no callback is provided, returns a Promise that either resolves with the encrypted value, or rejects with an error. If a callback is provided, returns nothing.

Examples

// Encryption with callback API

function encryptMyData(value, callback) {

clientEncryption.createDataKey('local', (err, keyId) => {

if (err) {

return callback(err);

}

clientEncryption.encrypt(value, { keyId, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);

});

}

// 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' });

}

Type Definitions

createDataKeyCallback(error, dataKeyId)

node_modules/mongodb-client-encryption/lib/clientEncryption.js, line 92

Name	Type	Description
error	Error	optional If present, indicates an error that occurred in the creation of the data key
dataKeyId	ClientEncryption~dataKeyId	optional If present, returns the id of the created data key

dataKeyIdBinary

The id of an existing dataKey. Is a bson Binary value.
Can be used for ClientEncryption.encrypt, and can be used to directly
query for the data key itself against the key vault namespace.

decryptCallback(err, result)

node_modules/mongodb-client-encryption/lib/clientEncryption.js, line 308

Name	Type	Description
err	Error	optional If present, indicates an error that occurred in the process of decryption
result	object	optional If present, is the decrypted result

encryptCallback(err, result)

node_modules/mongodb-client-encryption/lib/clientEncryption.js, line 228

Name	Type	Description
err	Error	optional If present, indicates an error that occurred in the process of encryption
result	Buffer	optional If present, is the encrypted result