Using customer-managed encryption keys

Go to concepts

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:

1. Enable the Cloud KMS API for the project that will store your encryption keys.

   Enable the API

2. 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 and cloudkms.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 accounts 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 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 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 Admin that 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.

4. Have a Cloud KMS key ring, and have at least one key within the key ring.

   Note: You must create the Cloud KMS key in the same location as the data you intend to encrypt. For available Cloud KMS locations, see Cloud KMS locations.
5. Note: The following step is not necessary if you are using the gsutil tool.

   Get the email address of the service account associated with the project that contains your Cloud Storage bucket.

Assigning a Cloud KMS key to a service account

In order to use customer-managed encryption keys, give your Cloud Storage service account permission to use your Cloud KMS key:

Console

1. Open the Cloud Key Management Service Keys browser in the Google Cloud Console.
   Open the Cloud KMS Keys browser

2. Click on the name of the key ring that contains the desired key.

3. Select the checkbox for the desired key.

   The Permissions tab in the right window pane becomes available.

4. In the Add members dialog, specify the email address of the Cloud Storage service account you are granting access.

5. In the Select a role drop down, select Cloud KMS CryptoKey Encrypter/Decrypter.

6. 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 account 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

C#

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

View on GitHub Feedback

using Google.Cloud.Iam.V1;
using Google.Cloud.Kms.V1;

public class IamAddMemberSample
{
    public Policy IamAddMember(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key",
      string member = "user:[e-mail]")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the resource name.
        CryptoKeyName resourceName = new CryptoKeyName(projectId, locationId, keyRingId, keyId);

        // The resource name could also be a key ring.
        // var resourceName = new KeyRingName(projectId, locationId, keyRingId);

        // Get the current IAM policy.
        Policy policy = client.GetIamPolicy(resourceName);

        // Add the member to the policy.
        policy.AddRoleMember("roles/cloudkms.cryptoKeyEncrypterDecrypter", member);

        // Save the updated IAM policy.
        Policy result = client.SetIamPolicy(resourceName, policy);

        // Return the resulting policy.
        return result;
    }
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
)

// iamAddMember adds a new IAM member to the Cloud KMS key
func iamAddMember(w io.Writer, name, member string) error {
	// NOTE: The resource name can be either a key or a key ring. If IAM
	// permissions are granted on the key ring, the permissions apply to all keys
	// in the key ring.
	//
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key"
	// member := "user:[e-mail]"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %v", err)
	}

	// Get the current IAM policy.
	handle := client.ResourceIAM(name)
	policy, err := handle.Policy(ctx)
	if err != nil {
		return fmt.Errorf("failed to get IAM policy: %v", err)
	}

	// Grant the member permissions. This example grants permission to use the key
	// to encrypt data.
	policy.Add(member, "roles/cloudkms.cryptoKeyEncrypterDecrypter")
	if err := handle.SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("failed to save policy: %v", err)
	}

	fmt.Fprintf(w, "Updated IAM policy for %s\n", name)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.kms.v1.CryptoKeyName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import java.io.IOException;

public class IamAddMember {

  public void iamAddMember() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String keyId = "my-key";
    String member = "user:[e-mail]";
    iamAddMember(projectId, locationId, keyRingId, keyId, member);
  }

  // Add the given IAM member to the key.
  public void iamAddMember(
      String projectId, String locationId, String keyRingId, String keyId, String member)
      throws IOException {
    // Initialize client that will be used to send requests. This client only
    // needs to be created once, and can be reused for multiple requests. After
    // completing all of your requests, call the "close" method on the client to
    // safely clean up any remaining background resources.
    try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {
      // Build the key version name from the project, location, key ring, key,
      // and key version.
      CryptoKeyName resourceName = CryptoKeyName.of(projectId, locationId, keyRingId, keyId);

      // The resource name could also be a key ring.
      // KeyRingName resourceName = KeyRingName.of(projectId, locationId, keyRingId);

      // Get the current policy.
      Policy policy = client.getIamPolicy(resourceName);

      // Create a new IAM binding for the member and role.
      Binding binding =
          Binding.newBuilder()
              .setRole("roles/cloudkms.cryptoKeyEncrypterDecrypter")
              .addMembers(member)
              .build();

      // Add the binding to the policy.
      Policy newPolicy = policy.toBuilder().addBindings(binding).build();

      client.setIamPolicy(resourceName, newPolicy);
      System.out.printf("Updated IAM policy for %s%n", resourceName.toString());
    }
  }
}

