This page describes customer-managed encryption keys (CMEK) forSpanner. For more information about CMEK in general,including when and why to enable it, see theCloud Key Management Service documentation.

By default, Spanner encrypts customer content at rest. Spanner handles encryption for you without any additional actions on your part. This option is calledGoogle default encryption.

If you want to control your encryption keys, then you can use customer-managed encryption keys (CMEKs) inCloud KMS with CMEK-integrated services including Spanner. Using Cloud KMS keys gives you control over their protection level, location, rotation schedule, usage and access permissions, and cryptographic boundaries. Using Cloud KMS also letsyoutrack key usage, view audit logs, andcontrol key lifecycles. Instead of Google owning and managing the symmetrickey encryption keys (KEKs) that protect your data, you control and manage these keys in Cloud KMS.

After you set up your resources with CMEKs, the experience of accessing your Spanner resources is similar to using Google default encryption. For more information about your encryption options, seeCustomer-managed encryption keys (CMEK).

To learn how to usemanually-created CMEKs to protect your Spanner resources, seeSecure a database with CMEK.

CMEK with Cloud KMS Autokey

You can either create CMEKs manually to protect your Spanner resources or use Cloud KMS Autokey. With Autokey, key rings and keys are generated on demand as part of resource creation in Spanner. Service agents that use the keys for encrypt and decrypt operations are created if they don't already exist and are granted the required Identity and Access Management (IAM) roles. For more information, seeAutokey overview.

Spanner isonly compatible with Cloud KMS Autokey whencreating resources using Terraform or the REST API. You can't useCloud KMS Autokey to create multiple regional (single-region)Cloud KMS keys for a Spanner database.

To use CMEKs created byCloud KMS Autokey to protect your Spanner resources,use the steps provided for Secret Manager atUsing Autokey withSecret Manager resourcesas an example.

Features

• Data access control: administrators can rotate, manage access to, anddisable or destroy the key used to protect data at rest inSpanner.
• Auditability: if youenable audit loggingfor the Cloud KMS API in your project, all actions on the key,including those performed by Spanner, are logged and viewableinCloud Logging.Cloud EKM keys supportKey Access Justification,which adds a justification field to all key requests. With select externalkey management partners, you can automatically approve or deny theserequests, based on the justification.
• Performance: there are no changes to Spannerperformanceor theservice level agreementby using CMEK.
• Multiple regional keys support: you can create multiple regional(single-region) Cloud KMS keys to protect a database in aSpannercustom, dual-region, or multi-region instance configuration.

Pricing

Spanner bills CMEK-enabled databases just like any otherdatabase. There are no additional Spanner costs for enablingCMEK. For more information, seeSpanner pricing.

You are billed by Cloud KMS for both the cost of the key and anycryptographic operations on that key (whenever Spanner uses thekey for encryption/decryption). We expect those costs to be minimal based on theexpected number of cryptographic operations generated by Spanner.For more information, seeCloud KMS pricing.

What is protected with CMEK

In a CMEK-enabled database, Spanner uses your Cloud KMSkeys to protectdata at rest. This includes data in a database that is storedon disk or flash.

Some exceptions apply. The following types of data are protected by Googledefault encryption at rest and not by the CMEK key:

• A subset of row keys that mark range boundaries
• Debugging data including core dumps and operational logs
• Data in transit or in memory
• Database metadata

In Spanner, there are three layers of encryption.Data at rest is broken into subfile chunks for storage, and each chunk isencrypted at the storage level with an individual encryption key. The key usedto encrypt the data in a chunk is called a data encryption key (DEK). Because ofthe high volume of keys at Google, and the need for low latency and highavailability, these keys are stored near the data that they encrypt. The DEKsare encrypted with (or wrapped by) a key encryption key (KEK). Finally, eachKEK is encrypted with your CMEK.

When yourotate the CMEK key, Spannerre-encrypts only the intermediate KEKs with the latest primary version of theCMEK key. After the re-encryption finishes, disabling or deleting the earlierversions of the CMEK key won't disable access to the database. You can alsoview the key versions that are being used toprotect a database.

Enable CMEK

To use CMEK for Spanner databases, you must create a new databaseand specify the Cloud KMS key at the time ofdatabase creation.Spanner is able to access the key on your behalf after you granttheCloud KMS CryptoKey Encrypter/Decrypter(roles/cloudkms.cryptoKeyEncrypterDecrypter) role to a Google-managedSpanner service account.For detailed instructions, seeSecure a database with CMEK.

