Docs Menu
Docs Home
/
MongoDB Manual
/
Security
/
Encryption
/
In-Use Encryption
/
Queryable Encryption
/
Tutorials
/
Enable

Create a Customer Master Key

On this page

  • Overview
  • Before You Start
  • Procedure
  • Next Steps

Overview

In this guide, you will learn how to generate a Customer Master Key in your Key Management System of choice. Generate a Customer Master Key before creating your Queryable Encryption-enabled application.

Tip

Customer Master Keys

To learn more about the Customer Master Key, see Encryption Keys and Key Vaults

Before You Start

Complete the preceding tasks before continuing:

  1. Install a Queryable Encryption compatible driver and dependencies

  2. Install and configure a Queryable Encryption library

Procedure

Select the tab for your key provider below.

1

Create the Customer Master Key

1

Log in to your AWS Management Console.

2

Navigate to the AWS KMS Console.

3

Create your Customer Master Key

Create a new symmetric key by following the official AWS documentation on Creating symmetric KMS keys. The key you create is your Customer Master Key. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration of your CMK.

In the Usage Permissions step of the key generation process, apply the following default key policy that enables Identity and Access Management (IAM) policies to grant access to your Customer Master Key:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Enable IAM User Permissions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<ARN of your AWS account principal>"
      },
      "Action": "kms:*",
      "Resource": "*"
    }
  ]
}

Important

Record the Amazon Resource Name (ARN) and Region of your Customer Master Key. You will use these in later steps of this guide.

Tip

Key Policies

To learn more about key policies, see Key Policies in AWS KMS in the official AWS documentation.

2

Create an AWS IAM User

1

Navigate to the AWS IAM Console.

2

Create an IAM User

Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. You will use this IAM user as a service account for your Queryable Encryption-enabled application. Your application authenticates with AWS KMS using the IAM user to encrypt and decrypt your Data Encryption Keys (DEKs) with your Customer Master Key (CMK).

Important

Record your Credentials

Ensure you record the following IAM credentials in the final step of creating your IAM user:

  • access key ID

  • secret access key

You have one opportunity to record these credentials. If you do not record these credentials during this step, you must create another IAM user.

3

Grant Permissions

Grant your IAM user kms:Encrypt and kms:Decrypt permissions for your remote master key.

Important

The new client IAM user should not have administrative permissions for the master key. To keep your data secure, follow the principle of least privilege.

The following inline policy allows an IAM user to encrypt and decrypt with the Customer Master Key with the least privileges possible:

Note

Remote Master Key ARN

The following policy requires the ARN of the key you generate in the Create the Master Key step of this guide.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt", "kms:Encrypt"],
      "Resource": "<the Amazon Resource Name (ARN) of your remote master key>"
    }
  ]
}

To apply the preceding policy to your IAM user, follow the Adding IAM identity permissions guide in the AWS documentation.

Important

Authenticate with IAM Roles in Production

When deploying your Queryable Encryption-enabled application to a production environment, authenticate your application by using an IAM role instead of an IAM user.

To learn more about IAM roles, see the following pages in the official AWS documentation:

1

Register your Application with Azure

1

Log in to Azure.

2

Register your Application with Azure Active Directory

To register an application on Azure Active Directory, follow Microsoft's official Register an application with the Microsoft identity platform Quick Start.

Important

Record your Credentials

Ensure you record the following credentials:

  • Tenant ID

  • Client ID

  • Client secret

You will need them to construct your kmsProviders object later in this tutorial.

Important

Record your Credentials

Ensure you record the following credentials:

  • Tenant ID

  • Client ID

  • Client secret

You will need them to construct your kmsProviders object later in this tutorial.

Important

Record your Credentials

Ensure you record the following credentials:

  • Tenant ID

  • Client ID

  • Client secret

You will need them to construct your kmsProviders object later in this tutorial.

Important

Record your Credentials

Ensure you record the following credentials:

  • tenant id

  • client id

  • client secret

Unless you are running your client within an Azure Virtual Machine, you will need these credentials to construct your kmsProviders object later in this tutorial.

Important

Record your Credentials

Ensure you record the following credentials:

  • Tenant ID

  • Client ID

  • Client secret

You will need them to construct your kmsProviders object later in this tutorial.

Important

Record your Credentials

Ensure you record the following credentials:

  • Tenant ID

  • Client ID

  • Client secret

You will need them to construct your kmsProviders object later in this tutorial.

2

Create the Customer Master Key

1

Create your Azure Key Vault and Customer Master Key

