Kunden-verwaltete Verschlüsselungsschlüssel (CMEK)

Gemini Data Analytics verschlüsselt ruhende Kundeninhalte standardmäßig. Die Verschlüsselung wird von Gemini Data Analytics für Sie übernommen. Weitere Maßnahmen Ihrerseits sind nicht erforderlich. Diese Option heißt Google-Standardverschlüsselung.

Wenn Sie Ihre Verschlüsselungsschlüssel selbst verwalten möchten, können Sie vom Kunden verwaltete Verschlüsselungsschlüssel (CMEKs, Customer-Managed Encryption Keys) in Cloud KMS mit CMEK-integrierten Diensten wie Gemini Data Analytics verwenden. Mit Cloud KMS-Schlüsseln haben Sie die Kontrolle über Schutzlevel, Speicherort, Rotationszeitplan, Nutzungs- und Zugriffsberechtigungen sowie über kryptografische Grenzen. Mit Cloud KMS können Sie außerdem Audit-Logs aufrufen und den Lebenszyklus von Schlüsseln steuern. Statt es Google zu überlassen, die symmetrischen Schlüsselverschlüsselungsschlüssel (Key Encryption Keys, KEKs) zum Schutz Ihrer Daten zu besitzen und zu verwalten, können Sie diese auch über Cloud KMS steuern und verwalten.

Nachdem Sie Ihre Ressourcen mit CMEKs eingerichtet haben, ähnelt der Zugriff auf Ihre Gemini Data Analytics-Ressourcen der Verwendung der Standard-Verschlüsselung von Google. Weitere Informationen zu Ihren Verschlüsselungsoptionen finden Sie unter Kundenverwaltete Verschlüsselungsschlüssel (CMEK).

Auf dieser Seite wird beschrieben, wie Sie kundenverwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) verwenden, um Daten zu schützen, die von der Conversational Analytics API verwendet werden. Die Conversational Analytics API ist ein Produkt im Gemini Data Analytics-Dienst (geminidataanalytics.googleapis.com).

CMEK für Conversational Analytics API-Ressourcen

Wenn Sie CMEK für eine Conversational Analytics API-Ressource konfigurieren, werden die sensiblen ruhenden Daten mit dem angegebenen Cloud KMS-Schlüssel verschlüsselt. Sie können CMEK für DataAgent- und Conversation-Ressourcen unabhängig voneinander konfigurieren.

CMEK für die Conversational Analytics API ist nur an regionalen und multiregionalen Standorten verfügbar, nicht am Standort global. Informationen zu den von den einzelnen Datenquellen unterstützten Speicherorten finden Sie unter Unterstützte Datenspeicherorte.

Mit CMEK geschützte Inhalte

CMEK für die Conversational Analytics API schützt die folgenden inaktiven Daten:

  • Bei DataAgent-Ressourcen werden alle zentralen Kundendaten im Feld data_analytics_agent geschützt. Dieser Inhalt umfasst die Felder staging_context, published_context und last_published_context sowie die Felder system_instruction und example_queries.
  • Bei Conversation-Ressourcen werden alle Nachrichten- und Statusverlaufsdaten geschützt.

Die folgenden Daten werden nicht mit dem CMEK-Schlüssel des Kunden verschlüsselt. Stattdessen werden diese Daten durch die standardmäßige Google-Verschlüsselung geschützt:

  • Bei DataAgent-Ressourcen schützt die standardmäßige Google-Verschlüsselung Metadatenfelder wie name, display_name, description, labels, create_time, update_time, delete_time, purge_time und kms_key.
  • Bei Conversation-Ressourcen schützt die standardmäßige Google-Verschlüsselung Metadatenfelder wie name, agents, labels, create_time, last_used_time und kms_key.

Beschränkungen

Für CMEK für die Conversational Analytics API gelten die folgenden Einschränkungen:

  • CMEK muss beim Erstellen der Ressource konfiguriert werden. Sie kann nicht zu einer vorhandenen Ressource hinzugefügt oder geändert werden.
  • CMEK-Organisationsrichtlinien werden nicht unterstützt.
  • Der erforderliche Speicherort des Cloud KMS-Schlüssels hängt vom Ressourcentyp und vom Speicherort ab. In einer einzelnen Region muss sich der Schlüssel in derselben Region wie die Ressource befinden. In der multiregionalen Region us oder eu unterscheidet sich der Schlüsselspeicherort für DataAgent- und Conversation-Ressourcen. Weitere Informationen finden Sie unter Standortanforderungen.
  • Die Region global wird nicht unterstützt.
  • Sie können pro Projekt und Region nur einen CMEK für alle Conversation-Ressourcen in diesem Projekt und dieser Region verwenden.

