mongodb-client-encryption

MongoDB Client Encryption

The Node.js wrapper for libmongocrypt

Requirements

Follow the instructions for building libmongocrypt here.

Installation

Now you can install mongodb-client-encryption with the following:

npm install mongodb-client-encryption

Testing

Run the test suite using:

npm test

Documentation

Classes

AutoEncrypter

An internal class to be used by the driver for auto encryption NOTE: Not meant to be instantiated directly, this is for internal use only.

ClientEncryption

The public interface for explicit client side encryption

MongoCryptError

An error indicating that something went wrong specifically with MongoDB Client Encryption

Typedefs

KMSProviders : object

Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.

AWSEncryptionKeyOptions : object

Configuration options for making an AWS encryption key

GCPEncryptionKeyOptions : object

Configuration options for making a GCP encryption key

AzureEncryptionKeyOptions : object

Configuration options for making an Azure encryption key

AutoEncrypter

An internal class to be used by the driver for auto encryption NOTE: Not meant to be instantiated directly, this is for internal use only.

• AutoEncrypter

  • new AutoEncrypter(client, [options])

  • ~logLevel

  • ~AutoEncryptionOptions

  • ~AutoEncryptionExtraOptions

  • ~logger

new AutoEncrypter(client, [options])

Param	Type	Description
client	MongoClient	The client autoEncryption is enabled on
[options]	AutoEncryptionOptions	Optional settings

Create an AutoEncrypter

Note: Do not instantiate this class directly. Rather, supply the relevant options to a MongoClient

Note: Supplying options.schemaMap provides more security than relying on JSON Schemas obtained from the server. It protects against a malicious server advertising a false JSON Schema, which could trick the client into sending unencrypted data that should be encrypted. Schemas supplied in the schemaMap only apply to configuring automatic encryption for client side encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.

Example

// Enabling autoEncryption via a MongoClient
const { MongoClient } = require('mongodb');
const client = new MongoClient(URL, {
  autoEncryption: {
    kmsProviders: {
      aws: {
        accessKeyId: AWS_ACCESS_KEY,
        secretAccessKey: AWS_SECRET_KEY
      }
    }
  }
});

await client.connect();
// From here on, the client will be encrypting / decrypting automatically

AutoEncrypter~logLevel

The level of severity of the log message

Value	Level
0	Fatal Error
1	Error
2	Warning
3	Info
4	Trace

AutoEncrypter~AutoEncryptionOptions

Properties

Name	Type	Description
[keyVaultClient]	MongoClient	A MongoClient used to fetch keys from a key vault
[keyVaultNamespace]	string	The namespace where keys are stored in the key vault
[kmsProviders]	KMSProviders	Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
[schemaMap]	object	A map of namespaces to a local JSON schema for encryption
[bypassAutoEncryption]	boolean	Allows the user to bypass auto encryption, maintaining implicit decryption
[options.logger]	logger	An optional hook to catch logging messages from the underlying encryption engine
[extraOptions]	AutoEncryptionExtraOptions	Extra options related to the mongocryptd process

Configuration options for a automatic client encryption.

AutoEncrypter~AutoEncryptionExtraOptions

Properties

Name	Type	Default	Description
[mongocryptdURI]	string		A local process the driver communicates with to determine how to encrypt values in a command. Defaults to "mongodb://%2Fvar%2Fmongocryptd.sock" if domain sockets are available or "mongodb://localhost:27020" otherwise
[mongocryptdBypassSpawn]	boolean	false	If true, autoEncryption will not attempt to spawn a mongocryptd before connecting
[mongocryptdSpawnPath]	string		The path to the mongocryptd executable on the system
[mongocryptdSpawnArgs]	Array.<string>		Command line arguments to use when auto-spawning a mongocryptd

Extra options related to the mongocryptd process

AutoEncrypter~logger

Param	Type	Description
level	logLevel	The level of logging.
message	string	The message to log

A callback that is invoked with logging information from the underlying C++ Bindings.

ClientEncryption

The public interface for explicit client side encryption

• ClientEncryption

  • new ClientEncryption(client, options)

  • instance

    • .createDataKey(provider, [options], [callback])

    • .encrypt(value, options, [callback])

    • .decrypt(value, callback)

  • inner

    • ~dataKeyId

    • ~createDataKeyCallback

    • ~encryptCallback

    • ~decryptCallback

new ClientEncryption(client, options)

Param	Type	Description
client	MongoClient	The client used for encryption
options	object	Additional settings
options.keyVaultNamespace	string	The namespace of the key vault, used to store encryption keys
options.tlsOptions	object	An object that maps KMS provider names to TLS options.
[options.keyVaultClient]	MongoClient	A MongoClient used to fetch keys from a key vault. Defaults to client
[options.kmsProviders]	KMSProviders	options for specific KMS providers to use

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

Example

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

clientEncryption.createDataKey(provider, [options], [callback])

