本頁面由 Cloud Translation API 翻譯而成。

使用客戶自行管理的加密金鑰

本頁說明如何搭配使用 Cloud Storage 與手動建立的 Cloud Key Management Service 加密金鑰，包括在值區中設定預設金鑰，以及將金鑰新增至個別物件。Cloud KMS 加密金鑰為「客戶代管的加密金鑰」 (CMEK)。這類金鑰是透過 Cloud KMS 建立及管理，並以軟體金鑰的形式儲存在 HSM 叢集或外部。

如要改用 Cloud KMS Autokey 功能，視需要產生金鑰環和金鑰，保護 Cloud Storage 值區和其中的物件，請參閱搭配 Cloud Storage 資源使用 Autokey。如要比較 CMEK 與使用 Autokey 的 Cloud KMS 和 Google 預設加密機制，並決定適合您的金鑰類型，請參閱「CMEK 與 Google-owned and Google-managed encryption keys」。

事前準備

在 Cloud Storage 中使用這項功能之前，請務必：

針對要用來儲存加密金鑰的專案啟用 Cloud KMS API。

啟用 API
針對要用來儲存加密金鑰的專案取得足夠的權限：
- 如果您擁有要用來儲存金鑰的專案，代表您非常有可能已經具備必要權限。
- 如果您打算建立新的加密金鑰環和金鑰，您必須具備 cloudkms.keyRings.create 和 cloudkms.cryptoKeys.create 權限。
- 無論您要使用新的或現有的金鑰環和金鑰，都必須針對要用於加密的金鑰具備 cloudkms.cryptoKeys.setIamPolicy 權限。
  
  這項權限可讓您向 Cloud Storage 服務代理授予 Cloud KMS 金鑰的存取權。
- Cloud KMS 管理員角色中包含了以上所有權限。
  
  如需取得這個角色或其他 Cloud KMS 角色的說明，請參閱對 Cloud KMS 使用身分與存取權管理一文。
具備 Cloud KMS 金鑰環，並且在金鑰環中至少具備一組金鑰。

金鑰環的位置必須與待加密資料相同，但可以位於不同專案。如需 Cloud KMS 可用位置資訊，請參閱 Cloud KMS 位置。

注意： 如果是雙區域中的值區，Cloud KMS 位置必須與雙區域相關聯的位置代碼相符。也就是說，如果是可設定的雙區域，您必須在相關聯的多區域中建立金鑰環；如果是預先定義的雙區域，則必須在同一個預先定義的雙區域中建立金鑰環。
針對要在 Cloud Storage 值區中使用的物件取得足夠的權限：
- 如果您擁有包含該值區的專案，代表您非常有可能已經具備必要權限。
- 如果您使用身分與存取權管理，您應具備 storage.objects.create 權限來寫入物件到值區，並具備 storage.objects.get 權限來從值區讀取物件。請參閱使用 IAM 權限的操作說明，瞭解如何取得具有這些權限的角色 (如Storage 物件管理員)。
- 如果您使用 ACL，您應具備值區範圍的 WRITER 權限來寫入物件到值區，以及物件範圍的 READER 權限來從值區讀取物件。相關操作說明請參閱設定 ACL 一節。
注意： 如果您使用 Google Cloud CLI，以下為非必要步驟。

針對與包含 Cloud Storage 值區的專案相關聯的服務代理，取得服務代理的電子郵件地址。執行這個步驟時，系統會自動建立服務代理 (如果目前沒有的話)。

為服務代理指派 Cloud KMS 金鑰

如要使用 CMEK，請授予與值區相關聯的 Cloud Storage 服務代理，使用 Cloud KMS 金鑰加密及解密的權限：

控制台

前往 Google Cloud 控制台的「金鑰管理」頁面。
前往「金鑰管理」
按一下包含要使用金鑰的金鑰環名稱。
選取要使用金鑰的核取方塊。

右邊窗格的「Permissions」(權限) 分頁隨即顯示。
在「新增主體」對話方塊中，指定授予存取權的 Cloud Storage 服務代理程式電子郵件地址。
在「Select a role」(選取角色) 下拉式清單中，選取 [Cloud KMS CryptoKey Encrypter/Decrypter] (Cloud KMS CryptoKey 加密者/解密者)。
按一下「新增」。

如要瞭解如何透過 Google Cloud 控制台取得 Cloud Storage 作業失敗的詳細錯誤資訊，請參閱「疑難排解」一文。

指令列

