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) - [Recommended practices for using CMEKs](https://cloud.google.com/kms/docs/cmek-recommended-practices) For instructions on performing CMEK-related tasks with Cloud Firestore, see [Use CMEK](https://firebase.google.com/docs/firestore/use-cmek.md.txt). > [!NOTE] > **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.md.txt), 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.md.txt#import_data) or [export](https://firebase.google.com/docs/firestore/manage-data/export-import.md.txt#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.md.txt#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] > **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.md.txt). ## 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.md.txt#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] > **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] > **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] > **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.md.txt#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.md.txt#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.md.txt#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.md.txt#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.md.txt) and [IAM](https://firebase.google.com/docs/firestore/security/iam.md.txt) 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.md.txt), [Clone](https://firebase.google.com/docs/firestore/use-pitr.md.txt#clone), or [Import](https://firebase.google.com/docs/firestore/manage-data/export-import.md.txt#import_data) and [Export](https://firebase.google.com/docs/firestore/manage-data/export-import.md.txt#export_data). Use appropriate [IAM controls](https://firebase.google.com/docs/firestore/security/iam.md.txt) 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.md.txt)