This page discusses customer-managed encryption keys and how they are used in Cloud Storage. For other encryption options, see Data Encryption Options.
If you need more control over key operations than what Google-managed encryption keys allows, you can use customer-managed encryption keys. These keys are created and managed using Cloud Key Management Service, and you store the keys as software keys, in an HSM cluster, or externally. You can use customer-managed encryption keys on individual objects, or configure your bucket to use a key by default on all new objects added to a bucket.
When is the key used?
When you apply a customer-managed encryption key to an object, Cloud Storage uses the key when encrypting:
- The object's data.
- The object's CRC32C checksum.
- The object's MD5 hash.
Cloud Storage uses standard server-side keys to encrypt the remaining metadata for the object, including the object's name. Thus, if you have sufficient permission, you can perform actions such as reading most metadata, listing objects, and deleting objects even after you've disabled or destroyed the associated customer-managed encryption key.
Each project has a special Cloud Storage service account called a service agent that performs encryption and decryption with customer-managed encryption keys. Once you give the service agent access to an encryption key, that service agent encrypts:
- Objects added to a bucket that uses the key as the default key.
- Specific objects that you indicate should be encrypted with that key.
When adding or rewriting an object in Cloud Storage, if you have both a default key set on your bucket and a specific key included in your request, Cloud Storage uses the specific key to encrypt the object.
When a requester wants to read an object encrypted with a customer-managed encryption key, they simply access the object as they normally would. During such a request, the service agent automatically decrypts the requested object as long as:
- The service agent still has permission to decrypt using the key.
- You have not disabled or destroyed the key.
If one of these conditions is not met, the service agent does not decrypt the data, and the request fails.
The following restrictions apply when using customer-managed encryption keys:
You cannot encrypt an object with a customer-managed encryption key by updating the object's metadata. Include the key as part of a rewrite of the object instead.
You must create the Cloud KMS key in the same location as the data you intend to encrypt. For example, if your bucket is located in
US-EAST1, any Cloud KMS key encrypting objects in that bucket must also be created in
US-EAST1. For available Cloud KMS locations, see Cloud KMS locations.
Cloud KMS encryption and decryption rates are subject to a quota.
Relation to customer-supplied encryption keys
In addition to customer-managed encryption, Cloud Storage offers Customer-Supplied Encryption Keys as a way of controlling your data encryption. You can encrypt different objects in a single bucket with different encryption methods, but note that:
A single object can only be encrypted by one of these methods at a time.
If you have a default customer-managed key set for your bucket and specify a customer-supplied key in a request, Cloud Storage uses the customer-supplied key to encrypt the object.
This section discusses considerations when rotating keys, replacing keys, and disabling or destroying key versions.
Object uploads when the destination bucket uses the key as its default encryption key.
Object upload, copy, and rewrite operations that specifically use the key in the operation.
Previous versions of the key are not disabled or destroyed, so Cloud Storage can still decrypt existing objects that were previously encrypted using those versions.
Use the following guidelines when replacing the key you use to encrypt Cloud Storage objects with a new key:
Check your buckets to see which use the key as their default encryption key. For these buckets, replace the old key with a new key.
This ensures that all objects written to the bucket use the new key going forward.
Inspect your source code to understand which requests use the key in ongoing operations, such as setting bucket configurations and uploading, copying, or rewriting objects. Update these instances to use the new key.
Disable all versions of the old key. After disabling old key versions, monitor client and service logs for operations that fail due to a version becoming unavailable.
Disabling or destroying a key version
For example, you cannot download, copy, or rewrite the object, and attempting to do so results in an error.
If you disable a key version, you can re-enable it. Once re-enabled, you can access objects that were encrypted by that key version.
If you destroy a key version, downloads of objects encrypted with that version are never possible again.
Before disabling or destroying a key version, you should identify all objects, in all buckets, that were encrypted using the specific key version. Once identified, use the Rewrite Object method to re-encrypt each object using a new key version, a whole new key, or server-side keys.
When you disable or destroy the primary version of a key, you cannot use the key for encryption until you have a new primary version. For example, without a primary version:
You cannot specify the key as part of an object upload, copy, or rewrite.
You cannot upload, copy, or rewrite objects to a bucket that has the key set as its default encryption key unless you specify a different, valid key as part of the operation.
Once you have a primary version for your key, operations that use the key to encrypt objects succeed.
Before disabling or destroying a key version that is the primary version of the key, you should first stop using it as the primary version. You can do so by either:
Preserving a key during a Storage Transfer Service transfer
You can optionally preserve the original customer-managed encryption key that
a source object uses as part of a Storage Transfer Service transfer by including
kmsKey field in the transfer's
The default behavior is to write the object using the destination bucket's encryption method. You can set a default customer-managed key on your destination bucket prior to performing the transfer.
- Set customer-managed encryption keys on your Cloud Storage buckets and objects.
- View pricing for using Cloud KMS.
- Learn more about encryption in Cloud Storage.
- Learn more about Cloud KMS.