Create a Customer Master Key
On this page
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:
Procedure
Select the tab for your key provider below.
Create the Customer Master Key
Log in to your AWS Management Console.
Navigate to the AWS KMS Console.
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
Navigate to the AWS IAM Console.
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.
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:
Register your Application with Azure
Log in to Azure.
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.
Create the Customer Master Key
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.
Register a GCP Service Account
Register or log in to 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.
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
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);
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.