Vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK)

Standardmäßig verschlüsselt Google Cloud Daten im inaktiven Zustand automatisch mit von Google verwalteten Verschlüsselungsschlüsseln. Google Cloud

Wenn Sie bestimmte Compliance- oder behördliche Anforderungen in Bezug auf die Schlüssel zum Schutz Ihrer Daten haben, können Sie für Document AI vom Kunden verwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) verwenden. Anstatt die Verschlüsselungsschlüssel zum Schutz Ihrer Daten von Google verwalten zu lassen, wird Ihr Document AI-Prozessor mit einem Schlüssel geschützt, den Sie in Cloud Key Management Service (KMS) steuern und verwalten.

In diesem Leitfaden wird CMEK für Document AI beschrieben. Weitere allgemeine Informationen zu CMEK einschließlich ihrer Aktivierung finden Sie in der Dokumentation zum Cloud Key Management Service.

Voraussetzungen

Der Dienst-Agent für Document AI muss die Rolle Cloud KMS CryptoKey-Verschlüsseler/Entschlüsseler für den verwendeten Schlüssel haben.

Im folgenden Beispiel wird eine Rolle zugewiesen, die den Zugriff auf einen Cloud KMS-Schlüssel ermöglicht:

gcloud

gcloud kms keys add-iam-policy-binding key \
    --keyring key-ring \
    --location location \
    --project key_project_id \
    --member serviceAccount:[e-mail] \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter

Ersetzen Sie key durch den Namen des Schlüssels. Ersetzen Sie key-ring durch den Namen des Schlüsselbunds, in dem sich der Schlüssel befindet. Ersetzen Sie location durch den Speicherort für die Dokument-KI für den Schlüsselbund. Ersetzen Sie key_project_id durch das Projekt für den Schlüsselbund. Ersetzen Sie project_number durch die Nummer Ihres Projekts.

C#

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI C# API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

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

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

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

        // Get the current IAM policy.
        Policy policy = client.IAMPolicyClientte-xref-link" href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html" track-type="exampleCode" track-name="xrefLink" track-metadata-lang="DOT"NET" track-metadata-modifier="Google.Cloud".Iam.V1" track-metadata-href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html">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.IAMPolicyClientte-xref-link" href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html" track-type="exampleCode" track-name="xrefLink" track-metadata-lang="DOTNET" track-metadata-modifier="Google.Cloud.Iam.V1" track-metadata-href="https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Iam.V1/latest/Google.Cloud.Iam.V1.IAMPolicyClient.html">IAMPolicyClient.SetIamPolicy(
            new SetIamPolicyRequest
            {
                ResourceAsResourceName = resourceName,
                Policy = policy
            });

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

Go

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI Go API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

