Chiavi di crittografia gestite dal cliente

Per impostazione predefinita, Agent Search cripta i contenuti inattivi dei clienti. Agent Search 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 Agent Search. 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 monitorare l'utilizzo delle chiavi, 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 Agent Search è simile all'utilizzo della crittografia predefinita di Google. Per saperne di più sulle opzioni di crittografia, consulta Chiavi di crittografia gestite dal cliente (CMEK).

Quando viene registrata una chiave CMEK, Agent Search chiama periodicamente Cloud KMS per mantenere un'istanza isolata logicamente dei tuoi dati. Ciò accade anche se la configurazione CMEK non è impostata come predefinita e non ci sono app o connettori di dati che la utilizzano. L'utilizzo deriva dalla configurazione e dall'esecuzione dell'istanza, non dal volume di dati o dal numero di utenti che vi accedono. Consulta Prezzi di Cloud Key Management Service.

Limitazioni di Cloud KMS in Agent Search

Si applicano le seguenti limitazioni alle chiavi CMEK (Cloud KMS) in Agent Search:

  • Le chiavi già applicate a un'app o a un connettore dati non possono essere modificate, anche se le versioni delle chiavi possono essere ruotate.
  • Devi utilizzare app e data store multiregionali US o EU (non globali). Per saperne di più sulle multiregioni e sulla residenza dei dati, inclusi i limiti associati all'utilizzo di località non globali, consulta Località.

  • Se devi registrare più di una chiave per un progetto, contatta il team del tuo account Google per richiedere un aumento della quota per le configurazioni CMEK, fornendo una motivazione per cui hai bisogno di più di una chiave.

    Si applicano le seguenti limitazioni a EKM o HSM con CMEK:

    • La quota EKM e HSM per le chiamate di crittografia e decrittografia deve avere almeno 1000 QPM di margine. Per informazioni su come controllare le quote, consulta Controllare le quote di Cloud KMS.

    • Se utilizzi EKM, la chiave deve essere raggiungibile per più del 90% di qualsiasi finestra temporale superiore a 30 secondi. Se la chiave non è raggiungibile per questo periodo di tempo, può influire negativamente sull'indicizzazione e sulla freschezza della ricerca.

    • Se si verificano problemi di fatturazione, problemi persistenti di superamento della quota o problemi persistenti di mancata raggiungibilità per più di 12 ore, il servizio disattiva automaticamente CmekConfig associato alla chiave EKM o HSM.

  • Le app o i connettori di dati creati prima della registrazione di una chiave nel progetto non possono essere protetti dalla chiave.
  • Per le app con più connettori dati, se un connettore dati utilizza una configurazione CMEK, anche tutti gli altri connettori dati devono utilizzare la stessa configurazione CMEK.

Informazioni sulle chiavi a singola regione per i connettori di terze parti

Se utilizzi connettori di terze parti e vuoi utilizzare le tue chiavi per proteggere i dati connessi, devi creare tre chiavi a singola regione supplementari oltre alla chiave multi-regione. I comandi per creare le chiavi sono riportati nella procedura seguente, Registra la chiave Cloud KMS.

Le singole chiavi devono essere create per le seguenti regioni:

Più regioni Regioni singole
eu europe-west1 europe-west4 europe-north1
us us-east1 us-central1 us-west1

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

  • Crea una chiave Cloud KMS simmetrica multiregionale. Consulta le sezioni Crea un keyring e Crea una chiave nella documentazione di Cloud KMS.

    • Imposta il periodo di rotazione su Mai (rotazione manuale).

    • Per Località, seleziona Più regioni e poi europe o us dal menu a discesa.

  • Il ruolo IAM CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) per la chiave è stato concesso all'agente di servizio Discovery Engine. L'account service agent ha un indirizzo email che utilizza il seguente formato: service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com. Per istruzioni generali su come aggiungere un ruolo a un agente di servizio, vedi Concedere o revocare un singolo ruolo.

  • Il ruolo IAM Autore crittografia/decrittografia CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) per la chiave è stato concesso all'agente di servizio Cloud Storage. Se questo ruolo non viene concesso, l'importazione dei dati per le app e i connettori di dati protetti da CMEK non andrà a buon fine perché Discovery Engine non è in grado di creare il bucket e la directory temporanei protetti da CMEK necessari per l'importazione.

  • Non creare app o connettori di dati che vuoi gestire con la tua chiave finché non hai completato le istruzioni per la registrazione della chiave riportate in questa pagina.

