Setup

This page discusses customer-supplied encryption keys. For other encryptionoptions, seeData Encryption Options.

Overview

As an additional layer on top ofstandard Cloud Storage encryption, you can choose to provide yourown AES-256 encryption key, encoded instandard Base64. Thiskey is known as acustomer-supplied encryption key. If you provide acustomer-supplied encryption key, Cloud Storage does not permanentlystore your key in its servers or otherwise manage your key.

Instead, you provide your key for each Cloud Storage operation, andyour key is purged from Cloud Storage servers after the operation iscomplete. Cloud Storage stores only a cryptographic hash of the key sothat future requests can be validated against the hash. Your key cannot berecovered from this hash, and the hash cannot be used to decrypt your data.

We recommend you back up each key to a secure location and take precautions toensure that your keys are not shared with untrusted parties. If any file ormachine containing your encryption key is compromised, you should immediatelyperform key rotation for all objects encrypted with the compromised key.

When is the key used?

When you apply a customer-supplied encryption key to an object, Cloud Storageuses the key when encrypting:

• The object's data.
• The object's CRC32C checksum.
• The object's MD5 hash.

Standard Cloud Storage encryption is used to encrypt theremainingmetadata for the object, including the object's name. This letsyou read and update general metadata, as well as list, overwrite, and deleteobjects, without needing the customer-supplied encryption key. However, toperform any of these actions, you must have sufficientpermission to do so.

For example, if an object is encrypted with a customer-supplied encryption key,the key must be used to perform operations on the object such as downloading ormoving it. If you attempt to read the object's metadata without providing thekey, you receive metadata such as the object name andContent-Type, but notthe object's CRC32C checksum or MD5 hash. If you do supply your key with therequest for the object metadata, the object's CRC32C checksum and MD5 hash areincluded with the metadata.

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

Rewrite behavior

If yourewrite an object encrypted with a customer-supplied encryption keywithout supplying a key for encrypting the rewritten object, the followinghappens:

• If you include an appropriate decryption key in the request, the rewrittenobject becomes encrypted using the destination bucket'sdefault Cloud Key Management Service encryption key, or, in the absence of such a key,bystandard Cloud Storage encryption.

• If you don't include an appropriate decryption key in your request, youreceive an error.

HTTPS check

To protect your data as it travels over the Internet during read and writeoperations, use Transport Layer Security, commonly known as TLS or HTTPS. TLS isrequired when you provide an encryption key. If you accidentally use yourencryption key over an unencrypted (HTTP) connection, it is possible for anattacker to intercept your key. Because of this possibility, theCloud Storage API returns an error message warning you that your key may becompromised. If this occurs, you should immediatelyrotate your keys.

Restrictions

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

• You cannot use the Google Cloud console to download objects that are encryptedwith a customer-supplied encryption key. Similarly, when you use theGoogle Cloud console to upload an object, you cannot encrypt the object with acustomer-supplied encryption key.

• Storage Transfer Service andCloud Dataflow don't support objectsencrypted with customer-supplied encryption keys.

• You can only set customer-supplied encryption keys on individual objects.You cannot set a default customer-supplied encryption key for a bucket.

• If you are performing acompose operation on objects encrypted bycustomer-supplied encryption keys, the component objects must beencrypted by the same key, and you need to provide the key with the composerequest. The resulting composite object is encrypted by the same key.

• When serving an object encrypted by a customer-supplied encryption key,Cloud Storage ignoresCache-Control metadata associatedwith the object and serves the object withCache-Control set toprivate, max-age=0.

Encryption keys with REST APIs

When you use a customer-supplied encryption key and work directly with theJSON orXML API, you must provide both the AES-256 key and a SHA256hash of the key. You should store both the AES-256 key and the SHA256 hash ofthe key securely. Cloud Storage stores the SHA256 hash of your key in theobject's metadata, where you can retrieve it later. This SHA256 hash cannot beused by Cloud Storage (or anyone else) to decrypt your data. It isstored as a way to uniquely identify the AES-256 key that was used to encrypt aparticular object.

Note: Unlike typicalobject listing with the JSON API, list results forencrypted objects do not return the CRC32C or MD5 hashes of those objects,even if you supply the encryption key in the request.

Request headers

Include the following HTTP headers in your JSON or XML request:

Header name	Value	Description
x-goog-encryption-algorithm	string	The encryption algorithm to use. You must use the valueAES256.
x-goog-encryption-key	string	AnRFC 4648 Base64-encoded string of your AES-256 encryption key.
x-goog-encryption-key-sha256	string	AnRFC 4648 Base64-encoded string of the SHA256 hash of your encryption key.

If you are performing arewrite operation with the JSON API, theheaders listed above are used for encrypting the destination object, andthe following headers are used for decrypting the source object:

Header name	Value	Description
x-goog-copy-source-encryption-algorithm	string	The encryption algorithm to use. You must use the valueAES256.
x-goog-copy-source-encryption-key	string	AnRFC 4648 Base64-encoded string of the source object's AES-256 encryption key.
x-goog-copy-source-encryption-key-sha256	string	AnRFC 4648 Base64-encoded string of the SHA256 hash of the source object's encryption key.

Response

You receive an HTTP 400 error in the following cases:

• You upload an object using a customer-supplied encryption key, and you attemptto perform another operation on the object (other than requesting or updatingmost metadata or deleting the object) without providing the key.
• You upload an object using a customer-supplied encryption key, and you attemptto perform another operation on the object with an incorrect key.
• You upload an object without providing a customer-supplied encryption key, andyou attempt to perform another operation on the object with a customer-suppliedencryption key.
• You specify an encryption algorithm, key, or SHA256 hash that is not valid.

Encryption keys withgcloud storage

TheGoogle Cloud CLI supports the use of customer-supplied encryption keys.When using the gcloud CLI with customer-supplied encryption keys,keep in mind the following:

• The key specified as the encryption key is used in commands as both anencryption key and, when needed, as a decryption key.

• You can optionally specify up to 100 decryption keys, which are used only todecrypt objects.

• When decrypting, the SHA256 hash of any supplied encryption and decryptionkeys is calculated, and the correct key to use for a particular object isselected by matching the SHA256 hash in the object's metadata.

• When adding orrotating a customer-supplied encryption key for anexisting object, the object is rewritten as part of the request. This is trueeven for thegcloud storage objects update command.

• List commands that can return the MD5 or CRC32C hash for objects encryptedwith a customer-supplied key perform an additional metadataGET request foreach such object. These additional requests can make listing substantiallyslower than listing objects encrypted with standard Cloud Storageencryption.

• In situations where the encryption key can or does change during apartially-completed write or copy operation, such as when you re-run acpupload after force quitting or encountering a network timeout, the operationrestarts to ensure that the destination object is written with the new key.

Encryption key rotation

If an object is encrypted using a customer-supplied encryption key, you canrotate the object's key byrewriting the object. Rewrites aresupported through the JSON API, but not the XML API. SeeRotating an encryption key for examples of key rotation.

Note: If your bucket usesobject versioning, be sure to deletethe noncurrent versions of your objects after you rotate the key. Noncurrentversions are not deleted automatically and remain encrypted with the old key.

What's next

• Learn how touse customer-supplied encryption keys.