By default, Pub/Sub encrypts customer content at rest. Pub/Sub 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 Pub/Sub. 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 Pub/Sub resources is similar to using Google default encryption. For more information about your encryption options, seeCustomer-managed encryption keys (CMEK).

CMEK with Cloud KMS Autokey

You can either create CMEKs manually to protect your Pub/Sub resources or use Cloud KMS Autokey. With Autokey, key rings and keys are generated on demand as part of resource creation in Pub/Sub. 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.

How CMEK works with Pub/Sub

When you configure Pub/Sub with CMEK, the serviceautomatically encrypts all data using the specified key. Cloud KMSusage for CMEK might incur additional costs depending on your usage patterns.

Every message is encrypted at the following states and layers:

• At rest

  • Hardware layer
  • Infrastructure layer
  • Application layer

• In transit

At the application layer, Pub/Sub individually encrypts incomingmessages as soon as the message is received. This implementation adds thefollowing features:

• Keeps messages encrypted on data-center internal links
• Enablescustomer-managed encryption keys (CMEK)

Envelope encryption pattern

Pub/Sub uses theenvelope encryption pattern with CMEK.In this approach, the messages are not encrypted by Cloud KMS. Instead,Cloud KMS is used to encrypt Data Encryption Keys (DEKs) created byPub/Sub for each topic. These DEKs are stored only in encrypted,or wrapped, form by Pub/Sub. Before storing a DEK, the servicesends the DEK to Cloud KMS to be encrypted with the key encryptionkey (KEK) specified on the topic. A new DEK is generated foreach topic approximately every six hours.

Before Pub/Sub publishes messages to a subscription, itencrypts them using the newest DEK that was generated for the topic.Pub/Sub decrypts the messages shortly before they are deliveredto subscribers.

Configure CMEK with Pub/Sub

You can configure CMEK manually or by using Autokey.

Before you begin

You can configure CMEK for Pub/Sub usingthe Google Cloud console or the Google Cloud CLI.

Complete the following tasks:

• Enable the Cloud KMS API.

• Create a key ring and a key in Cloud KMS. Keys and keyrings cannot be deleted.

For instructions on how to accomplish these tasks,Create a keyring andCreate a key.

Because Pub/Sub resources are global, we strongly recommendthat you useglobal Cloud KMS keys to configure CMEK-enabledtopics. Depending on the locations of a topic's publishers and subscribers, theuse of a regional Cloud KMS key could introduce unnecessarydependencies on cross-region network links.

Required roles and permissions

Pub/Sub uses a Google Cloudservice agent toaccess Cloud KMS. The service agent is maintained internally byPub/Sub for each project, and is not visible ontheService Accounts page in the Google Cloud console by default.

The Pub/Sub service agent has the formservice-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Pub/Sub requires specific permissions to encrypt anddecrypt data using CMEK.

Complete the following steps to set up the required access:

• Grant the Pub/Sub service agent theCloud KMS Crypto Key Encrypter/Decrypter(roles/cloudkms.cryptoKeyEncrypterDecrypter) role.

  gcloudkmskeysadd-iam-policy-bindingCLOUD_KMS_KEY_NAME\--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com\--role=roles/cloudkms.cryptoKeyEncrypterDecrypter

  Replace the following:

  • CLOUD_KMS_KEY_NAME: The name of the Cloud KMS key.

    The key is of the formatprojects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/CRYPTO_KEY.

    An example isprojects/test-project/locations/us-central1/keyRings/test-keyring/cryptoKeys/test-key.

  • PROJECT_NUMBER: The project number of thePub/Sub project.

For more information about granting Identity and Access Management roles, seeGranting roles on a resource.

Configure a topic manually with CMEK

You can manually configure CMEK for a topic using the Google Cloud console orgcloud CLI.

Update a CMEK topic manually

You have the flexibility to add, change, or remove the CMEK linked to aPub/Sub topic. You can use gcloud CLI to update theCMEK. However, this change doesn't apply retroactively.

Messages published to the topic before the key changes remain encrypted withthe original key, regardless of whether it was a CMEK orGoogle-owned and Google-managed encryption key. Changing a topic's CMEK does not re-encryptpreviously published messages — these messages remain protected with thekey that they were originally encrypted with, so message data within a topicmight still depend on the previous key for up to 31 days, depending on themessage retention duration specified on the topic or any of its subscriptions.

