This document provides instructions for configuring customer-managed encryptionkeys (CMEK) for logs stored inlog buckets.This document alsodescribes how to manage those keys, and limitations associated with using CMEK.

You can configure CMEK as a default resource setting for an organization ora folder. When configured, Cloud Logging ensures that all new log bucketsin the organization or folder areencrypted with a customer-managed key.If you don't supply a key when you create the log bucket, then thedefault key is used. For more information, seeConfigure CMEK for Cloud Logging.

Overview

By default, Cloud Logging encrypts customer content at rest. Logging 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 Logging. 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 letsyou view audit logs and control 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 Logging resources is similar to using Google default encryption. For more information about your encryption options, seeCustomer-managed encryption keys (CMEK).

Prerequisites

Complete the following steps:

1. There are some limitations when using CMEK. Before you create alog bucket with CMEK enabled, review theLimitations.

2. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

3. Configure the Google Cloud project where you plan to create your keys:

   1. To get the permissions that you need to create keys, ask your administrator to grant you theCloud KMS Admin (roles/cloudkms.admin) IAM role on the project or a parent resource. For more information about granting roles, seeManage access to projects, folders, and organizations.

      You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

   2. Enable the Cloud KMS API.

   3. Create a key ring and keys.

      Cloud Logging lets you use a key from any region.However, when you create a log bucket, the location of the log bucket mustmatch the location of the key. For information about supported regions,see the following:

      • Cloud KMS locations
      • Logging Supported regions

      You can't enable CMEK for log buckets created in theglobal region.

4. Ensure that you have the following Cloud Logging permissions on theGoogle Cloud project where you plan to create log buckets:

   • logging.settings.get
   • logging.buckets.get
   • logging.buckets.list
   • logging.buckets.create
   • logging.buckets.update

Enable CMEK

After you've completed theprerequisite steps, follow theseinstructions to enable CMEK for an individual log bucket.

Determine the service account ID

To determine the service account ID associated with the Google Cloudresource for which CMEK will apply, do the following:

1. Run the followinggcloud logging settings describecommand:

   gcloud logging settings describe --project=BUCKET_PROJECT_ID

   Before running the previous command, make the following replacement:

   • BUCKET_PROJECT_ID: Name of the Google Cloud project where youplan to create the log bucket.

   The previous command generates a service account for the specifiedresource, when one doesn't exist already, and it returns the ID of thatservice account in thekmsServiceAccountId field:

   kmsServiceAccountId:KMS_SERVICE_ACCT_NAME@gcp-sa-logging.iam.gserviceaccount.comloggingServiceAccountId:SERVICE_ACCT_NAME@gcp-sa-logging.iam.gserviceaccount.comname: projects/BUCKET_PROJECT_ID/settings

   ThekmsServiceAccountId field lists the service account that is usedby Cloud Logging to call Cloud Key Management Service.

2. If theKMS_SERVICE_ACCT_NAME field has the format ofcmek-pPROJECT_NUMBER,and if you are using VPC Service Controls or if youenable domain restricted sharing,then determine whether you need to migrate your CMEK service account.For information about when you need to migrate and the steps to performthe migration, seeTroubleshoot VPC Service Controls and domain restricted sharing.

Assign the Encrypter/Decrypter role

When you're configuring CMEK at the log bucket level, give theservice account permission to use your Cloud KMS by assigning theCloud KMS CryptoKey Encrypter/Decrypterrole to the service account identified by thekmsServiceAccountId field:

gcloud kms keys add-iam-policy-binding \--project=KMS_PROJECT_ID \--member=serviceAccount:KMS_SERVICE_ACCT_NAME@gcp-sa-logging.iam.gserviceaccount.com \--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \--location=KMS_KEY_LOCATION \--keyring=KMS_KEY_RING \KMS_KEY_NAME

Before running the previous command, make the following replacements:

• KMS_PROJECT_ID: The unique alphanumericidentifier, composed of your Google Cloud project name and a randomlyassigned number, of the Google Cloud project running Cloud KMS.For information about getting this identifier, seeIdentifying projects.
• KMS_SERVICE_ACCT_NAME: The name of theservice account shown in thekmsServiceAccountId field of theresponse of thegcloud logging settings describecommand.
• KMS_KEY_LOCATION: The Cloud KMS key's region.
• KMS_KEY_RING: The Cloud KMS key ring's name.
• KMS_KEY_NAME:The Cloud KMS key's name. It is formatted like this:projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Create a log bucket and supply the Cloud KMS key

To create a log bucket and enable CMEK for the log bucket,run the followinggcloud logging buckets createcommand:

gcloud logging buckets createBUCKET_ID \--location=LOCATION \--cmek-kms-key-name=KMS_KEY_NAME \--project=BUCKET_PROJECT_ID

Before running the previous command, make the following replacements:

• BUCKET_ID: The name or ID of the log bucket.
• LOCATION: The location of the log bucket.
• KMS_KEY_NAME:The Cloud KMS key's name. It is formatted like this:projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.
• BUCKET_PROJECT_ID: Name of the Google Cloud project where thelog bucket will be created.

Verify key enablement

To verify that you've successfully created a log bucket with CMEK enabled,run the followinggcloud logging buckets listcommand:

gcloud logging buckets list --project=BUCKET_PROJECT_ID

Before running the previous command, make the following replacement:

• BUCKET_PROJECT_ID: Name of the Google Cloud project that stores thelog bucket.

In the tabular output, you see a column labeledCMEK. If the value oftheCMEK column isTRUE, then CMEK is enabled for the log bucket.

To view the details for a specific log bucket, including the key's details, runthis command:

gcloud logging buckets describeBUCKET_ID --location=LOCATION --project=BUCKET_PROJECT_ID

Manage your Cloud KMS key

The following sections describe how to update a log bucket to use thelatest primary key version of a Cloud KMS key. They also describehow to change, revoke access for, and disable your Cloud KMS key.

Rotate your Cloud KMS key

When youcreate a Cloud KMS key,you can configure a rotation period. You can alsorotate a Cloud KMS key manually.Each time a key is rotated, a new version for that key is created.

If you rotate a Cloud KMS key, then the new key version applies onlyto log buckets created after the key rotation. If the key is used byan existing log bucket, rotating the key doesn't change how the log bucketprotects its data.

For example, suppose that you create a log bucket and enable CMEK,and then you rotate the Cloud KMS key. The log bucket that youcreated doesn't use the new key version, instead it continues to protect itsdata with the key version that was marked as primary when the log bucket wascreated.

To update a log bucket to use the most recent primary key version of aCloud KMS key, do the following:

1. Identify the current Cloud KMS key for the log bucket.For more information, seeVerify key enablement.
2. Identify another Cloud KMS key that you can use. If yourkey ring has only one key,thenCreate a key.
3. Change the Cloud KMS key for the log bucket to theCloud KMS key created in the previous step.
4. Change the Cloud KMS key for the log bucket to theoriginal Cloud KMS key.

Change your Cloud KMS key

To change the Cloud KMS key associated with your log bucket,create a key and updatethe CMEK settings for log bucket:

gcloud logging buckets updateBUCKET_ID --location=LOCATION \--cmek-kms-key-name=NEW_KMS_KEY_NAME --project=BUCKET_PROJECT_ID

• BUCKET_ID: The name or ID of the log bucket.
• LOCATION: The location of the log bucket.
• NEW_KMS_KEY_NAME: Name of the new key.
• BUCKET_PROJECT_ID: Name of the Google Cloud project that stores thelog bucket.

Revoke access to the Cloud KMS key

To revoke Logging's access to the Cloud KMS key at anytime, remove the configured service account's IAM permission forthat key.

If you remove Logging's access to a key, it can take up toone hour for the change to take effect.

If you have alinked BigQuery dataset,BigQuery can't use this access to apply to key to a new BigQuerytable. If you want to use a key on BigQuery table that aren'tlinked to Logging, followBigQuery's documentationto do so. If you revoke Logging's access to a key and if you havealinked BigQuery dataset,then you also revoke BigQuery's access to the same key.

You can't revoke BigQuery's access to the linked dataset's keywhile preserving Logging's access.

For more information about the impact of revoking access, seeLimitations.

To remove Logging's access to a key, run the following command:

gcloud kms keys remove-iam-policy-binding \--project=KMS_PROJECT_ID \--member=serviceAccount:KMS_SERVICE_ACCT_NAME@gcp-sa-logging.iam.gserviceaccount.com \--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \--location=KMS_KEY_LOCATION \--keyring=KMS_KEY_RING \KMS_KEY_NAME

Before running the previous command, make the following replacements:

• KMS_PROJECT_ID: The unique alphanumericidentifier, composed of your Google Cloud project name and a randomlyassigned number, of the Google Cloud project running Cloud KMS.For information about getting this identifier, seeIdentifying projects.
• KMS_SERVICE_ACCT_NAME: The name of theservice account shown in thekmsServiceAccountId field of theresponse of thegcloud logging settings describecommand.
• KMS_KEY_LOCATION: The Cloud KMS key's region.
• KMS_KEY_RING: The Cloud KMS key ring's name.
• KMS_KEY_NAME:The Cloud KMS key's name. It is formatted like this:projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Limitations

The following are known limitations.

CMEK disables Error Reporting

If you want to use Error Reporting, then don'tenable customer-managed encryption keys (CMEK) on your log buckets.For more information, seeTroubleshooting.

CMEK can't be removed from log buckets

You can't reconfigure log buckets to change or remove CMEK.

Degradation due to Cloud KMS key unavailability

A Cloud KMS key is considered available and accessible byLogging if both of the following are true:

• The key isenabled.
• The Logging service account has encryption and decryptionpermissions on the key.

Cloud Customer Care can't read your resource's logs if its keyisn't properly configured or becomes unavailable.

Degraded query performance

When a customer-managed encryption key is inaccessible, Cloud Loggingcontinues to encrypt your data and store data in log buckets. However,Cloud Logging can't perform background optimizations on this data.If key access is restored, the data becomes available;however, the data is initially be stored in an unoptimized state and queryperformance may suffer.

Degradation due to Cloud EKM key unavailability

When you use a Cloud EKM key, Google Cloud has no control over theavailability of your externally managed key in the external key-managementpartner system. For bucket-level CMEK, if an externally managed key isunavailable, Cloud Logging continues to store logs in log bucketsbut users aren't able to access those logs.

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

Regionality

When you create a log bucket and enable CMEK, you must use a key whoseregion matches the regional scope of your data.You can't configure CMEK for log buckets created in theglobalregion.

Client library availability

Logging client libraries don't provide methods for configuringCMEK.

Quotas

When you use CMEK in Logging,your projects can consume Cloud KMS cryptographic requestsquotas.For example, enabling CMEK on a log bucket can consumethese quotas.Encryption and decryption operations using CMEK keys affect Cloud KMSquotas only if you use hardware (Cloud HSM) or external(Cloud EKM) keys.For more information, seeCloud KMS quotas.

For details on Logging usage limits, seeQuotas and limits.

Troubleshoot configuration errors

For information about troubleshooting CMEK configuration errors, seeTroubleshoot CMEK and organization setting errors.