Param	Type	Description
provider	string	The KMS provider used for this data key. Must be 'aws', 'azure', 'gcp', or 'local'
[options]	object	Options for creating the data key
[options.masterKey]	AWSEncryptionKeyOptions | AzureEncryptionKeyOptions | GCPEncryptionKeyOptions	Idenfities a new KMS-specific key used to encrypt the new data key
[options.keyAltNames]	Array.<string>	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]	createDataKeyCallback	Optional callback to invoke when key is created

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

Returns: Promise | void - If 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. Example

// Using callbacks to create a local key
clientEncryption.createDataKey('local', (err, dataKey) => {
  if (err) {
    // This means creating the key failed.
  } else {
    // key creation succeeded
  }
});

Example

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

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

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

clientEncryption.encrypt(value, options, [callback])

Param	Type	Description
value	*	The value that you wish to serialize. Must be of a type that can be serialized into BSON
options	object
[options.keyId]	dataKeyId	The id of the Binary dataKey to use for encryption
[options.keyAltName]	string	A unique string name corresponding to an already existing dataKey.
options.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]	encryptCallback	Optional callback to invoke when value is encrypted

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.

Returns: Promise | void - If 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. Example

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

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

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

clientEncryption.decrypt(value, callback)

Param	Type	Description
value	Buffer | Binary	An encrypted value
callback	decryptCallback	Optional callback to invoke when value is decrypted

Explicitly decrypt a provided encrypted value

Returns: Promise | void - If 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. Example

// Decrypting value with callback API
function decryptMyValue(value, callback) {
  clientEncryption.decrypt(value, callback);
}

Example

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

ClientEncryption~dataKeyId

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.

ClientEncryption~createDataKeyCallback

Param	Type	Description
[error]	Error	If present, indicates an error that occurred in the creation of the data key
[dataKeyId]	dataKeyId	If present, returns the id of the created data key

ClientEncryption~encryptCallback

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

ClientEncryption~decryptCallback

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

MongoCryptError

An error indicating that something went wrong specifically with MongoDB Client Encryption

KMSProviders

Properties

Name	Type	Description
[aws]	object	Configuration options for using 'aws' as your KMS provider
[aws.accessKeyId]	string	The access key used for the AWS KMS provider
[aws.secretAccessKey]	string	The secret access key used for the AWS KMS provider
[local]	object	Configuration options for using 'local' as your KMS provider
[local.key]	Buffer	The master key used to encrypt/decrypt data keys. A 96-byte long Buffer.
[azure]	object	Configuration options for using 'azure' as your KMS provider
[azure.tenantId]	string	The tenant ID identifies the organization for the account
[azure.clientId]	string	The client ID to authenticate a registered application
[azure.clientSecret]	string	The client secret to authenticate a registered application
[azure.identityPlatformEndpoint]	string	If present, a host with optional port. E.g. "example.com" or "example.com:443". This is optional, and only needed if customer is using a non-commercial Azure instance (e.g. a government or China account, which use different URLs). Defaults to "login.microsoftonline.com"
[gcp]	object	Configuration options for using 'gcp' as your KMS provider
[gcp.email]	string	The service account email to authenticate
[gcp.privateKey]	string | Binary	A PKCS#8 encrypted key. This can either be a base64 string or a binary representation
[gcp.endpoint]	string	If present, a host with optional port. E.g. "example.com" or "example.com:443". Defaults to "oauth2.googleapis.com"

Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.

AWSEncryptionKeyOptions

Properties

Name	Type	Description
region	string	The AWS region of the KMS
key	string	The Amazon Resource Name (ARN) to the AWS customer master key (CMK)
[endpoint]	string	An alternate host to send KMS requests to. May include port number

Configuration options for making an AWS encryption key

GCPEncryptionKeyOptions

Properties

Name	Type	Description
projectId	string	GCP project id
location	string	Location name (e.g. "global")
keyRing	string	Key ring name
keyName	string	Key name
[keyVersion]	string	Key version
[endpoint]	string	KMS URL, defaults to https://www.googleapis.com/auth/cloudkms

Configuration options for making a GCP encryption key

AzureEncryptionKeyOptions

Properties

Name	Type	Description
keyName	string	Key name
keyVaultEndpoint	string	Key vault URL, typically <name>.vault.azure.net
[keyVersion]	string	Key version

Configuration options for making an Azure encryption key

Changelog

2.2.0-alpha.1 (2022-06-01)

• 50fba9e fix: add missing import in Node.js bindings TS definitions (#353)
• f2c401b fix(NODE-4279): handle decrypted nested documents well with devtools decoration (#350)
• 3fbd57d [MONGOCRYPT-434] Rename "csfle" to "crypt_shared" (#352)
• 8a07c72 test(NODE-4254): use majority write concern (#348)
• 5b13ce2 test(NODE-4254): use majority write concern (#347)
• d1c222f chore(NODE-4236): use latest node driver (#345)
• 8105956 fix(NODE-4254): allow csfle to be dynamically required (#342)
• 0e8749a feat(NODE-4241): add support for rewrapManyDataKey and keyMaterial (#334)
• 2e8903f fix(NODE-4242): do not run mongocryptd if bypassQueryAnalysis (#335)
• 006f326 feat(NODE-4220): add FLE2 explicit encryption API (#327)