Node.js

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

View on GitHub Feedback

//
// TODO(developer): Uncomment these variables before running the sample.
//
// const projectId = 'my-project';
// const locationId = 'us-east1';
// const keyRingId = 'my-key-ring';
// const keyId = 'my-key';
// const member = 'user:[e-mail]';

// Imports the Cloud KMS library
const {KeyManagementServiceClient} = require('@google-cloud/kms');

// Instantiates a client
const client = new KeyManagementServiceClient();

// Build the resource name
const resourceName = client.cryptoKeyPath(
  projectId,
  locationId,
  keyRingId,
  keyId
);

// The resource name could also be a key ring.
// const resourceName = client.keyRingPath(projectId, locationId, keyRingId);

async function iamAddMember() {
  // Get the current IAM policy.
  const [policy] = await client.getIamPolicy({
    resource: resourceName,
  });

  // Add the member to the policy.
  policy.bindings.push({
    role: 'roles/cloudkms.cryptoKeyEncrypterDecrypter',
    members: [member],
  });

  // Save the updated policy.
  const [updatedPolicy] = await client.setIamPolicy({
    resource: resourceName,
    policy: policy,
  });

  console.log('Updated policy');
  return updatedPolicy;
}

return iamAddMember();

PHP

For more information, see the Cloud Storage PHP API reference documentation.

View on GitHub Feedback

use Google\Cloud\Iam\V1\Binding;
use Google\Cloud\Kms\V1\KeyManagementServiceClient;

function iam_add_member_sample(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $member = 'user:[e-mail]'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

    // Build the resource name.
    $resourceName = $client->cryptoKeyName($projectId, $locationId, $keyRingId, $keyId);

    // The resource name could also be a key ring.
    // $resourceName = $client->keyRingName($projectId, $locationId, $keyRingId);

    // Get the current IAM policy.
    $policy = $client->getIamPolicy($resourceName);

    // Add the member to the policy.
    $bindings = $policy->getBindings();
    $bindings[] = (new Binding())
        ->setRole('roles/cloudkms.cryptoKeyEncrypterDecrypter')
        ->setMembers([$member]);
    $policy->setBindings($bindings);

    // Save the updated IAM policy.
    $updatedPolicy = $client->setIamPolicy($resourceName, $policy);
    printf('Added %s' . PHP_EOL, $member);
    return $updatedPolicy;
}

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

def iam_add_member(project_id, location_id, key_ring_id, key_id, member):
    """
    Add an IAM member to a resource.

    Args:
        project_id (string): Google Cloud project ID (e.g. 'my-project').
        location_id (string): Cloud KMS location (e.g. 'us-east1').
        key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring').
        key_id (string): ID of the key to use (e.g. 'my-key').
        member (string): Member to add (e.g. 'user:[e-mail]')

    Returns:
        Policy: Updated Cloud IAM policy.

    """

    # Import the client library.
    from google.cloud import kms

    # Create the client.
    client = kms.KeyManagementServiceClient()

    # Build the resource name.
    resource_name = client.crypto_key_path(project_id, location_id, key_ring_id, key_id)

    # The resource name could also be a key ring.
    # resource_name = client.key_ring_path(project_id, location_id, key_ring_id);

    # Get the current policy.
    policy = client.get_iam_policy(request={'resource': resource_name})

    # Add the member to the policy.
    policy.bindings.add(
        role='roles/cloudkms.cryptoKeyEncrypterDecrypter',
        members=[member])

    # Save the updated IAM policy.
    request = {
        'resource': resource_name,
        'policy': policy
    }

    updated_policy = client.set_iam_policy(request=request)
    print('Added {} to {}'.format(member, resource_name))
    return updated_policy

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

View on GitHub Feedback

# TODO(developer): uncomment these values before running the sample.
# project_id  = "my-project"
# location_id = "us-east1"
# key_ring_id = "my-key-ring"
# key_id      = "my-key"
# member      = "user:[e-mail]"