To create a new Azure Key Vault instance and Customer Master Key, follow Microsoft's official Set and retrieve a key from Azure Key Vault using the Azure portal Quick Start.

Important

Record your Credentials

Ensure you record the following credentials:

  • Key Name

  • Key Identifier (referred to as keyVaultEndpoint later in this guide)

  • Key Version

You will need them to construct your dataKeyOpts object later in this tutorial.

2

Grant Permissions

Grant your client application wrap and unwrap permissions to the key.

1

Register a GCP Service Account

1

Register or log in to your existing account on Google Cloud.

2

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.

3

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.

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.

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.

Important

When creating your service account key, you receive a one-time download of the private key information. Unless you are using an attached service account, make sure to download this file in either the PKCS12 or JSON format for use later in this tutorial.

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.

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.

2

Create a GCP Customer Master Key

1

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

Configure your KMIP-Compliant Key Provider

To connect a MongoDB driver client to your KMIP-compliant key provider, you must configure your KMIP-compliant key provider such that it accepts your client's TLS certificate.

Consult the documentation for your KMIP-compliant key provider for information on how to accept your client certificate.

2

Specify your Certificates

Your client must connect to your KMIP-compliant key provider through TLS and present a client certificate that your KMIP-compliant key provider accepts:

const tlsOptions = {
  kmip: {
    tlsCAFile: process.env["KMIP_TLS_CA_FILE"], // Path to your TLS CA file
    tlsCertificateKeyFile: process.env["KMIP_TLS_CERT_FILE"], // Path to your TLS certificate key file
  },
};
var tlsOptions = new Dictionary<string, SslSettings>();
var sslSettings = new SslSettings();
var clientCertificate = new X509Certificate2(_appSettings["Kmip:TlsCertP12"]!); // Full path to your client certificate p12 file
sslSettings.ClientCertificates = new[] { clientCertificate };
tlsOptions.Add("kmip", sslSettings);

Important

Your client certificate must be in pcks12 format. You can convert your certificate using OpenSSL with the following command:

openssl pcks12 -export -out "<new pcks12 certificate>" -in "<certificate to convert>" \
-name "<new certificate name>" -password "<new certificate password>"
tlsOpts := map[string]interface{}{
	"tlsCertificateKeyFile": os.Getenv("KMIP_TLS_CERT_ECDSA_FILE"), // Path to your client certificate file
	"tlsCAFile":             os.Getenv("KMIP_TLS_CA_ECDSA_FILE"),   // Path to your KMIP certificate authority file
}
kmipConfig, err := options.BuildTLSConfig(tlsOpts)
if err != nil {
	panic(fmt.Sprintf("Unable to retrieve certificates from your environment: %s\n", err))
}
tlsConfig := map[string]*tls.Config{
	"kmip": kmipConfig,
}

Important

You must use certificates with ECDSA keys when using the Go driver with PyKMIP.

Configure the following virtual machine options to specify the keystore and truststore that contain your KMIP TLS certificates and add them to the command that you use to start your Java application:

-Djavax.net.ssl.enabled=true
-Djavax.net.ssl.keyStoreType=pkcs12
-Djavax.net.ssl.keyStore=REPLACE-WITH-PATH-TO-PKC-KEYSTORE
-Djavax.net.ssl.keyStorePassword=REPLACE-WITH-KEYSTORE-PASSWORD
-Djavax.net.ssl.trustStoreType=jks
-Djavax.net.ssl.trustStore=REPLACE-WITH-PATH-TO-TRUSTSTORE
-Djavax.net.ssl.trustStorePassword=REPLACE-WITH-TRUSTSTORE-PASSWORD

Note

Configure Client With SSLContext

If you would rather configure your client application using an SSL context, use the kmsProviderSslContextMap method.

const tlsOptions = {
  kmip: {
    tlsCAFile: process.env.KMIP_TLS_CA_FILE, // Path to your TLS CA file
    tlsCertificateKeyFile: process.env.KMIP_TLS_CERT_FILE, // Path to your TLS certificate key file
  },
};
tls_options = {
    "kmip": {
        "tlsCAFile": os.environ['KMIP_TLS_CA_FILE'], # Path to your TLS CA file
        "tlsCertificateKeyFile": os.environ['KMIP_TLS_CERT_FILE'] # Path to your TLS certificate key file
    }
}

Next Steps

After installing drivers and dependencies and creating a Customer Master Key, you can create your Queryable Encryption enabled application.

Back

Install a Library