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. A Cloud KMS encryption key is a customer-managed encryption key. Such keys are created and managed through Cloud KMS and stored as software keys, in an HSM cluster, or externally.
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 for 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.cryptoKeys.create
permission.Whether you plan to use new or existing key rings and keys, you should have
cloudkms.cryptoKeys.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 a Cloud KMS key ring, and have at least one key within the key ring.
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.
-
Get the email address of the service agent associated with the project that contains your Cloud Storage bucket. By performing this step, you automatically create the service agent if it doesn't currently exist.
Assign a Cloud KMS key to a service agent
In order to use customer-managed encryption keys, give the Cloud Storage service agent associated with your bucket 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 principals 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.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
Command line
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 or number 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 Google Cloud CLI 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. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "policy": { "bindings": { "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter", "members": "serviceAccount: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 \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://cloudkms.googleapis.com/v1/KEY_RESOURCE:setIamPolicy"
Where:
JSON_FILE_NAME
is the path for the JSON file that 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.
Use default encryption keys
Set the default key for a bucket
To add, change, or remove the Cloud KMS key that is used by default when objects are written to a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
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.
Set or remove the default Cloud KMS key for the bucket.
If the bucket isn't currently using a Cloud KMS key, select the Customer-managed key radio button, then select one of the available keys in the associated drop-down menu.
If the bucket currently uses a Cloud KMS key, change the Cloud KMS key in the drop-down menu, or remove the Cloud KMS key by selecting the Google-managed key radio button.
Click Save.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
Command line
Use the gsutil kms encryption
command:
gsutil kms encryption STATE
gs://BUCKET_NAME
Where:
STATE
is the desired state of the default key on the bucket. Use one of the following formats:-k
and a Cloud KMS key resource, if you want to add or change a default key. For example,-k projects/my-pet-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key
.-d
, if you want to remove the default key on the bucket.
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.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample sets a default customer-managed encryption key on a bucket: The following sample removes the default customer-managed encryption key from a bucket: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. For instructions, see API authentication.
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
.To remove the default Cloud KMS key from a bucket, use the following in the JSON file:
{ "encryption": { "defaultKmsKeyName": null } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME \ -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 path for the JSON file that 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. For instructions, see API authentication.
Create an 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
.To remove the default Cloud KMS key from a bucket, use the following in the XML file:
<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 \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
Where:
XML_FILE_NAME
is the path for the XML file that 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
.
View the default key for a bucket
To view the Cloud KMS key that is currently set as default for your bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
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.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
Command line
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. For instructions, see API authentication.
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. For instructions, see API authentication.
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>
Encrypt 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. The name of the key used to encrypt the object is stored in the object's metadata.
Console
The Cloud console cannot be used to specify Cloud KMS keys on a per-object basis. Use gsutil or the client libraries instead.
Command line
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. For instructions, see API authentication.
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 URL-encoded name of the object you are uploading. For example,pets/dog.png
, URL-encoded aspets%2Fdog.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. For instructions, see API authentication.
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 URL-encoded name of the object you are uploading. For example,pets/dog.png
, URL-encoded aspets%2Fdog.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
.
Rotate 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 encryption keys on a per-object basis. Use gsutil or the client libraries instead.
Command line
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 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. For instructions, see API authentication.
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 URL-encoded name of the object whose keys you are rotating. For example,pets/dog.png
, URL-encoded aspets%2Fdog.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:
Identify the key used to encrypt an object
To find the name of the Cloud KMS key that was used to encrypt an object:
Console
- In the Google Cloud console, go to the Cloud Storage Browser page.
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
Command line
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. For instructions, see API authentication.
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 URL-encoded name of the encrypted object. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
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 URL-encoded name of the encrypted object. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
Decrypt 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.
- Learn about the
restrictNonCmekServices
andrestrictCmekCryptoKeyProjects
organization policy constraints to take more control over the usage of Cloud KMS keys.