Chiavi di crittografia gestite dal cliente (CMEK)

Per impostazione predefinita, Gemini Data Analytics cripta i contenuti inattivi dei clienti. Gemini Data Analytics gestisce la crittografia per conto tuo senza che tu debba fare altro. Questa opzione è denominata crittografia predefinita di Google.

Se vuoi controllare le tue chiavi di crittografia, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) in Cloud KMS con servizi integrati con CMEK, tra cui Gemini Data Analytics. L'utilizzo delle chiavi Cloud KMS ti consente di controllare il livello di protezione, la località, la pianificazione della rotazione, le autorizzazioni di utilizzo e di accesso e i limiti crittografici. Con Cloud KMS puoi inoltre visualizzare gli audit log e controllare i cicli di vita delle chiavi. Invece di Google, sei tu ad avere la proprietà e la gestione delle chiavi di crittografia della chiave (KEK) simmetriche che proteggono i tuoi dati. Puoi controllare e gestire queste chiavi in Cloud KMS.

Dopo aver configurato le risorse con le chiavi CMEK, l'esperienza di accesso alle risorse Gemini Data Analytics è simile all'utilizzo della crittografia predefinita di Google. Per saperne di più sulle opzioni di crittografia, vedi Chiavi di crittografia gestite dal cliente (CMEK).

Questa pagina descrive come utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per proteggere i dati utilizzati dall'API Analisi conversazionale con le origini dati di Looker. L'API Analisi conversazionale è un prodotto del servizio Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK per le risorse dell'API Analisi conversazionale

Quando configuri CMEK per una risorsa API Analisi conversazionale, la chiave Cloud KMS specificata cripta i dati sensibili at-rest. Puoi configurare CMEK per le risorse DataAgent e Conversation in modo indipendente.

Puoi configurare CMEK solo al momento della creazione della risorsa. Per utilizzare CMEK, devi specificare il campo kms_key quando crei una risorsa DataAgent o Conversation. Non puoi aggiungere o modificare una chiave Cloud KMS in una risorsa esistente.

Cosa viene protetto con CMEK

CMEK per l'API Analisi conversazionale protegge i seguenti dati at-rest:

  • Risorse DataAgent: tutti i contenuti principali del cliente nei campi staging_context, published_context e last_published_context di data_analytics_agent. Sono inclusi campi come system_instruction e example_queries.
  • Risorse Conversation: tutti i messaggi e la cronologia dello stato.

I seguenti dati non sono criptati con la chiave CMEK del cliente. Questi dati sono invece protetti dalla crittografia predefinita di Google:

  • Risorse DataAgent: campi dei metadati, tra cui name, display_name, description, labels, create_time, update_time, delete_time, purge_time e kms_key
  • Risorse Conversation: campi dei metadati, tra cui name, agents, labels, create_time, last_used_time e kms_key

Limitazioni

CMEK per l'API Analisi conversazionale presenta le seguenti limitazioni:

  • La CMEK deve essere configurata al momento della creazione della risorsa. Non può essere aggiunto o modificato in una risorsa esistente.
  • La chiave Cloud KMS e la risorsa API Analisi conversazionale devono trovarsi nella stessa località. La regione global non è supportata.
  • Per le risorse API di Analisi conversazionale, CMEK è supportata nella regione us-east4.
  • Per le risorse dell'API Analisi conversazionale, CMEK è supportata solo per le origini dati Looker.
  • Puoi utilizzare una sola chiave CMEK per progetto per regione per tutte le risorse Conversation all'interno di quel progetto e di quella regione.

Prima di iniziare

