Using customer-managed encryption keys

This page describes how to use a Key Management Service encryption key with Cloud Storage, including getting started with the feature, using default keys on buckets, and adding keys to individual objects. The KMS encryption key is a customer-managed encryption key, which is created by KMS and managed by you. For details about this feature, including countries where it's available, see Customer-Managed Encryption Keys. For other encryption options in Cloud Storage, see Data Encryption Options.

Prerequisites

Before using this feature in Cloud Storage, you should:

1. Enable the 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 KMS keys.

   • The above permissions are contained in the roles/cloudkms.admin role.

     See Using IAM with Cloud KMS for instructions on how to get this or other 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 roles/storage.objectAdmin 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 KMS key ring, and have at least one key within the key ring.

   Note: You must create the KMS key in the same location as the data you intend to encrypt. For available KMS locations, see 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 KMS key to a service account

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

Console

1. Open the Key Management Service Keys browser in the Google Cloud Console.
   Open the 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.

gsutil

Use the gsutil kms authorize command to give the service account associated with your bucket permission to encrypt and decrypt objects using your 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

        public static void AddMemberToCryptoKeyPolicy(string projectId, string locationId,
            string keyRingId, string cryptoKeyId, string role, string member)
        {
            KeyManagementServiceClient client = KeyManagementServiceClient.Create();
            CryptoKeyName cryptoKeyName =
                new CryptoKeyName(projectId, locationId, keyRingId, cryptoKeyId);

            Policy policy = client.GetIamPolicy(KeyNameOneof.From(cryptoKeyName));
            policy.Bindings.Add(new Binding
            {
                Role = role,
                Members = { member }
            });

            Policy updateResult = client.SetIamPolicy(KeyNameOneof.From(cryptoKeyName), policy);

            foreach (Binding bindingResult in updateResult.Bindings)
            {
                Console.WriteLine($"Role: {bindingResult.Role}");
                foreach (string memberResult in bindingResult.Members)
                {
                    Console.WriteLine($"  Member: {memberResult}");
                }
            }
        }

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/iam"
	cloudkms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// addMemberRingPolicy adds a new member to a specified IAM role for the key ring.
func addMemberRingPolicy(w io.Writer, keyRingName, member string, role iam.RoleName) error {
	// keyRingName := "projects/PROJECT_ID/locations/global/keyRings/RING_ID"
	// member := "[e-mail]"
	// role := iam.Viewer
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("cloudkms.NewKeyManagementClient: %v", err)
	}

	// Get the KeyRing.
	keyRingObj, err := client.GetKeyRing(ctx, &kmspb.GetKeyRingRequest{Name: keyRingName})
	if err != nil {
		return fmt.Errorf("GetKeyRing: %v", err)
	}
	// Get IAM Policy.
	handle := client.KeyRingIAM(keyRingObj)
	policy, err := handle.Policy(ctx)
	if err != nil {
		return fmt.Errorf("Policy: %v", err)
	}
	// Add Member.
	policy.Add(member, role)
	if err = handle.SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("SetPolicy: %v", err)
	}
	fmt.Fprintf(w, "Added member %s to keyring policy.", member)
	return nil
}

Java

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

View on GitHub Feedback

/**
 * Adds the given member to the given key, with the given role.
 *
 * @param projectId The id of the project.
 * @param locationId The location id of the key.
 * @param keyRingId The id of the keyring.
 * @param cryptoKeyId The id of the crypto key.
 * @param member The member to add. Must be in the proper format, eg:
 *
 * allUsers user:$userEmail serviceAccount:$serviceAccountEmail
 *
 * See https://g.co/cloud/kms/docs/reference/rest/v1/Policy#binding for more details.
 * @param role Must be in one of the following formats: roles/[role]
 * organizations/[organizationId]/roles/[role] projects/[projectId]/roles/[role]
 *
 * See https://g.co/cloud/iam/docs/understanding-roles for available values for [role].
 */
public static Policy addMemberToCryptoKeyPolicy(
    String projectId, String locationId, String keyRingId, String cryptoKeyId, String member,
    String role)
    throws IOException {

  // Create the Cloud KMS client.
  try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {

    // The resource name of the cryptoKey version
    String keyName = CryptoKeyName.format(projectId, locationId, keyRingId, cryptoKeyId);

    // Get the current IAM policy
    Policy iamPolicy = client.getIamPolicy(keyName);

    // Create a new binding with the selected role and member
    Binding newBinding = Binding.newBuilder()
        .setRole(role)
        .addMembers(member)
        .build();

    // Create a new IAM policy containing the existing settings plus the new binding.
    Policy newPolicy = Policy.newBuilder()
        .mergeFrom(iamPolicy)
        .addBindings(newBinding)
        .build();

    // Set the new IAM Policy.
    Policy policyResult = client.setIamPolicy(keyName, newPolicy);

    return policyResult;
  }
}