# Require the library.
require "google/cloud/kms"

# Create the client.
client = Google::Cloud::Kms.key_management_service

# Build the resource name.
resource_name = client.crypto_key_path project:    project_id,
                                       location:   location_id,
                                       key_ring:   key_ring_id,
                                       crypto_key: key_id

# The resource name could also be a key ring.
# resource_name = client.key_ring_path project: project_id, location: location_id, key_ring: key_ring_id

# Create the IAM client.
iam_client = Google::Cloud::Kms::V1::IAMPolicy::Client.new

# Get the current IAM policy.
policy = iam_client.get_iam_policy resource: resource_name

# Add the member to the policy.
policy.bindings << Google::Iam::V1::Binding.new(
  members: [member],
  role:    "roles/cloudkms.cryptoKeyEncrypterDecrypter"
)

# Save the updated policy.
updated_policy = iam_client.set_iam_policy resource: resource_name, policy: policy
puts "Added #{member}"

REST APIs

JSON API

Note: This task uses a separate endpoint compared to most Cloud Storage tasks.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file that contains the following information:

   {
     "policy": {
       "bindings": {
         "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
         "members": "SERVICE_ACCOUNT_EMAIL_ADDRESS"
       },
     }
   }

   Where SERVICE_ACCOUNT_EMAIL_ADDRESS is the email address associated with your service account. For example, [e-mail].

3. Use cURL to call the Cloud KMS API with a POST 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.

Caution: This request replaces any existing IAM policy on the key resource.

Note: There may be a delay of several seconds between assigning the role and having it applied to your service account. If you grant this permission programmatically, wait 30 seconds before configuring Cloud Storage.

XML API

The XML API cannot be used to assign a Cloud KMS to a service account. 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

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. In the list of buckets, click on the desired bucket.

3. In the bucket details page, click on the Configuration tab.

4. Click on the Pencil icon associated with the Encryption type entry.

5. If the bucket isn't currently using a Cloud KMS key, select the Customer-managed key radio button.

6. In the drop-down menu associated with customer-managed keys, select one of the available keys.

7. 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

C++

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

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& key_name) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().SetEncryption(
                       gcs::BucketEncryption{key_name}));
  if (!updated) throw std::runtime_error(updated.status().message());

  if (!updated->has_encryption()) {
    std::cerr << "The change to set the encryption attribute on bucket "
              << updated->name()
              << " was sucessful, but the encryption is not set."
              << "This is unexpected, maybe a concurrent change?\n";
    return;
  }

  std::cout << "Successfully set default KMS key on bucket "
            << updated->name() << " to "
            << updated->encryption().default_kms_key_name << "."
            << "\nFull metadata: " << *updated << "\n";
}

C#

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

View on GitHub Feedback

