Use customer-managed encryption keys (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Use customer-managed encryption keys

Overview

This page describes how to use a manually-created 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_ (CMEK). Such keys are created and managed through Cloud KMS and stored as software keys, in an HSM cluster, or externally.

If you instead want to use the Cloud KMS Autokey feature to generate key rings and keys on demand that protect your Cloud Storage buckets and the objects within them, seeUsing Autokey with Cloud Storage resources. To decide which key type is right for you when comparing CMEK to Cloud KMS with Autokey and Google default encryption, seeComparison of CMEK and Google-owned and Google-managed encryption keys.

Before you begin

Before using this feature in Cloud Storage, you must:

1. Enable the Cloud KMS API for the project that will store your encryption keys.
   Enable the API
2. 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 and cloudkms.cryptoKeys.createpermission.
   • 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.
3. Have a Cloud KMS key ring, and have at least one keywithin the key ring.
   The key ring must be in the same location as the data you intend to encrypt, but it can be in a different project. For available Cloud KMS locations, see Cloud KMS locations.
4. 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 permissionto write objects to the bucket and storage.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 Adminthat has these permissions.
   • If you use ACLs, you should have bucket-scoped WRITER permission to write objects to the bucket and object-scoped READER permission to read objects from the bucket. See Setting ACLs for instructions on how to do this.
5. 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 CMEKs, grant the Cloud Storage service agent associated with your bucket the permission to use your Cloud KMS key for encrypting and decrypting:

Console

1. In the Google Cloud console, go to the Key management page.
   Go to Key management
2. Click the name of the key ring that contains the key you want to use.
3. Select the checkbox for the desired key.
   The Permissions tab in the right window pane becomes available.
4. In the Add principals dialog, specify the email address of the Cloud Storage service agent you are granting access.
5. In the Select a role drop down, select Cloud KMS CryptoKey Encrypter/Decrypter.
6. Click Add.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage service-agent command with the--authorize-cmek flag to give the service agent associated with your bucket permission to encrypt and decrypt objects using your Cloud KMS key:

gcloud storage service-agent --project=PROJECT_STORING_OBJECTS --authorize-cmek=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.

Client libraries

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. 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.
3. Use cURL to call the Cloud KMS API with a POST setIamPolicy request:
   curl -X POST --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • KEY_RESOURCE is yourCloud KMS key resource.

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 the gcloud CLI, instead.

Use default encryption keys

The following sections describe how to 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

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the desired bucket.
3. In the Bucket details page, click the Configuration tab.
4. Click the Pencil icon associated with the Encryption type entry.
5. Set or remove the default Cloud KMS key for the bucket.
   1. 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.
   2. 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 theGoogle-managed encryption key radio button.
6. Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage buckets update command with the appropriate flag:

gcloud storage buckets update gs://BUCKET_NAME FLAG

Where:

• BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
• FLAG is the desired setting for the default key on the bucket. Use one of the following formats:
  • --default-encryption-key= and a Cloud KMS key resource, if you want to add or change a default key.
  • --clear-default-encryption-key, if you want to remove the default key on the bucket.

If successful, the response looks like:

Updating gs://my-bucket/... Completed 1

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create a JSON file that contains the following information:
   {
   "encryption": {
   "defaultKmsKeyName": "KEY_RESOURCE"
   }
   }
   Where KEY_RESOURCE is yourCloud KMS key resource.
   To remove the default Cloud KMS key from a bucket, use the following in the JSON file:
   {
   "encryption": {
   "defaultKmsKeyName": null
   }
   }
3. Use cURL to call the JSON API with aPATCH Bucket request:
   curl -X PATCH --data-binary @JSON_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

XML API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create an XML file that contains the following information: KEY_RESOURCE Where `KEY_RESOURCE` is your[Cloud KMS key resource](/kms/docs/resource-hierarchy#retrieve%5Fresource%5Fid). To remove the default Cloud KMS key from a bucket, use the following in the XML file:
3. Use cURL to call the XML API with aPUT Bucket request and encryptionConfig query string parameter:
   curl -X PUT --data-binary @XML_FILE_NAME \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • 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

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the desired bucket.
3. In the Bucket details page, click the Configuration tab.
4. The current default key for your bucket appears in theEncryption key field.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

Use the gcloud storage buckets describe command with the--format flag:

gcloud storage buckets describe gs://BUCKET_NAME --format="default(default_kms_key)"

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_kms_key: KEY_RESOURCE

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the default KMS key, follow the instructions for displaying a bucket's metadata and look for the default KMS key field in the response.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aGET Bucket request that includes the desired fields:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"
   Where 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

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the XML API with aGET Bucket request that includes the encryption query parameter:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
   Where 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: KEY_RESOURCE

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 resource used to encrypt the object is stored in the object's metadata.

Console

The Google Cloud console cannot be used to specify Cloud KMS keys on a per-object basis. Use the gcloud CLI or the client libraries instead.

Command line

Use the gcloud storage cp command with the --encryption-keyflag:

gcloud storage cp SOURCE_DATA gs://BUCKET_NAME/OBJECT_NAME --encryption-key=KEY_RESOURCE

Where:

• SOURCE_DATA is the source location of the data you're encrypting. This can be any source location supported by thecp command. For example gs://my-bucket/pets/old-dog.png.
• BUCKET_NAME is the name of the destination bucket for this copy command. For example, my-bucket.
• OBJECT_NAME is the name of the final, encrypted object. For example, pets/new-dog.png.
• KEY_RESOURCE is theCloud KMS key resource you want to use for encrypting the object.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Add the object's data to the request body.
3. Use cURL to call the JSON API with aPOST Object request:
   curl -X POST --data-binary @OBJECT \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • OBJECT_CONTENT_TYPE is thecontent 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 as pets%2Fdog.png.
   • KEY_RESOURCE is theCloud KMS key resource.

XML API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Add the object's data to the request body.
3. Use cURL to call the XML API with a PUT Objectrequest:
   curl -X PUT --data-binary @OBJECT \
   -H "Authorization: Bearer $(gcloud auth print-access-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.
   • OBJECT_CONTENT_TYPE is thecontent 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 as pets%2Fdog.png.
   • KEY_RESOURCE is yourCloud KMS key resource.

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 Google Cloud console cannot be used to change encryption keys on a per-object basis. Use the gcloud CLI or the client libraries instead.

Command line

Use the gcloud storage objects update command with the appropriate flags:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --encryption-key=KMS_KEY --decryption-keys=CSEK_KEY

Where:

• BUCKET_NAME is the name of the bucket that contains the object whose key you are rotating. For example,my-bucket.
• OBJECT_NAME is the name of the object whose key you are rotating. For example, pets/dog.png.
• KMS_KEY is the Cloud KMS key resourceyou want to use for encrypting the object.
• CSEK_KEY is the current customer-supplied encryption key used on the object.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aPOST Object request:
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-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:
   • 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 as pets%2Fdog.png.
   • KEY_RESOURCE is theCloud KMS key resource.

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:

1. Download the existing object.
2. Re-upload the object using a Cloud KMS key.

Identify the key used to encrypt an object

To find the Cloud KMS key that was used to encrypt an object:

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket that contains the desired object.
   The Bucket details page opens, with the Objects tab selected.
3. Navigate to the object, which may be located in a folder.
4. In the Encryption column, hover your mouse over the entry for the desired object.
   The key name and version appear in the format:
   LOCATION/KEY_RING_NAME/KEY_NAME/KEY_VERSION

Command line

Use the gcloud storage objects describe command with the--format flag:

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(kms_key)"

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 looks like:

kms_key: projects/my-pet-project/locations/LOCATION_NAME/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME/cryptoKeyVersions/VERSION_NUMBER

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the KMS key associated with an object, follow the instructions for displaying an object's metadata and look for the KMS key name field in the response.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the KMS key associated with an object, follow the instructions for displaying an object's metadata and look for the KMS key name field in the response.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the KMS key associated with an object, follow the instructions for displaying an object's metadata and look for the KMS key name field in the response.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the KMS key associated with an object, follow the instructions for displaying an object's metadata and look for the KMS key name field in the response.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the KMS key associated with an object, follow the instructions for displaying an object's metadata and look for the KMS key name field in the response.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view the KMS key associated with an object, follow the instructions for displaying an object's metadata and look for the KMS key name field in the response.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with aGET Object request:
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?fields=kmsKeyName"
   Where:
   • 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 as pets%2Fdog.png.

XML API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the XML API with a GET Objectrequest:
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?encryption"
   Where:
   • 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 as pets%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 CMEKs.

What's next

• Learn more about CMEKs 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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-09 UTC.