Class: ClientEncryption

ClientEncryption

The public interface for explicit client side encryption

Create a new encryption instance

Name Type Description
client MongoClient

The client used for encryption

options object

Additional settings

Name Type Description
keyVaultNamespace string

The namespace of the key vault, used to store encryption keys

keyVaultClient MongoClient optional

A MongoClient used to fetch keys from a key vault. Defaults to client

kmsProviders KMSProviders optional

options for specific KMS providers to use

Examples

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}

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

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}

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

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.

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

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