mongodb-client-encryption
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.7 • Public • Published

    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.

    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

    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.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 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

    Keywords

    none

    Install

    npm i mongodb-client-encryption

    DownloadsWeekly Downloads

    29,970

    Version

    1.2.7

    License

    Apache-2.0

    Unpacked Size

    132 kB

    Total Files

    15

    Last publish

    Collaborators

    • mbroadst
    • durran
    • nbbeeken
    • kmahar
    • dariakp