Pub/Sub has a caching mechanism for keys that lasts approximately30 minutes. It might take up to this duration for Pub/Sub torecognize and start using a new key that was manually changed in the topicconfiguration.

Cloud KMS key rotation in Pub/Sub

Key configuration changes such as key rotation within Cloud KMS don'tdirectly trigger the creation of data encryption keys in Pub/Sub.It might take up to 12 hours for Pub/Sub to start using new keyversions for encrypting message data.

As with manual configuration changes made to encryption settings inPub/Sub, these changes don't apply retroactively to messages thatwere published in the past. Existing messages continue to be protected withprevious versions of the cryptographic key. These messages remain protected withthe key that they were originally encrypted with, so message data within a topicmight still depend on the previous key version for up to 31 days, depending onthe message retention duration specified on the topic or any of itssubscriptions.

Configure a topic with Cloud KMS Autokey

For more information on using Cloud KMS Autokey withPub/Sub, seeCloud KMS withAutokey.

Audit logs

Cloud KMS producesaudit logs when keysare enabled, disabled, or used by Pub/Sub to encrypt and decryptmessages. This is useful in debugging issues with publish or deliveryavailability.

Cloud KMS keys are attached to audit logs forPub/Sub topic resources. Pub/Sub does notinclude any other Cloud KMS-related information.

Pricing and cost

For the following Pub/Sub requests, the use of CMEK incurscharges for access to the Cloud KMS service based onPub/Subpricing:

• For each topic using CMEK, a new DEK is encrypted and stored every six hours.

• The key is used to decrypt DEKs every six minutes. The decryption happensthree times, once for every zone in the region where thePub/Sub service runs.

For example, consider a topic with:

• At least one subscription

• Publisher and subscriber clients in the same region

The number of Cloud KMS cryptographic operations can be estimated as:

1 key access for ENCRYPT * (30 days / month * 24 hours / day) / 6 hours + 3 key accesses for DECRYPT   * (30 days / month * 24 hours / day * 60 minutes / hour ) / 6 minutes   = 21,720 Cloud KMS key access events

In practice, keys might be fetched more or less frequently depending on accesspatterns. Use these numbers as estimates only.

Monitoring and troubleshooting

Issues with key access can have these effects:

• Delays in message delivery

• Publish errors

Monitor publish and pull request errors using the followingmetrics, grouped byresponse_classandresponse_code:

• topic/send_request_count
• subscription/pull_request_count
• subscription/streaming_pull_response_count

StreamingPull response has a 100%error rate. This is an indication that the stream has ended, not that requestsare failing. To monitor StreamingPull, look for theFAILED_PRECONDITIONresponse code.

Publishing and message delivery can fail withFAILED_PRECONDITION errors formultiple reasons.

• The Cloud KMS key could be disabled. For details, seeDisabling and re-enabling keys on thispage.

• If you are using externally managed keys through Cloud EKM, seetheCloud EKM error reference.

For push subscriptions, there is no way to directly detect CMEK-specificdelivery issues. Instead:

• Monitor the size and age of the backlog of a push subscription usingsubscription/num_unacked_messages.

• Monitorsubscription/oldest_unacked_message_age for unusual spikes.

• Use publish errors and CMEK audit logs to spot issues.

Disabling and re-enabling keys

There are two ways to prevent Pub/Sub from decrypting yourmessage data:

• Recommended:Disable the Cloud KMS keyyou've associated with the topic using Pub/Sub. This approachaffects only the Pub/Sub topics and subscriptions that areassociated with that specific key.

• Revoke thePub/Sub CryptoKey Encrypter/Decrypter rolefrom the Pub/Sub service account(service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com) usingIAM. This approach affects all of the project'sPub/Sub topics and the subscriptions that contain messagesencrypted using CMEK.

Although neither operation confirms instantaneous access revocation,IAM changes generally propagate faster. To learnmore, seeCloud KMS resource consistency andAccess change propagation.

When Pub/Sub cannot access a Cloud KMS key, messagepublishing and delivery with StreamingPull or pull fails withFAILED_PRECONDITION errors. Message delivery to push endpoints will stop. Toresume delivery and publishing,restore access to theCloud KMS key.

Once the Cloud KMS key is accessible to Pub/Sub,publishing is available within 12 hours and message delivery resumes within 2hours.

Although intermittent outages of less than a minutefor Cloud KMS are unlikely tosignificantly interrupt publishing and delivery, extended Cloud KMSunavailability has the same effect as key revocation.