(DOCSP-18745) Node CSFLE fundementals (#277)

* (DOCSP-18745) Node CSFLE fundementals

Co-authored-by: Neal Beeken <[email protected]>

Author: zach-carr

source/fundamentals.txt

@@ -18,6 +18,7 @@ Fundamentals
    /fundamentals/logging
    /fundamentals/monitoring
    /fundamentals/gridfs
+   /fundamentals/csfle
    /fundamentals/time-series
    /fundamentals/typescript
    /fundamentals/utf8-validation

source/fundamentals/csfle.txt

@@ -0,0 +1,220 @@
+==================================
+Client-Side Field Level Encryption
+==================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to install and use **Client-Side Field
+Level Encryption (CSFLE)** in the MongoDB Node.js driver.
+
+CSFLE allows you to encrypt specific data fields within a document with
+your MongoDB client application before sending the data to the server.
+Starting in MongoDB 4.2 Enterprise, you can perform this client-side 
+encryption automatically.
+
+With CSFLE, your client application encrypts fields client-side without 
+requiring any server-side configuration or directives. CSFLE is useful 
+for situations in which applications must guarantee that unauthorized 
+parties, including server administrators, cannot read the encrypted 
+data.
+
+This guide is a quick introduction to CSFLE using the Node.js driver. 
+For in-depth information on how CSFLE works, see
+the :manual:`CSFLE reference </core/security-client-side-encryption/>` 
+documentation. For a real-world scenario and implementation, see our 
+`CSFLE Guide <https://docs.mongodb.com/drivers/security/client-side-field-level-encryption-guide>`_.
+
+Installation
+------------
+
+To get started with CSFLE in your client application, you need:
+
+- the MongoDB Node.js driver
+- `mongodb-client-encryption <https://www.npmjs.com/package/mongodb-client-encryption>`__
+- ``mongocryptd`` if using automatic encryption (Enterprise or Atlas)
+
+``mongodb-client-encryption``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``mongodb-client-encryption`` module is the official client 
+encryption module for the MongoDB Node.js driver. It contains bindings 
+to communicate with the native library that manages the encryption.
+
+Add it to your project using ``npm``:
+
+.. code-block:: sh
+   :copyable: true
+
+   npm install mongodb-client-encryption --save
+
+``mongocryptd``
+~~~~~~~~~~~~~~~
+
+``mongocryptd`` is launched automatically by the package, and it is used for 
+automatic encryption. ``mongocryptd`` communicates with 
+``mongodb-client-encryption`` to automatically encrypt the information 
+specified by a user-provided 
+:manual:`JSON Schema </reference/security-client-side-automatic-json-schema/>`.
+
+For more detailed information on ``mongocryptd``, see the
+:manual:`mongocryptd reference documentation </reference/security-client-side-encryption-appendix/#mongocryptd>`
+
+Example
+-------
+
+The following example shows how to configure a CSFLE-enabled client 
+with a local key and a JSON schema. Values in the ``ssn`` field are 
+automatically encrypted before insertion, and decrypted when calling 
+``find()`` with a CSFLE-enabled client.
+
+.. warning::
+
+   MongoDB recommends using local key management only for testing 
+   purposes, and using a remote key management service
+   for production.
+
+An expanded example with support for remote key management services is 
+available at MongoDB University's GitHub 
+`Node CSFLE Example <https://github.com/mongodb-university/csfle-guides/tree/master/nodejs>`__.
+
+.. note::
+   
+   Auto encryption requires MongoDB **Enterprise** or **Atlas**.
+
+To run this example, first complete the following steps:
+
+- Save `master-key.txt <https://github.com/mongodb-university/csfle-guides/raw/master/nodejs/master-key.txt>`__
+  to the same directory as this example code.
+- Start a ``mongod`` locally on the default port 27017.
+- Start a ``mongocryptd`` locally on the default port 27020.
+
+.. code-block:: javascript
+  
+   const { MongoClient, Binary } = require("mongodb");
+   const { ClientEncryption } = require("mongodb-client-encryption");
+   const fs = require("fs/promises");
+   
+   async function getRegularClient() {
+     const client = new MongoClient("mongodb://localhost:27017");
+     return await client.connect();
+   }
+   
+   async function getCsfleEnabledClient(schemaMap) {
+     const client = new MongoClient("mongodb://localhost:27017", {
+       autoEncryption: {
+         keyVaultNamespace: "encryption.__keyVault",
+         kmsProviders: {
+           local: {
+             key: await fs.readFile("./master-key.txt"),
+           },
+         },
+         schemaMap,
+       },
+     });
+     return await client.connect();
+   }
+   
+   function createJsonSchemaMap(dataKey) {
+     return {
+       "users.ssns": {
+         bsonType: "object",
+         encryptMetadata: {
+           keyId: [new Binary(Buffer.from(dataKey, "base64"), 4)],
+         },
+         properties: {
+           ssn: {
+             encrypt: {
+               bsonType: "int",
+               algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
+             },
+           },
+         },
+       },
+     };
+   }
+   
+   async function makeDataKey(client) {
+     const encryption = new ClientEncryption(client, {
+       keyVaultNamespace: "encryption.__keyVault",
+       kmsProviders: {
+         local: {
+           key: await fs.readFile("./master-key.txt"),
+         },
+       },
+     });
+     
+     let dataKey = await encryption.createDataKey("local", {
+       masterKey: null,
+     });
+     
+     return dataKey.toString("base64");
+   }
+   
+   async function run(regularClient, csfleClient) {
+     try {
+   
+       regularClient = await getRegularClient();
+   
+       let dataKey = await makeDataKey(regularClient);
+       console.log(
+         "New dataKey created for this run:\n",
+         dataKey
+       );
+   
+       const schemaMap = createJsonSchemaMap(dataKey);
+       
+       csfleClient = await getCsfleEnabledClient(schemaMap);
+   
+       const regularClientSsnsColl = regularClient
+         .db("users")
+         .collection("ssns");
+       const csfleClientSsnsColl = csfleClient
+         .db("users")
+         .collection("ssns");
+   
+       const exampleDocument = {
+         name: "Jon Doe",
+         ssn: 241014209,
+       };
+   
+       await csfleClientSsnsColl.updateOne(
+         { ssn: exampleDocument.ssn },
+         { $set: exampleDocument },
+         { upsert: true }
+       );
+   
+       const csfleFindResult = await csfleClientSsnsColl.findOne({
+         ssn: exampleDocument.ssn,
+       });
+       console.log(
+         "Document retrieved with csfle enabled client:\n",
+         csfleFindResult
+       );
+   
+       const regularFindResult = await regularClientSsnsColl.findOne({
+         name: "Jon Doe",
+       });
+       console.log(
+         "Document retrieved with regular client:\n", 
+         regularFindResult
+       );
+   
+     } finally {
+       if (regularClient) await regularClient.close();
+       if (csfleClient) await csfleClient.close();
+     }
+   }
+   
+   run().catch(error => {
+     console.dir(error);
+     process.exit(1);
+   });

source/includes/fundamentals-sections.rst

@@ -13,7 +13,7 @@ Fundamentals section:
 - :doc:`Log Events in the Driver </fundamentals/logging>`
 - :doc:`Monitor Driver Events </fundamentals/monitoring>`
 - :doc:`Store and Retrieve Large Files in MongoDB </fundamentals/gridfs>`
+- :doc:`Encrypt Fields from the Client </fundamentals/csfle>`
 - :doc:`Create and Query Time Series Collection </fundamentals/time-series>`
 - :doc:`Specify Type Parameters with TypeScript </fundamentals/typescript>`
 - :doc:`Specify UTF-8 Validation Settings </fundamentals/utf8-validation>`
-