Registra la chiave Cloud KMS

Per criptare i dati utilizzando CMEK, devi registrare la chiave multiregionale. Se i tuoi dati richiedono chiavi a singola regione, ad esempio quando utilizzi connettori di terze parti, devi anche registrare le chiavi a singola regione.

Prima di iniziare

Verifica quanto segue:

  • La regione non è già protetta da una chiave. La procedura riportata di seguito non va a buon fine se una chiave è già registrata per la regione tramite il comando REST. Per determinare se esiste una chiave attiva in Agent Search per una località, consulta Visualizzare le chiavi Cloud KMS.

Procedura

REST

Per registrare la tua chiave per la ricerca di agenti, segui questi passaggi:

  1. Chiama il metodo UpdateCmekConfig con la chiave che vuoi registrare.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"kmsKey":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"

    Sostituisci quanto segue:

    • KMS_PROJECT_ID: l'ID del progetto che contiene la chiave. Il numero di progetto non funziona.
    • KMS_LOCATION: la multiregione della chiave: us o europe.
    • KEY_RING: il nome delle chiavi automatizzate che contengono la chiave.
    • KEY_NAME: il nome della chiave.
    • PROJECT_ID: l'ID del progetto che contiene l'app o il connettore dati.
    • LOCATION: la multiregione dell'app o del connettore di dati: us o eu.
    • CMEK_CONFIG_ID: imposta un ID univoco per la risorsa CmekConfig, ad esempio default_cmek_config.

    • SET_DEFAULT: impostato su true per utilizzare la chiave come chiave predefinita per le app e i connettori dati successivi creati nella multiregione.

  2. (Facoltativo) Registra il valore name restituito dal metodo e segui le istruzioni riportate in Visualizzare i dettagli di un'operazione a lunga esecuzione per vedere quando l'operazione è completata.

    In genere, la registrazione di una chiave richiede alcuni minuti.

    Al termine dell'operazione, i nuovi connettori di app e dati in questa regione multipla sono protetti dalla chiave. Per informazioni generali sulla creazione di app, vedi Informazioni su app e datastore.

  3. Crea l'app. Per istruzioni, vedi Crea un'app e Informazioni su app e datastore.

Console

Procedura

Per registrare la tua chiave per la ricerca dell'agente, segui questi passaggi:

  1. Nella Google Cloud console, vai alla pagina AI Applications.

    Applicazioni di AI

  2. Fai clic su Impostazioni e seleziona la scheda CMEK.

  3. Fai clic su Aggiungi chiave per la posizione us o eu.

    Fai clic su Aggiungi chiave per una posizione.
    Fai clic su Aggiungi chiave.

    1. Fai clic sul menu a discesa Seleziona una chiave Cloud KMS e seleziona la chiave.

      • Se la chiave si trova in un altro progetto, fai clic su Cambia progetto, fai clic sul nome del progetto, digita il nome della chiave che hai creato e selezionala.

      • Se conosci il nome risorsa della chiave, fai clic su Inserisci manualmente, incolla il nome risorsa della chiave e fai clic su Salva.

    2. Fai clic su Ok > Salva.

  4. Crea l'app. Per istruzioni, vedi Informazioni su app e datastore.

In questo modo viene registrata la chiave e viene creato un CmekResource denominato default_cmek_config.

Potrebbero essere necessarie diverse ore prima che i dati importati vengano visualizzati nei risultati di ricerca.

Visualizzare le chiavi Cloud KMS

