This page describes how to use your own encryption key, referred to as a customer-supplied encryption key, with Cloud Storage. For details about this feature, including countries where it's available, see Customer-Supplied Encryption Keys. 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 .
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 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
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: [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:
[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
.[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
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Remove the original object from Cloud Storage. To do so, use
cURL
to call the XML API with aDELETE
OBJECT request:curl -X DELETE \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ "https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]"
Where:
[OAUTH2_TOKEN]
is the access token you generated in Step 1.[BUCKET_NAME]
is the name of the bucket from which you are removing the object. For example,my-bucket
.[OBJECT_NAME]
is the name of the object you are removing. For example,Desktop/dogs.png
.
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: [NEW_ENCRYPTION_KEY]" \ -H "x-goog-encryption-key-sha256: [HASH_OF_NEW_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
.[NEW_ENCRYPTION_KEY]
is the new AES-256 key used to encrypt your object.[HASH_OF_NEW_KEY]
is the SHA-256 key for your new 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,Desktop/dogs.png
.
See Encryption request headers for more information on encryption-specific headers.