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._metaDataClient = options.metadataClient || client;
  104.       this._bypassEncryption =
  105.         typeof options.bypassAutoEncryption === 'boolean' ? options.bypassAutoEncryption : false;
  107.       const mongoCryptOptions = {};
  108.       if (options.schemaMap) {
  109.         mongoCryptOptions.schemaMap = Buffer.isBuffer(options.schemaMap)
  110.           ? options.schemaMap
  111.           : this._bson.serialize(options.schemaMap);
  112.       }
  114.       if (options.kmsProviders) {
  115.         mongoCryptOptions.kmsProviders = !Buffer.isBuffer(options.kmsProviders)
  116.           ? this._bson.serialize(options.kmsProviders)
  117.           : options.kmsProviders;
  118.       }
  120.       if (options.logger) {
  121.         mongoCryptOptions.logger = options.logger;
  122.       }
  124.       Object.assign(mongoCryptOptions, { cryptoCallbacks });
  125.       this._mongocrypt = new mc.MongoCrypt(mongoCryptOptions);
  126.       this._contextCounter = 0;
  127.     }
  129.     /**
  130.      * @ignore
  131.      * @param {Function} callback Invoked when the mongocryptd client either successfully connects or errors
  132.      */
  133.     init(callback) {
  134.       const _callback = (err, res) => {
  135.         if (
  136.           err &&
  137.           err.message &&
  138.           (err.message.match(/timed out after/) || err.message.match(/ENOTFOUND/))
  139.         ) {
  140.           callback(
  141.             new MongoError(
  142.               'Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn'
  143.             )
  144.           );
  145.           return;
  146.         }
  148.         callback(err, res);
  149.       };
  151.       if (this._mongocryptdManager.bypassSpawn) {
  152.         return this._mongocryptdClient.connect(_callback);
  153.       }
  155.       this._mongocryptdManager.spawn(() => this._mongocryptdClient.connect(_callback));
  156.     }
  158.     /**
  159.      * @ignore
  160.      * @param {Function} callback Invoked when the mongocryptd client either successfully disconnects or errors
  161.      */
  162.     teardown(force, callback) {
  163.       this._mongocryptdClient.close(force, callback);
  164.     }
  166.     /**
  167.      * @ignore
  168.      * Encrypt a command for a given namespace.
  169.      *
  170.      * @param {string} ns The namespace for this encryption context
  171.      * @param {object} cmd The command to encrypt
  172.      * @param {Function} callback
  173.      */
  174.     encrypt(ns, cmd, options, callback) {
  175.       if (typeof ns !== 'string') {
  176.         throw new TypeError('Parameter `ns` must be a string');
  177.       }
  179.       if (typeof cmd !== 'object') {
  180.         throw new TypeError('Parameter `cmd` must be an object');
  181.       }
  183.       if (typeof options === 'function' && callback == null) {
  184.         callback = options;
  185.         options = {};
  186.       }
  188.       // If `bypassAutoEncryption` has been specified, don't encrypt
  189.       if (this._bypassEncryption) {
  190.         callback(undefined, cmd);
  191.         return;
  192.       }
  194.       const bson = this._bson;
  195.       const commandBuffer = Buffer.isBuffer(cmd) ? cmd : bson.serialize(cmd, options);
  197.       let context;
  198.       try {
  199.         context = this._mongocrypt.makeEncryptionContext(databaseNamespace(ns), commandBuffer);
  200.       } catch (err) {
  201.         callback(err, null);
  202.         return;
  203.       }
  205.       // TODO: should these be accessors from the addon?
  206.       context.id = this._contextCounter++;
  207.       context.ns = ns;
  208.       context.document = cmd;
  210.       const stateMachine = new StateMachine(Object.assign({ bson }, options));
  211.       stateMachine.execute(this, context, callback);
  212.     }
  214.     /**
  215.      * @ignore
  216.      * Decrypt a command response
  217.      *
  218.      * @param {Buffer} buffer
  219.      * @param {Function} callback
  220.      */
  221.     decrypt(response, options, callback) {
  222.       if (typeof options === 'function' && callback == null) {
  223.         callback = options;
  224.         options = {};
  225.       }
  227.       const bson = this._bson;
  228.       const buffer = Buffer.isBuffer(response) ? response : bson.serialize(response, options);
  230.       let context;
  231.       try {
  232.         context = this._mongocrypt.makeDecryptionContext(buffer);
  233.       } catch (err) {
  234.         callback(err, null);
  235.         return;
  236.       }
  238.       // TODO: should this be an accessor from the addon?
  239.       context.id = this._contextCounter++;
  241.       const stateMachine = new StateMachine(Object.assign({ bson }, options));
  242.       stateMachine.execute(this, context, callback);
  243.     }
  244.   }
  246.   return { AutoEncrypter };
  247. };