Use customer-managed encryption keys (CMEK)

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 Firestore 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.iam.gserviceaccount.com
role: roles/cloudkms.cryptoKeyEncrypterDecrypter

Console

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

   Go to the Databases page

2. Click Create Database.

3. Select your database mode. Click Continue.

4. On the Configure your database page, enter a database ID.

5. Select a location.

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 Firestore service account, click Grant. To create a CMEK database, your Firestore service account must be granted the cloudkms.cryptoKeyEncrypterDecrypter role.

10. Select security rules for mobile and web clients.

11. Click Create Database.

Once 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 \
      --kms-key-name=KMS_KEY_NAME \
      --project=FIRESTORE_PROJECT

Replace the following:

• FIRESTORE_DATABASE_LOCATION with the Firestore 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 Firestore database

REST API

HTTP request:

POST https://firestore.googleapis.com/v1/projects/{FIRESOTRE_PROJECT}/databases

In the request body configure CMEK in the cmek_config.kms_key_name field.

Set to the full resource ID of a Cloud KMS key. Only a key in the same location as this database is allowed.

This value should be the Cloud KMS key resource ID in the format of projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}

For more details for other fields, see the database create page.

Example request:

curl -X POST 'https://firestore.googleapis.com/v1/projects/FIRESTORE_PROJECT/databases?databaseId={DATABASE_ID}' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-d '{
  "type":"FIRESTORE_NATIVE",
  "locationId":"{FIRESTORE_DATABASE_LOCATION}",
  "cmekConfig": {
    "kmsKeyName":"projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID"
  }
}'

Firebase CLI

To create a CMEK-enabled database, use the KMS Key Name field. If you don't specify the --kms-key-name parameter, Firestore creates a non-CMEK database by default.

firebase firestore:databases:create DATABASE_ID
--location LOCATION
--kms-key-name projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID
--project FIRESTORE_PROJECT

Replace the following:

• DATABASE_ID with the ID of your database
• LOCATION with the location of your database
• KMS_PROJECT with the project that contains your CMEK key
• KMS_LOCATION with the location that contains your CMEK key and key ring
• KMS_KEYRING_ID with the ID of your CMEK key ring
• FIRESTORE_PROJECT with the project to use for your Firestore database

Confirm that your Firestore database is protected with Firebase CLI:

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

The following CMEK information appears in the response message:

• The KMS Key Name field provides the full key resource name that is used to encrypt your Firestore CMEK database.
• The Active Key Versions field provides a list of all key versions currently used by this CMEK database. During key rotation, you can have multiple active key versions.

Terraform

To create a CMEK-enabled database, use the google_firestore_database resource. For more information and examples, see google_firestore_database.

resource "google_firestore_database" "database" {
  project     = "FIRESTORE_PROJECT"
  name        = "DATABASE_ID"
  location_id = "FIRESTORE_DATABASE_LOCATION"
  type        = "DATABASE_TYPE"

  cmek_config {
    kms_key_name = "KMS_KEY_NAME"
  }

}

Replace the following:

• FIRESTORE_PROJECT with the project to use for your Firestore database
• DATABASE_ID with an ID for the database
• FIRESTORE_DATABASE_LOCATION with the Firestore location for the database
• DATABASE_TYPE with either FIRESTORE_NATIVE for Native mode or DATASTORE_MODE for Datastore mode.

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

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

gcloud

Restore a CMEK-protected database to CMEK encryption

To restore to CMEK encryption, run the gcloud firestore databases restore command with the optional encryption-type and kms-key-name flags to configure the encryption type for the restored database. If you don't specify the encryption type, the restored database will use the same encryption configuration as the backup.

  gcloud firestore databases restore
  --encryption-type=customer-managed-encryption
  --kms-key-name=KMS_KEY_NAME

Replace KMS_KEY_NAME with the name that 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

Restore a CMEK-protected database to default encryption

To restore to Google's default encryption (non-CMEK), set the encryption-type flag in the following way:

  gcloud firestore databases restore
  --encryption-type=google-default-encryption

Restore a CMEK-protected database to the same encryption type as the backup

To restore to the same encryption type as the backup, set the encryption-type flag in the following way:

  gcloud firestore databases restore --encryption-type=use-source-encryption

Firebase CLI

Restore a CMEK-protected database to CMEK encryption

To restore to CMEK encryption, use the optional encryption-type and kms-key-name flag. If you don't specify the encryption type, the restored database will use the same encryption configuration as the backup.