private void AddBucketDefaultKmsKey(string bucketName,
    string keyLocation, string kmsKeyRing, string kmsKeyName)
{
    string KeyPrefix = $"projects/{s_projectId}/locations/{keyLocation}";
    string FullKeyringName = $"{KeyPrefix}/keyRings/{kmsKeyRing}";
    string FullKeyName = $"{FullKeyringName}/cryptoKeys/{kmsKeyName}";
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName, new GetBucketOptions()
    {
        Projection = Projection.Full
    });
    bucket.Encryption = new Bucket.EncryptionData
    {
        DefaultKmsKeyName = FullKeyName
    };
    var updatedBucket = storage.UpdateBucket(bucket, new UpdateBucketOptions()
    {
        // Avoid race conditions.
        IfMetagenerationMatch = bucket.Metageneration,
    });
}

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// setBucketDefaultKMSKey sets the Cloud KMS encryption key for the bucket.
func setBucketDefaultKMSKey(w io.Writer, bucketName, keyName string) error {
	// bucketName := "bucket-name"
	// keyName := "key"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		Encryption: &storage.BucketEncryption{DefaultKMSKeyName: keyName},
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Default KMS Key Name: %v", bucketAttrsToUpdate.Encryption.DefaultKMSKeyName)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of the existing bucket to set a default KMS key for, e.g. "my-bucket"
// String bucketName = "my-bucket"

// The name of the KMS-key to use as a default
// Key names are provided in the following format:
// 'projects/<PROJECT>/locations/<LOCATION>/keyRings/<RING_NAME>/cryptoKeys/<KEY_NAME>'
// String kmsKeyName = ""

BucketInfo bucketInfo =
    BucketInfo.newBuilder(bucketName).setDefaultKmsKeyName(kmsKeyName).build();

Bucket bucket = storage.update(bucketInfo);

System.out.println("Default KMS Key Name: " + bucket.getDefaultKmsKeyName());

Node.js

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

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const defaultKmsKeyName = 'KMS key resource id, e.g. my-key';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function enableDefaultKMSKey() {
  await storage.bucket(bucketName).setMetadata({
    encryption: {
      defaultKmsKeyName,
    },
  });

  console.log(
    `Default KMS key for ${bucketName} was set to ${defaultKmsKeyName}.`
  );
}

enableDefaultKMSKey().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation.

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Enable a bucket's requesterpays metadata.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName Name of your Google Cloud Storage bucket.
 * @param string $kmsKeyName KMS key ID to use as the default KMS key.
 *
 * @return void
 */
function enable_default_kms_key($projectId, $bucketName, $kmsKeyName)
{
    $storage = new StorageClient([
        'projectId' => $projectId
    ]);
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'encryption' => [
            'defaultKmsKeyName' => $kmsKeyName
        ]
    ]);
    printf('Default KMS key for %s was set to %s' . PHP_EOL,
        $bucketName,
        $bucket->info()['encryption']['defaultKmsKeyName']);
}

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def enable_default_kms_key(bucket_name, kms_key_name):
    """Sets a bucket's default KMS key."""
    # bucket_name = "your-bucket-name"
    # kms_key_name = "projects/PROJ/locations/LOC/keyRings/RING/cryptoKey/KEY"

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)
    bucket.default_kms_key_name = kms_key_name
    bucket.patch()

    print(
        "Set default KMS key for bucket {} to {}.".format(
            bucket.name, bucket.default_kms_key_name
        )
    )

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

View on GitHub Feedback

# bucket_name     = "Name of your Google Cloud Storage bucket"
# default_kms_key = "KMS key resource id"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.default_kms_key = default_kms_key

puts "Default KMS key for #{bucket.name} was set to #{bucket.default_kms_key}"

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. 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.

3. Use cURL to call the JSON API with a PATCH 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

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. 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.

3. Use cURL to call the XML API with a PUT Bucket request and encryption 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.

Note: Objects that were written to a bucket prior to adding or changing the default key remain encrypted with the previous encryption method.

Viewing the default key for a bucket

To view the Cloud KMS key that is currently set as default for your bucket:

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. In the list of buckets, click on the desired bucket.

3. In the bucket details page, click on the Configuration tab.

4. 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

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a GET Bucket request that includes the desired fields:

   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

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the XML API with a GET Bucket request that includes the encryption 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

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. In the list of buckets, click on the desired bucket.

3. In the bucket details page, click on the Configuration tab.

4. Click on the Pencil icon associated with the Encryption type entry.

5. Select the Google-managed key radio button.

6. 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

C++

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

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> updated = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().ResetEncryption());
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "Successfully removed default KMS key on bucket "
            << updated->name() << "\n";
}

Java

For more information, see the Cloud Storage Java API reference documentation.

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class RemoveBucketDefaultKMSKey {
  public static void removeBucketDefaultKmsKey(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setDefaultKmsKeyName(null).build().update();

    System.out.println("Default KMS key was removed from " + bucketName);
  }
}

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def bucket_delete_default_kms_key(bucket_name):
    """Delete a default KMS key of bucket"""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.default_kms_key_name = None
    bucket.patch()

    print("Default KMS key was removed from {}".format(bucket.name))
    return bucket

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .json file that contains the following information:

   {
     "encryption": {
       "defaultKmsKeyName": null
     }
   }

3. Use cURL to call the JSON API with a PATCH 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

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Create a .xml file that contains the following information:

   <EncryptionConfiguration></EncryptionConfiguration>

3. Use cURL to call the XML API with a PUT Bucket request and encryption 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.

Note: Objects that were written to a bucket prior to removing the default key and which used the default key remain encrypted by it.

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