Per visualizzare una chiave registrata per la ricerca dell'agente, esegui una delle seguenti operazioni:

  • Se hai il nome della risorsa CmekConfig, chiama il metodo GetCmekConfig:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

    Sostituisci quanto segue:

    • LOCATION: la multiregione dell'app o del connettore di dati: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene i dati.
    • CMEK_CONFIG_ID: l'ID della risorsa CmekConfig. Se hai registrato la chiave utilizzando la console, l'ID è default_cmek_config.

    Un esempio di chiamata curl e risposta è il seguente: 

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"

    
{
  "name":
  "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
  "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
  "state": "ACTIVE"
  "isDefault": true
}

  • Se non hai il nome della risorsa CmekConfig, chiama il metodo ListCmekConfigs:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"

    Sostituisci quanto segue:

    • LOCATION: la multiregione del connettore di app o dati: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene i dati.

    Un esempio di chiamata curl e risposta è il seguente: 

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs"

    
{
  "cmek_configs": [
    {
      "name":
      "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
      "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
      "state": "ACTIVE"
      "isDefault": true
    }
  ]
}

Annulla la registrazione della chiave Cloud KMS

Per annullare la registrazione della chiave dalla ricerca dell'agente:

  1. Chiama il metodo DeleteCmekConfig con il nome della risorsa CmekConfig che vuoi annullare la registrazione.

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

    Sostituisci quanto segue:

    • LOCATION: la multiregione del connettore di app o dati: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene l'app o il connettore dati.
    • CMEK_CONFIG_ID: l'ID della risorsa CmekConfig. Se hai registrato la chiave utilizzando la console, l'ID è default_cmek_config.

    Un esempio di chiamata curl e risposta è il seguente: 

    $ curl -X DELETE
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"
 
{
 "name": "projects/my-ai-app-project-123/locations/us/operations/delete-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.DeleteCmekConfigMetadata"
 }
}

  2. (Facoltativo) Registra il valore name restituito dal metodo e segui le istruzioni riportate in Recuperare i dettagli di un'operazione di lunga durata per vedere quando l'operazione è completata.

    L'eliminazione di un CmekConfig è un'operazione a lunga esecuzione che può richiedere fino a un paio di giorni. Questo perché le risorse criptate sottostanti vengono completamente deprovisionate prima della rimozione di CmekConfig.

Verificare che un'app o un connettore dati sia protetto da una chiave

Le app e i connettori di dati creati dopo la registrazione della chiave sono protetti dalla chiave. Se vuoi verificare che una determinata app o un determinato connettore di dati sia protetto dalla tua chiave, segui questi passaggi:

Verifica utilizzando la console Google Cloud

Puoi utilizzare la console Google Cloud per verificare se è impostata una configurazione CMEK predefinita.

  1. Nella Google Cloud console, vai alla pagina AI Applications.
  2. Fai clic su Impostazioni e seleziona la scheda CMEK.
  3. Verifica che lo stato della configurazione per la tua sede sia visualizzato come Attivo e che mostri la chiave registrata.

