Enabling customer-managed encryption keys for Logs Router

This page describes how to enable customer-managed encryption keys (CMEK) for the Logs Router in Cloud Logging to meet your compliance needs. Instead of Google managing the encryption keys that protect your data, you create, control, and manage encryption keys in Cloud Key Management Service.

For a summary of your encryption options, go to Encryption at rest.

CMEK for Logs Router

CMEK lets you control the keys that are used to encrypt your data-at-rest. You might use it to fulfill the following requirements for your Google Cloud organization:

• Compliance and internal control: CMEK can be used to control sensitive or regulated data that you store in Google Cloud products. This control is often a documented element of internal compliance procedures; it might be disclosed to regulators and difficult to change.

• Advanced encryption: Your organization might have advanced encryption requirements (for instance, fast key deletion) that are not provided by our default encryption at rest. CMEK provides a path to meeting these requirements through an integration with Cloud KMS.

• Regulatory requirements: Your organization might need to control sensitive material due to government regulation (for instance, Export Administration Regulations (EAR)).

Encryption at rest is already provided across Google Cloud services, including in the Logs Router. While it's not currently possible to use CMEK on logs that are stored in Cloud Logging, you can use CMEK to protect the temporary disaster-recovery files used by the Logs Router and the temporary files used during exports to Cloud Storage. For more details, go to Limitations.

For a description of the Logs Router, go to the Overview.

Getting started

1. Create or identify the Google Cloud project in which you want to run Cloud KMS.
2. Enable the Cloud KMS API for the Google Cloud project that runs Cloud KMS.

3. Create a key ring and keys for the Google Cloud project that runs Cloud KMS.

   Note that the regional scope of keys should match the regional scope of your data. Cloud KMS locations lists the available regions.

4. Identify the required parameters below; in the samples on this page, the following convention is used to indicate Google Cloud resource metadata:

   • [ORGANIZATION_ID] is the unique numeric identifier of the Google Cloud organization for which you are enabling CMEK
   • [KMS_PROJECT_ID] is the unique alphanumeric identifier, composed of your project name and a randomly assigned number, of the project running Cloud KMS
   • [KMS_KEY_NAME] is the Cloud KMS key's resource name. It is formatted like this: projects/[KMS_PROJECT_ID]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY]

   For information about identifying these parameters, go to Identifying projects and Getting your organization ID.

Enable CMEK for an organization

Once you have completed the getting started steps, follow these instructions to enable CMEK for your Google Cloud organization.

Grant encryption and decryption permission

Determine the appropriate service account ID and give the service account permission to use your Cloud KMS key.

Determine the service account ID

REST API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Issue a GET request to obtain the serviceAccountId associated with the Google Cloud organization for which you want to enable CMEK:

    curl -H "Authorization: Bearer [AUTH_TOKEN]" \
       https://logging.googleapis.com/v2/organizations/[ORGANIZATION_ID]/cmekSettings
   
   {
       "serviceAccountId": "[SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com"
   }
   

gcloud

To obtain the serviceAccountId associated with the Google Cloud organization for which you want to enable CMEK, run the following gcloud command:

gcloud alpha logging cmek-settings describe --organization=[ORGANIZATION_ID]

serviceAccountId: "[SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com"

Assign the Encrypter/Decrypter role

To use CMEK, give the service account permission to use your Cloud KMS by assigning the Cloud KMS CryptoKey Encrypter/Decrypter role to the service account:

REST API

Note: This task uses a separate endpoint compared to most Logging tasks.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a JSON file that contains the following information:

   {
     "policy": {
       "bindings": {
         "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
         "members": "serviceAccount:[SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com"
       },
     }
   }

3. Use cURL to call the Cloud KMS API with a POST setIamPolicy request:

   curl -X POST --data-binary @[JSON_FILE_NAME].json \
   -H "Authorization: Bearer [OAUTH2_TOKEN]" \
   -H "Content-Type: application/json" \
   "https://cloudkms.googleapis.com/v1/[KEY_RESOURCE]:setIamPolicy"