Spanner'sdata access APIs,such as those that are used to manage sessions and execute transactions on data,are exactly the same for both CMEK and Google-owned and Google-managed encryption keys.Applications don't need to specify keys or encryption configurations whenreading or writing data. All encryption is handled by the service.

Note: After you enable CMEK in your Spanner database, you can'tchange its encryption configuration unless youback up and restorethe database, orexport then import thedatabase back to Spanner.

Manage keys

Key management operations are performed using Cloud KMS.Spanner can't detect or act upon any key changes until they arepropagated by Cloud KMS. Some operations, such as disabling ordestroying a key, can takeup to three hours to propagate;changes to permissions usually propagate much faster.

After the database is created, Spanner calls Cloud KMSabout every five minutes to make sure that the key is still valid.

If Spanner detects that your Cloud KMS key has beendisabled or destroyed, an operation to make your database inaccessible beginsimmediately. Any subsequent calls to the database, including sessions, reads,and writes, return aFAILED_PRECONDITION error:KMS key required by theSpanner resource is not accessible. If Spanner'scalls to Cloud KMS detect that a formerly disabled key has beenre-enabled, Cloud KMS restores access to the Spannerdatabase automatically.

In addition, if a database is protected by multiple regional keys and all keysare disabled or destroyed, then Spanner immediately starts tomake your database inaccessible. If Spanner detects that only asubset of the database's keys are disabled or destroyed, then it disables thedatabase over a period of time within 12 hours. Disabling or destroying only asubset of keys in a CMEK-enabled database is strongly discouraged and mightresult in uncertain behavior. To prevent this from happening, you can use theSpanner CMEK Keys metric(instance/replica/cmek/total_keys) to trigger an alert if a subset of keys aredisabled or destroyed. For more information, seeCreate alert for disabling a subset of CMEK.

Warning: If a database remains disabled for more than seven consecutivedays, Spanner automatically deletes it. To avoid permanent dataloss, don't leave CMEK keys in an inaccessible state for an extended time.

If a Cloud KMS key is deleted and can't be recovered, anySpanner database encrypted with that key becomes permanentlyinaccessible.

We strongly recommend against disabling or destroying only a subset ofkeys in a CMEK database that uses multiple keys. You must disable allkeys in the database.

Create alert for disabling a subset of CMEK

You can use theSpanner CMEK Keys (/instance/replica/cmek/total_keys) metric to trigger an alert if a subset of CMEK are disabled or destroyed. To create this alerting policy, expand the following steps and settings:

Steps to create an alerting policy.

To create an alerting policy, do the following:

1. In the Google Cloud console, go to thenotifications Alerting page:

   Go toAlerting

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. If you haven't created your notification channels and if you want to be notified, then clickEdit Notification Channels and add your notification channels. Return to theAlerting page after you add your channels.
3. From theAlerting page, selectCreate policy.
4. To select the resource, metric, and filters, expand theSelect a metric menu and then use the values in theNew condition table:
   1. Optional: To limit the menu to relevant entries, enter the resource or metric name in the filter bar.
   2. Select aResource type. For example, selectVM instance.
   3. Select aMetric category. For example, selectinstance.
   4. Select aMetric. For example, selectCPU Utilization.
   5. SelectApply.
5. ClickNext and then configure the alerting policy trigger. To complete these fields, use the values in theConfigure alert trigger table.
6. ClickNext.

7. Optional: To add notifications to your alerting policy, clickNotification channels. In the dialog, select one or more notification channels from the menu, and then clickOK.

   To be notified when incidents are openend and closed, checkNotify on incident closure. By default, notifications are sent only when incidents are openend.

8. Optional: Update theIncident autoclose duration. This field determines when Monitoring closes incidents in the absence of metric data.
9. Optional: ClickDocumentation, and then add any information that you want included in a notification message.
10. ClickAlert name and enter a name for the alerting policy.
11. ClickCreate Policy.

After you create the alert, if Spanner detects that a subset ofCMEK has been disabled, an incident summary item appears under theIncidents table on the alert'sPolicy details page. You can also set upoptional notification channels. For more information, seeCreate and manage notification channels.