使用 gcloud storage service-agent 指令搭配 --authorize-cmek 標記，為與值區相關聯的服務代理提供利用 Cloud KMS 金鑰加密或解密物件的權限：

gcloud storage service-agent --project=PROJECT_STORING_OBJECTS --authorize-cmek=KEY_RESOURCE

其中：

PROJECT_STORING_OBJECTS 是包含您要加密或解密之物件的專案 ID 或編號。例如：my-pet-project。
KEY_RESOURCE 是您的 Cloud KMS 金鑰資源。

用戶端程式庫

C#

詳情請參閱 Cloud Storage C# API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


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:foo@example.com")
    {
        // 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.IAMPolicyClient.GetIamPolicy(
            new GetIamPolicyRequest
            { 
                ResourceAsResourceName = resourceName
            });

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

        // Save the updated IAM policy.
        Policy result = client.IAMPolicyClient.SetIamPolicy(
            new SetIamPolicyRequest
            {
                ResourceAsResourceName = resourceName,
                Policy = policy
            });

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

Go

詳情請參閱 Cloud Storage Go API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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:foo@example.com"

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

	// 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: %w", 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: %w", err)
	}

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

Java

詳情請參閱 Cloud Storage Java API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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:foo@example.com";
    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

詳情請參閱 Cloud Storage Node.js API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

//
// 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:foo@example.com';

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

詳情請參閱 Cloud Storage PHP API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\Iam\V1\Binding;
use Google\Cloud\Iam\V1\GetIamPolicyRequest;
use Google\Cloud\Iam\V1\SetIamPolicyRequest;
use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;

function iam_add_member(
    string $projectId = 'my-project',
    string $locationId = 'us-east1',
    string $keyRingId = 'my-key-ring',
    string $keyId = 'my-key',
    string $member = 'user:foo@example.com'
) {
    // 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.
    $getIamPolicyRequest = (new GetIamPolicyRequest())
        ->setResource($resourceName);
    $policy = $client->getIamPolicy($getIamPolicyRequest);

    // 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.
    $setIamPolicyRequest = (new SetIamPolicyRequest())
        ->setResource($resourceName)
        ->setPolicy($policy);
    $updatedPolicy = $client->setIamPolicy($setIamPolicyRequest);
    printf('Added %s' . PHP_EOL, $member);

    return $updatedPolicy;
}

Python

詳情請參閱 Cloud Storage Python API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

from google.cloud import kms
from google.iam.v1 import policy_pb2 as iam_policy


def iam_add_member(
    project_id: str, location_id: str, key_ring_id: str, key_id: str, member: str
) -> iam_policy.Policy:
    """
    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:foo@example.com')

    Returns:
        Policy: Updated Cloud IAM policy.

    """

    # 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(f"Added {member} to {resource_name}")
    return updated_policy

Ruby

詳情請參閱 Cloud Storage Ruby API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

# 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:foo@example.com"

# 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 API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立包含下列資訊的 JSON 檔案：

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

其中 SERVICE_AGENT_EMAIL_ADDRESS 是與服務代理程式相關聯的電子郵件地址。例如：service-7550275089395@gs-project-accounts.iam.gserviceaccount.com。

使用 cURL 透過 POST setIamPolicy 要求呼叫 Cloud KMS API：

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"

其中：

JSON_FILE_NAME 是您在步驟 2 建立的 JSON 檔案路徑。
KEY_RESOURCE 是您的 Cloud KMS 金鑰資源。

XML API

XML API 無法用於將 Cloud KMS 指派到服務代理程式。請改用 gcloud CLI 等其他 Cloud Storage 工具。

使用預設加密金鑰

設定 bucket 的預設金鑰

如要在寫入物件到值區時，新增、變更或移除依預設使用的 Cloud KMS 金鑰：

控制台

在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。

前往「Buckets」(值區) 頁面
在值區清單中，按一下所需值區的名稱。
在「Bucket details」(值區詳細資料) 頁面中，按一下「Configuration」(設定) 分頁標籤。
按一下與「加密類型」項目相關的鉛筆圖示。
設定或移除值區的預設 Cloud KMS 金鑰。
1. 如果該值區目前並未使用 Cloud KMS 金鑰，請選取「客戶管理的金鑰」圓形按鈕，然後在相關聯的下拉式選單中選取其中一個可用金鑰。
2. 如果該值區目前使用 Cloud KMS 金鑰，請在下拉式選單中變更 Cloud KMS 金鑰，或選取 Google-managed encryption key 圓形按鈕來移除 Cloud KMS 金鑰。
按一下 [儲存]。

