<br />

By default, all the data at rest in Cloud Firestore is encrypted using
[Google's default encryption](https://cloud.google.com/security/encryption/default-encryption#googles_default_encryption). Cloud Firestore 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
Cloud Firestore. Instead of Google managing the encryption keys that protect
your data, your Cloud Firestore database is protected using a key that you
control and manage in [Cloud Key Management Service (Cloud KMS)](https://cloud.google.com/kms).

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

- [Customer-managed encryption keys (CMEK)](https://cloud.google.com/kms/docs/cmek)
- [Best practices for using CMEKs](https://cloud.google.com/kms/docs/cmek-best-practices)

For instructions on performing CMEK-related tasks with Cloud Firestore, see [Use CMEK](https://firebase.google.com/docs/firestore/use-cmek).
| **Note:** For information about access to this release, see the [access request form](https://docs.google.com/forms/d/e/1FAIpQLSfKs8wJf4IXu1NizvfyU2vT59JDbdPvkehMVZ2ab5l_aDLIIA/viewform?resourcekey=0-O15dlRFvA0JIDmh6VFUEcA).

## 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 Cloud Firestore database.
- **Performance** : CMEK does not impact the [Cloud Firestore SLA](https://cloud.google.com/firestore/sla).
- **Auditability** : If you [enable audit logging for Cloud KMS](https://cloud.google.com/logging/docs/audit/configure-data-access#config-console-enable), all the operations on the key are logged and viewable in Cloud Logging.
- **Organization policy constraints** : You can use [CMEK organization policy constraints](https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints) to specify encryption compliance requirements for Cloud 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](https://cloud.google.com/kms/pricing).

You are billed for the operation costs when Cloud Firestore asks the
Cloud KMS key to perform an encryption or decryption operation.
Encryption/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
Cloud Firestore. 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 Cloud Firestore costs for using CMEK-protected database
and the [Cloud Firestore pricing](https://cloud.google.com/firestore/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 Cloud Firestore 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 Cloud Firestore 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 Cloud Firestore database,
including reads, writes, and queries, return a `FAILED_PRECONDITION` 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](https://firebase.google.com/docs/firestore/ttl), and if
any expiration times get exceeded while the key is unavailable, [data deletion
by TTL](https://firebase.google.com/docs/firestore/ttl#ttl_deletion) will be delayed until the key gets reinstated. If the
database has long-running operations in progress, they will be affected as
follows:

- Data [import](https://firebase.google.com/docs/firestore/manage-data/export-import#import_data) or [export](https://firebase.google.com/docs/firestore/manage-data/export-import#export_data) operations will stop making progress, and be marked as `Failed`. The failed operations will **not** be retried if the key gets reinstated.
- [Index build](https://firebase.google.com/docs/firestore/query-data/indexing#index_build_time) operations, and operations [enabling new TTL
  policies](https://firebase.google.com/docs/firestore/ttl#ttl_policy_enablement_duration) will stop making progress. The stopped operations will be retried if the key gets reinstated.

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

- [Disabling](https://cloud.google.com/kms/docs/enable-disable#disable) or [destroying](https://cloud.google.com/kms/docs/destroy-restore) the in-use key version. Be careful when destroying a key version, because this [can cause unrecoverable data loss](https://cloud.google.com/kms/docs/destroy-restore#understand-risks).
- [Removing permission](https://cloud.google.com/kms/docs/iam#revoking_access_to_a_resource) to access the key from the Cloud Firestore service account.

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](https://cloud.google.com/kms/docs/consistency) to propagate. Cloud Firestore 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](https://cloud.google.com/kms/docs/enable-disable#enable) a disabled key version.
- [Restoring](https://cloud.google.com/kms/docs/destroy-restore#restore) 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](https://cloud.google.com/kms/docs/iam#granting_roles_on_a_resource) the Cloud Firestore service agent permission to access the key.

| **Warning:** Don't let your key become unavailable for longer than seven days. CMEK-protected databases with keys unavailable for more than 7 days may be deleted. In the event of a key being unavailable, to preserve data beyond the seven days limit, we recommend that you enable backups for your Cloud Firestore CMEK database with the required retention period. Before you revoke the key, ensure a backup has been created, as a valid key is required for backup creation. Additional charges apply for backups. For backup pricing details, see [Cloud Firestore pricing](https://firebase.google.com/docs/firestore/pricing).

## Key rotation considerations

When you rotate the CMEK key, Cloud Firestore re-encrypts the database
with the latest primary version of the CMEK key. During the re-encryption
process, keep both the old and the new key version available. Once re-encryption
finishes, disabling or deleting the old 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](https://firebase.google.com/docs/firestore/use-cmek#view-key).

## 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, Cloud Firestore continues to
support full database operations on a best-effort basis for up to one hour.

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

See the [Cloud External Key Manager documentation](https://cloud.google.com/kms/docs/ekm#considerations) for more
information about using external keys.
| **Caution:** If a database remains disabled for more than 7 consecutive days, Cloud Firestore might automatically delete it. To avoid permanent data loss, don't leave external keys in an inaccessible state for an extended time.
| **Warning:** If an external key is deleted and cannot be recovered, any Cloud Firestore database encrypted with that key becomes permanently inaccessible.

## Backup and restore

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

Cloud Firestore creates the first backup of a CMEK database after 24
hours pass from the moment when you enable backup schedules.
| **Note:** Once the backup is created, you can't modify its key and key version, even if you rotate the Cloud KMS key.

For more information about Cloud Firestore backups, see [Back up and
restore data](https://firebase.google.com/docs/firestore/backups).

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](https://cloud.google.com/security/encryption/default-encryption#googles_default_encryption).
- Restore to a database that uses the same encryption as the backup.

For more information about restoring a Cloud Firestore database from a
backup, see [Restore data from a database backup](https://firebase.google.com/docs/firestore/backups#restore_data_from_a_database_backup). For more
information about restoring a CMEK-protected Cloud Firestore database
from a backup, see [Restore a CMEK-protected database](https://firebase.google.com/docs/firestore/use-cmek#restore_a_cmek-protected_database).

## Clone

By default, a database cloned from another database uses the same encryption
mechanism as the source database. When you clone a database, you can specify a
different encryption type in one of the following ways:

- Clone to a CMEK database with a newly specified key.
- Clone to a non-CMEK database that uses [Google's default encryption](https://cloud.google.com/security/encryption/default-encryption#googles_default_encryption).
- (Default) Clone to a database that uses the same encryption as the source database.

For more information about cloning a Cloud Firestore database, see
[Clone a database](https://firebase.google.com/docs/firestore/use-pitr#clone). For more
information about cloning a CMEK-protected Cloud Firestore database, see
[Clone a CMEK-protected database](https://firebase.google.com/docs/firestore/use-cmek#clone-cmek-db).

## Key tracking

You can use key tracking to view resources, for example, Cloud Firestore
databases, that a key protects. For more information about key tracking, see
[View key usage](https://cloud.google.com/kms/docs/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 change Cloud Firestore point-in-time recovery (PITR) settings on a CMEK-enabled database even if the key is unavailable because PITR settings are database metadata, which isn't encrypted by CMEK.
- 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 `FAILED_PRECONDITION` error 400.

## Limitations

- You can't change a key for a CMEK-protected database. You can rotate, enable, and disable keys.
- CMEK-protected databases support [Key Visualizer](https://cloud.google.com/firestore/docs/key-visualizer) only for entity and document data, not for index data.
- 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 or clone data from a non-CMEK database to a CMEK database.
- Cloud Firestore supports a limited number of CMEK-protected databases.
- We don't support CMEK protection with Cloud Functions (1st gen) integration. If you want to have CMEK protection, use [Cloud Run functions Firestore Triggers (2nd gen)](https://cloud.google.com/functions/docs/calling/cloud-firestore).

## How data can leave CMEK-protected databases

- Data copied by your application can be stored by its users in arbitrary ways. Appropriate security controls are required for any application accessing Cloud Firestore data to make sure that data is only accessed by those with proper authorization.

  See [security rules](https://firebase.google.com/docs/firestore/security/get-started) and [IAM](https://firebase.google.com/docs/firestore/security/iam) for more details.

- Data from a CMEK-protected database can be moved to a non-CMEK database by using [Backup and Restore](https://firebase.google.com/docs/firestore/backups), [Clone](https://firebase.google.com/docs/firestore/use-pitr#clone), or [Import](https://firebase.google.com/docs/firestore/manage-data/export-import#import_data) and [Export](https://firebase.google.com/docs/firestore/manage-data/export-import#export_data). Use appropriate [IAM controls](https://firebase.google.com/docs/firestore/security/iam) to only grant permission for these actions to authorized users. Additionally, [CMEK organization policy constraints](https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints) can be used to require that any databases created by restore or clone and any Cloud Storage buckets used for Import are CMEK-protected.

## What's next

- [Learn how to use CMEK with Cloud Firestore.](https://firebase.google.com/docs/firestore/use-cmek)