This guide shows you how to implement automatic Client-Side Field Level Encryption (CSFLE) using supported MongoDB drivers and is intended for full-stack developers. The guide presents the following information in the context of a real-world scenario.

Once you complete the steps in this guide, you should have:

• an understanding of how client-side field level encryption works and in what situations it is practical
• a working client application that demonstrates automatic CSFLE
• resources on how to move the sample client application to production

• MongoDB Atlas 4.2+
• MongoDB Node driver 3.6.2+
• The libmongocrypt library installed
• The mongocryptd binary installed

1. Clone this repository and navigate to the nodejs directory.

   git clone https://github.com/mongodb-university/csfle-guides.git
   cd nodejs

   Work from the nodejs directory for the remainder of these instructions.

2. Start a locally running mongod instance (Enterprise version >= 4.2) running on port 27017

3. Install the dependencies in package.json

   npm install

4. Make sure you have the master-key.txt file in the root of your execution environment. This is a 96-byte cryptographically-secure generated master encryption key required to run this example project. To generate your own master key or use a KMS, refer to the CSFLE Use Case Guide.

5. Run the make-data-key.js script to make a data key. If there is an existing data key in the encryption.__keyVault collection this script will not create a duplicate data key.

   node make-data-key.js

   This outputs a base64 encoded string of the UUID of your newly created data key. Paste this into clients.js where you see this line

   let dataKey = null // change this!

6. Run the clients.js script to insert a document with the CSFLE-enabled client and then read that document with it as well as a regular client. You will see that the CSFLE-enabled client prints the document out in plaintext, and the regular client prints the document out with encrypted fields in binary format. This is safe to run multiple times as the insert operation used is an update with upsert specified.

   node clients.js

7. Suggestion: Try inserting a document with the regular client. What happens?

1. Change directories to the docker directory.

cd docker

2. Build Docker image with a tag name. Within this directory execute:

   • For using the latest driver version:

     docker build . -t mdb-csfle-example

   This will build a Docker image with a tag name mdb-csfle-example.

3. Run the Docker image by executing:

   docker run -tih csfle mdb-csfle-example

   The command above will run a Docker image with tag mdb-csfle-example and provide it with csfle as its hostname.

4. Once you're inside the Docker container, you could follow below steps to run the NodeJS code example.

$ export MONGODB_URL="mongodb+srv://USER:[email protected]/dbname?retryWrites=true&w=majority"`
$ node ./example.js

If you're connecting to MongoDB Atlas please make sure to Configure Whitelist Entries

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Joe Karlsson