Use customer-managed encryption keys

You can use customer-managed encryption keys (CMEK) to protect Eventarc and related data at rest. Such keys are created and managed through Cloud Key Management Service (Cloud KMS) and stored as software keys, in a Cloud HSM cluster, or externally using Cloud External Key Manager.

Enabling a channel with a CMEK protects the data associated with it by using an encryption key that only you can access. This type of encryption allows you to meet compliance requirements in certain industries, such as financial services. Because the key is owned by you and is not controlled by Google, no one (including you) can access the data protected by these encryption keys when the keys are disabled or destroyed.

Cloud KMS produces Cloud Audit Logs when keys are enabled, disabled, or used by Eventarc channel resources to encrypt and decrypt messages. For more information, see Cloud KMS audit logging information.

Before you begin

Before using this feature in Eventarc, you should:

Console

  1. Enable the Cloud KMS and Eventarc APIs.

    Enable the APIs

  2. Create a key ring and add a new key to it.

gcloud

  1. Update gcloud components.
    gcloud components update
    
  2. Enable the Cloud KMS and Eventarc APIs for the project that will store your encryption keys.
    gcloud services enable cloudkms.googleapis.com eventarc.googleapis.com
    
  3. Create a key ring and add a new key to it.

For more information, see Creating symmetric encryption keys.

Note that Cloud KMS and Eventarc are regionalized services. The region for the Cloud KMS key and the protected Eventarc channel must be the same.

Grant the Eventarc service account access to a key

To grant the Eventarc service account access to the Cloud KMS key, add the service account as a principal of the key, and grant the service account the Cloud KMS CryptoKey Encrypter/Decrypter role:

Console

You will be prompted to grant the Cloud KMS CryptoKey Encrypter/Decrypter role to the service account through the console when you enable CMEK for a Google or third-party channel. For more information, in this document, see Enable CMEK for a Google channel or third-party channel.

gcloud

gcloud kms keys add-iam-policy-binding KEY_NAME \
--keyring KEY_RING \
--location LOCATION \
--member serviceAccount:SERVICE_AGENT_EMAIL \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

  • KEY_NAME: the name of the key. For example, my-key.
  • KEY_RING: the name of the key ring. For example, my-keyring.
  • LOCATION: the location of the key. For example, us-central1.
  • SERVICE_AGENT_EMAIL: the email address of the service account with the eventarc.serviceAgentrole.

    For example, service-PROJECT_NUMBER@gcp-sa-eventarc.iam.gserviceaccount.com. For more information, see Service agents.

Enable CMEK for a Google channel

A Google channel is a resource through which Google Cloud sources can interact with destinations. For more information, see List event providers.

To enable CMEK for a Google channel:

Console

  1. In the console, go to the Eventarc > Channels page.
    Go to Eventarc
  2. Click a channel with a Google Provider.
  3. In the Edit channel page, select the Use a customer-managed encryption key (CMEK) checkbox.
  4. Click Add encryption key.
  5. Select a Region and, in the CMEK encryption key list, select a key ring that you have created for the region.
  6. Optional: To manually enter the resource name of the key, in the CMEK encryption key list, click Don't see your key? Enter key resource name, and enter the key name in the specified format.
  7. If prompted, grant the cloudkms.cyptoKeyEncrypterDecrypter role to the Eventarc service account with the eventarc.serviceAgent role.
  8. Click Save.

gcloud

gcloud eventarc google-channels update \
--location=LOCATION \
--crypto-key=KEY

Replace the following:

  • LOCATION: the location of the Google channel to be protected. It must match the location of the key used.
  • KEY: the fully qualified Cloud KMS key name in the format projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME.

If you are creating Pub/Sub triggers using your own existing topics, for comprehensive CMEK protection, consider configuring the KMS key on the topic. For more information, see Configuring Pub/Sub topics.

Verify Cloud KMS usage

To verify that the channel is now CMEK-compliant:

Console

  1. In the console, go to the Eventarc > Triggers page.
    Go to Eventarc
  2. Click a trigger that lists a Google Cloud source as its Event provider and a Region that you have protected using CMEK.
  3. In the Trigger details page, the status of Encryption displays the message, Events encrypted using Customer-managed encryption keys.

gcloud