import (
	"context"
	"fmt"
	"io"

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

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

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %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

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI Java API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

public class IamAddMember {

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

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

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

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

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

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

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

Node.js

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI Node.js API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

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

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

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

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

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

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

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

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

return iamAddMember();

PHP

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI PHP API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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:[e-mail]'
) {
    // Create the Cloud KMS client.
    $client = new KeyManagementServiceClient();

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

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

    // Get the current IAM policy.
    $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

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI Python API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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:[e-mail]')

    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

Weitere Informationen finden Sie in der Referenzdokumentation zur Document AI Ruby API.

Richten Sie zur Authentifizierung bei Document AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

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

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

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

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

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

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

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

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

CMEK verwenden

Verschlüsselungseinstellungen sind verfügbar, wenn Sie einen Prozessor erstellen. Wenn Sie CMEK verwenden möchten, wählen Sie die Option CMEK und dann einen Schlüssel aus.

Hinweis: Der Speicherort Ihres Schlüssels muss mit dem Speicherort Ihres Prozessors übereinstimmen. Wenn sich Ihr Prozessor beispielsweise in europe-west2 befindet, muss sich der entsprechende CMEK-Schlüssel auch in europe-west2 befinden. Bei den Multi-Regionen us und eu muss sich der Schlüssel jedoch in us-central1 bzw. europe-west4 befinden.

Der CMEK-Schlüssel wird für alle Daten verwendet, die mit dem Prozessor und seinen untergeordneten Ressourcen verknüpft sind. Alle an den Auftragsverarbeiter gesendeten kundenbezogenen Daten werden automatisch mit dem angegebenen Schlüssel verschlüsselt, bevor sie auf die Festplatte geschrieben werden.

Nachdem ein Prozessor erstellt wurde, können Sie seine Verschlüsselungseinstellungen nicht mehr ändern. Wenn Sie einen anderen Schlüssel verwenden möchten, müssen Sie einen neuen Prozessor erstellen.

Externe Schlüssel

Mit Cloud External Key Manager (EKM) können Sie externe Schlüssel erstellen und verwalten, um Daten in Google Cloudzu verschlüsseln.

Wenn Sie einen Cloud EKM-Schlüssel verwenden, hat Google keine Kontrolle über die Verfügbarkeit Ihres extern verwalteten Schlüssels. Wenn Sie Zugriff auf eine Ressource anfordern, die mit einem extern verwalteten Schlüssel verschlüsselt ist, und der Schlüssel nicht verfügbar ist, lehnt Document AI die Anfrage ab. Es kann bis zu 10 Minuten dauern, bis Sie auf die Ressource zugreifen können, sobald der Schlüssel verfügbar ist.

Weitere Informationen zur Verwendung externer Schlüssel finden Sie unter EKM-Hinweise.

Von CMEK unterstützte Ressourcen

Wenn beim Speichern einer Ressource auf dem Laufwerk Kundendaten als Teil der Ressource gespeichert werden, verschlüsselt Document AI den Inhalt zuerst mit dem CMEK-Schlüssel.

Ressource	Verschlüsseltes Material
Processor	– keine Nutzerdaten Wenn Sie jedoch beim Erstellen des Prozessors einen CMEK-Schlüssel angeben, muss dieser gültig sein.
ProcessorVersion	Alle
Evaluation	Alle

Von CMEK unterstützte APIs

Die folgenden APIs verwenden den CMEK-Schlüssel für die Verschlüsselung:

Methode	Verschlüsselung
processDocument	– keine Daten auf dem Laufwerk gespeichert
batchProcessDocuments	Die Daten werden vorübergehend auf der Festplatte gespeichert und mit einem sitzungsspezifischen Schlüssel verschlüsselt (siehe CMEK-Compliance).
trainProcessorVersion	Für das Training verwendete Dokumente werden mit dem angegebenen KMS-/CMEK-Schlüssel verschlüsselt.
evaluateProcessorVersion	Die Bewertungen werden mit dem angegebenen KMS-/CMEK-Schlüssel verschlüsselt.

API-Anfragen, die auf verschlüsselte Ressourcen zugreifen, schlagen fehl, wenn der Schlüssel deaktiviert oder nicht erreichbar ist. Beispiele:

Methode	Entschlüsselung
getProcessorVersion	Mit Kundendaten trainierte Prozessorversionen werden verschlüsselt. Für den Zugriff ist eine Entschlüsselung erforderlich.
processDocument	Für die Verarbeitung von Dokumenten mit einer verschlüsselten Prozessorversion ist eine Entschlüsselung erforderlich.
Import Documents	Wenn Sie Dokumente mit aktivierter auto-labeling mit einer verschlüsselten Prozessorversion importieren, ist eine Entschlüsselung erforderlich.

CMEK und Cloud Storage

Mit APIs wie der batchProcess können Sie in Cloud Storage-Buckets lesen und schreiben.

Alle Daten, die von Document AI in Cloud Storage geschrieben werden, werden mit dem konfigurierten Verschlüsselungsschlüssel des Buckets verschlüsselt. Dieser Schlüssel kann sich vom CMEK-Schlüssel Ihres Prozessors unterscheiden.

Weitere Informationen finden Sie in der CMEK-Dokumentation für Cloud Storage.