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 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 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 CMEK, l'esperienza di accesso alle risorse di Gemini Data Analytics è simile all'utilizzo della crittografia predefinita di Google. Per saperne di più sulle opzioni di crittografia, consulta 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. L'API Conversational Analytics è un prodotto del servizio Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK per le risorse dell'API Conversational Analytics

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

La chiave CMEK per l'API Conversational Analytics è disponibile solo in località regionali e multiregionali, non nella località global. Per le località supportate da ciascuna origine dati, consulta Località dei dati supportate.

Cosa è protetto con CMEK

CMEK per l'API Conversational Analytics protegge i seguenti dati at-rest:

  • Per le risorse DataAgent, tutti i contenuti principali dei clienti all'interno del campo data_analytics_agent sono protetti. Questi contenuti includono i campi staging_context, published_context e last_published_context, nonché i campi system_instruction e example_queries.
  • Per le risorse Conversation, tutti i dati della cronologia dei messaggi e dello stato sono protetti.

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

  • Per le risorse DataAgent, la crittografia predefinita di Google protegge i campi dei metadati come name, display_name, description, labels, create_time, update_time, delete_time, purge_time e kms_key.
  • Per le risorse Conversation, la crittografia predefinita di Google protegge i campi dei metadati come name, agents, labels, create_time, last_used_time e kms_key.

Limitazioni

CMEK per l'API Conversational Analytics presenta le seguenti limitazioni:

  • La chiave CMEK deve essere configurata al momento della creazione della risorsa. Non può essere aggiunto o modificato su una risorsa esistente.
  • Le policy dell'organizzazione CMEK non sono supportate.
  • La località richiesta della chiave Cloud KMS dipende dal tipo di risorsa e dalla località. In una singola regione, la chiave deve trovarsi nella stessa regione della risorsa. Nella multi-regione us o eu, la località della chiave per le risorse DataAgent e Conversation è diversa. Per saperne di più, consulta Requisiti per la località delle chiavi.
  • La regione global non è supportata.
  • Puoi utilizzare una sola CMEK per progetto per regione per tutte le risorse Conversation all'interno del progetto e della regione.

Requisiti principali per le località

La località richiesta della chiave Cloud KMS dipende dal tipo di risorsa che proteggi e dalla località della risorsa:

Località della risorsa Località della chiave per DataAgent risorsa Località della chiave per Conversation risorsa
us multiregionale us us-central1
eu multiregionale europe europe-west1
Una singola regione, ad esempio us-east4 La stessa regione della risorsa La stessa regione della risorsa

Le risorse DataAgent in una multi-regione vengono archiviate nella multi-regione specificata nel nome della risorsa, quindi la chiave deve trovarsi nella multi-regione Cloud KMS corrispondente. Per la multiregione us, la località di Cloud KMS è anche us. Per la regione multipla eu, la località Cloud KMS è europe, perché Cloud KMS non ha una località eu. Per saperne di più, consulta Località di Cloud KMS.

Le risorse Conversation in una multi-regione vengono archiviate in una regione specifica all'interno di quella multi-regione: us-central1 per us e europe-west1 per eu. La chiave deve trovarsi in quella regione. Ad esempio, per proteggere una risorsa Conversation denominata projects/PROJECT_ID/locations/us/conversations/CONVERSATION_ID, utilizza una chiave nella località us-central1.

Prima di iniziare