如要瞭解如何透過 Google Cloud 控制台取得 Cloud Storage 作業失敗的詳細錯誤資訊，請參閱「疑難排解」一文。

指令列

使用 gcloud storage buckets update 指令並加上適當的旗標：

gcloud storage buckets update gs://BUCKET_NAME FLAG

其中：

BUCKET_NAME 是相關值區的名稱。例如：my-bucket。
FLAG 是值區中預設金鑰的所需設定。請使用下列其中一種格式：
- --default-encryption-key= 和 Cloud KMS 金鑰資源 (如要新增或變更預設金鑰)。
- --clear-default-encryption-key，如要移除 Bucket 的預設金鑰。

如果成功，回應如下所示：

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

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：

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::move(updated).status();

  if (!updated->has_encryption()) {
    std::cerr << "The change to set the encryption attribute on bucket "
              << updated->name()
              << " was successful, 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";
}

下例示範如何從值區移除預設的客戶代管加密金鑰：

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::move(updated).status();

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

C#

詳情請參閱 Cloud Storage C# API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class EnableDefaultKMSKeySample
{
    public Bucket EnableDefaultKMSKey(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name",
        string keyLocation = "us-west1",
        string kmsKeyRing = "kms-key-ring",
        string kmsKeyName = "key-name")
    {
        // KMS Key identifier of an already created KMS key.
        // If you use the Google.Cloud.Kms.V1 library, you can construct these names using helper class CryptoKeyName.
        // var fullKeyName = new CryptoKeyName(projectId, keyLocation, kmsKeyRing, kmsKeyName).ToString();
        string keyPrefix = $"projects/{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);
        Console.WriteLine($"Default KMS key for {bucketName} was set to {kmsKeyName}.");
        return updatedBucket;
    }
}

下例示範如何從值區移除預設的客戶代管加密金鑰：


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketDeleteDefaultKmsKeySample
{
    public Bucket BucketDeleteDefaultKmsKey(string bucketName = "your-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName);

        if (bucket.Encryption == null)
        {
            Console.WriteLine("No default kms key to remove");
        }
        else
        {
            bucket.Encryption.DefaultKmsKeyName = null;
            bucket = storage.UpdateBucket(bucket);
            Console.WriteLine($"Default KMS key was removed from {bucketName}. ");
        }

        return bucket;
    }
}

Go

詳情請參閱 Cloud Storage Go API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：

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: %w", 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: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Default KMS Key Name: %v", bucketAttrsToUpdate.Encryption.DefaultKMSKeyName)
	return nil
}

下例示範如何從值區移除預設的客戶代管加密金鑰：

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

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

// removeBucketDefaultKMSKey removes any default Cloud KMS key set on a bucket.
func removeBucketDefaultKMSKey(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

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

Java

詳情請參閱 Cloud Storage Java API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：


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

public class SetBucketDefaultKmsKey {
  public static void setBucketDefaultKmsKey(String projectId, String bucketName, String kmsKeyName)
      throws StorageException {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The name of the KMS key to use as a default
    // String kmsKeyName =
    // "projects/your-project-id/locations/us/keyRings/my_key_ring/cryptoKeys/my_key"

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    // first look up the bucket, so we will have its metageneration
    Bucket bucket = storage.get(bucketName);

    Bucket updated =
        storage.update(
            bucket.toBuilder().setDefaultKmsKeyName(kmsKeyName).build(),
            BucketTargetOption.metagenerationMatch());

    System.out.println(
        "KMS Key "
            + updated.getDefaultKmsKeyName()
            + "was set to default for bucket "
            + bucketName);
  }
}

下例示範如何從值區移除預設的客戶代管加密金鑰：

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.Storage.BucketTargetOption;
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();
    // first look up the bucket, so we will have its metageneration
    Bucket bucket = storage.get(bucketName);
    storage.update(
        bucket.toBuilder().setDefaultKmsKeyName(null).build(),
        BucketTargetOption.metagenerationMatch());

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

Node.js

詳情請參閱 Cloud Storage Node.js API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The name of the KMS-key to use as a default
// const defaultKmsKeyName = '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);

下例示範如何從值區移除預設的客戶代管加密金鑰：

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

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

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

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

  console.log(`Default KMS key was removed from ${bucketName}`);
}

removeDefaultKMSKey().catch(console.error);

PHP

