Customer-managed encryption keys (CMEK)

By default, all the data at rest in Firestore with MongoDB compatibility is encrypted using Google's default encryption. Firestore with MongoDB compatibility handles and manages this encryption for you without any additional action on your part.

If you have specific compliance or regulatory requirements related to the keys that protect your data, you can use customer-managed encryption keys (CMEK) for Firestore with MongoDB compatibility. Instead of Google managing the encryption keys that protect your data, your Firestore database is protected using a key that you control and manage in Cloud Key Management Service (Cloud KMS).

This page describes CMEK for Firestore with MongoDB compatibility. For more information about CMEK in general, including when and why to enable it, see the following Cloud KMS documentation:

For instructions on performing CMEK-related tasks with Firestore with MongoDB compatibility, see Use CMEK.

Features

  • Data control: CMEK lets you manage the KMS key. You can rotate, disable, and destroy the key used to encrypt the data at rest in your Firestore database.
  • Performance: CMEK does not impact the Firestore SLA.
  • Auditability: If you enable audit logging for Cloud KMS, all the operations on the key are logged and viewable in Cloud Logging.
  • Organization policy constraints: You can use CMEK organization policy constraints to specify encryption compliance requirements for Firestore databases in your organization.

Pricing

Cloud KMS charges for the cost of the key and any cryptographic operations performed using that key. For more information, see Cloud KMS pricing.

You are billed for the operation costs when Firestore with MongoDB compatibility asks the Cloud KMS key to perform an encryption or decryption operation. Encryption or decryption operation by the customer-managed key occurs every 5 minutes and is not synchronized with database requests. Costs are generally low, given the expected number of cryptographic operations generated by Firestore with MongoDB compatibility. Costs for Cloud Audit Logs are an additional expense, but is also expected to be generally low, given the expected number of cryptographic operations.

There are no additional Firestore with MongoDB compatibility costs for using CMEK-protected database and the Firestore with MongoDB compatibility pricing continues to apply.

If you revoke your key to a database, storage cost will be charged based on the size of the last day that the key was available. You will continue to incur storage costs at that database size until the database is deleted or the key becomes available again.

What is protected with CMEK

When you create a Firestore with MongoDB compatibility CMEK-protected database, your Cloud KMS key is used to protect data at rest. This includes data that you store on a disk or a flash drive, including indexes and backups. Some exceptions apply. The following data types are encrypted with Google default encryption and not by the CMEK key:

  • Data in transit or in memory
  • Database metadata

How an unavailable key status is handled

Encrypt and decrypt operations are not issued on every data request. Instead, the Firestore with MongoDB compatibility system polls Cloud KMS every 5 minutes to check if the key is still available and then performs encrypt and decrypt operations if the key is available.

If the system detects that the key is unavailable, within 10 minutes any subsequent calls to the Firestore database, including reads, writes, and queries, return a INVALID_ARGUMENT error with the The customer-managed encryption key required by the requested resource is not accessible message.

If the database has time-to-live (TTL) policies, and if any expiration times get exceeded while the key is unavailable, data deletion by TTL will be delayed until the key gets reinstated. If the database has long-running operations in progress, they will be affected as follows:

Keys are considered unavailable in any situation that intentionally disallows Firestore with MongoDB compatibility from accessing the key. This includes:

If the key is reinstated, the polling operation detects that the key is available again. Access is re-enabled, usually within minutes, but it can take up to a few hours in rare cases. Note that some operations on Cloud KMS keys, such as disabling or destroying a key, can take up to 3 hours to propagate. Firestore with MongoDB compatibility doesn't detect any changes until after they take effect in Cloud KMS.

Reinstatement of a key involves the following, depending on the situation:

  • Re-enabling a disabled key version.
  • Restoring a destroyed key version. Before being permanently destroyed, a key version is scheduled for destruction. You can only restore a key during the period when a key version is scheduled for destruction. You cannot restore a key that has already been permanently destroyed.
  • Re-granting the Firestore service agent permission to access the key.

Key rotation considerations

When you rotate the CMEK key, Firestore with MongoDB compatibility re-encrypts the database with the latest primary version of the CMEK key. During the re-encryption process, keep both the earlier and the new key version available. Once re-encryption finishes, disabling or deleting the earlier versions of the CMEK key won't disable access to the database since it's encrypted with the new primary key version.

You can also view the key versions that are being used to protect a database. For more information, see View the key in use.

External key considerations

When you use a Cloud EKM key, Google has no control over the availability of your externally-managed key in the external key management partner system.

If an externally-managed key is unavailable, Firestore with MongoDB compatibility continues to support full database operations using a cached version of the key, for up to one hour.

After an hour, if Firestore with MongoDB compatibility is still unable to connect with Cloud KMS, Firestore with MongoDB compatibility begins taking the database offline as a protective measure. Calls to the database will fail with a INVALID_ARGUMENT error that includes additional details.

See the Cloud External Key Manager documentation for more considerations when using external keys.

Backup and restore

A backup uses the same encryption mechanism as the database from which you created it. When a CMEK-protected Firestore database creates a backup, it encrypts the backup with the primary key version used at the time of backup creation.

Firestore with MongoDB compatibility creates the first backup of a CMEK database after 24 hours pass from the moment when you enable backup schedules.

For more information about Firestore with MongoDB compatibility backups, see Back up and restore data.

A database restored from a backup uses the same encryption mechanism as the backup by default. When you restore a database, you can specify a different encryption type in one of the following ways:

  • Restore to a CMEK database with a newly specified key.
  • Restore to a non-CMEK database that uses Google's default encryption.
  • Restore to a database that uses the same encryption as the backup.

For more information about restoring a Firestore database from a backup, see Restore data from a database backup. For more information about restoring a CMEK-protected Firestore database from a backup, see Restore a CMEK-protected database.

Key tracking

You can use key tracking to view resources, for example, Firestore databases, that a key protects. For more information about key tracking, see View key usage.

CMEK and key availability

When keys are unavailable or disabled, be aware of the following behaviors that can occur in CMEK-enabled databases:

  • You can delete a CMEK database that has unavailable keys.
  • When you create a CMEK-enabled database, disabled keys don't show on the list of available keys in the Google Cloud console. If you manually input a disabled key, the database creation process will fail with a INVALID_ARGUMENT error 400.

Limitations

  • You can't change a key for a CMEK-protected database. You can rotate, enable, and disable keys.

  • You can't enable CMEK on existing databases. You can enable CMEK only on new databases, and you must enable it when you create the database. To migrate data in an existing non-CMEK database to a CMEK-protected database, export your data and then import data to a new CMEK-protected database. You can also restore data from a non-CMEK database to a CMEK database.

  • Firestore supports a limited number of CMEK-protected databases.

What's next