Prima di poter utilizzare CMEK con l'API Conversational Analytics, 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 .

    Abilita l'API Gemini Data Analytics

    Abilita l'API Gemini for 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. Crea un keyring e una chiave Cloud KMS nella località richiesta per le risorse dell'API Conversational Analytics, come descritto in Requisiti per la località delle chiavi. Per saperne di più, consulta Crea una chiave.

  3. Crea gli agenti di servizio gestiti da Google, noti anche come service account per prodotto e per progetto (P4SA), se non esistono già. Questi agenti di servizio sono necessari per consentire ai servizi coinvolti nella protezione delle risorse dell'API Conversational Analytics con CMEK di accedere alla 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 .

  4. Concedi il ruolo Cloud KMS CryptoKey Encrypter/Decrypter (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 Conversational Analytics. Se utilizzi più di una chiave, ad esempio chiavi separate per le risorse DataAgent e Conversation nella regione multi-regionale us o eu, concedi il ruolo su ogni chiave.

    Concedi l'autorizzazione all'agente di servizio 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. \
  --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. \
  --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 delle chiavi automatizzate (ad esempio us-east4).
    • KEY_RING_NAME: il nome delle chiavi automatizzate.
    • PROJECT_NUMBER: il numero di progetto Google Cloud in cui stai creando le risorse API.
    • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Può essere lo stesso progetto in cui stai creando le risorse API.

Proteggi 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 attivare CMEK solo quando crei una risorsa DataAgent o Conversation.

La località richiesta di una chiave Cloud KMS dipende dal tipo e dalla località della risorsa che protegge. Per saperne di più, consulta Requisiti per la località delle chiavi.

Proteggi 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 per i dati.

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, consulta Crea un agente per i 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" # 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

Nell'esempio precedente, sostituisci i valori come segue:

  • BILLING_PROJECT_ID: l'ID del tuo ID progetto di fatturazione.
  • KEY_RING_NAME: il nome della tua chiave automatizzata Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.
  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Se il campo viene lasciato vuoto, viene utilizzato billing_project.
  • LOCATION: la località dell'agente per i dati, ad esempio us, eu o us-east4.
  • KEY_LOCATION: la posizione delle chiavi automatizzate. Per la multi-regione eu, utilizza europe. Per tutte le altre località, utilizza la stessa località di LOCATION. Se lasciato vuoto, il valore predefinito è la località dell'agente per i dati, che funziona per tutte le località, ad eccezione della multi-regione eu.

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, consulta Crea un agente per i dati utilizzando HTTP e Python.

# 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,
          }
      }
  }

Nell'esempio precedente, sostituisci i valori come segue:

  • KEY_RING_NAME: il nome della tua chiave automatizzata Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.
  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave.
  • LOCATION: la località dell'agente per i dati, ad esempio us, eu o us-east4.
  • KEY_LOCATION: la posizione delle chiavi automatizzate. Per la multi-regione eu, utilizza europe. Per tutte le altre località, utilizza la stessa località dell'agente per i dati.

Proteggi 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 l'SDK Python. Per un esempio di richiesta create completa, consulta Crea un agente per i 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" # 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

Nell'esempio precedente, sostituisci i valori come segue:

  • BILLING_PROJECT_ID: l'ID del tuo ID progetto di fatturazione.
  • KEY_RING_NAME: il nome della tua chiave automatizzata Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.
  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave. Se il campo viene lasciato vuoto, viene utilizzato billing_project.
  • LOCATION: la località della conversazione e dell'agente per i dati, ad esempio us, eu o us-east4.
  • KEY_LOCATION: la posizione delle chiavi automatizzate. Per la multi-regione us, utilizza us-central1. Per la multi-regione eu, utilizza europe-west1. Per una singola regione, utilizza la stessa regione di LOCATION. Se non viene specificata, per impostazione predefinita viene utilizzata la località della conversazione, che funziona solo per singole regioni.

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, consulta Crea un agente per i dati utilizzando HTTP e Python.

# 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}"
}

Nell'esempio precedente, sostituisci i valori come segue:

  • KEY_RING_NAME: il nome della tua chiave automatizzata Cloud KMS.
  • KEY_NAME: il nome della chiave Cloud KMS.
  • KMS_PROJECT_ID: l'ID progetto in cui è stata creata la chiave.
  • LOCATION: la località della conversazione e dell'agente per i dati, ad esempio us, eu o us-east4.
  • KEY_LOCATION: la posizione delle chiavi automatizzate. Per la multi-regione us, utilizza us-central1. Per la multi-regione eu, utilizza europe-west1. Per una singola regione, utilizza la stessa regione della conversazione.

Risoluzione dei problemi

Questa sezione illustra i problemi comuni e le considerazioni importanti sull'utilizzo di CMEK con l'API Conversational Analytics.

Modifiche principali allo stato

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 di 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 all'agente di servizio gcp-sa-geminidataanalytics o gcp-sa-cloudaicompanion, l'operazione in genere non riesce 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 gli agenti di servizio dispongano delle autorizzazioni IAM richieste, come descritto in Prima di iniziare.

Quote di Cloud KMS e API Conversational Analytics

Quando utilizzi CMEK nell'API Conversational Analytics, i tuoi progetti possono consumare le quote delle richieste di crittografia di Cloud KMS. Ad esempio, la lettura di una risorsa DataAgent o l'accesso alla cronologia Conversation protetta da CMEK richiede che Cloud KMS decripti i dati.

Le operazioni di crittografia e decriptazione che utilizzano 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 di Cloud KMS.
  • Per le chiavi CMEK esterne, a volte chiamate chiavi Cloud EKM, le operazioni di crittografia e decriptazione vengono conteggiate ai fini delle quote di Cloud EKM nel progetto che contiene la chiave.

Per saperne di più, consulta Quote di Cloud KMS.

Passaggi successivi