Kunden-verwaltete Verschlüsselungsschlüssel (CMEK)

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

Wenn Sie bestimmte Compliance- oder regulatorische Vorgaben in Bezug auf die Schlüssel zum Schutz Ihrer Daten haben, können Sie kundenverwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) für Document AI verwenden. Anstatt Google die Verwaltung der Verschlüsselungsschlüssel zum Schutz Ihrer Daten zu überlassen, ist Ihr Document AI-Prozessor durch einen Schlüssel geschützt, den Sie in Cloud Key Management Service (KMS) selbst erstellen, steuern und verwalten.

In diesem Leitfaden wird CMEK für Document AI beschrieben. Weitere Informationen zu CMEK im Allgemeinen, einschließlich wann und warum sie aktiviert werden sollten, finden Sie in der Dokumentation zu Cloud Key Management Service.

Voraussetzungen

Der Document AI Dienst-Agent muss die Rolle „Cloud KMS CryptoKey Encrypter/Decrypter“ für den von Ihnen 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 Document AI-Standort 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 Document AI C# API Referenzdokumentation.

Richten Sie zur Authentifizierung bei Document AI die 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.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

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

Richten Sie zur Authentifizierung bei Document AI die 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 Document AI Java API Referenzdokumentation.

Richten Sie zur Authentifizierung bei Document AI die 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 Document AI Node.js API Referenzdokumentation.

Richten Sie zur Authentifizierung bei Document AI die 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 die 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 Document AI Python API Referenzdokumentation.

Richten Sie zur Authentifizierung bei Document AI die 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 Document AI Ruby API Referenzdokumentation.

Richten Sie zur Authentifizierung bei Document AI die 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

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

Hinweis: Der Standort Ihres Schlüssels muss mit dem Standort Ihres Prozessors übereinstimmen. Wenn sich Ihr Prozessor beispielsweise in europe-west2 befindet, muss sich der entsprechende CMEK-Schlüssel ebenfalls in europe-west2 befinden. Für die us und eu Multiregionen 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 kundenspezifischen Daten, die an den Prozessor gesendet werden, 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

Sie können Cloud External Key Manager (EKM) verwenden, um externe Schlüssel zum Verschlüsseln von Daten in zu erstellen und zu verwalten Google Cloud.

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, nachdem der Schlüssel verfügbar geworden ist.

Weitere Überlegungen zur Verwendung externer Schlüssel finden Sie unter Überlegungen zu EKM.

Von CMEK unterstützte Ressourcen

Wenn Sie eine Ressource auf dem Laufwerk speichern und Kundendaten als Teil der Ressource gespeichert werden, verschlüsselt Document AI die Inhalte zuerst mit dem CMEK-Schlüssel.

Ressource	Verschlüsseltes Material
Processor	Nicht zutreffend – keine Nutzerdaten. Wenn Sie jedoch bei der Prozessorerstellung einen CMEK-Schlüssel angeben, muss dieser gültig sein.
ProcessorVersion	Alle
Evaluation	Alle

Von CMEK unterstützte APIs

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

Methode	Verschlüsselung
processDocument	Nicht zutreffend – keine Daten auf der Festplatte gespeichert.
batchProcessDocuments	Daten werden vorübergehend auf dem Laufwerk gespeichert und mit einem kurzlebigen 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	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	Für den Import von Dokumenten mit auto-labeling mit einer verschlüsselten Prozessorversion ist eine Entschlüsselung erforderlich.

CMEK und Cloud Storage

APIs wie batchProcess, können aus Cloud Storage-Buckets lesen und in sie schreiben.

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

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