Wichtige Standortanforderungen

Der erforderliche Speicherort des Cloud KMS-Schlüssels hängt vom Typ der zu schützenden Ressource und vom Speicherort dieser Ressource ab:

Ressourcenstandort Schlüsselspeicherort für DataAgent-Ressourcen Schlüsselspeicherort für Conversation-Ressourcen
us, multiregional us us-central1
eu, multiregional europe europe-west1
Eine einzelne Region, z. B. us-east4 Dieselbe Region wie die Ressource Dieselbe Region wie die Ressource

DataAgent-Ressourcen in einer Multiregion werden in der Multiregion gespeichert, die im Ressourcennamen angegeben ist. Der Schlüssel muss sich also in der entsprechenden Cloud KMS-Multiregion befinden. Für die multiregionale Region us ist der Cloud KMS-Standort ebenfalls us. Für die multiregionale eu-Region ist der Cloud KMS-Standort europe, da Cloud KMS keinen eu-Standort hat. Weitere Informationen finden Sie unter Cloud KMS-Standorte.

Conversation-Ressourcen in einer Multiregion werden in einer bestimmten Region innerhalb dieser Multiregion gespeichert: us-central1 für us und europe-west1 für eu. Der Schlüssel muss sich in dieser Region befinden. Wenn Sie beispielsweise eine Conversation-Ressource mit dem Namen projects/PROJECT_ID/locations/us/conversations/CONVERSATION_ID schützen möchten, verwenden Sie einen Schlüssel am Standort us-central1.

Hinweis

Bevor Sie CMEK mit der Conversational Analytics API verwenden können, müssen Sie die folgenden Schritte ausführen:

  1. Aktivieren Sie die erforderlichen APIs in der Google Cloud Console oder der Google Cloud CLI.

    Console

    Aktivieren Sie die folgenden APIs in der Google Cloud Console für Ihr Projekt in Google Cloud .

    Gemini Data Analytics API aktivieren

    Gemini für Google Cloud API aktivieren

    Cloud Key Management Service API aktivieren

    gcloud

    Führen Sie mit der Google Cloud CLI die folgenden gcloud services enable-Befehle aus, um die Gemini Data Analytics API, die Gemini for Google Cloud API und die Cloud Key Management Service API zu aktivieren:

    gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id

    Ersetzen Sie in den vorherigen Beispielbefehlen der gcloud CLI project_id durch die Projekt-ID Ihres Projekts in Google Cloud .

  2. Erstellen Sie einen Cloud KMS-Schlüsselbund und einen Schlüssel am Standort, der für Ihre Conversational Analytics API-Ressourcen erforderlich ist, wie unter Anforderungen an den Schlüsselspeicherort beschrieben. Weitere Informationen finden Sie unter Schlüssel erstellen.

  3. Erstellen Sie die von Google verwalteten Dienst-Agents, auch als P4SAs (Per-Product-Per-Project Service Accounts) bezeichnet, falls sie noch nicht vorhanden sind. Diese Dienst-Agents sind erforderlich, damit die Dienste, die am Schutz Ihrer Conversational Analytics API-Ressourcen mit CMEK beteiligt sind, auf Ihren Cloud KMS-Schlüssel zugreifen können.

    Führen Sie die folgenden gcloud-Befehle aus, um die Dienst-Agents zu erstellen: 

    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID in Google Cloud .

  4. Weisen Sie beiden Dienst-Agents, die Sie im vorherigen Schritt erstellt haben, in Identity and Access Management (IAM) die Rolle Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) zu, damit der Gemini Data Analytics-Dienst Ihren Cloud KMS-Schlüssel zum Verschlüsseln und Entschlüsseln Ihrer Conversational Analytics API-Daten verwenden kann. Wenn Sie mehr als einen Schlüssel verwenden, z. B. separate Schlüssel für DataAgent- und Conversation-Ressourcen in der multiregionalen us- oder eu-Ressource, weisen Sie die Rolle jedem Schlüssel zu.

    Erteilen Sie dem Gemini Data Analytics-Dienst-Agent die Berechtigung:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    Gewähren Sie dem Gemini for Google Cloud API-Dienst-Agent die Berechtigung:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    Ersetzen Sie in den vorherigen Codebeispielen die Beispielwerte so:

    • KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
    • KEY_LOCATION: Die Region Ihres Schlüsselbunds, z. B. us-east4.
    • KEY_RING_NAME: Name des Schlüsselbunds.
    • PROJECT_NUMBER: Die Projektnummer Ihres Google Cloud -Projekts, in dem Sie API-Ressourcen erstellen.
    • KMS_PROJECT_ID: Die Projekt-ID, unter der der Schlüssel erstellt wurde. Dies kann dasselbe Projekt sein, in dem Sie API-Ressourcen erstellen.