firebase firestore:databases:restore \
--database DATABASE_ID \
--backup 'projects/FIRESTORE_PROJECT/locations/FIRESTORE_LOCATION/backups/BACKUP_ID' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION \
--kms-key-name projects/KMS_PROJECT/locations/KMS_LOCATION/keyRings/KMS_KEYRING_ID/cryptoKeys/KMS_KEY_ID \
--project FIRESTORE_PROJECT

Replace the following:

• DATABASE_ID with the ID of your database
• FIRESTORE_PROJECT with the project to use for your Firestore database
• FIRESTORE_LOCATION with the location of your Firestore database
• BACKUP_ID with the ID of your backup
• KMS_PROJECT with the project that contains your CMEK key
• KMS_LOCATION with the location that contains your CMEK key and key ring
• KMS_KEYRING_ID with the ID of your CMEK key ring

Confirm that your restored Firestore database is CMEK-encrypted:

firebase firestore:databases:get DATABASE_ID --project FIRESTORE_PROJECT

Restore a CMEK-protected database to default encryption

To restore to Google's default encryption (non-CMEK), set the encryption-type flag in the following way:

firebase firestore:databases:restore \
--database DATABASE_ID \
--backup 'projects/FIRESTORE_PROJECT/locations/FIRESTORE_LOCATION/backups/BACKUP_ID' \
--encryption-type GOOGLE_DEFAULT_ENCRYPTION \
--project FIRESTORE_PROJECT

Replace the following:

• DATABASE_ID with the ID of your database
• FIRESTORE_PROJECT with the project to use for your Firestore database
• FIRESTORE_LOCATION with the location of your Firestore database
• BACKUP_ID with the ID of your backup

Restore a CMEK-protected database to the same encryption type as the backup

To restore to the same encryption type as the backup, set the encryption-type flag in the following way:

firebase firestore:databases:restore \
--database DATABASE_IDD \
--backup 'projects/FIRESTORE_PROJECT/locations/FIRESTORE_LOCATION/backups/BACKUP_ID' \
--encryption-type USE_SOURCE_ENCRYPTION

Replace the following:

• DATABASE_ID with the ID of your database
• FIRESTORE_PROJECT with the project to use for your Firestore database
• FIRESTORE_LOCATION with the location of your Firestore database
• BACKUP_ID with the ID of your backup

gcloud

You can use the databases describe gcloud CLI command to confirm database CMEK configuration:

gcloud firestore databases describe --database=DATABASE_ID --project=FIRESTORE_PROJECT

You should see CMEK information in the cmekConfig field in the response similar to the following:

cmekConfig:
    activeKeyVersion:
    - projects/PROJECT_ID/locations/us/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME/cryptoKeyVersions/1
    kmsKeyName: projects/PROJECT_ID/locations/us/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME
  locationId: nam5
  name: projects/PROJECT_ID/databases/DATABASE_ID

The response includes the following information:

• kmsKeyName: the full key resource name of the key that's used to encrypt your CMEK-protected database.
• activeKeyVersion: a list of all key versions currently in use by the CMEK-protected database. During key rotation, you can have multiple active key versions. Both the old key version and new key version need to be available during key rotation. Don't disable the old key version until it no longer appears in the activeKeyVersion field.

REST API

HTTP request:

GET https://firestore.googleapis.com/v1/{name=projects/FIRESTORE_PROJECT/databases/DATABASE_ID}

In the request body configure CMEK in the cmek_config.kms_key_name field. Set to the full resource ID of a Cloud KMS key. Only a key in the same location as this database is allowed.

This value should be the Cloud KMS key resource ID in the format of projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}

For more details for other fields, see the database create page.

Example request and response:

curl 'https://firestore.googleapis.com/v1/projects/FIRESTORE_PROJECT/databases/{DATABASE_ID}' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json"

—----------------------------------------- Response —--------------------------------------------
{
  "name": "projects/FIRESTORE_PROJECT/databases/{DATABASE_ID}",
  "locationId": "{FIRESTORE_DATABASE_LOCATION}",
  "type": "FIRESTORE_NATIVE",
  "cmekConfig": {
    "kmsKeyName": "projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}",
    "activeKeyVersion": [
      "projects/{KMS_PROJECT}/locations/{KMS_LOCATION}/keyRings/{KMS_KEYRING_ID}/cryptoKeys/{KMS_KEY_ID}/cryptoKeyVersions/1"
    ]
  },
  ……
}