1. 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.

   Note: You can alternatively include this information in each gsutil command by using the -o top-level flag: -o "GSUtil:encryption_key=KEY_RESOURCE".

2. Write an object to the bucket as you normally would, for example with gsutil cp or gsutil rewrite.

Code samples

C++

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

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& old_csek_key_base64,
   std::string const& new_cmek_key_name) {
  StatusOr<gcs::ObjectMetadata> metadata = client.RewriteObjectBlocking(
      bucket_name, object_name, bucket_name, object_name,
      gcs::SourceEncryptionKey::FromBase64Key(old_csek_key_base64),
      gcs::DestinationKmsKeyName(new_cmek_key_name));
  if (!metadata) throw std::runtime_error(metadata.status().message());

  std::cout << "Changed object " << metadata->name() << " in bucket "
            << metadata->bucket()
            << " from using CSEK to CMEK key.\nFull Metadata: " << *metadata
            << "\n";
}

C#

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

View on GitHub Feedback

        private void UploadEncryptedFileWithKmsKey(string bucketName,
            string keyLocation, string kmsKeyRing, string kmsKeyName,
            string localPath, string objectName = null)
        {
            string KeyPrefix = $"projects/{s_projectId}/locations/{keyLocation}";
            string FullKeyringName = $"{KeyPrefix}/keyRings/{kmsKeyRing}";
            string FullKeyName = $"{FullKeyringName}/cryptoKeys/{kmsKeyName}";

            var storage = StorageClient.Create();
            using (var f = File.OpenRead(localPath))
            {
                objectName = objectName ?? Path.GetFileName(localPath);
                storage.UploadObject(bucketName, objectName, null, f,
                    new UploadObjectOptions()
                    {
                        KmsKeyName = FullKeyName
                    });
                Console.WriteLine($"Uploaded {objectName}.");
            }
        }

Go

For more information, see the Cloud Storage Go API reference documentation.

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// uploadWithKMSKey writes an object using Cloud KMS encryption.
func uploadWithKMSKey(w io.Writer, bucket, object, keyName string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// keyName := "projects/projectId/locations/global/keyRings/keyRingID/cryptoKeys/cryptoKeyID"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	obj := client.Bucket(bucket).Object(object)

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	// Encrypt the object's contents.
	wc := obj.NewWriter(ctx)
	wc.KMSKeyName = keyName
	if _, err := wc.Write([]byte("top secret")); err != nil {
		return fmt.Errorf("Writer.Write: %v", err)
	}
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %v", err)
	}
	fmt.Fprintf(w, "Uploaded blob %v with KMS key.\n", object)
	return nil
}

Node.js

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

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'Local file to upload, e.g. ./local/path/to/file.txt';
// const kmsKeyName = 'KMS key resource id, e.g. my-key';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function uploadFileWithKmsKey() {
  // Uploads a local file to the bucket with the kms key
  await storage.bucket(bucketName).upload(filename, {
    kmsKeyName,
  });

  console.log(`${filename} uploaded to ${bucketName} using ${kmsKeyName}.`);
}

uploadFileWithKmsKey().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation.

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Upload a file using KMS encryption.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName the name of your Google Cloud bucket.
 * @param string $objectName the name of the object.
 * @param string $source the path to the file to upload.
 * @param string $kmsKeyName KMS key ID used to encrypt objects server side.
 *
 * @return Psr\Http\Message\StreamInterface
 */
function upload_with_kms_key($projectId, $bucketName, $objectName, $source, $kmsKeyName)
{
    $storage = new StorageClient([
        'projectId' => $projectId,
    ]);
    $file = fopen($source, 'r');
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->upload($file, [
        'name' => $objectName,
        'destinationKmsKeyName' => $kmsKeyName,
    ]);
    printf('Uploaded %s to gs://%s/%s using encryption key %s' . PHP_EOL,
        basename($source),
        $bucketName,
        $objectName,
        $kmsKeyName);
}

Python

For more information, see the Cloud Storage Python API reference documentation.

View on GitHub Feedback

from google.cloud import storage