Ressourcen mit CMEK schützen

In diesem Abschnitt wird beschrieben, wie Sie eine neue DataAgent- oder Conversation-Ressource mit CMEK schützen, indem Sie die REST API verwenden, um beim Erstellen der Ressource einen Cloud KMS-Schlüssel im Feld kms_key anzugeben.

Sie können CMEK nur aktivieren, wenn Sie eine DataAgent- oder Conversation-Ressource erstellen.

Der erforderliche Speicherort eines Cloud KMS-Schlüssels hängt vom Typ und Speicherort der Ressource ab, die er schützt. Weitere Informationen finden Sie unter Standortanforderungen.

DataAgent-Ressource mit CMEK schützen

Wenn Sie eine neue DataAgent-Ressource mit CMEK schützen möchten, geben Sie beim Erstellen des KI-Datenagenten einen Cloud KMS-Schlüssel im Feld kms_key an.

Python SDK

Das folgende Beispiel zeigt, wie Sie einen Cloud KMS-Schlüssel angeben, wenn Sie eine DataAgent-Ressource mit dem Python SDK erstellen. Ein Beispiel für eine vollständige create-Anfrage finden Sie unter KI-Datenagenten mit dem Python SDK erstellen.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_data_agent = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

Ersetzen Sie im vorherigen Beispiel die Werte so:

  • BILLING_PROJECT_ID: Ihre Abrechnungsprojekt-ID.
  • KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
  • KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
  • KMS_PROJECT_ID: Die Projekt-ID, unter der der Schlüssel erstellt wurde. Wenn das Feld leer bleibt, wird billing_project verwendet.
  • LOCATION: Der Standort des KI-Datenagenten, z. B. us, eu oder us-east4.
  • KEY_LOCATION: Der Speicherort Ihres Schlüsselbunds. Verwenden Sie für den multiregionalen Standort eu den Wert europe. Verwenden Sie für alle anderen Standorte denselben Standort wie für LOCATION. Wenn Sie das Feld leer lassen, wird standardmäßig der Standort des KI-Datenagenten verwendet. Das funktioniert für alle Standorte außer dem multiregionalen Standort eu.

HTTP

Im folgenden Beispiel wird gezeigt, wie Sie einen Cloud KMS-Schlüssel im Anfragetext angeben, wenn Sie eine DataAgent-Ressource mit HTTP und Python erstellen. Ein Beispiel für eine vollständige create-Anfrage finden Sie unter KI-Datenagenten mit HTTP und Python erstellen.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

Ersetzen Sie im vorherigen Beispiel die Werte so:

  • KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
  • KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
  • KMS_PROJECT_ID: Die Projekt-ID, unter der der Schlüssel erstellt wurde.
  • LOCATION: Der Standort des KI-Datenagenten, z. B. us, eu oder us-east4.
  • KEY_LOCATION: Der Speicherort Ihres Schlüsselbunds. Verwenden Sie für den multiregionalen Standort eu den Wert europe. Verwenden Sie für alle anderen Standorte denselben Standort wie für den KI-Datenagenten.

Conversation-Ressource mit CMEK schützen

Wenn Sie eine neue Conversation-Ressource mit CMEK schützen möchten, geben Sie beim Erstellen der Unterhaltung einen Cloud KMS-Schlüssel im Feld kms_key an.

Python SDK

Das folgende Beispiel zeigt, wie Sie einen Cloud KMS-Schlüssel angeben, wenn Sie eine Conversation-Ressource mit dem Python SDK erstellen. Ein Beispiel für eine vollständige create-Anfrage finden Sie unter KI-Datenagenten mit dem Python SDK erstellen.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_conversation = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