Node.js

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

View on GitHub Feedback

async function addMemberToCryptoKeyPolicy(
  projectId = 'your-project-id', // Your GCP Project Id
  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
  cryptoKeyId = 'my-key', // Name of the crypto key
  member = 'user:[e-mail]', // Member to add to the crypto key
  role = 'roles/viewer' // Role to give the member
) {
  // Import the library and create a client
  const kms = require('@google-cloud/kms');
  const client = new kms.KeyManagementServiceClient();

  // The location of the crypto key's key ring
  const locationId = 'global';

  // Get the full path to the crypto key
  const resource = client.cryptoKeyPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId
  );

  // Gets the IAM policy of a crypto key
  const [result] = await client.getIamPolicy({resource});
  let policy = Object.assign({bindings: []}, result);
  const index = policy.bindings.findIndex(binding => binding.role === role);

  // Add the role/member combo to the policy
  const members = [];
  const binding = Object.assign({role, members}, policy.bindings[index]);
  if (index === -1) {
    policy.bindings.push(binding);
  }
  if (!binding.members.includes(member)) {
    binding.members.push(member);
  }

  // Adds the member/role combo to the policy of the crypto key
  [policy] = await client.setIamPolicy({resource, policy});
  console.log(
    `${member}/${role} combo added to policy for crypto key ${cryptoKeyId}.`
  );
  if (policy.bindings) {
    policy.bindings.forEach(binding => {
      if (binding.members && binding.members.length) {
        console.log(`${binding.role}:`);
        binding.members.forEach(member => {
          console.log(`  ${member}`);
        });
      }
    });
  } else {
    console.log(`Policy for crypto key ${cryptoKeyId} is empty.`);
  }
}

PHP

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

View on GitHub Feedback

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

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $locationId = 'The location ID of the crypto key. Can be "global", "us-west1", etc.';
// $keyRingId = 'The KMS key ring ID';
// $cryptoKeyId = 'The KMS key ID';
// $member = 'Must be in the format "user:$userEmail" or "serviceAccount:$serviceAccountEmail"';
// $role = 'Must be in the format "roles/$role", "organizations/$organizationId/roles/$role", or "projects/$projectId/roles/$role"';

$kms = new KeyManagementServiceClient();

// The resource name of the CryptoKey.
$cryptoKeyName = $kms->cryptoKeyName($projectId, $locationId, $keyRingId, $cryptoKeyId);

// Get the current IAM policy and add the new account to it.
$policy = $kms->getIamPolicy($cryptoKeyName);
$bindings = $policy->getBindings();
$bindings[] = new Binding([
    'members' => [$member],
    'role' => $role,
]);
$policy->setBindings($bindings);

// Set the new IAM Policy.
$kms->setIamPolicy($cryptoKeyName, $policy);

printf('Member %s added to policy for cryptoKey %s in keyRing %s' . PHP_EOL, $member, $cryptoKeyId, $keyRingId);

Python

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

View on GitHub Feedback

def add_member_to_crypto_key_policy(
        project_id, location_id, key_ring_id, crypto_key_id, member, role):
    """Adds a member with a given role to the Identity and Access Management
    (IAM) policy for a given CryptoKey associated with a KeyRing."""

    from google.cloud import kms_v1

    # Creates an API client for the KMS API.
    client = kms_v1.KeyManagementServiceClient()

    # The resource name of the CryptoKey.
    resource = client.crypto_key_path_path(project_id, location_id,
                                           key_ring_id, crypto_key_id)
    # Get the current IAM policy.
    policy = client.get_iam_policy(resource)

    # Add member
    policy.bindings.add(
        role=role,
        members=[member])

    # Update the IAM Policy.
    client.set_iam_policy(resource, policy)

    # Print results
    print('Member {} added with role {} to policy for CryptoKey {} \
           in KeyRing {}'.format(member, role, crypto_key_id, key_ring_id))

Ruby

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

View on GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# location_id = "The location of the key ring"
# key_ring_id = "The ID of the key ring"
# member      = "Member to add to the key ring policy"
# role        = "Role assignment for new member"

