Pub/Sub encrypts messages with Google-managed keys by default. There is no setup or configuration required and no need to modify the way you access the service. 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 incoming messages as soon as the message is received. This implementation adds the following features:
- Keeps messages encrypted on data-center internal links
- Enables customer-managed encryption keys (CMEK)
Using customer-managed encryption keys
Pub/Sub uses the envelope 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 by Pub/Sub for each topic. These DEKs are stored only in encrypted, or wrapped, form by Pub/Sub. Before storing a DEK, the service sends the DEK to Cloud KMS to be encrypted with the key encryption key (KEK) specified on the topic. A new DEK is generated for each topic approximately every six hours.
Before Pub/Sub publishes messages to a subscription, it encrypts them using the newest DEK that was generated for the topic. Pub/Sub decrypts the messages shortly before they are delivered to subscribers.
Pub/Sub uses a Google Cloud
service account to access
Cloud KMS. The service account is maintained internally by
Pub/Sub for each project, and will not be visible on your list
of service accounts. The service account has the form
service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
. For the CMEK
feature to work, you must grant this account
the Cloud KMS CryptoKey Encrypter/Decrypter
role in Identity and Access Management.
Configuring topics
You can configure CMEK using the Google Cloud console or the gcloud command-line tool. For prerequisites, you must have:
- Created a key ring and a regional or global key in Cloud KMS. Keys and key rings cannot be deleted.
- Enabled the Cloud KMS API.
See the Cloud KMS quickstart guide for instructions on how to accomplish these tasks.
Because Pub/Sub resources are global, we strongly recommend that you use global Cloud KMS keys to configure CMEK-enabled topics. Depending on the locations of a topic's publishers and subscribers, the use of a regional Cloud KMS key could introduce unnecessary dependencies on cross-region network links.
Using the Google Cloud console
You can use the Google Cloud console topic creation dialog to add your encryption keys. See the Google Cloud console quickstart for information about how to access that dialog.
The Google Cloud console:
Simplifies IAM configuration while ensuring that the Pub/Sub service account has the appropriate permissions.
Lets you configure encryption within the topic creation dialog.
Using the command line
This example illustrates how to use the Google Cloud CLI to configure CMEK on a topic:
# Grant the Pub/Sub service account the Cloud KMS CryptoKey # Encrypter/Decrypter role. This service account is different # from the service account you are using to authorize requests to Google Cloud. gcloud projects add-iam-policy-binding ${PROJECT_ID} --member=\ "serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role='roles/cloudkms.cryptoKeyEncrypterDecrypter' # Create a topic that uses customer-managed encryption, using the # --topic-encryption-key argument to specify the Cloud KMS key to use # for protecting message data. KEY_ID=projects/${PROJECT_ID}/locations/global/keyRings/my-key-ring/cryptoKeys/my-crypto-key alias pubsub="gcloud pubsub" pubsub topics create $TOPIC_NAME --topic-encryption-key=$KEY_ID # Confirm that the topic is configured for customer-managed encryption, # indicated by the presence of the kmsKeyName specified on the topic. pubsub topics describe $TOPIC_NAME
Audit logs
Cloud KMS produces audit logs when keys are enabled, disabled, or used by Pub/Sub to encrypt and decrypt messages. This is useful in debugging issues with publish or delivery availability.
Cloud KMS keys are attached to audit logs for Pub/Sub topic resources. Pub/Sub does not include any other Cloud KMS-related information.
Pricing and cost
For the following Pub/Sub requests, the use of CMEK incurs charges for access to the Cloud KMS service based on Pub/Sub pricing:
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 happens three times, once for every zone in the region where the Pub/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 eventsGiven a pricing structure in which cryptographic operations cost $0.03 per 10,000 operations, the above usage would cost approximately $0.07. Refer to Cloud KMS pricing for the most current pricing information.
In practice, keys might be fetched more or less frequently depending on access patterns. 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 following
metrics, grouped by response_class
and response_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 requests
are failing. To monitor StreamingPull, look for the FAILED_PRECONDITION
response code.
Publishing and message delivery can fail with FAILED_PRECONDITION
errors for
multiple reasons.
The Cloud KMS key could be disabled, see below for more details.
If you are using externally managed keys through Cloud EKM, see this troubleshooting guide.
For push subscriptions, there is no way to directly detect CMEK-specific delivery issues. Instead:
Monitor the size and age of the backlog of a push subscription using
subscription/num_unacked_messages
.Monitor
subscription/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 your message data:
Recommended: Disable the Cloud KMS key you've associated with the topic using Pub/Sub. This approach affects only the Pub/Sub topics and subscriptions that are associated with that specific key.
Revoke the Pub/Sub CryptoKey Encrypter/Decrypter role from the Pub/Sub service account (
service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
) using IAM. This approach affects all of the project's Pub/Sub topics and the subscriptions that contain messages encrypted using CMEK.
Although neither operation guarantees instantaneous access revocation, IAM changes generally propagate faster. To learn more, see Cloud KMS resource consistency and this IAM FAQ.
When Pub/Sub cannot access a Cloud KMS key, message
publishing and delivery with StreamingPull or pull fails with
FAILED_PRECONDITION
errors. Message delivery to push endpoints will stop. To
resume delivery and publishing,
restore access to the
Cloud KMS key.
Once the Cloud KMS key is accessible to Pub/Sub, publishing is available within 12 hours and message delivery resumes within 2 hours.
Although intermittent outages of less than a minute for Cloud KMS are unlikely to significantly interrupt publishing and delivery, extended Cloud KMS unavailability has the same effect as key revocation.