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 te senza ulteriori azioni da parte tua. Questa opzione è denominata crittografia predefinita di Google.

Se vuoi controllare le chiavi di crittografia, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) in Cloud KMS con i 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 anche 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 di Gemini Data Analytics è simile all'utilizzo della crittografia predefinita di Google. Per ulteriori informazioni 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 Conversational Analytics con le origini dati di Looker. L'API Conversational Analytics è un prodotto del servizio Gemini Data Analytics (geminidataanalytics.googleapis.com).

Chiavi CMEK per le risorse dell'API Conversational Analytics

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

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

Cosa è protetto con le chiavi CMEK

Le chiavi CMEK per l'API Conversational Analytics proteggono i seguenti dati at-rest:

  • DataAgent risorse: tutti i contenuti principali dei clienti 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 degli stati.

I seguenti dati non vengono 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

Le chiavi CMEK per l'API Conversational Analytics presentano le seguenti limitazioni:

  • Le chiavi CMEK devono essere configurate al momento della creazione della risorsa. Non possono essere aggiunte o modificate su una risorsa esistente.
  • La chiave Cloud KMS e la risorsa dell'API Conversational Analytics devono trovarsi nella stessa località. La regione global non è supportata.
  • Per le risorse dell'API Conversational Analytics, le chiavi CMEK sono supportate nella regione us-east4.
  • Per le risorse dell'API Conversational Analytics, le chiavi CMEK sono supportate solo per le origini dati di Looker.
  • Puoi utilizzare una sola chiave CMEK per progetto e per regione per tutte le risorse Conversation all'interno di quel progetto e di quella regione.

Prima di iniziare

Prima di poter utilizzare le chiavi CMEK con l'API Conversational Analytics, completa i seguenti passaggi:

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

    Console

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

    Abilita l'API Gemini Data Analytics

    Abilita l'API Gemini for Google Cloud

    Abilita l'API Cloud Key Management Service

    Google Cloud

    gcloud

    Con la 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 Google Cloud ID progetto.

  2. Aggiungi il tuo progetto alla lista consentita.

    Il tuo Google Cloud progetto deve essere aggiunto a una lista consentita per utilizzare le chiavi CMEK con Gemini Data Analytics. Per richiedere l'aggiunta del tuo progetto alla lista consentita, invia il tuo ID progetto tramite il modulo di aggiunta alla lista consentita per le chiavi CMEK di GDA. L'aggiunta del tuo 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 Conversational Analytics. Per ulteriori informazioni, vedi 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 Conversational Analytics con le chiavi CMEK di accedere alla tua chiave Cloud KMS.

    Esegui i seguenti comandi gcloud per creare i service agent: 

    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 il tuo Google Cloud ID progetto.

  5. Concedi il ruolo Autore crittografia/decrittografia CryptoKey Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) in Identity and Access Management (IAM) a entrambi i service agent creati 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 Conversational Analytics.

    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 al service agent 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 tua chiave Cloud KMS.
    • KEY_LOCATION: la regione del keyring (ad esempio, us-east4).
    • KEY_RING_NAME: il nome del keyring.
    • PROJECT_NUMBER: il numero del tuo progetto in cui stai creando le risorse API. Google Cloud
    • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Può essere lo stesso del progetto in cui stai creando le risorse API.

Proteggere le risorse con le chiavi CMEK

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

Puoi abilitare le chiavi 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 le chiavi CMEK

Per proteggere una nuova risorsa DataAgent con le chiavi CMEK, specifica una chiave Cloud KMS nel campo kms_key quando crei il data agent.

SDK Python

L'esempio seguente mostra come specificare una chiave Cloud KMS quando crei una risorsa DataAgent con l'SDK Python. Per un esempio di richiesta create completa, vedi Creare un data agent 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 keyring Cloud KMS.
  • KEY_NAME: il nome della tua 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 del keyring.

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 data agent 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 del keyring.
  • KEY_RING_NAME: il nome del keyring Cloud KMS.
  • KEY_NAME: il nome della tua chiave Cloud KMS.

Proteggere una risorsa Conversation con le chiavi CMEK

Per proteggere una nuova risorsa Conversation con le chiavi 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 l'SDK Python. Per un esempio di richiesta create completa, vedi Creare un data agent 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 keyring Cloud KMS.
  • KEY_NAME: il nome della tua 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 del keyring.

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 data agent 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 del keyring.
  • KEY_RING_NAME: il nome del keyring Cloud KMS.
  • KEY_NAME: il nome della tua chiave Cloud KMS.

Risoluzione dei problemi

Questa sezione illustra i problemi comuni e le considerazioni importanti quando utilizzi le chiavi CMEK con l'API Conversational Analytics.

Modifiche dello stato delle chiavi

Se una versione della chiave Cloud KMS che protegge una risorsa dell'API Conversational Analytics non è più disponibile, perdi l'accesso ai dati criptati con quella chiave. Se tenti di accedere ai 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 restituito 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 restituito un errore PERMISSION_DENIED o NOT_FOUND.

Anche quando la chiave non è disponibile, puoi comunque eseguire operazioni che non richiedono la decriptazione dei contenuti, ad esempio eliminare la 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 Conversational Analytics

Quando utilizzi le chiavi CMEK nell'API Conversational Analytics, i tuoi progetti possono consumare 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 chiavi CMEK richiede a Cloud KMS di decriptare i dati.

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

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

Per ulteriori informazioni, vedi Quote di Cloud KMS.

Passaggi successivi