詳情請參閱 Cloud Storage PHP API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：

use Google\Cloud\Storage\StorageClient;

/**
 * Enable a bucket's requesterpays metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $kmsKeyName The KMS key to use as the default KMS key.
 *     Key names are provided in the following format:
 *     `projects/<PROJECT>/locations/<LOCATION>/keyRings/<RING_NAME>/cryptoKeys/<KEY_NAME>`.
 */
function enable_default_kms_key(string $bucketName, string $kmsKeyName): void
{
    $storage = new StorageClient();
    $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']);
}

下例示範如何從值區移除預設的客戶代管加密金鑰：

use Google\Cloud\Storage\StorageClient;

/**
 * Delete the default KMS key on the given bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function bucket_delete_default_kms_key(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $objects = $bucket->objects([
        'encryption' => [
            'defaultKmsKeyName' => null,
        ]
    ]);

    printf('Default KMS key was removed from %s', $bucketName);
}

Python

詳情請參閱 Cloud Storage Python API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：

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

下例示範如何從值區移除預設的客戶代管加密金鑰：

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(f"Default KMS key was removed from {bucket.name}")
    return bucket

Ruby

詳情請參閱 Cloud Storage Ruby API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下例示範如何對值區設定預設的客戶管理加密金鑰：

def set_bucket_default_kms_key bucket_name:, default_kms_key:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

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

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

下例示範如何從值區移除預設的客戶代管加密金鑰：

def bucket_delete_default_kms_key bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

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

  bucket.default_kms_key = nil

  puts "Default KMS key was removed from #{bucket_name}"
end

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立包含下列資訊的 JSON 檔案：
```
{
  "encryption": {
    "defaultKmsKeyName": "KEY_RESOURCE"
  }
}
```
其中 KEY_RESOURCE 是您的 Cloud KMS 金鑰資源。

如要從值區移除預設的 Cloud KMS 金鑰，請在 JSON 檔案中使用下列項目：
```
{
  "encryption": {
    "defaultKmsKeyName": null
  }
}
```

使用 cURL 來透過 PATCH 值區要求呼叫 JSON API：

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"

其中：

JSON_FILE_NAME 是您在步驟 2 建立的 JSON 檔案路徑。
BUCKET_NAME 是相關值區的名稱。例如：my-bucket。

XML API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立包含下列資訊的 XML 檔案：
```
<EncryptionConfiguration>
  <DefaultKmsKeyName>KEY_RESOURCE</DefaultKmsKeyName>
</EncryptionConfiguration>
```
其中 KEY_RESOURCE 是您的 Cloud KMS 金鑰資源。

如要從值區移除預設的 Cloud KMS 金鑰，請在 XML 檔案中使用下列項目：
```
<EncryptionConfiguration></EncryptionConfiguration>
```
使用 cURL 透過 PUT 值區要求和 encryptionConfig 查詢字串參數呼叫 XML API：
```
curl -X PUT --data-binary @XML_FILE_NAME \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
```
其中：
- XML_FILE_NAME 是您在步驟 2 建立的 XML 檔案路徑。
- BUCKET_NAME 是相關值區的名稱。例如：my-bucket。

查看值區的預設金鑰

如要查看目前為值區預設的 Cloud KMS 金鑰：

控制台

在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。

前往「Buckets」(值區) 頁面
在值區清單中，按一下所需值區的名稱。
在「Bucket details」(值區詳細資料) 頁面中，按一下「Configuration」(設定) 分頁標籤。
目前值區預設的金鑰會出現在「Encryption key」(加密金鑰) 欄位。

如要瞭解如何透過 Google Cloud 控制台取得 Cloud Storage 作業失敗的詳細錯誤資訊，請參閱「疑難排解」一文。

指令列

使用加上 --format 旗標的 gcloud storage buckets describe 指令：

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

其中 BUCKET_NAME 是您要查看其金鑰的值區名稱。例如：my-bucket。

如果成功，回應如下所示：

default_kms_key: KEY_RESOURCE

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考說明文件。

如要驗證 Cloud Storage，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> metadata =
      client.GetBucketMetadata(bucket_name);
  if (!metadata) throw std::move(metadata).status();

  if (!metadata->has_encryption()) {
    std::cout << "The bucket " << metadata->name()
              << " does not have a default KMS key set.\n";
    return;
  }

  std::cout << "The default KMS key for bucket " << metadata->name()
            << " is: " << metadata->encryption().default_kms_key_name << "\n";
}