Prima di poter utilizzare CMEK con l'API Analisi conversazionale, completa i seguenti passaggi:

  1. Abilita le API richieste nella console Google Cloud o in Google Cloud CLI.

    Console

    Abilita le seguenti API nella console Google Cloud per il tuo progetto Google Cloud .

    Attiva l'API Gemini Data Analytics

    Abilitare l'API Gemini per Google Cloud

    Abilita l'API Cloud Key Management Service

    gcloud

    Con Google Cloud CLI, esegui i seguenti comandi gcloud services enable per abilitare rispettivamente l'API Gemini Data Analytics, l'API Gemini for Google Cloud e l'API Cloud Key Management Service:

    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

    Nei comandi gcloud CLI di esempio precedenti, sostituisci project_id con il tuo ID progetto Google Cloud .

  2. Aggiungi il tuo progetto alla lista consentita.

    Il tuo progetto Google Cloud deve essere aggiunto a una lista consentita per utilizzare CMEK con Gemini Data Analytics. Per richiedere l'aggiunta del tuo progetto alla lista consentita, invia l'ID progetto tramite il modulo di inclusione nella lista consentita di GDA CMEK. L'aggiunta del progetto alla lista consentita richiede circa uno o due giorni lavorativi.

  3. Crea un keyring e una chiave Cloud KMS nella stessa località delle risorse dell'API Analisi conversazionale. Per saperne di più, consulta Creare una chiave.

  4. Crea i service agent gestiti da Google, noti anche come service account per prodotto e per progetto (P4SA), se non esistono già. Questi service agent sono necessari per consentire ai servizi coinvolti nella protezione delle risorse dell'API Analisi conversazionale con CMEK di accedere alla tua chiave Cloud KMS.

    Esegui i seguenti comandi gcloud per creare gli agenti di servizio: 

    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

  5. Concedi il ruolo Autore crittografia/decrittografia CryptoKey Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) in Identity and Access Management (IAM) a entrambi gli agenti di servizio che hai creato nel passaggio precedente per consentire al servizio Gemini Data Analytics di utilizzare la tua chiave Cloud KMS per criptare e decriptare i dati dell'API Analisi conversazionale.

    Concedi l'autorizzazione al service agent Gemini Data Analytics:

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

    Concedi l'autorizzazione all'agente di servizio dell'API Gemini for Google Cloud :

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

    Negli esempi di codice precedenti, sostituisci i valori di esempio come segue:

    • KEY_NAME: il nome della chiave Cloud KMS.
    • KEY_LOCATION: la regione del tuo portachiavi (ad esempio us-east4).
    • KEY_RING_NAME: il nome delle chiavi automatizzate.
    • PROJECT_NUMBER: il numero del tuo progetto Google Cloud in cui stai creando risorse API.
    • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Può essere lo stesso progetto in cui stai creando risorse API.

Proteggere le risorse con CMEK

Questa sezione mostra come proteggere una nuova risorsa DataAgent o Conversation con CMEK utilizzando l'API REST per specificare una chiave Cloud KMS nel campo kms_key durante la creazione della risorsa.

Puoi abilitare CMEK solo quando crei una risorsa DataAgent o Conversation.

Una chiave CMEK deve trovarsi nella stessa regione della risorsa che protegge. Per ulteriori informazioni, vedi Limitazioni.

Proteggere una risorsa DataAgent con CMEK

Per proteggere una nuova risorsa DataAgent con CMEK, specifica una chiave Cloud KMS nel campo kms_key quando crei l'agente dati.

SDK Python

L'esempio seguente mostra come specificare una chiave Cloud KMS quando crei una risorsa DataAgent con Python SDK. Per un esempio di richiesta create completa, vedi Creare un agente dati utilizzando l'SDK Python.

# 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" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_data_agent = f"projects/{key_project}/locations/{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

Nell'esempio precedente, sostituisci i valori come segue:

  • BILLING_PROJECT_ID: il tuo ID progetto di fatturazione.
  • KEY_RING_NAME: il nome del tuo key ring Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.
  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Se lasciato vuoto, viene utilizzato billing_project.
  • LOCATION: la regione delle chiavi automatizzate.

HTTP

L'esempio seguente mostra come specificare una chiave Cloud KMS nel corpo della richiesta quando crei una risorsa DataAgent con HTTP e Python. Per un esempio di richiesta create completa, vedi Creare un agente dati utilizzando HTTP e Python.

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/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

Nell'esempio precedente, sostituisci i valori come segue:

  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave.
  • LOCATION: la regione delle chiavi automatizzate.
  • KEY_RING_NAME: il nome del tuo key ring Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.