Caution: This request replaces any existing Cloud Identity and Access Management policy on the key resource.

Note: There may be a delay of several seconds between assigning the role and having it applied to your service account. If you grant this permission programmatically, wait 30 seconds before configuring Logging.

gcloud

gcloud kms keys add-iam-policy-binding \
--project=[KMS_PROJECT_ID] \
--member [SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=[KMS_KEY_LOCATION] \
--keyring=[KMS_KEY_RING] \
[KMS_KEY]

Replace [KMS_PROJECT_ID] with the ID of your Google Cloud project that is running Cloud KMS and replace [KMS_KEY_LOCATION], [KMS_KEY_RING], [KMS_KEY_RING], and [KMS_KEY] with location, key ring and key names of your Cloud KMS key.

Console

1. Open the Cloud Key Management Service Keys browser in the Google Cloud Console.
   Open the Cloud KMS Keys browser

2. Click on the name of the key ring that contains the desired key.

3. Select the checkbox for the desired key.

   The Permissions tab in the right window pane becomes available.

4. In the Add members dialog, specify the email address of the Logging service account you are granting access.

5. In the Select a role drop down, select Cloud KMS CryptoKey Encrypter/Decrypter.

6. Click Add.

Configure the Cloud KMS key

Update the CMEK settings for the Google Cloud organization with a Cloud KMS key name to enable the feature for your organization.

These updates fail if [KMS_KEY_NAME] is invalid, the associated service account does not have the required encrypter/decrypter role, or access to the key is disabled.

REST API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a JSON file that contains the following information:

   {
       "kms_key_name": "[KMS_KEY_NAME]"
   }
   

3. Issue a PATCH request to update kms_key_name to be associated with the Google Cloud organization for which you want to enable CMEK:

   curl -X PATCH \
       -H "Authorization: Bearer [AUTH_TOKEN] \
       -H "Content-Type: application/json" \
       --data-binary @[JSON_FILE_NAME]
       https://logging.googleapis.com/v2/organizations/[ORGANIZATION_ID]/cmekSettings?update_mask="kms_key_name"
   

Note: The project containing the Cloud KMS key is notified of related issues.

gcloud

Run the following gcloud command:

gcloud alpha logging cmek-settings update \
    --organization=[ORGANIZATION_ID] --kms-key-name=[KMS_KEY_NAME]

Note: The project containing the Cloud KMS key is notified of related issues.

Verify key enablement

Update the CMEK settings for the Google Cloud organization with a Cloud KMS key name to verify that CMEK is enabled for your organization.

REST API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Issue a GET request to obtain the CMEK settings associated with the Google Cloud organization for which you want to verify key enablement. Ifkms_key_name is populated, then CMEK is enabled for your organization:

    curl -H "Authorization: Bearer [AUTH_TOKEN]" \
       https://logging.googleapis.com/v2/organizations/[ORGANIZATION_ID]/cmekSettings
   
   {
       "kmsKeyName": "[KMS_KEY_NAME]",
       "serviceAccountId": "[SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com"
   }
   

gcloud

Run the following gcloud command to obtain the CMEK settings associated with the Google Cloud organization for which you want to verify key enablement. If kmsKeyName is populated, then CMEK is enabled for your organization:

gcloud alpha logging cmek-settings describe --organization=[ORGANIZATION_ID]

kmsKeyName: [KMS_KEY_NAME]
serviceAccountId: [SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com

Manage your Cloud KMS key

The following explains how to change, revoke access for, or delete your Cloud KMS key.

Note: If Logging loses access to the Cloud KMS key, there are data loss and user implications; to learn more, review Limitations.

Change your Cloud KMS key

To change the Cloud KMS key associated with your organization, create a key and update the CMEK settings for the organization with the new Cloud KMS key name.

REST API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a JSON file that contains the following information:

   {
       "kms_key_name": "[NEW_KMS_KEY_NAME]"
   }
   

3. Issue a PATCH request to update kms_key_name:

   curl -X PATCH \
       -H "Authorization: Bearer [AUTH_TOKEN] \
       -H "Content-Type: application/json" \
       --data-binary @[JSON_FILE_NAME]
       https://logging.googleapis.com/v2/organizations/[ORGANIZATION_ID]/cmekSettings?update_mask="kms_key_name"
   

Note: The project containing the Cloud KMS key is notified of related issues.

gcloud

Run the following gcloud command:

gcloud alpha logging cmek-settings update \
    --organization=[ORGANIZATION_ID]
    --kms-key-name=[NEW_KMS_KEY_NAME]

Note: The project containing the Cloud KMS key is notified of related issues.

This update fails if [KMS_KEY_NAME] is invalid, the associated service account does not have the required encrypter/decrypter role, or access to the key is disabled.

Revoke access to the Cloud KMS key

To revoke Logging's access to the Cloud KMS key at any time, remove the Cloud IAM permission for that key.

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

REST API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a JSON file that contains the following information:

   revoke.json:
   {
     "policy": {
       "bindings": {
         "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
         "members":
       },
     }
   }
   

3. Issue a POST request:

   curl -X POST --data-binary @revoke.json -H "Authorization: Bearer
   ${OAUTH_TOKEN}" -H "Content-Type: application/json"
   "https://cloudkms.googleapis.com/v1/{$KEY}:setIamPolicy"
   

Note: This removes all members from the key. The project containing the Cloud KMS key is notified of related issues.

gcloud

Run the following gcloud command:

gcloud kms keys remove-iam-policy-binding \
--project=[KMS_PROJECT_ID] \
--member [SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=[KMS_KEY_LOCATION] \
--keyring=[KMS_KEY_RING] \
[KMS_KEY]

Disable CMEK for your organization

REST API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a JSON file that contains the following information:

   {
       "kms_key_name": ""
   }
   

3. Issue a PATCH request to update kms_key_name:

   curl -X PATCH \
       -H "Authorization: Bearer [AUTH_TOKEN] \
       -H "Content-Type: application/json" \
       --data-binary @[JSON_FILE_NAME]
       https://logging.googleapis.com/v2/organizations/[ORGANIZATION_ID]/cmekSettings?update_mask="kms_key_name"
   

Note: The project containing the Cloud KMS key is notified of related issues.

gcloud

Run the following gcloud command to update the serviceAccountId associated with the organization for which you want to disable CMEK:

gcloud alpha logging cmek-settings update --organization=[ORGANIZATION_ID] --clear-kms-key

Note: The project containing the Cloud KMS key is notified of related issues.

This update fails if [KMS_KEY_NAME] is invalid, the associated service account does not have the required encrypter/decrypter role, or access to the key is disabled.

For instructions on destroying your key, go to Destroying and restoring key versions.

Impact of Cloud KMS key rotation

The Logs Router doesn't automatically rotate the encryption key for temporary disaster recovery files when the Cloud KMS key associated with the Google Cloud organization rotates. Existing recovery files continue to use the key version with which they were created. New recovery files use the current primary key version.

CMEK for exports

If you use log sinks to export logs to another destination, you must properly configure CMEK to protect data stored at that destination.

Cloud Storage supports CMEK for logs exports if the destination is CMEK-encrypted. For details, go to Using customer-managed encryption keys.

The other two Logging sink destinations, BigQuery and Pub/Sub, don't yet support using CMEK to protect data exported by Cloud Logging.

Limitations

The following are known limitations of CMEK for the Logs Router.

Organization-level configuration only

CMEK for the Logs Router can currently only be configured for Google Cloud organizations. Once configured, it applies to all projects and folders in the Google Cloud organization.

CMEK for Cloud Logging storage not supported

CMEK is not supported for logs that are stored in Cloud Logging. You can use CMEK to protect the temporary disaster-recovery files used by the Logs Router and the temporary files used during exports to Cloud Storage.

To prevent log entries from being written to Cloud Logging storage, you can exclude them. For instructions, go to Using exclusion queries.

Disaster recovery file unavailability

If Logging loses access to the Cloud KMS key, your user experience can suffer significantly and data loss may occur. Data in these CMEK-protected temporary disaster recovery files and temporary files used for exports to Cloud Storage can no longer be accessed.

A Cloud KMS key is considered available and accessible by Logging if:

• The key is enabled
• The Logging service account has encrypt and decrypt permissions on the key

If the Cloud KMS key becomes unavailable, the Logs Router is unable to write temporary disaster recovery files. Disaster recovery files are unavailable for data that is processed during this time.

Exports to Cloud Storage might also be affected because the Logs Router will be unable to write temporary files required to facilitate the export. If an error is encountered while encrypting or decrypting data, a notification is sent to the project that contains the Cloud KMS key.

Client library availability

Logging client libraries do not support commands for configuring CMEK.

Pricing

For details on Logging usage limits, go to Quotas and limits. For details on costs you might incur, go to Pricing.

Troubleshoot configuration errors

The following sections describe how to find and mitigate common CMEK configuration errors.

Identify configuration errors

To find and view the CMEK configuration errors, do the following:

1. Navigate to the Google Cloud Console:

   Go to Google Cloud Console

2. Select the project that contains the encryption key.

   The project id can be identified via the following gcloud command:

   gcloud alpha logging cmek-settings describe --organization=[ORGANIZATION_ID]
   
   kmsKeyName: projects/[KMS_PROJECT_ID]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY]
   serviceAccountId: [SERVICE_ACCOUNT_ID]@gcp-sa-logging.iam.gserviceaccount.com
   

   The Cloud KMS key's full name in the command's output contains the project id in the kmsKeyName field.

3. Select the Activity tab in the Cloud Console.

4. Check for Cloud Logging Stackdriver Logging CMEK Configuration Error notifications for your selected project.

Each error notification contains steps that you can take to mitigate the issue:

Error	Recommendation
Cryptographic key permission denied	The Logging service account associated with your project does not have sufficient Cloud IAM permission to operate on the specified Cloud KMS key. Follow the instructions in the error or in this documentation to grant the proper Cloud IAM permission.
Cryptographic key is disabled	The specified Cloud KMS was disabled. Follow the instructions in the error to re-enable the key.
Cryptographic key was destroyed	The specified Cloud KMS was disabled. Follow the instructions in the error or in this documentation to configure CMEK encryption with a different key.

To fix the issue, follow the steps outlined in the error's notification message.

Verify key usability

To verify the key usability, run the following gcloud command to list all keys:

    gcloud kms keys list 

    --location=[KMS_KEY_LOCATION] 

    --keyring=[KMS_KEY_RING]

NAME    PURPOSE   ALGORITHM   PROTECTION_LEVEL  LABELS  PRIMARY_ID  PRIMARY_STATE
<var>[KMS_KEY_NAME]</var>  ENCRYPT_DECRYPT  GOOGLE_SYMMETRIC_ENCRYPTION  SOFTWARE  1  ENABLED

Verify that the Cloud KMS CryptoKey is listed in the command's output as enabled, and that the purpose of the key is symmetric encryption: the PURPOSE column must contain ENCRYPT_DECRYPT and the PRIMARY_STATE column must contain ENABLED.

If necessary, create a new key; for instructions, see the sections above.

Verify permissions configuration

Service accounts that are associated with the organization's CMEK settings must have the Cloud KMS CryptoKey Encrypter/Decrypter Cloud IAM role for the configured key.

To list the key's Cloud IAM policy, run the following gcloud command:

    gcloud kms keys get-iam-policy [KMS_KEY_NAME]
   

If necessary, add the service account that contains the Cloud KMS CryptoKey Encrypter/Decrypter Cloud IAM role to the key.