Node.js MongoDB Driver API

Source: node_modules/mongodb-client-encryption/lib/autoEncrypter.js

  1. 'use strict';
  3. module.exports = function(modules) {
  4.   const mc = require('bindings')('mongocrypt');
  5.   const common = require('./common');
  6.   const databaseNamespace = common.databaseNamespace;
  7.   const StateMachine = modules.stateMachine.StateMachine;
  8.   const MongocryptdManager = require('./mongocryptdManager').MongocryptdManager;
  9.   const MongoClient = modules.mongodb.MongoClient;
  10.   const MongoError = modules.mongodb.MongoError;
  11.   const cryptoCallbacks = require('./cryptoCallbacks');
  13.   /**
  14.    * Configuration options for a automatic client encryption.
  15.    *
  16.    * @typedef {Object} AutoEncrypter~AutoEncryptionOptions
  17.    * @property {MongoClient} [keyVaultClient] A `MongoClient` used to fetch keys from a key vault
  18.    * @property {string} [keyVaultNamespace] The namespace where keys are stored in the key vault
  19.    * @property {KMSProviders} [kmsProviders] Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
  20.    * @property {object} [schemaMap] A map of namespaces to a local JSON schema for encryption
  21.    * @property {boolean} [bypassAutoEncryption] Allows the user to bypass auto encryption, maintaining implicit decryption
  22.    * @property {AutoEncrypter~logger} [options.logger] An optional hook to catch logging messages from the underlying encryption engine
  23.    * @property {AutoEncrypter~AutoEncryptionExtraOptions} [extraOptions] Extra options related to the mongocryptd process
  24.    */
  26.   /**
  27.    * Extra options related to the mongocryptd process
  28.    * @typedef {object} AutoEncrypter~AutoEncryptionExtraOptions
  29.    * @property {string} [mongocryptdURI] 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
  30.    * @property {boolean} [mongocryptdBypassSpawn=false] If true, autoEncryption will not attempt to spawn a mongocryptd before connecting
  31.    * @property {string} [mongocryptdSpawnPath] The path to the mongocryptd executable on the system
  32.    * @property {string[]} [mongocryptdSpawnArgs] Command line arguments to use when auto-spawning a mongocryptd
  33.    */
  35.   /**
  36.    * @callback AutoEncrypter~logger
  37.    * @description A callback that is invoked with logging information from
  38.    * the underlying C++ Bindings.
  39.    * @param {AutoEncrypter~logLevel} level The level of logging.
  40.    * @param {string} message The message to log
  41.    */
  43.   /**
  44.    * @name AutoEncrypter~logLevel
  45.    * @enum {number}
  46.    * @description
  47.    * The level of severity of the log message
  48.    *
  49.    * | Value | Level |
  50.    * |-------|-------|
  51.    * | 0 | Fatal Error |
  52.    * | 1 | Error |
  53.    * | 2 | Warning |
  54.    * | 3 | Info |
  55.    * | 4 | Trace |
  56.    */
  58.   /**
  59.    * @classdesc An internal class to be used by the driver for auto encryption
  60.    * **NOTE**: Not meant to be instantiated directly, this is for internal use only.
  61.    */
  62.   class AutoEncrypter {
  63.     /**
  64.      * Create an AutoEncrypter
  65.      *
  66.      * **Note**: Do not instantiate this class directly. Rather, supply the relevant options to a MongoClient
  67.      *
  68.      * **Note**: Supplying `options.schemaMap` provides more security than relying on JSON Schemas obtained from the server.
  69.      * It protects against a malicious server advertising a false JSON Schema, which could trick the client into sending unencrypted data that should be encrypted.
  70.      * Schemas supplied in the schemaMap only apply to configuring automatic encryption for client side encryption.
  71.      * Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.
  72.      * @param {MongoClient} client The client autoEncryption is enabled on
  73.      * @param {AutoEncrypter~AutoEncryptionOptions} [options] Optional settings
  74.      *
  75.      * @example
  76.      * // Enabling autoEncryption via a MongoClient
  77.      * const { MongoClient } = require('mongodb');
  78.      * const client = new MongoClient(URL, {
  79.      *   autoEncryption: {
  80.      *     kmsProviders: {
  81.      *       aws: {
  82.      *         accessKeyId: AWS_ACCESS_KEY,
  83.      *         secretAccessKey: AWS_SECRET_KEY
  84.      *       }
  85.      *     }
  86.      *   }
  87.      * });
  88.      *
  89.      * await client.connect();
  90.      * // From here on, the client will be encrypting / decrypting automatically
  91.      */
  92.     constructor(client, options) {
  93.       this._client = client;
  94.       this._bson = options.bson || client.topology.bson;
  95.       this._mongocryptdManager = new MongocryptdManager(options.extraOptions);
  96.       this._mongocryptdClient = new MongoClient(this._mongocryptdManager.uri, {
  97.         useNewUrlParser: true,
  98.         useUnifiedTopology: true,
  99.         serverSelectionTimeoutMS: 1000
  100.       });
  101.       this._keyVaultNamespace = options.keyVaultNamespace || 'admin.datakeys';
  102.       this._keyVaultClient = options.keyVaultClient || client;
  103.       this._bypassEncryption =
  104.         typeof options.bypassAutoEncryption === 'boolean' ? options.bypassAutoEncryption : false;
  106.       const mongoCryptOptions = {};
  107.       if (options.schemaMap) {
  108.         mongoCryptOptions.schemaMap = Buffer.isBuffer(options.schemaMap)
  109.           ? options.schemaMap
  110.           : this._bson.serialize(options.schemaMap);
  111.       }
  113.       if (options.kmsProviders) {
  114.         mongoCryptOptions.kmsProviders = options.kmsProviders;
  115.       }
  117.       if (options.logger) {
  118.         mongoCryptOptions.logger = options.logger;
  119.       }
  121.       Object.assign(mongoCryptOptions, { cryptoCallbacks });
  122.       this._mongocrypt = new mc.MongoCrypt(mongoCryptOptions);
  123.       this._contextCounter = 0;
  124.     }
  126.     /**
  127.      * @ignore
  128.      * @param {Function} callback Invoked when the mongocryptd client either successfully connects or errors
  129.      */
  130.     init(callback) {
  131.       const _callback = (err, res) => {
  132.         if (err && err.message && err.message.match(/timed out after/)) {
  133.           callback(
  134.             new MongoError(
  135.               'Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn'
  136.             )
  137.           );
  138.           return;
  139.         }
  141.         callback(err, res);
  142.       };
  144.       if (this._mongocryptdManager.bypassSpawn) {
  145.         return this._mongocryptdClient.connect(_callback);
  146.       }
  148.       this._mongocryptdManager.spawn(() => this._mongocryptdClient.connect(_callback));
  149.     }
  151.     /**
  152.      * @ignore
  153.      * @param {Function} callback Invoked when the mongocryptd client either successfully disconnects or errors
  154.      */
  155.     teardown(force, callback) {
  156.       this._mongocryptdClient.close(force, callback);
  157.     }
  159.     /**
  160.      * @ignore
  161.      * Encrypt a command for a given namespace.
  162.      *
  163.      * @param {string} ns The namespace for this encryption context
  164.      * @param {object} cmd The command to encrypt
  165.      * @param {Function} callback
  166.      */
  167.     encrypt(ns, cmd, options, callback) {
  168.       if (typeof ns !== 'string') {
  169.         throw new TypeError('Parameter `ns` must be a string');
  170.       }
  172.       if (typeof cmd !== 'object') {
  173.         throw new TypeError('Parameter `cmd` must be an object');
  174.       }
  176.       if (typeof options === 'function' && callback == null) {
  177.         callback = options;
  178.         options = {};
  179.       }
  181.       // If `bypassAutoEncryption` has been specified, don't encrypt
  182.       if (this._bypassEncryption) {
  183.         callback(undefined, cmd);
  184.         return;
  185.       }
  187.       const bson = this._bson;
  188.       const commandBuffer = Buffer.isBuffer(cmd) ? cmd : bson.serialize(cmd, options);
  190.       let context;
  191.       try {
  192.         context = this._mongocrypt.makeEncryptionContext(databaseNamespace(ns), commandBuffer);
  193.       } catch (err) {
  194.         callback(err, null);
  195.         return;
  196.       }
  198.       // TODO: should these be accessors from the addon?
  199.       context.id = this._contextCounter++;
  200.       context.ns = ns;
  201.       context.document = cmd;
  203.       const stateMachine = new StateMachine(Object.assign({ bson }, options));
  204.       stateMachine.execute(this, context, callback);
  205.     }
  207.     /**
  208.      * @ignore
  209.      * Decrypt a command response
  210.      *
  211.      * @param {Buffer} buffer
  212.      * @param {Function} callback
  213.      */
  214.     decrypt(response, options, callback) {
  215.       if (typeof options === 'function' && callback == null) {
  216.         callback = options;
  217.         options = {};
  218.       }
  220.       const bson = this._bson;
  221.       const buffer = Buffer.isBuffer(response) ? response : bson.serialize(response, options);
  223.       let context;
  224.       try {
  225.         context = this._mongocrypt.makeDecryptionContext(buffer);
  226.       } catch (err) {
  227.         callback(err, null);
  228.         return;
  229.       }
  231.       // TODO: should this be an accessor from the addon?
  232.       context.id = this._contextCounter++;
  234.       const stateMachine = new StateMachine(Object.assign({ bson }, options));
  235.       stateMachine.execute(this, context, callback);
  236.     }
  237.   }
  239.   return { AutoEncrypter };
  240. };