Proteggere una risorsa Conversation con CMEK

Per proteggere una nuova risorsa Conversation con CMEK, specifica una chiave Cloud KMS nel campo kms_key quando crei la conversazione.

SDK Python

L'esempio seguente mostra come specificare una chiave Cloud KMS quando crei una risorsa Conversation con Python SDK. Per un esempio di richiesta create completa, vedi Creare un agente dati utilizzando l'SDK Python.

# 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" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_conversation = f"projects/{key_project}/locations/{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

Nell'esempio precedente, sostituisci i valori come segue:

  • BILLING_PROJECT_ID: il tuo ID progetto di fatturazione.
  • KEY_RING_NAME: il nome del tuo key ring Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.
  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Se lasciato vuoto, viene utilizzato billing_project.
  • LOCATION: la regione delle chiavi automatizzate.

HTTP

L'esempio seguente mostra come specificare una chiave Cloud KMS nel corpo della richiesta quando crei una risorsa Conversation con HTTP e Python. Per un esempio di richiesta create completa, vedi Creare un agente dati utilizzando HTTP e Python.

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/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"
}

Nell'esempio precedente, sostituisci i valori come segue:

  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave.
  • LOCATION: la regione delle chiavi automatizzate.
  • KEY_RING_NAME: il nome del tuo key ring Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.

Risoluzione dei problemi

Questa sezione tratta i problemi comuni e le considerazioni importanti quando utilizzi CMEK con l'API Analisi conversazionale.

Modifiche principali dello stato

Se una versione della chiave Cloud KMS che protegge una risorsa dell'API Analisi conversazionale non è più disponibile, perdi l'accesso ai dati criptati da quella chiave. Se tenti di accedere a dati protetti mentre la chiave non è disponibile, ad esempio leggendo il contesto di una risorsa DataAgent o accedendo alla cronologia Conversation, la richiesta non va a buon fine. L'errore restituito dipende dal motivo per cui la chiave non è disponibile:

  • Se la versione della chiave è disattivata o eliminata, l'operazione in genere non va a buon fine e viene visualizzato un errore FAILED_PRECONDITION.
  • Se il ruolo IAM cloudkms.cryptoKeyEncrypterDecrypter viene revocato dal service agent gcp-sa-geminidataanalytics o gcp-sa-cloudaicompanion, l'operazione in genere non va a buon fine e viene visualizzato un errore PERMISSION_DENIED o NOT_FOUND.

Anche quando la chiave non è disponibile, puoi comunque eseguire operazioni che non richiedono la decrittografia dei contenuti, ad esempio l'eliminazione della risorsa DataAgent o Conversation.

Per ripristinare l'accesso ai dati criptati, riattiva la chiave e assicurati che i service agent dispongano delle autorizzazioni IAM richieste, come descritto in Prima di iniziare.

Quote di Cloud KMS e API Analisi conversazionale

Quando utilizzi CMEK nell'API Analisi conversazionale, i tuoi progetti possono utilizzare le quote per le richieste crittografiche di Cloud KMS. Ad esempio, la lettura di una risorsa DataAgent o l'accesso alla cronologia Conversation protetta da CMEK richiede a Cloud KMS di decriptare i dati.

Le operazioni di crittografia e decriptazione che utilizzano le chiavi CMEK influiscono sulle quote di Cloud KMS nei seguenti modi:

  • Per le chiavi CMEK software generate in Cloud KMS, non viene consumata alcuna quota Cloud KMS.
  • Per le chiavi CMEK hardware, a volte chiamate chiavi Cloud HSM, le operazioni di crittografia e decrittografia vengono conteggiate in base alle quote Cloud HSM nel progetto che contiene la chiave.
  • Per le chiavi CMEK esterne, a volte chiamate chiavi Cloud EKM, le operazioni di crittografia e decrittografia vengono conteggiate in base alle quote Cloud EKM nel progetto che contiene la chiave.

Per maggiori informazioni, consulta Quote di Cloud KMS.

Passaggi successivi