Client-Side Field Level Encryption

On this page

Overview

Installation
Example

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 CSFLE reference documentation. For a real-world scenario and implementation, see our CSFLE Guide.

Installation

To get started with CSFLE in your client application, you need:

the MongoDB Node.js driver
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:

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

For more detailed information on mongocryptd, see the mongocryptd reference documentation

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.

Note

Auto encryption requires MongoDB Enterprise or Atlas.

To run this example, first complete the following steps:

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

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);
});

← GridFS Time Series →