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

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

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

  • ~AutoEncryptionExtraOptions

  • ~logger

new AutoEncrypter(client, [options])

Param	Type	Default	Description
client	MongoClient		The client autoEncryption is enabled on
[options]	object		Optional settings
[options.keyVaultNamespace]	string	"'admin.dataKeys'"	The namespace of the key vault, used to store encryption keys
[options.schemaMap]	object		A local specification of a JSON schema used for encryption
[options.kmsProviders]	KMSProviders		options for specific KMS providers to use
[options.logger]	function		An optional hook to catch logging messages from the underlying encryption engine
[options.extraOptions]	AutoEncryptionExtraOptions		Extra options related to mongocryptd

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~AutoEncryptionExtraOptions

Properties

Name	Type	Default	Description
[mongocryptdURI]	string		overrides the uri used to connect to mongocryptd
[mongocryptdBypassSpawn]	boolean	false	if true, autoEncryption will not spawn a mongocryptd
[mongocryptdSpawnPath]	string		the path to the mongocryptd executable
[mongocryptdSpawnArgs]	Array.<string>		command line arguments to pass to the mongocryptd executable

AutoEncrypter~logger

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

Param	Type	Description
level	logLevel	The level of logging. Valid values are 0 (Fatal Error), 1 (Error), 2 (Warning), 3 (Info), 4 (Trace)
message	string	The message to log

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

    • ~dataKey

    • ~createDataKeyCallback

    • ~encryptCallback

    • ~decryptCallback

new ClientEncryption(client, options)

Param	Type	Description
client	MongoClient	The client used for encryption
options	object	Optional settings
options.keyVaultNamespace	string	The namespace of the key vault, used to store encryption keys
[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' or 'local'
[options]	object	Options for creating the data key
[options.masterKey]	object	Idenfities a new KMS-specific key used to encrypt the new data key. If the kmsProvider is "aws" it is required.
[options.masterKey.region]	string	The AWS region of the KMS
[options.masterKey.key]	string	The Amazon Resource Name (ARN) to the AWS customer master key (CMK)
[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

Returns: Promise | void - If no callback is provided, returns a Promise that either resolves with the created data key, or rejects with an error. If a callback is provided, returns nothing.
Example

// Using callbacks to create a local key
clientEncrypion.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 dataKey = await clientEncryption.createDataKey('local');

Example

// Using async/await to create an aws key
const dataKey = 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 dataKey = 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.dataKey]	dataKey	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.dataKey or options.keyAltName must be specified. Specifying both options.dataKey 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, dataKey) => {
    if (err) {
      return callback(err);
    }
    clientEncryption.encrypt(value, { dataKey, algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' }, callback);
  });
}

Example

// Encryption with async/await api
async function encryptMyData(value) {
  const dataKey = await clientEncryption.createDataKey('local');
  return clientEncryption.encrypt(value, { dataKey, 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	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~dataKey

A key used for manual encryption / decryption. Is a BSON Binary object.

ClientEncryption~createDataKeyCallback

Param	Type	Description
[error]	Error	If present, indicates an error that occurred in the creation of the data key
[dataKey]	dataKey	If present, returns the new 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	An AWS Access Key
[aws.secretAccessKey]	string	An AWS Secret Key
[local]	object	Configuration options for using 'local' as your KMS provider
[local.key]	Buffer	A 96-byte long Buffer used for local encryption

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

Changelog

v0.3.1

• e60f3ef NODE: incorporate documentation feedback
• d07b509 NODE: docs: document the public API of the node bindings
• 3f00866 NODE: test(cryptoHooks): test error handling of random hooks
• b0b3255 NODE: fix(cryptoHooks): propagate random hook error
• 2ea51d8 NODE: fix(crypyoHooks): make crypto hooks work in Node 4
• 3f962b7 NODE: feat(node12): add node 12 and election support
• 5cc47c1 NODE: chore(osx): target node 10.12
• 0e63dfa NODE: chore(osx): fix build on osx in evergreen
• d00d757 NODE: fix typo
• 1c2b5d6 NODE: format: minor formatting changes
• d8932a2 NODE: real v0.3.0 with proper prebuild-install command