Use customer-managed encryption keys (CMEK)

This page describes how to perform tasks related to customer-managed encryption keys (CMEK) for Cloud Firestore with MongoDB compatibility. For more information about CMEK in general, including when and why to enable it, see the Cloud KMS documentation.

Prepare your CMEK keys

Before you can create a CMEK-protected Cloud Firestore with MongoDB compatibility database, you must complete the following steps:

  1. Request access to the Cloud Firestore with MongoDB compatibility CMEK feature.
  2. Create (or retrieve) a Cloud Firestore with MongoDB compatibility service agent.
  3. Create a CMEK key.
  4. Configure IAM settings for that key.

Complete these steps for each project that will contain CMEK-protected Cloud Firestore with MongoDB compatibility databases. If you later create a new CMEK key, you must configure IAM settings for that key.

Request access

Before you create a Cloud Firestore with MongoDB compatibility service agent, request access to the CMEK feature by filling in the access request form.

Create a Cloud Firestore with MongoDB compatibility service agent

Before you create a CMEK key, you must have a Cloud Firestore with MongoDB compatibility service agent, which is a type of Google-managed service account that Cloud Firestore with MongoDB compatibility uses to access the key.

Run the services identity create command to create the service agent that Cloud Firestore with MongoDB compatibility uses to access the CMEK key on your behalf. This command creates the service account if it does not already exist, then displays it.

gcloud beta services identity create \
    --service=firestore.googleapis.com \
    --project FIRESTORE_PROJECT

Replace FIRESTORE_PROJECT with the project you plan to use for your Cloud Firestore with MongoDB compatibility databases.

The command displays the service agent ID, which is formatted like an email address. Record the output email string, because you'll use it in a later step.

Service identity created:
service-xxx@gcp-sa-firestore.

Create a key

You can use a key created directly in Cloud KMS or an externally managed key that you make available with Cloud External Key Manager.

The Cloud KMS key location must be the same as the location of the Cloud Firestore with MongoDB compatibility database that it will be used with.

  • For regional database locations, use the same location name for key ring, key, and database because the location names have a one-to-one mapping.

    For example, if you want to create a CMEK-protected database in us-west1, create a key ring and key in us-west1.

  • For multi-region database locations, use the location name of the KMS multi-region location:

    • Use the Cloud KMS us multi-region location for the Cloud Firestore with MongoDB compatibility nam5 multi-region location.

    • Use the Cloud KMS europe multi-region location for the Cloud Firestore with MongoDB compatibility eur3 multi-region location.

In the Google Cloud project where you want to manage your keys, complete the following:

  1. Enable the Cloud KMS API.

  2. Create a key ring and a key using one of the following options:

Configure IAM settings for the key

Console

To grant an Cloud KMS role to your service agent, do the following. You are also able to grant permission at the key or key-ring level if you want lower granularity.

  1. In the Google Cloud console, go to the IAM page.

    Go to the IAM page

  2. Click Add.

  3. Enter the email-formatted ID for your Cloud Firestore with MongoDB compatibility service agent.

  4. Select the Cloud KMS CryptoKey Encrypter/Decrypter role.

  5. Click Save.

gcloud

Grant the cloudkms.cryptoKeyEncrypterDecrypter role to your service agent:

gcloud kms keys add-iam-policy-binding KMS_KEY \
--keyring KMS_KEYRING\
--location KMS_LOCATION \
--member serviceAccount:SERVICE_AGENT_EMAIL \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--project KMS_PROJECT

Replace the following:

  • KMS_KEY with the name that you assigned to the key
  • KMS_KEYRING with the KMS key ring that contains the key
  • KMS_LOCATION with the region that contains the key ring
  • SERVICE_AGENT_EMAIL with the email-formatted identifier for the service agent that you are granting access to
  • KMS_PROJECT with the project that contains the key

The terminal should display a response similar to the following:

Updated IAM policy for key KMS_KEY.
bindings:
- members:
- serviceAccount:
service-{project-number}@gcp-sa-firestore.
role: roles/cloudkms.cryptoKeyEncrypterDecrypter

Create a CMEK-enabled database

After your CMEK keys are created and configured, you can create a CMEK-protected database. Existing Cloud Firestore with MongoDB compatibility databases that are protected by Google default encryption can't be converted to use CMEK.

You can choose an encryption type and key only when you create a CMEK-enabled database.

Console

  1. In the Google Cloud console, go to the Databases page.

    Go to the Databases page

  2. Click Create a Firestore Database.

  3. Enter a database ID.

  4. Select Enterprise Edition.

  5. Select a location for your database.

  6. Click Show Encryption Options, and then select Cloud KMS key.

  7. Select or enter the resource name for the CMEK key that you want to use for the database.

  8. The list of keys is limited to the current Google Cloud project and the database location that you selected. To use a key from a different Google Cloud project, click Switch Project or Enter Key Manually.

  9. If you are prompted to grant key permission to the Cloud Firestore with MongoDB compatibility service account, click Grant. To create a CMEK database, your Cloud Firestore with MongoDB compatibility service account must be granted the cloudkms.cryptoKeyEncrypterDecrypter role.

  10. Select security rules for mobile and web clients.

  11. Click Create Database.

After the database is created, you can verify that the database is CMEK-enabled by viewing Database details:

  • If your database is protected by CMEK, the Encryption type field shows as Customer-managed and the Encryption key field lists the corresponding Cloud KMS and the key version that is used to protect this database.
  • If your database is not protected by CMEK, the Encryption type field shows as Google-managed.

gcloud

Before you create a CMEK-enabled database with Google Cloud CLI, install the latest version and authorize the gcloud CLI. For more information, see Install the gcloud CLI.

gcloud firestore databases create \
    --location=FIRESTORE_DATABASE_LOCATION \
    --database=DATABASE_ID \
    --edition=enterprise \
    --kms-key-name=KMS_KEY_NAME \
    --project=FIRESTORE_PROJECT

Replace the following:

  • FIRESTORE_DATABASE_LOCATION with the location for the database
  • DATABASE_ID with an ID for the database

  • KMS_KEY_NAME with the name you assigned to the key. Use the full resource name for the key in the following format:

    projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID

  • FIRESTORE_PROJECT with the project to use for your Cloud Firestore with MongoDB compatibility database

Access a CMEK-protected database

All the read, write, and query operations sent to a CMEK-protected database should function the same as with a Google default encrypted database. For example, you don't need to provide a key for each request.

Restore a CMEK-protected database

Before you restore CMEK-protected database from a backup:

  • Decide if you want to restore the database to CMEK encryption, to