How an unavailable key status is handled

In rare scenarios, such as during periods when Cloud KMS isunavailable, Spanner might be unable to retrieve the status ofyour key from Cloud KMS.

If your Spanner database is protected by a key that is enabled atthe time at which Spanner is first unable to communicate withCloud KMS, Spanner continues to support full databaseoperations on a best-effort basis for a period of up to one hour, to minimizethe impact of any such incident on your workload. After one hour, ifSpanner is still unable to connect with Cloud KMS,Spanner begins taking the database offline as a protectivemeasure. The data in your Spanner database remains inaccessibleuntil your database can reconnect with Cloud KMS and Cloud KMSresponds that the key is active.

Conversely, if your Spanner database is protected by a key thatis disabled at the time at which Spanner is first unable tocommunicate with Cloud KMS, your database remains inaccessible until itis able to reconnect to Cloud KMS and you have re-enabled your key.

If you're using multiple regional keys to protect a Spannerdatabase, only those replicas that are protected by a key residing in theunavailable regional Cloud KMS are affected by the unavailability.

External key considerations

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

If an externally-managed key is unavailable, Spanner continues tosupport full database operations on a best-effort basis for up to one hour.After one hour, if Spanner is still unable to connect withCloud KMS, then Spanner begins taking the databaseoffline as a protective measure. Calls to the database will fail with aFAILED_PRECONDITION error:External key error: Could not find a key resourceat the key URI.

If you're using multiple Cloud EKM keys to protect yourSpanner database, only those replicas that are protected by theunavailable key are affected by the unavailability.

For more considerations when using external keys, see theCloud External Key Manager documentation.

Warning: If a database remains disabled for more than seven consecutivedays, Spanner automatically deletes it. To avoid permanent dataloss, don't leave external keys in an inaccessible state for an extended time.

If an external key is deleted and can't be recovered, anySpanner database encrypted with that key becomes permanentlyinaccessible.

Back up and restore

You can use CMEK or Google-owned and Google-managed encryption keys to protect Spannerbackups. By default, a backup uses the sameencryption configurationas its database, but you can override this behavior by specifying a differentencryption configuration when creating the backup. If the backup isCMEK-enabled, it is encrypted using the primary version of the KMS key at thetime of backup creation. Once the backup is created, its key and key versioncan't be modified, even if the KMS key is rotated. For more information, seeBack up a database.

When yourestore a database froma backup, by default, the restored database uses the sameencryption configurationas the backup. You can override this behavior by specifying a differentencryption configuration when restoring the database. To restore a CMEK-enabledbackup, both the key and key version that was used to encrypt the backup must beavailable. For more information, seeRestore from a backup.

You can perform backup operations such as create, copy, and restore on adatabase encrypted with multiple regional keys.

All backups created bybackup schedulescan be protected by CMEK or Google-owned and Google-managed encryption keys.

Geo-partitioning

You can use CMEK or Google-owned and Google-managed encryption keys to protect Spannerdatabases that usegeo-partitioning. Whenusing geo-partitioning, you must use a regional Cloud KMS key for eachinstance replica locatoin, including those in the instance partitionconfiguration. Multi-region keys aren't supported. Each regionalCloud KMS key must be located in the same region as thecorresponding Spanner instance replica or instance partitionlocation.

For example, if your Spanner database is in the multi-regioninstance configurationnam3, with instance partitions located ineurope-west1 andeurope-west2, then you must create Cloud KMS keysin the following regions:

• us-east4 (part ofnam3)
• us-east1 (part ofnam3)
• us-central1 (part ofnam3)
• europe-west1 (location of instance partition)
• europe-west2 (location of instance partition)

For more information, seeSecure a database with CMEK.

Logging

You can audit the requests that Spanner sends tCloud KMS on your behalf in Logging, if you haveenabled audit loggingfor the Cloud KMS API in your project. TheseCloud KMS log entries are visible inLogging.

Require or limit CMEK within your organization

You can set organization-wide policies regarding the use of CMEK protectionacross various Google Cloud products, including Spanner. Withthese policies, you can:

• Require that new Spanner databases created by your organizationuse CMEK protection.

• Limit which of your organization's Cloud KMS keys are available forCMEK protection.

For more information, seeCMEK organization policies.

What's next

• Learn how tosecure a database with CMEK.