gcloud eventarc google-channels describe \
--location=LOCATION

The output should be similar to the following:

cryptoKeyName: projects/PROJECT_ID/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
name: projects/PROJECT_ID/locations/LOCATION/googleChannelConfig
updateTime: '2022-06-28T17:24:56.365866104Z'

The cryptokeyName shows the Cloud KMS key used for the Google channel.

Enable CMEK for a third-party channel

An Eventarc channel is a resource through which non-Google Cloud entities that offer an Eventarc source can interact with destinations.

To enable CMEK for a third-party channel:

Console

  1. In the console, go to the Eventarc > Channels page.
    Go to Eventarc
  2. Click a channel with a third-party Provider.
  3. In the Channel details page, click Edit.
  4. In the Edit channel page, select the Use a customer-managed encryption key (CMEK) checkbox.
  5. In the CMEK encryption key list, select a key ring that you have created for the region.
  6. Optional: To manually enter the resource name of the key you want to use, in the CMEK encryption key list, click Don't see your key? Enter key resource name and enter the key name in the specified format.
  7. If prompted, grant the cloudkms.cyptoKeyEncrypterDecrypter role to the Eventarc service account with the eventarc.serviceAgent role.
  8. Click Save.

gcloud

gcloud eventarc channels update CHANNEL_NAME \
--location=LOCATION \
--crypto-key=KEY

Replace the following:

  • CHANNEL_NAME: the name of the third-party channel. To create a new third-party channel, see Create a channel.
  • LOCATION: the location of the third-party channel to be protected. It must match the location of the key.
  • KEY: the fully qualified Cloud KMS key name in the format projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME.

Verify Cloud KMS usage

To verify that the channel is now CMEK-compliant:

Console

  1. In the console, go to the Eventarc > Triggers page.
    Go to Eventarc
  2. Click a trigger with a third-party source as its Event provider and a Region that you have protected using CMEK.
  3. In the Trigger details page, the status of Encryption displays the message, Events encrypted using Customer-managed encryption keys.

gcloud

gcloud eventarc channels describe CHANNEL \
--location=LOCATION

The output should be similar to the following:

createTime: '2022-06-28T18:05:52.403999904Z'
cryptoKeyName: projects/PROJECT_ID/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
name: projects/PROJECT_ID/locations/LOCATION/googleChannelConfig
pubsubTopic: projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID
state: ACTIVE
uid: 5ea277f9-b4b7-4e7f-a8e0-6ca9d7204fa3
updateTime: '2022-06-28T18:09:18.650727516Z'

The cryptokeyName shows the Cloud KMS key used for the third-party channel.

Disable Cloud KMS

To prevent Eventarc from decrypting your event data:

  • Disable the key version you have configured for the channel. This affects only the Eventarc channels and triggers that are associated with the specific key.
  • Revoke the cloudkms.cryptoKeyEncrypterDecrypter role from the Eventarc service account. This affects all the project's Eventarc channels and triggers that support events encrypted using CMEK.
  • Delete the CMEK protection associated with a region:
    1. In the console, go to the Eventarc > Channels page.
      Go to Eventarc
    2. Based on the type of channel, do the following:

      Google channel

      1. Click a channel with a Google Provider.
      2. In the Edit channel page, hold the pointer over the CMEK encryption key list box to see the Delete item button.
      3. Click Delete item.
      4. Click Save.

      Third-party channel

      1. Click a channel with a third-party Provider.
      2. In the Channel details page, click Edit.
      3. In the Edit channel page, clear the Use a customer-managed encryption key (CMEK) checkbox.
      4. Click Save.

Although neither operation guarantees instantaneous access revocation, Identity and Access Management (IAM) changes generally propagate faster. For more information, see Cloud KMS resource consistency and this IAM FAQ.

Re-enable Cloud KMS

When Eventarc cannot access Cloud KMS, event publishing with channels fails with FAILED_PRECONDITION errors and event delivery stops. To resume event delivery and publishing, restore access to Cloud KMS.

Pricing

This integration does not incur additional costs beyond the key operations, which are billed to your Google Cloud project. The use of CMEK on a channel incurs charges for access to the Cloud KMS service based on Pub/Sub pricing.

For more information on the most current pricing information, see Cloud KMS Pricing.

What's next