Customer-managed encryption keys

This page discusses customer-managed encryption keys. For other encryption options, see Data Encryption Options. For examples of using this feature, see Using Customer-Managed Encryption Keys.

Overview

As an additional layer on top of Google-managed encryption keys, you can choose to use keys generated by Cloud Key Management Service. Such keys are known as customer-managed encryption keys. If you use a customer-managed encryption key, your encryption keys are stored within Cloud KMS. The project that holds your encryption keys can then be independent from the project that contains your buckets, thus allowing for better separation of duties.

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. This allows you to read and update general metadata, as well as list and delete objects, without needing the customer-managed encryption key. However, to perform any of these actions, you must have sufficient permission to do so.

For example, if an object is encrypted with a customer-managed encryption key, the key must be used to perform operations on the object such as downloading or moving it. If you attempt to read the object's metadata without providing the key, you receive metadata such as the object name and Content-Type, but not the object's CRC32C checksum or MD5 hash. If you do supply your key with the request for the object metadata, the object's CRC32C checksum and MD5 hash are included with the metadata.

Note: Because most metadata can be read regardless of encryption method, do not include sensitive information in your object and bucket metadata or names.

Service accounts

Encryption and decryption with customer-managed encryption keys is accomplished using service accounts. Once you give your Cloud Storage service account access to an encryption key, that service account 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 account automatically decrypts the requested object as long as:

• The service account 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 account does not decrypt the data, and the request fails.

Important: There is a delay between when you disable a key and when that key no longer can be used to encrypt and decrypt objects. For information about the typical length of the delay and ways to effectively shorten it, see Cloud KMS Resource Consistency.

Caution: If you destroy a key that encrypts existing objects, you will be unable to recover that data, but you continue to be charged for storage of your objects until you delete them. If you destroy a key, use the object metadata field kmsKeyName to identify objects that used the destroyed key, and delete those objects.

Key resources

A Cloud KMS key resource has the following format:

projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]

Where [VALUES_IN_BRACKETS] are values that depend on your key resource.

Restrictions

The following restrictions apply when using customer-managed encryption keys:

• Cloud SQL exports to Cloud Storage and Cloud Dataflow do not currently support objects encrypted with customer-managed encryption keys.

• Customer-managed encryption keys are available in the following countries:

  Argentina, Austria, Australia, Belgium, Bulgaria, Canada, Chile, Colombia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Hungary, India, Indonesia, Ireland, Israel, Italy, Japan, Lithuania, Luxembourg, Latvia, Malaysia, Malta, Mexico, Netherlands, New Zealand, Norway, Peru, Poland, Portugal, Romania, Singapore, Slovakia, South Africa, South Korea, Spain, Sweden, Switzerland, Taiwan, Thailand, Turkey, United Kingdom (UK), United States (US), Vietnam

• You cannot use the JSON API Copy Object method when the source object is encrypted with a customer-managed encryption key or when the destination object would become encrypted by a customer-managed encryption key. Use the Rewrite Object method instead.

• You cannot use the JSON API Compose Object method when one or more of the source objects are encrypted with a customer-managed encryption key.

• 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.

• You cannot specify a customer-managed encryption key as part of a Storage Transfer Service transfer, and any such keys on source objects are not applied to the transferred objects. Set a default customer-managed key on your bucket prior to performing the transfer.

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.

• You can set a default customer-managed key on your bucket, but you cannot set a default customer-supplied key on your bucket.