Create a Customer Master Key

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.

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:

   • IAM roles

   • When to create an IAM role (instead of a user)

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.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   Python

   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.

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.

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.

   MongoDB Shell

   C#

   Go

   Java (Sync)

   Node.js

   Python

   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.

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.

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.

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

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,
}

-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

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