Ersetzen Sie im vorherigen Beispiel die Werte so:

  • BILLING_PROJECT_ID: Ihre Abrechnungsprojekt-ID.
  • KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
  • KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
  • KMS_PROJECT_ID: Die Projekt-ID, unter der der Schlüssel erstellt wurde. Wenn das Feld leer bleibt, wird billing_project verwendet.
  • LOCATION: Der Standort des Konversations- und Daten-Agents, z. B. us, eu oder us-east4.
  • KEY_LOCATION: Der Speicherort Ihres Schlüsselbunds. Verwenden Sie für den multiregionalen Standort us den Wert us-central1. Verwenden Sie für den multiregionalen Standort eu den Wert europe-west1. Verwenden Sie für eine einzelne Region dieselbe Region wie LOCATION. Wenn Sie dieses Feld leer lassen, wird standardmäßig der Standort der Unterhaltung verwendet. Das funktioniert nur für einzelne Regionen.

HTTP

Im folgenden Beispiel wird gezeigt, wie Sie einen Cloud KMS-Schlüssel im Anfragetext angeben, wenn Sie eine Conversation-Ressource mit HTTP und Python erstellen. Ein Beispiel für eine vollständige create-Anfrage finden Sie unter KI-Datenagenten mit HTTP und Python erstellen.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
}

Ersetzen Sie im vorherigen Beispiel die Werte so:

  • KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
  • KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
  • KMS_PROJECT_ID: Die Projekt-ID, unter der der Schlüssel erstellt wurde.
  • LOCATION: Der Standort des Konversations- und Daten-Agents, z. B. us, eu oder us-east4.
  • KEY_LOCATION: Der Speicherort Ihres Schlüsselbunds. Verwenden Sie für den multiregionalen Standort us den Wert us-central1. Verwenden Sie für den multiregionalen Standort eu den Wert europe-west1. Verwenden Sie für eine einzelne Region dieselbe Region wie für die Unterhaltung.

Fehlerbehebung

In diesem Abschnitt werden häufige Probleme und wichtige Überlegungen bei der Verwendung von CMEK mit der Conversational Analytics API behandelt.

Wichtige Statusänderungen

Wenn eine Cloud KMS-Schlüsselversion, die eine Conversational Analytics API-Ressource schützt, nicht mehr verfügbar ist, verlieren Sie den Zugriff auf die Daten, die mit diesem Schlüssel verschlüsselt sind. Wenn Sie versuchen, auf geschützte Daten zuzugreifen, während der Schlüssel nicht verfügbar ist, z. B. durch Lesen des Kontexts einer DataAgent-Ressource oder durch Zugriff auf den Conversation-Verlauf, schlägt die Anfrage fehl. Der zurückgegebene Fehler hängt davon ab, warum der Schlüssel nicht verfügbar ist:

  • Wenn die Schlüsselversion deaktiviert oder gelöscht ist, schlägt der Vorgang normalerweise mit einem FAILED_PRECONDITION-Fehler fehl.
  • Wenn die IAM-Rolle cloudkms.cryptoKeyEncrypterDecrypter für den Dienst-Agent gcp-sa-geminidataanalytics oder gcp-sa-cloudaicompanion widerrufen wird, schlägt der Vorgang in der Regel mit dem Fehler PERMISSION_DENIED oder NOT_FOUND fehl.

Auch wenn der Schlüssel nicht verfügbar ist, können Sie Vorgänge ausführen, für die keine Entschlüsselung des Inhalts erforderlich ist, z. B. das Löschen der DataAgent- oder Conversation-Ressource.

Wenn Sie den Zugriff auf verschlüsselte Daten wiederherstellen möchten, aktivieren Sie den Schlüssel wieder und sorgen Sie dafür, dass die Dienst-Agents die erforderlichen IAM-Berechtigungen haben, wie unter Vorbereitung beschrieben.

Cloud KMS-Kontingente und die Conversational Analytics API

Wenn Sie CMEK in der Conversational Analytics API verwenden, können Ihre Projekte Kontingente für kryptografische Cloud KMS-Anfragen verbrauchen. Wenn Sie beispielsweise eine DataAgent-Ressource lesen oder auf den Conversation-Verlauf zugreifen, der durch CMEK geschützt ist, muss Cloud KMS die Daten entschlüsseln.

Ver- und Entschlüsselungsvorgänge über CMEK-Schlüssel wirken sich auf die Cloud KMS-Kontingente so aus:

  • Für in Cloud KMS generierte Software-CMEK-Schlüssel wird kein Cloud KMS-Kontingent verbraucht.
  • Bei externen CMEK-Schlüsseln (manchmal auch Cloud EKM-Schlüssel genannt) werden Verschlüsselungs- und Entschlüsselungsvorgänge auf Cloud EKM-Kontingente in dem Projekt angerechnet, das den Schlüssel enthält.

Weitere Informationen finden Sie unter Cloud KMS-Kontingente.

Nächste Schritte