Verifica tramite CLI / API

  1. Per verificare un datastore:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID"

    Sostituisci quanto segue:

    • LOCATION: la multiregione del tuo progetto: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene l'app o il connettore dati.
    • DATA_STORE_ID: l'ID del datastore associato all'app o al connettore dati.

    Un esempio di chiamata curl ha il seguente aspetto: 

    curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"

  2. Per eseguire la verifica per un'app:

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/ENGINE_ID"

    Sostituisci quanto segue:

    • LOCATION: la multiregione del tuo progetto: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene l'app.
    • ENGINE_ID: l'ID della tua app.

    Un esempio di chiamata curl ha il seguente aspetto: 

    curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/engines/my-app"

  3. Esamina l'output del comando: se il campo cmekConfig è presente nell'output e il campo kmsKey mostra la chiave che hai registrato, l'app o il connettore dati è protetto dalla chiave.

    Una risposta di esempio per un datastore è simile alla seguente:

    {
 "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1",
 "displayName": "my-data-store-1",
 "industryVertical": "GENERIC",
 "createTime": "2023-09-05T21:20:21.520552Z",
 "solutionTypes": [
   "SOLUTION_TYPE_SEARCH"
 ],
 "defaultSchemaId": "default_schema",
 "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

    Una risposta di esempio per un'app è simile alla seguente:

    {
  "name": "projects/969795412903/locations/us/collections/default_collection/engines/my-app",
  "displayName": "my-app",
  "dataStoreIds": [
    "my-data-store-1"
  ],
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_STANDARD"
  },
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

Altri dati protetti dalla chiave Cloud KMS

Oltre ai dati nelle app e nei connettori di dati, le chiavi possono proteggere altri tipi di informazioni di base di proprietà delle app detenute da Agent Search, come i dati di sessione generati durante la ricerca con follow-up. Questo tipo di informazioni di base è protetto da CMEK se le app e i connettori di dati sono protetti da CMEK.

Anche se non puoi eseguire un comando specifico per verificare che le sessioni siano protette, puoi verificare se l'app è protetta. Esegui il comando Verifica che un'app o un connettore dati sia protetto da una chiave per consentire all'app di visualizzare la chiave nella risorsa cmekConfig. In questo modo saprai che i dati della sessione sono protetti.

Ruota le chiavi Cloud KMS

Quando ruoti le chiavi, crei una nuova versione della chiave e la imposti come versione principale. Lascia la versione originale della chiave abilitata per un po' prima di disattivarla. In questo modo, le operazioni a lunga esecuzione che potrebbero utilizzare la chiave precedente hanno il tempo di essere completate.

La seguente procedura descrive i passaggi per la rotazione delle chiavi per un'app di ricerca agenti o un connettore dati. Per informazioni generali sulla rotazione delle chiavi, consulta la sezione Rotazione delle chiavi nella guida di Cloud KMS.

Importante:non ruotare le chiavi su app o connettori di dati associati a consigli o a qualsiasi app che necessita di analisi e non ruotare le chiavi a singola regione utilizzate per i connettori di terze parti. Consulta Limitazioni di Cloud KMS in Agent Search.

  1. Registra nuovamente il token. Per farlo, ripeti il passaggio 1 di Registra la chiave Cloud KMS.

  2. Per eseguire le seguenti operazioni, consulta le istruzioni nella sezione Gestire le chiavi della guida di Cloud KMS:

    1. Crea una nuova versione della chiave, attivala e impostala come principale.

      Una volta impostata la nuova chiave come principale, i documenti nell'app o nel connettore dati vengono ricriptati utilizzando la nuova chiave e tutti i documenti successivi aggiunti all'app o al connettore dati vengono criptati con la nuova chiave.

    2. Lascia abilitata la versione precedente della chiave.

    3. Dopo circa una settimana, disattiva la versione precedente della chiave e assicurati che tutto funzioni come prima.

    4. In un secondo momento, quando avrai la certezza che la disattivazione della versione precedente della chiave non ha causato problemi, potrai eliminarla.

Se una chiave Cloud KMS è disabilitata o revocata

Se una chiave è disattivata o le autorizzazioni per la chiave sono revocate, l'app o il connettore dati interrompe l'importazione dei dati e la pubblicazione dei dati entro 15 minuti. Puoi riattivare la chiave entro 30 giorni per riprendere le operazioni prima che la configurazione CMEK scada e che tutti i dati associati vengano eliminati definitivamente. Tuttavia, la riattivazione di una chiave o il ripristino delle autorizzazioni richiede molto tempo. Potrebbero trascorrere fino a 24 ore prima che l'app o il connettore dati possa riprendere a pubblicare dati.

Pertanto, non disattivare una chiave a meno che non sia necessario. La disattivazione e l'attivazione di una chiave in un'app o in un connettore dati è un'operazione che richiede molto tempo. Ad esempio, se una chiave viene disattivata e attivata ripetutamente, l'app o il connettore dati impiegherà molto tempo per raggiungere uno stato protetto. La disabilitazione di una chiave e la sua riattivazione immediata potrebbero comportare giorni di inattività perché la chiave viene prima disabilitata dal connettore di app o dati e successivamente riattivata.

Risoluzione dei problemi: errore Progetti chiave KMS non trovati

Sintomo: quando provi a creare un connettore di app o dati utilizzando una chiave KMS, ricevi un errore simile al seguente:

KMS key projects/[...] not found for location: [...] and project number: [...]

Problema: questo messaggio di errore può essere fuorviante. Ciò non significa necessariamente che la chiave non esista. Potrebbe invece indicare che la chiave KMS non è stata registrata per l'utilizzo con Agent Search nella località specificata.

Soluzione:per risolvere il problema, registra la chiave seguendo i passaggi descritti in Registrare la chiave Cloud KMS. Una volta completata la registrazione, puoi creare app o connettori di dati protetti da questa chiave.