def object_csek_to_cmek(bucket_name, blob_name, encryption_key, kms_key_name):
    """Change a blob's customer-supplied encryption key to KMS key"""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # encryption_key = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="
    # kms_key_name = "projects/PROJ/locations/LOC/keyRings/RING/cryptoKey/KEY"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)

    current_encryption_key = base64.b64decode(encryption_key)
    source_blob = bucket.blob(blob_name, encryption_key=current_encryption_key)

    destination_blob = bucket.blob(blob_name, kms_key_name=kms_key_name)
    token, rewritten, total = destination_blob.rewrite(source_blob)

    while token is not None:
        token, rewritten, total = destination_blob.rewrite(source_blob, token=token)

    print(
        "Blob {} in bucket {} is now managed by the KMS key {} instead of a customer-supplied encryption key".format(
            blob_name, bucket_name, kms_key_name
        )
    )
    return destination_blob

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

View on GitHub Feedback

# bucket_name       = "Your Google Cloud Storage bucket name"
# local_file_path   = "Path to local file to upload"
# storage_file_path = "Path to store the file in Google Cloud Storage"
# kms_key           = "KMS key resource id"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket bucket_name

file = bucket.create_file local_file_path, storage_file_path,
                          kms_key: kms_key

puts "Uploaded #{file.name} and encrypted service side using #{file.kms_key}"

Java

For more information, see the Cloud Storage Java API reference documentation.

The following sample encrypts an object using a customer-managed encryption key:

View on GitHub Feedback

byte[] data = "Hello, World!".getBytes(UTF_8);

// The name of the existing bucket to set a default KMS key for, e.g. "my-bucket"
// String bucketName = "my-bucket"

// The name of the KMS-key to use as a default
// Key names are provided in the following format:
// 'projects/<PROJECT>/locations/<LOCATION>/keyRings/<RING_NAME>/cryptoKeys/<KEY_NAME>'
// String kmsKeyName = ""

BlobId blobId = BlobId.of(bucketName, blobName);
BlobInfo blobInfo = BlobInfo.newBuilder(blobId).setContentType("text/plain").build();
Blob blob = storage.create(blobInfo, data, BlobTargetOption.kmsKeyName(kmsKeyName));

The following sample changes the key used to encrypt an object from a customer-supplied encryption key to a customer-managed encryption key:

View on GitHub Feedback

import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ChangeObjectCSEKtoKMS {
  public static void changeObjectFromCSEKtoKMS(
      String projectId,
      String bucketName,
      String objectName,
      String decryptionKey,
      String kmsKeyName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The Base64 encoded decryption key, which should be the same key originally used to encrypt
    // the object
    // String decryptionKey = "TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=";

    // The name of the KMS key to manage this object with
    // String kmsKeyName =
    // "projects/your-project-id/locations/global/keyRings/your-key-ring/cryptoKeys/your-key";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    Storage.CopyRequest request =
        Storage.CopyRequest.newBuilder()
            .setSource(blobId)
            .setSourceOptions(Storage.BlobSourceOption.decryptionKey(decryptionKey))
            .setTarget(blobId, Storage.BlobTargetOption.kmsKeyName(kmsKeyName))
            .build();
    storage.copy(request);

    System.out.println(
        "Object "
            + objectName
            + " in bucket "
            + bucketName
            + " is now managed by the KMS key "
            + kmsKeyName
            + " instead of a customer-supplied encryption key");
  }
}

REST APIs

JSON API

Note: These steps apply specifically to inserting objects using the JSON API. You can follow a similar procedure to compose or rewrite objects with the JSON API.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Add the object's data to the request body.

3. Use cURL to call the JSON API with a POST 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

Note: These steps apply specifically to uploading objects using the XML API. You can follow a similar procedure to compose or copy objects with the XML API.

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Add the object's data to the request body.

3. Use cURL to call the XML API with a PUT 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.

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

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser

2. 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.

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 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
...

REST APIs

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the JSON API with a GET 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

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

2. Use cURL to call the XML API with a GET 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.

Note: If the object was written with an encryption method other than Cloud KMS, there is no information associated with this metadata field.

Decrypting an object

Decrypting an object encrypted with a customer-managed encryption key is performed automatically as long as the relevant service account has access to the key. For more information, see Service accounts 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.
• Explore other products that can work with Cloud KMS.