Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

顧客管理の暗号鍵（CMEK）

デフォルトでは、 Google Cloud は、Google が管理する暗号鍵を使用して、保存されているデータを自動的に暗号化します。

データを保護する鍵について特定のコンプライアンスや規制の要件がある場合は、Document AI に顧客管理の暗号鍵（CMEK）を使用できます。Google がデータを保護する暗号鍵を管理するのではなく、ユーザーが Cloud Key Management Service（KMS）で制御、管理する鍵を使用して、Document AI プロセッサを保護します。

このガイドでは、Document AI の CMEK について説明します。CMEK 全般について詳しくは、 Cloud Key Management Service のドキュメントをご覧ください。

前提条件

Document AI サービスエージェントには、使用する鍵に対する Cloud KMS CryptoKey Encrypter/Decrypter のロールが必要です。

次の例では、Cloud KMS 鍵へのアクセスを提供するロールを付与します。

gcloud

gcloud kms keys add-iam-policy-binding key \
    --keyring key-ring \
    --location location \
    --project key_project_id \
    --member serviceAccount:service-project_number@gcp-sa-prod-dai-core. \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter

key は鍵の名前に置き換えます。key-ring は、鍵が配置されている鍵リングの名前に置き換えます。 location は、鍵リングの Document AI の場所に置き換えます。 key_project_id は、鍵リングのプロジェクトに置き換えます。 project_number は、プロジェクトの番号に置き換えます。

C#

詳細については、 Document AI C# API リファレンスドキュメントをご覧ください。

Document AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


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

詳細については、 Document AI 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

詳細については、 Document AI 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

詳細については、 Document AI 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

詳細については、 Document AI 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

詳細については、 Document AI 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

詳細については、 Document AI 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}"

CMEK の使用

暗号化の設定は、プロセッサを作成するときに利用できます。 CMEK を使用するには、[CMEK] オプションを選択して鍵を選択します。

security-3

CMEK 鍵は、プロセッサとその子リソースに関連付けられたすべてのデータに使用されます。プロセッサに送信される顧客関連データはすべて、ディスクに書き込まれる前に、指定された鍵で自動的に暗号化されます。

プロセッサの作成後に、暗号化の設定を変更することはできません。別の鍵を使用するには、新しいプロセッサを作成する必要があります。

外部鍵

Cloud External Key Manager（EKM）を使用して、外部鍵を作成して管理し、内のデータを暗号化できます Google Cloud。

Cloud EKM 鍵を使用する場合、Google は外部で管理される鍵の可用性を制御できません。外部で管理される鍵で暗号化されたリソースへのアクセスをリクエストし、鍵が使用できない場合、Document AI はリクエストを拒否します。鍵が使用可能になってからリソースにアクセスできるようになるまで、最大 10 分の遅延が発生する可能性があります。

外部鍵を使用する際のその他の考慮事項については、 EKM の考慮事項をご覧ください。

CMEK でサポートされているリソース

リソースをディスクに保存するときに、顧客データがリソースの一部として保存されている場合、Document AI はまず CMEK 鍵を使用してコンテンツを暗号化します。

リソース	暗号化されたマテリアル
`Processor`	該当なし - ユーザーデータはありません。ただし、プロセッサの作成時に CMEK 鍵を指定する場合は、有効である必要があります。
`ProcessorVersion`	すべて
`Evaluation`	すべて

CMEK でサポートされている API

暗号化に CMEK 鍵を使用する API は次のとおりです。

メソッド	暗号化
`processDocument`	該当なし - ディスクに保存されるデータはありません。
`batchProcessDocuments`	データは一時的にディスクに保存され、エフェメラル鍵を使用して暗号化されます（CMEK コンプライアンスをご覧ください）。
`trainProcessorVersion`	トレーニングに使用されるドキュメントは、指定された KMS/CMEK 鍵を使用して暗号化されます。
`evaluateProcessorVersion`	評価は、指定された KMS/CMEK 鍵を使用して暗号化されます。

鍵が無効になっているか、到達できない場合、暗号化されたリソースにアクセスする API リクエストは失敗します。以下に例を示します。

メソッド	復号
`getProcessorVersion`	顧客データを使用してトレーニングされたプロセッサバージョンは暗号化されます。アクセスには復号が必要です。
`processDocument`	暗号化されたプロセッサバージョンを使用してドキュメントを処理するには、復号が必要です。
`Import Documents`	暗号化されたプロセッサバージョンを使用して `auto-labeling` が有効になっているドキュメントをインポートするには、復号が必要です。

CMEK と Cloud Storage

batchProcessなどの API は、Cloud Storage バケットから読み取り、Cloud Storage バケットに書き込むことができます。

Document AI によって Cloud Storage に書き込まれたデータは、バケットに構成された暗号鍵を使用して暗号化されます。これは、プロセッサの CMEK 鍵とは異なる場合があります。

詳細については、Cloud Storage の CMEK ドキュメントをご覧ください。

セキュリティとコンプライアンス

監査ロギングを追加する