require "google/cloud/kms/v1"
CloudKMS = Google::Cloud::Kms::V1

# Initialize the client
client = CloudKMS::KeyManagementServiceClient.new

# The key ring to use
key_ring =
  CloudKMS::KeyManagementServiceClient.key_ring_path project_id, location_id, key_ring_id

# Get the current IAM policy
policy = client.get_iam_policy key_ring

# Add new member to current bindings
policy.bindings ||= []
policy.bindings << Google::Iam::V1::Binding.new(members: [member], role: role)

# Update IAM policy
client.set_iam_policy key_ring, policy

puts "Member #{member} added to policy for " +
     "key ring #{key_ring_id}"

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 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 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 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. Click Edit bucket at the top of the page.

4. In the Edit Bucket page, click the Show advanced settings expandable.

5. If the bucket isn't currently using a 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.

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:

Authorized service account [SERVICE_ACCOUNT_NAME] to use key:
[KEY_RESOURCE]

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 bucket_name, std::string key_name) {
  StatusOr<gcs::BucketMetadata> updated_metadata = client.PatchBucket(
      bucket_name, gcs::BucketMetadataPatchBuilder().SetEncryption(
                       gcs::BucketEncryption{key_name}));

  if (!updated_metadata) {
    throw std::runtime_error(updated_metadata.status().message());
  }

  if (!updated_metadata->has_encryption()) {
    std::cerr << "The change to set the encryption attribute on bucket "
              << updated_metadata->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_metadata->name() << " to "
            << updated_metadata->encryption().default_kms_key_name << "."
            << "\nFull metadata: " << *updated_metadata << "\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

bucket := c.Bucket(bucketName)
bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
	Encryption: &storage.BucketEncryption{DefaultKMSKeyName: keyName},
}
if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
	return err
}

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

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

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

/**
 * 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';

// Enables a default KMS key for the bucket
await storage.bucket(bucketName).setMetadata({
  encryption: {
    defaultKmsKeyName,
  },
});

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

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

"""Sets a bucket's default KMS 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

# project_id      = "Your Google Cloud project ID"
# 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 project_id: project_id
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 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 Overview tab.

4. The current default key for your bucket appears in the Encryption key field.

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://[BUCKET_NAME]:
[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 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. Click Edit bucket at the top of the page.

4. In the Edit Bucket page, click the Show advanced settings expandable.

5. Select the Google-managed key radio button.

6. Click Save.

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://[BUCKET_NAME]...

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 KMS key

You can encrypt an individual object with a 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 bucket_name, std::string object_name,
   std::string kms_key_name) {
  gcs::ObjectWriteStream stream = client.WriteObject(
      bucket_name, object_name, gcs::KmsKeyName(kms_key_name));

  // Line numbers start at 1.
  for (int lineno = 1; lineno <= 10; ++lineno) {
    stream << lineno << ": placeholder text for CMEK example.\n";
  }

  stream.Close();

  StatusOr<gcs::ObjectMetadata> metadata = std::move(stream).metadata();

  if (!metadata) {
    throw std::runtime_error(metadata.status().message());
  }

  std::cout << "Successfully wrote to object " << metadata->name()
            << " its size is: " << metadata->size()
            << "\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

obj := client.Bucket(bucket).Object(object)
// Encrypt the object's contents
wc := obj.NewWriter(ctx)
wc.KMSKeyName = keyName
if _, err := wc.Write([]byte("top secret")); err != nil {
	return err
}
if err := wc.Close(); err != nil {
	return err
}

Java

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

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));

Node.js

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

View on GitHub Feedback

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

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

/**
 * 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';

// 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}.`);

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

"""Uploads a file to the bucket, encrypting it with the given KMS key."""
storage_client = storage.Client()
bucket = storage_client.get_bucket(bucket_name)
blob = bucket.blob(destination_blob_name, kms_key_name=kms_key_name)
blob.upload_from_filename(source_file_name)

print('File {} uploaded to {} with encryption key {}.'.format(
    source_file_name,
    destination_blob_name,
    kms_key_name))

Ruby

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

View on GitHub Feedback

# project_id        = "Your Google Cloud project ID"
# 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 project_id: project_id

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}"

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 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. Navigate to the desired object in the relevant bucket.

3. 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://[BUCKET_NAME]/[OBJECT_NAME]:
...
KMS key: [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 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 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.
• Learn more about Key Management Service.
• Learn about customer-supplied encryption keys.