This page describes how to use a Cloud Key Management Service encryption key with Cloud Storage, including setting default keys on buckets and adding keys to individual objects. The Cloud KMS encryption key is a customer-managed encryption key, which is created by Cloud KMS and managed by you.
For more general information about Cloud KMS, see Cloud KMS.
Prerequisites
Before using this feature in Cloud Storage, you should:
Enable the Cloud KMS API for the project that will store your encryption keys.
Have sufficient permission on the project that will store your encryption keys:
If you own the project that will store your keys, you most likely have the necessary permission.
If you plan to create new encryption key rings and keys, you should have
cloudkms.keyRings.create
andcloudkms.cryptoKey.create
permission.Whether you plan to use new or existing key rings and keys, you should have
cloudkms.cryptoKey.setIamPolicy
permission for the keys that you will use for encryption.This permission allows you to give Cloud Storage service agents access to Cloud KMS keys.
The above permissions are contained in the Cloud KMS Admin role.
See Using IAM with Cloud KMS for instructions on how to get this or other Cloud KMS roles.
Have sufficient permission to work with objects in your Cloud Storage bucket:
If you own the project that contains the bucket, you most likely have the necessary permission.
If you use IAM, you should have
storage.objects.create
permission to write objects to the bucket andstorage.objects.get
permission to read objects from the bucket. See Using IAM Permissions for instructions on how to get a role, such as Storage Object Admin that has these permissions.If you use ACLs, you should have bucket-scoped
WRITER
permission to write objects to the bucket and object-scopedREADER
permission to read objects from the bucket. See Setting ACLs for instructions on how to do this.
Have a Cloud KMS key ring, and have at least one key within the key ring.
-
Get the email address of the service agent associated with the project that contains your Cloud Storage bucket.
Assigning a Cloud KMS key to a service agent
In order to use customer-managed encryption keys, give your Cloud Storage service agent permission to use your Cloud KMS key:
Console
- Open the Cloud Key Management Service Keys browser in the Google Cloud Console.
Open the Cloud KMS Keys browser Click on the name of the key ring that contains the desired key.
Select the checkbox for the desired key.
The Permissions tab in the right window pane becomes available.
In the Add members dialog, specify the email address of the Cloud Storage service agent you are granting access.
In the Select a role drop down, select Cloud KMS CryptoKey Encrypter/Decrypter.
Click Add.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil kms authorize
command to give the service agent
associated with your bucket permission to encrypt and decrypt objects
using your Cloud KMS key:
gsutil kms authorize -p PROJECT_STORING_OBJECTS -k KEY_RESOURCE
Where:
PROJECT_STORING_OBJECTS
is the ID for the project containing the objects you want to encrypt or decrypt. For example,my-pet-project
.KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.
If you want to remove the granted permission, you need to use either the
gcloud
command-line tool or the Google Cloud Console.
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.
Create a .json file that contains the following information:
{ "policy": { "bindings": { "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter", "members": "SERVICE_AGENT_EMAIL_ADDRESS" }, } }
Where
SERVICE_AGENT_EMAIL_ADDRESS
is the email address associated with your service agent. For example,service-7550275089395@gs-project-accounts.iam.gserviceaccount.com
.Use
cURL
to call the Cloud KMS API with aPOST setIamPolicy
request:curl -X POST --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://cloudkms.googleapis.com/v1/KEY_RESOURCE:setIamPolicy"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.
XML API
The XML API cannot be used to assign a Cloud KMS to a service agent. Use one of the other Cloud Storage tools, such as gsutil, instead.
Using default encryption keys
Adding or changing the default key for a bucket
To add or change the Cloud KMS key that is used by default when objects are written to a bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the desired bucket.
In the bucket details page, click on the Configuration tab.
Click on the Pencil icon associated with the Encryption type entry.
If the bucket isn't currently using a Cloud KMS key, select the Customer-managed key radio button.
In the drop-down menu associated with customer-managed keys, select one of the available keys.
Click Save.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil kms encryption
command:
gsutil kms encryption -k KEY_RESOURCE gs://BUCKET_NAME
Where:
KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
If successful, the response looks like:
Setting default KMS key for bucket gs://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.
Create a .json file that contains the following information:
{ "encryption": { "defaultKmsKeyName": "KEY_RESOURCE" } }
Where
KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"
Where:
JSON_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .xml file that contains the following information:
<EncryptionConfiguration> <DefaultKmsKeyName>KEY_RESOURCE</DefaultKmsKeyName> </EncryptionConfiguration>
Where
KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.Use
cURL
to call the XML API with aPUT
Bucket request andencryption
query string paratmeter:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
Where:
XML_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Viewing the default key for a bucket
To view the Cloud KMS key that is currently set as default for your bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the desired bucket.
In the bucket details page, click on the Configuration tab.
The current default key for your bucket appears in the Encryption key field.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil kms encryption
command:
gsutil kms encryption gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the bucket whose
key you want to view. For example, my-bucket
.
If successful, the response looks like:
Default encryption key for gs://my-bucket: KEY_RESOURCE
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
Bucket request that includes the desiredfields
:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket whose key you want to view. For example,my-bucket
.
The response looks like the following example:
{ "encryption" : { "defaultKmsKeyName": "KEY_RESOURCE" }, }
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
Bucket request that includes theencryption
query parameter:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket whose key you want to view. For example,my-bucket
.
The response looks like the following example:
<EncryptionConfiguration> <DefaultKmsKeyName>KEY_RESOURCE</DefaultKmsKeyName> </EncryptionConfiguration>
Removing the default key from a bucket
To remove any default Cloud KMS key set on a bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the desired bucket.
In the bucket details page, click on the Configuration tab.
Click on the Pencil icon associated with the Encryption type entry.
Select the Google-managed key radio button.
Click Save.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil kms encryption
command:
gsutil kms encryption -d gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If successful, the response looks like:
Clearing default encryption key for gs://my-bucket...
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 Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
Go
Java
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.
Create a .json file that contains the following information:
{ "encryption": { "defaultKmsKeyName": null } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"
Where:
JSON_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .xml file that contains the following information:
<EncryptionConfiguration></EncryptionConfiguration>
Use
cURL
to call the XML API with aPUT
Bucket request andencryption
query string paratmeter:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
Where:
XML_FILE_NAME
is the file you created in Step 2.OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Encrypting an object with a Cloud KMS key
You can encrypt an individual object with a Cloud KMS key. This is useful if you want to use a different key from the default key set on the bucket, or if you don't have a default key set on the bucket.
Console
The Cloud Console cannot be used to encrypt individual objects. Use gsutil or the client libraries instead.
gsutil
Add the following option to the
[GSUtil]
section of your .boto configuration file:encryption_key = KEY_RESOURCE
Where
KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.Write an object to the bucket as you normally would, for example with
gsutil cp
orgsutil rewrite
.
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.
Add the object's data to the request body.
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" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=media&name=OBJECT_NAME&kmsKeyName=KEY_RESOURCE"
Where:
OBJECT
is the path to the object you are uploading. For example,Desktop/dog.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
.BUCKET_NAME
is the name of the bucket to which you are uploading your object. For example,my-bucket
.OBJECT_NAME
is the name of the object you are uploading. For example,pets/dog.png
.KEY_RESOURCE
is the Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Add the object's data to the request body.
Use
cURL
to call the XML API with aPUT
Object request:curl -X PUT --data-binary @OBJECT \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-encryption-kms-key-name: KEY_RESOURCE" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OBJECT
is the path to the object you are uploading. For example,Desktop/dog.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
.BUCKET_NAME
is the name of the bucket to which you are uploading your object. For example,my-bucket
.OBJECT_NAME
is the name of the object you are uploading. For example,pets/dog.png
.KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.
Rotating from a customer-supplied key to a Cloud KMS key
If your objects are encrypted with customer-supplied encryption keys, you can rotate them to use Cloud KMS keys by rewriting the object:
Console
The Cloud Console cannot be used to change the encryption key of an individual object. Use gsutil or the client libraries instead.
gsutil
Add the following options to the
[GSUtil]
section of your boto configuration file:encryption_key = KEY_RESOURCE decryption_key1 = CUSTOMER_SUPPLIED_ENCRYPTION_KEY
Where:
KEY_RESOURCE
is your Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.CUSTOMER_SUPPLIED_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 Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
Go
Java
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-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?kmsKeyName=KEY_RESOURCE"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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
.KEY_RESOURCE
is the Cloud KMS key resource. For example,projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.
XML API
The XML API does not support rotating from a customer-supplied encryption key to a Cloud KMS key through rewriting object. To perform such a rotation using the XML API, you should:
Identifying the key used to encrypt an object
To find the name of the Cloud KMS key that was used to encrypt an object:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that contains the desired object.
The Bucket details page opens, with the Objects tab selected.
Navigate to the object, which may be located in a folder.
In the Encryption column, hover your mouse over the entry for the desired object.
The key name appears in the format:
LOCATION/KEY_RING_NAME/KEY_NAME/KEY_VERSION
gsutil
Use the gsutil stat
command:
gsutil stat gs://BUCKET_NAME/OBJECT_NAME
Where:
BUCKET_NAME
is the name of the bucket containing the encrypted object. For example,my-bucket
.OBJECT_NAME
is the name of the encrypted object. For example,pets/dog.png
.
If successful, the response contains the key name:
gs://my-bucket/pets/dog.png: ... KMS key: projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key ...
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" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?fields=kmsKeyName"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket containing the encrypted object. For example,my-bucket
.OBJECT_NAME
is the name of the encrypted object. For example,pets/dog.png
.
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" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?encryption"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.BUCKET_NAME
is the name of the bucket containing the encrypted object. For example,my-bucket
.OBJECT_NAME
is the name of the encrypted object. For example,pets/dog.png
.
Decrypting an object
Decrypting an object encrypted with a Cloud KMS key is performed automatically as long as the relevant service agent has access to the key. For more information, see Service agents with customer-managed encryption keys.
What's next
- Learn more about customer-managed encryption keys in Cloud Storage.
- Learn about other encryption options available in Cloud Storage.
- Rotate your Cloud KMS keys.
- Explore other products that can work with Cloud KMS.