This page describes how to use your own encryption key, referred to as a customer-supplied encryption key, with Cloud Storage. For other encryption options in Cloud Storage, see Data Encryption Options.
Generating your own encryption key
There are many ways to generate a Base64-encoded AES-256 encryption key. Here are several examples:
C++
For more information, see the Cloud Storage C++ API reference documentation.
C#
For more information, see the Cloud Storage C# API reference documentation.
Go
For more information, see the Cloud Storage Go API reference documentation.
Java
For more information, see the Cloud Storage Java API reference documentation.
Node.js
For more information, see the Cloud Storage Node.js API reference documentation.
PHP
For more information, see the Cloud Storage PHP API reference documentation.
Python
For more information, see the Cloud Storage Python API reference documentation.
Ruby
For more information, see the Cloud Storage Ruby API reference documentation.
Uploading with your encryption key
To use customer-supplied encryption keys to upload an object:
gsutil
Add the following option to the
[GSUtil]
section of your boto configuration file:encryption_key = YOUR_ENCRYPTION_KEY
where
YOUR_ENCRYPTION_KEY
is the AES-256 encryption key used to encrypt your object.Use the
gsutil cp
command:gsutil cp LOCAL_OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME
Where:
LOCAL_OBJECT_LOCATION
is the path to the object you are uploading. For example,Desktop/dogs.png
.DESTINATION_BUCKET_NAME
is the name of the bucket to which you are uploading the object. For example,my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST --data-binary @OBJECT \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-encryption-algorithm: AES256" \ -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \ -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME"
Where:
OBJECT
is the path to the object you are uploading. For example,Desktop/dogs.png
.OAUTH2_TOKEN
is the access token you generated in Step 1.OBJECT_CONTENT_TYPE
is the content type of the object. For example,image/png
.YOUR_ENCRYPTION_KEY
is the AES-256 key used for encrypting the uploaded object.HASH_OF_YOUR_KEY
is the SHA-256 hash for your AES-256 key.BUCKET_NAME
is the name of the bucket to which you are uploading the object. For example,my-bucket
.OBJECT_NAME
is the name of the object you are uploading. For example,pets/dogs.png
.
See Encryption request headers for more information on encryption-specific headers.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aPUT
OBJECT request:curl -X -i PUT --data-binary @OBJECT \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-encryption-algorithm: AES256" \ -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \ -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OBJECT
is the path to the object you are uploading. For example,Desktop/dogs.png
.OAUTH2_TOKEN
is the access token you generated in Step 1.OBJECT_CONTENT_TYPE
is the content type of the object. For example,image/png
.YOUR_ENCRYPTION_KEY
is the AES-256 key used for encrypting the uploaded object.HASH_OF_YOUR_KEY
is the SHA-256 hash for your AES-256 key.BUCKET_NAME
is the name of the bucket to which you are uploading the object. For example,my-bucket
.OBJECT_NAME
is the name of the object you are uploading. For example,pets/dogs.png
.
See Encryption request headers for more information on encryption-specific headers.
Downloading objects you've encrypted
To download an object stored in Cloud Storage that is encrypted with a customer-supplied encryption key:
gsutil
Add the following option to the
[GSUtil]
section of your boto configuration file:decryption_key1 = YOUR_ENCRYPTION_KEY
where
YOUR_ENCRYPTION_KEY
is the key used to encrypt the object when it was uploaded.Use the
gsutil cp
command:gsutil cp gs://BUCKET_NAME/OBJECT_NAME OBJECT_DESTINATION
Where:
BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the name of the object you are downloading. For example,pets/dog.png
.OBJECT_DESTINATION
is the location where you want to save your object. For example,Desktop
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aGET
Object request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "x-goog-encryption-algorithm: AES256" \ -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \ -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.YOUR_ENCRYPTION_KEY
is the AES-256 key you used to encrypt the object.HASH_OF_YOUR_KEY
is the SHA-256 hash for your AES-256 key.SAVE_TO_LOCATION
is the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the bucket from which you are downloading the object. For example,my-bucket
.OBJECT_NAME
is the name of the object you are downloading. For example,pets/dogs.png
.
See Encryption request headers for more information on encryption-specific headers.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aGET
OBJECT request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "x-goog-encryption-algorithm: AES256" \ -H "x-goog-encryption-key: YOUR_ENCRYPTION_KEY" \ -H "x-goog-encryption-key-sha256: HASH_OF_YOUR_KEY" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.YOUR_ENCRYPTION_KEY
is the AES-256 key you used to encrypt the object.HASH_OF_YOUR_KEY
is the SHA-256 hash for your AES-256 key.SAVE_TO_LOCATION
is the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the bucket from which you are downloading the object. For example,my-bucket
.OBJECT_NAME
is the name of the object you are downloading. For example,pets/dogs.png
.
See Encryption request headers for more information on encryption-specific headers.
Rotating your encryption keys
To rotate a customer-supplied encryption key:
gsutil
Add the following options to the
[GSUtil]
section of your boto configuration file:encryption_key = NEW_ENCRYPTION_KEY decryption_key1 = OLD_ENCRYPTION_KEY
Where:
NEW_ENCRYPTION_KEY
is the new encryption key for your object.OLD_ENCRYPTION_KEY
is the current encryption key for your object.
Use the
gsutil rewrite
command with the-k
flag:gsutil rewrite -k gs://BUCKET_NAME/OBJECT_NAME
Where:
BUCKET_NAME
is the name of the bucket containing the relevant object. For example,my-bucket
.OBJECT_NAME
is the name of the relevant object. For example,pets/dog.png
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aPOST
Object request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Length: 0" \ -H "x-goog-encryption-algorithm: AES256" \ -H "x-goog-encryption-key: NEW_ENCRYPTION_KEY" \ -H "x-goog-encryption-key-sha256: HASH_OF_NEW_KEY" \ -H "x-goog-copy-source-encryption-algorithm: AES256" \ -H "x-goog-copy-source-encryption-key: OLD_ENCRYPTION_KEY" \ -H "x-goog-copy-source-encryption-key-sha256: HASH_OF_OLD_KEY" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.NEW_ENCRYPTION_KEY
is the new AES-256 key used for encrypting your object.HASH_OF_NEW_KEY
is the SHA-256 hash for your new AES-256 key.OLD_ENCRYPTION_KEY
is the current AES-256 key used to encrypt your object.HASH_OF_OLD_KEY
is the current SHA-256 hash for your AES-256 key.BUCKET_NAME
is the name of the bucket containing the relevant object. For example,my-bucket
.OBJECT_NAME
is the name of the object whose keys you are rotating. For example,Desktop/dogs.png
.
See Encryption request headers for more information on encryption-specific headers.
XML API
The XML API does not support rotating a customer-supplied encryption key through rewriting object. To apply a new customer-supplied key to an object using the XML API, you should:
What's next
- Learn more about customer-supplied encryption keys.