顧客管理の暗号鍵を使用する

概要

このページでは、バケットでデフォルトの鍵を設定する方法や個々のオブジェクトに鍵を追加する方法など、手動で作成した Cloud Key Management Service の暗号鍵を Cloud Storage で使用する方法について説明します。Cloud KMS 暗号鍵は顧客管理の暗号鍵（CMEK）です。このような鍵は、Cloud KMS で作成および管理され、HSM クラスタ内または外部でソフトウェア鍵として保存されます。

代わりに、Cloud KMS の Autokey 機能を使用して Cloud Storage バケットとその中のオブジェクトを保護するキーリングと鍵をオンデマンドで生成する場合は、Cloud Storage リソースでの Autokey の使用をご覧ください。CMEK と Cloud KMS with Autokey や Google のデフォルト暗号化を比較して適切な鍵タイプを判断するには、CMEK と Google が所有し管理する鍵の比較をご覧ください。

始める前に

Cloud Storage でこの機能を使用する前に、以下の準備が必要です。

暗号鍵を格納するプロジェクトの Cloud KMS API を有効にする。

API を有効にする
暗号鍵を格納するプロジェクトに対して十分な権限を持つ。
- 鍵が保存されるプロジェクトを所有している場合は、必要な権限があると考えられます。
- 新しい暗号キーリングと鍵を作成する予定がある場合は、cloudkms.keyRings.create と cloudkms.cryptoKeys.create の権限が必要です。
- キーリングと鍵を使用する予定がある場合は、それが新規か既存かを問わず、暗号化に使用する鍵に対する cloudkms.cryptoKeys.setIamPolicy 権限が必要です。
  
  この権限があると、Cloud Storage サービスエージェントに Cloud KMS 鍵へのアクセス権を付与できます。
- 上記の権限は、Cloud KMS 管理者ロールに含まれています。
  
  この役割を含め、Cloud KMS の役割の取得方法については、IAM と Cloud KMS の使用をご覧ください。
Cloud KMS キーリングと、キーリング内に少なくとも 1 つの鍵を持っている。

キーリングは暗号化するデータと同じロケーションに存在する必要がありますが、別のプロジェクトに配置することもできます。指定できる Cloud KMS のロケーションについては、Cloud KMS のロケーションをご覧ください。

注: デュアルリージョンのバケットの場合、Cloud KMS のロケーションはデュアルリージョンに関連付けられたロケーションコードと一致する必要があります。つまり、構成可能なデュアルリージョンの場合は、関連付けられたマルチリージョンにキーリングを作成する必要がありますが、事前定義されたデュアルリージョンの場合は、同じ事前定義されたデュアルリージョンにキーリングを作成する必要があります。
Cloud Storage バケット内のオブジェクトを操作するための十分な権限を持つ。
- バケットを含むプロジェクトを所有している場合は、必要な権限を持っていると考えられます。
- IAM を使用する場合は、バケットにオブジェクトを書き込むための storage.objects.create 権限とバケットからオブジェクトを読み取るための storage.objects.get 権限が必要です。これらの権限を持つロール（ストレージオブジェクト管理者など）を取得する手順については、IAM 権限の使用をご覧ください。
- ACL を使用する場合は、バケットにオブジェクトを書き込むためのバケット範囲の WRITER 権限とバケットからオブジェクトを読み取るためのオブジェクト範囲の READER 権限が必要です。設定方法については、ACL の設定をご覧ください。
注: Google Cloud CLI を使用している場合は、次の操作を行う必要はありません。
Cloud Storage バケットを含むプロジェクトに関連付けられているサービスエージェントのメールアドレスを取得する。この手順を行うと、サービスエージェントが自動的に作成されます（存在しない場合）。

サービスエージェントに Cloud KMS 鍵を割り当てる

CMEK を使用するには、バケットに関連付けられている Cloud Storage サービスエージェントに、Cloud KMS 鍵を使用して暗号化と復号を行う権限を付与します。

コンソール

Google Cloud コンソールで Cloud Key Management Service 鍵のブラウザを開きます。
Cloud KMS 鍵のブラウザを開く
使用する鍵を含むキーリングの名前をクリックします。
使用する鍵のチェックボックスをオンにします。

右側のウィンドウの [権限] タブが有効になります。
[プリンシパルを追加] ダイアログで、アクセス権を付与する Cloud Storage サービスエージェントのメールアドレスを指定します。
[ロールを選択] プルダウンで、[クラウド KMS 暗号鍵の暗号化 / 復号化] を選択します。
[追加] をクリックします。

失敗した Cloud Storage オペレーションの詳細なエラー情報を Google Cloud コンソールで確認する方法については、トラブルシューティングをご覧ください。

コマンドライン

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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。

//
// 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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。

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 のリファレンスドキュメントをご覧ください。

# 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 ツールを使用してください。

デフォルトの暗号鍵を使用する

バケットのデフォルトの鍵を設定する

オブジェクトがバケットに書き込まれたときにデフォルトで使用される Cloud KMS 鍵を追加、変更、または削除するには:

コンソール

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、目的のバケットの名前をクリックします。
[バケットの詳細] ページで、[構成] タブをクリックします。
暗号化タイプのエントリに関連付けられた鉛筆アイコンをクリックします。
バケットのデフォルトの Cloud KMS 鍵を設定または削除します。
1. 現在、バケットで Cloud KMS 鍵が使用されていない場合は、[顧客管理の暗号鍵] ラジオボタンを選択し、関連するプルダウンメニューで使用可能な鍵を選択します。
2. バケットで現在 Cloud KMS 鍵が使用されている場合は、プルダウンメニューで Cloud KMS 鍵を変更するか、[Google が管理する暗号鍵] ラジオボタンを選択して Cloud KMS 鍵を削除します。
[保存] をクリックします。

コマンドライン

適切なフラグを指定して、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。

成功した場合、レスポンスは次のようになります。

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