Use Automatic Client-Side Field Level Encryption with GCP
On this page
- Overview
- Before You Get Started
- Set Up the KMS
- Register a GCP Service Account
- Create a GCP Customer Master Key
- Create the Application
- Create a Unique Index on your Key Vault collection
- Create a Data Encryption Key
- Configure the MongoClient
- Insert a Document with Encrypted Fields
- Retrieve Your Encrypted Document
- Learn More
Overview
This guide shows you how to build a Client-Side Field Level Encryption (CSFLE)-enabled application using Google Cloud Key Management Service.
After you complete the steps in this guide, you should have:
A CMK hosted on Google Cloud Key Management Service.
A client application that inserts encrypted documents using your CMK.
Before You Get Started
To complete and run the code in this guide, you need to set up your development environment as shown in the Installation Requirements page.
Throughout this guide, code examples use placeholder text. Before you run the examples, substitute your own values for these placeholders.
For example:
dek_id := "<Your Base64 DEK ID>"
You would replace everything between quotes with your DEK ID.
dek_id := "abc123"
Select the programming language for which you want to see code examples for from the Select your language dropdown menu on the right side of the page.
Tip
See: Full Application
To view the complete runnable application code for this tutorial, go to the following link:
Set Up the KMS
Register a GCP Service Account
Register or log into your existing account on Google Cloud.
Create a service account for your project
To create a service account on Google Cloud, follow the Creating a service account guide in Google's official documentation.
Add a service account key
To add a service account key on Google Cloud, follow the Managing service account keys guide in Google's official documentation.
Important
When creating your service account key, you receive a one-time download of the private key information. Make sure to download this file in either the PKCS12 or JSON format for use later in this tutorial.
Create a GCP Customer Master Key
Create a new Customer Master Key
Create a key ring and a symmetric key by following the Create a key guide from Google's official documentation.
This key is your Customer Master Key (CMK).
Record the following details of your CMK for use in a future step of this tutorial.
Field | Required | Description |
---|---|---|
key_name | Yes | Identifier for the CMK. |
key_ring | Yes | Identifier for the group of keys your key belongs to. |
key_version | No | The version of the named key. |
location | Yes | Region specified for your key. |
endpoint | No | The host and optional port of the Google Cloud KMS.
The default value is cloudkms.googleapis.com . |
Create the Application
Select the tab that corresponds to the MongoDB driver you are using in your application to see relevant code samples.
Create a Data Encryption Key
Add your GCP KMS Credentials
Add the service account credentials to your CSFLE-enabled client code.
Tip
You saved a file containing your service account key credentials in the Create a GCP Service Account step of this guide.
If you downloaded your credentials in JSON format, you can
use the following command to extract the value of your private
key, substituting <credentials-filename>
with the name of
your credentials file:
cat <credentials-filename> | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64
If you downloaded your credentials in PKCS12 format, you need to
specify your GCP service account import password and to add a
PEM pass phrase to access the key when accessing it using the
following command, substituting <credentials-filename>
with
the name of your credentials file:
openssl pkcs12 -info -in <credentials-filename>
Tip
Learn More
To learn more about the KMS provider object for GCP, see Google Cloud Platform KMS.
Add Your Key Information
Update the following code to specify your Customer Master Key:
Tip
You recorded your Customer Master Key details in the in the Create a Customer Master Key step of this guide.
Tip
Learn More
To view a diagram showing how your client application creates your Data Encryption Key when using an Google Cloud Key Management Service, see Architecture.
To learn more about the options for creating a Data Encryption Key encrypted with a Customer Master Key hosted in Azure Key Vault, see kmsProviders Object and dataKeyOpts Object.
Tip
See: Complete Code
Configure the MongoClient
Create an Encryption Schema For Your Collection
Tip
Add Your Data Encryption Key Base64 ID
Make sure to update the following code to include your Base64 DEK ID. You received this value in the Generate your Data Encryption Key step of this guide.
Insert a Document with Encrypted Fields
Use your CSFLE-enabled
MongoClient
instance to insert an encrypted document into the
medicalRecords.patients
namespace using the following code
snippet:
When you insert a document, your CSFLE-enabled client encrypts the fields of your document such that it resembles the following:
{ "_id": { "$oid": "<_id of your document>" }, "name": "Jon Doe", "ssn": { "$binary": "<cipher-text>", "$type": "6" }, "bloodType": { "$binary": "<cipher-text>", "$type": "6" }, "medicalRecords": { "$binary": "<cipher-text>", "$type": "6" }, "insurance": { "provider": "MaestCare", "policyNumber": { "$binary": "<cipher-text>", "$type": "6" } } }
Tip
See: Complete Code
Retrieve Your Encrypted Document
Retrieve the encrypted document you inserted in the Insert a Document with Encrypted Fields step of this guide.
To show the functionality of CSFLE, the following code snippet queries for your document with a client configured for automatic CSFLE as well as a client that is not configured for automatic CSFLE.
The output of the preceding code snippet should look like this:
Finding a document with regular (non-encrypted) client. { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e7910c20697e5f4fa95710aafc9153f0a3dc769c8a132a604b468732ff1f4d8349ded3244b59cbfb41444a210f28b21ea1b6c737508d9d30e8baa30c1d8070c4d5e26", "hex"), 6), bloodType: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79022e238536dfd8caadb4d7751ac940e0f195addd7e5c67b61022d02faa90283ab69e02303c7e4001d1996128428bf037dea8bbf59fbb20c583cbcff2bf3e2519b4", "hex"), 6), 'key-id': 'demo-data-key', medicalRecords: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e790405163a3207cff175455106f57eef14e5610c49a99bcbd14a7db9c5284e45e3ee30c149354015f941440bf54725d6492fb3b8704bc7c411cff6c868e4e13c58233c3d5ed9593eca4e4d027d76d3705b6d1f3b3c9e2ceee195fd944b553eb27eee69e5e67c338f146f8445995664980bf0", "hex"), 6), insurance: { policyNumber: new Binary(Buffer.from("0217482732d8014cdd9ffdd6e2966e5e79108decd85c05be3fec099e015f9d26d9234605dc959cc1a19b63072f7ffda99db38c7b487de0572a03b2139ac3ee163bcc40c8508f366ce92a5dd36e38b3c742f7", "hex"), 6), provider: 'MaestCare' } } Finding a document with encrypted client, searching on an encrypted field { _id: new ObjectId("629a452e0861b3130887103a"), name: 'Jon Doe', ssn: 241014209, bloodType: 'AB+', 'key-id': 'demo-data-key', medicalRecords: [ { weight: 180, bloodPressure: '120/80' } ], insurance: { policyNumber: 123142, provider: 'MaestCare' } }
Tip
See: Complete Code
Learn More
To learn more about the topics mentioned in this guide, see the following links:
Learn more about CSFLE components on the Reference page.
Learn how Customer Master Keys and Data Encryption Keys work on the Keys and Key Vaults page
See how KMS Providers manage your CSFLE keys on the CSFLE KMS Providers page.