Clés de chiffrement gérées par le client

Par défaut, Agent Search chiffre le contenu client au repos. Agent Search gère le chiffrement sans intervention de votre part. Cette option est appelée chiffrement par défaut de Google.

Si vous souhaitez contrôler vos clés de chiffrement, vous pouvez utiliser des clés de chiffrement gérées par le client (CMEK) dans Cloud KMS avec des services bénéficiant d'une intégration des CMEK, y compris Agent Search. L'utilisation de clés Cloud KMS vous permet de contrôler leur niveau de protection, leur emplacement, leur calendrier de rotation, leurs autorisations d'utilisation et d'accès, ainsi que leurs limites cryptographiques.  Cloud KMS vous permet également de suivre l'utilisation des clés, de consulter les journaux d'audit et de contrôler les cycles de vie des clés. Au lieu de laisser Google posséder et gérer les clés de chiffrement de clés (KEK) symétriques qui protègent vos données, c'est vous qui vous chargez de cette tâche dans Cloud KMS.

Une fois que vous avez configuré vos ressources avec des CMEK, l'accès à vos ressources Agent Search est semblable à celui du chiffrement par défaut de Google. Pour en savoir plus sur les options de chiffrement, consultez Clés de chiffrement gérées par le client (CMEK).

Lorsqu'une clé CMEK est enregistrée, Agent Search appelle Cloud KMS régulièrement pour maintenir une instance logiquement isolée de vos données. Cela se produit même si la configuration CMEK n'est pas définie par défaut et qu'aucune application ni aucun connecteur de données ne l'utilise. L'utilisation provient de la configuration et de l'exécution de l'instance, et non du volume de données ou du nombre d'utilisateurs y accédant. Consultez les tarifs de Cloud Key Management Service.

Limites de Cloud KMS dans Agent Search

Les limites suivantes s'appliquent aux clés CMEK (Cloud KMS) dans la recherche par l'agent :

  • Les clés déjà appliquées à une application ou à un connecteur de données ne peuvent pas être modifiées, mais les versions de clé peuvent être permutées.
  • Vous devez utiliser des applications et des data stores multirégionaux aux États-Unis ou dans l'UE (et non mondiaux). Pour en savoir plus sur les régions multiples et la résidence des données, y compris sur les limites associées à l'utilisation d'emplacements non mondiaux, consultez la page Emplacements.

  • Si vous devez enregistrer plusieurs clés pour un projet, contactez l'équipe responsable de votre compte Google pour demander une augmentation du quota de configurations CMEK, en expliquant pourquoi vous avez besoin de plusieurs clés.

    Les limites suivantes s'appliquent à EKM ou HSM avec CMEK :

    • Votre quota EKM et HSM pour les appels de chiffrement et de déchiffrement doit disposer d'une marge d'au moins 1 000 QPM. Pour savoir comment vérifier vos quotas, consultez Vérifier vos quotas Cloud KMS.

    • Si vous utilisez EKM, la clé doit être accessible pendant plus de 90% de toute période de plus de 30 secondes. Si la clé n'est pas accessible pendant cette durée, cela peut avoir un impact négatif sur l'indexation et la fraîcheur des résultats de recherche.

    • En cas de problèmes de facturation, de problèmes persistants de dépassement de quota ou d'inaccessibilité persistante pendant plus de 12 heures, le service désactive automatiquement la configuration CmekConfig associée à la clé EKM ou HSM.

  • Les applications ou les connecteurs de données créés avant l'enregistrement d'une clé dans le projet ne peuvent pas être protégés par la clé.
  • Pour les applications comportant plusieurs connecteurs de données, si l'un d'eux utilise une configuration CMEK, tous les autres connecteurs de données doivent également utiliser la même configuration CMEK.

À propos des clés à région unique pour les connecteurs tiers

Si vous utilisez des connecteurs tiers et que vous souhaitez utiliser vos propres clés pour protéger les données connectées, vous devez créer trois clés à région unique supplémentaires en plus de la clé multirégionale. Les commandes permettant de créer des clés sont fournies dans la procédure suivante : Enregistrer votre clé Cloud KMS.

Les clés uniques doivent être créées pour les régions suivantes :

Emplacement multirégional Régions uniques
eu europe-west1 europe-west4 europe-north1
us us-east1 us-central1 us-west1

Avant de commencer

Assurez-vous de remplir les conditions préalables suivantes :

  • Créez une clé Cloud KMS symétrique multirégionale. Consultez Créer un trousseau de clés et Créer une clé dans la documentation Cloud KMS.

    • Définissez la période de rotation sur Jamais (rotation manuelle).

    • Pour Emplacement, sélectionnez Multirégional, puis europe ou us dans le menu déroulant.

  • Le rôle IAM Chiffreur/Déchiffreur de clés cryptographiques (roles/cloudkms.cryptoKeyEncrypterDecrypter) sur la clé a été accordé à l'agent de service Discovery Engine. Le compte de l'agent de service possède une adresse e-mail au format suivant : service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com. Pour obtenir des instructions générales sur l'ajout d'un rôle à un agent de service, consultez Attribuer ou révoquer un rôle unique.

  • Le rôle IAM Chiffreur/Déchiffreur de clés cryptographiques (roles/cloudkms.cryptoKeyEncrypterDecrypter) sur la clé a été attribué à l'agent de service Cloud Storage. Si ce rôle n'est pas accordé, l'importation de données pour les applications et les connecteurs de données protégés par CMEK échouera, car Discovery Engine ne pourra pas créer le bucket et le répertoire temporaires protégés par CMEK requis pour l'importation.

  • Ne créez aucune application ni aucun connecteur de données que vous souhaitez gérer avec votre clé tant que vous n'avez pas suivi les instructions d'enregistrement de la clé sur cette page.

Enregistrer votre clé Cloud KMS

Pour chiffrer des données à l'aide de CMEK, vous devez enregistrer votre clé multirégionale. Si vos données nécessitent des clés à région unique (par exemple, lorsque vous utilisez des connecteurs tiers), vous devez également enregistrer vos clés à région unique.

Avant de commencer

Assurez-vous que :

  • La région n'est pas déjà protégée par une clé. La procédure ci-dessous échoue si une clé est déjà enregistrée pour la région via la commande REST. Pour déterminer si une clé est active dans la recherche d'agents pour un établissement, consultez Afficher les clés Cloud KMS.

Procédure

REST

Pour enregistrer votre propre clé pour la recherche par agent, procédez comme suit :

  1. Appelez la méthode UpdateCmekConfig avec la clé que vous souhaitez enregistrer.

    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"

    Remplacez les éléments suivants :

    • KMS_PROJECT_ID : ID du projet contenant la clé. Le numéro de projet ne fonctionnera pas.
    • KMS_LOCATION : emplacement multirégional de votre clé : us ou europe.
    • KEY_RING : nom du trousseau de clés qui inclut la clé.
    • KEY_NAME : nom de la clé.
    • PROJECT_ID : ID du projet contenant l'application ou le connecteur de données.
    • LOCATION : emplacement multirégional de votre application ou connecteur de données : us ou eu.
    • CMEK_CONFIG_ID : définissez un ID unique pour la ressource CmekConfig, par exemple default_cmek_config.

    • SET_DEFAULT : définissez sur true pour utiliser la clé comme clé par défaut pour les applications et les connecteurs de données créés ultérieurement dans la région multirégionale.

  2. Facultatif : Enregistrez la valeur name renvoyée par la méthode et suivez les instructions de la section Obtenir des informations sur une opération de longue durée pour savoir quand l'opération est terminée.

    L'enregistrement d'une clé prend généralement quelques minutes.

    Une fois l'opération terminée, les nouvelles applications et connecteurs de données de cette multirégion sont protégés par la clé. Pour obtenir des informations générales sur la création d'applications, consultez À propos des applications et des data stores.

  3. Créez l'application. Pour obtenir des instructions, consultez Créer une application et À propos des applications et des datastores.

Console

Procédure

Pour enregistrer votre propre clé pour la recherche par agent, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Applications d'IA.

    AI Applications

  2. Cliquez sur Paramètres, puis sélectionnez l'onglet CMEK.

  3. Cliquez sur Add key (Ajouter une clé) pour l'emplacement us (États-Unis) ou eu (Europe).

    Cliquez sur "Ajouter une clé" pour un lieu.
    Cliquez sur "Ajouter une clé".

    1. Cliquez sur le menu déroulant Sélectionner une clé Cloud KMS, puis sélectionnez la clé.

      • Si la clé se trouve dans un autre projet, cliquez sur Changer de projet, cliquez sur le nom de votre projet, saisissez le nom de la clé que vous avez créée, puis sélectionnez-la.

      • Si vous connaissez le nom de ressource de la clé, cliquez sur Saisir manuellement, collez le nom de ressource de la clé, puis cliquez sur Enregistrer.

    2. Cliquez sur OK > Enregistrer.

  4. Créez l'application. Pour obtenir des instructions, consultez Créer une application et À propos des applications et des datastores.

Cela enregistre votre clé et crée une ressource CmekResource appelée default_cmek_config.

Plusieurs heures peuvent s'écouler avant que les données ingérées n'apparaissent dans les résultats de recherche.

Afficher les clés Cloud KMS

Pour afficher une clé enregistrée pour la recherche d'agents, effectuez l'une des opérations suivantes :

  • Si vous disposez du nom de ressource CmekConfig, appelez la méthode 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"

    Remplacez les éléments suivants :

    • LOCATION : emplacement multirégional de votre application ou connecteur de données : us ou eu.
    • PROJECT_ID : ID du projet contenant les données.
    • CMEK_CONFIG_ID : ID de la ressource CmekConfig. Si vous avez enregistré votre clé à l'aide de la console, l'ID est default_cmek_config.

    Voici un exemple d'appel et de réponse curl : 

    $ 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
}

  • Si vous ne disposez pas du nom de ressource CmekConfig, appelez la méthode ListCmekConfigs :

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

    Remplacez les éléments suivants :

    • LOCATION : emplacement multirégional de votre application ou connecteur de données : us ou eu.
    • PROJECT_ID : ID du projet contenant les données.

    Voici un exemple d'appel et de réponse curl : 

    $ 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
    }
  ]
}

Désenregistrer votre clé Cloud KMS

Pour annuler l'enregistrement de votre clé dans la recherche d'agents, procédez comme suit :

  1. Appelez la méthode DeleteCmekConfig avec le nom de ressource CmekConfig que vous souhaitez annuler.

    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"

    Remplacez les éléments suivants :

    • LOCATION : emplacement multirégional de votre application ou connecteur de données : us ou eu.
    • PROJECT_ID : ID du projet contenant l'application ou le connecteur de données.
    • CMEK_CONFIG_ID : ID de la ressource CmekConfig. Si vous avez enregistré votre clé à l'aide de la console, l'ID est default_cmek_config.

    Voici un exemple d'appel et de réponse curl : 

    $ 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. Facultatif : Enregistrez la valeur name renvoyée par la méthode et suivez les instructions de la section Obtenir des détails sur une opération de longue durée pour savoir quand l'opération est terminée.

    La suppression d'une configuration CmekConfig est une opération de longue durée qui peut prendre jusqu'à deux jours. En effet, les ressources chiffrées sous-jacentes sont entièrement déprovisionnées avant la suppression de CmekConfig.

Vérifier qu'une application ou un connecteur de données sont protégés par une clé

Les applications et les connecteurs de données créés après l'enregistrement de votre clé sont protégés par celle-ci. Si vous souhaitez vérifier qu'une application ou un connecteur de données spécifique est protégé par votre clé, procédez comme suit :

Valider à l'aide de la console Google Cloud

Vous pouvez utiliser la console Google Cloud pour vérifier si une configuration CMEK par défaut est définie.

  1. Dans la console Google Cloud , accédez à la page Applications d'IA.
  2. Cliquez sur Paramètres, puis sélectionnez l'onglet CMEK.
  3. Vérifiez que l'état de la configuration de votre établissement est défini sur Active et que votre clé enregistrée s'affiche.

Vérifier à l'aide de la CLI / API

  1. Pour valider un data store :

    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"

    Remplacez les éléments suivants :

    • LOCATION : emplacement multirégional de votre projet : us ou eu.
    • PROJECT_ID : ID du projet contenant l'application ou le connecteur de données.
    • DATA_STORE_ID : ID du data store associé à votre application ou à votre connecteur de données.

    Voici un exemple d'appel curl : 

    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. Pour valider une application :

    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"

    Remplacez les éléments suivants :

    • LOCATION : emplacement multirégional de votre projet : us ou eu.
    • PROJECT_ID : ID du projet contenant l'application.
    • ENGINE_ID : ID de votre application.

    Voici un exemple d'appel curl : 

    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. Examinez le résultat de la commande : si le champ cmekConfig figure dans le résultat et que le champ kmsKey affiche la clé que vous avez enregistrée, l'application ou le connecteur de données sont protégés par la clé.

    Voici un exemple de réponse pour un data store :

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

    Voici un exemple de réponse pour une application :

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

Autres données protégées par la clé Cloud KMS

En plus des données des applications et des connecteurs de données, vos clés peuvent protéger d'autres types d'informations de base appartenant à l'application et détenues par Agent Search, comme les données de session générées lors de la recherche avec suivi. Ce type d'informations de base est protégé par CMEK si les applications et les connecteurs de données sont protégés par CMEK.

Bien que vous ne puissiez pas exécuter de commande spécifique pour vérifier que les sessions sont protégées, vous pouvez vérifier si l'application est protégée. Exécutez la commande Vérifier qu'une application ou un connecteur de données est protégé par une clé pour que l'application puisse voir la clé dans la ressource cmekConfig. Vous saurez alors que les données de session sont protégées.

Effectuer une rotation des clés Cloud KMS

Lorsque vous effectuez une rotation de clés, vous créez une nouvelle version de la clé et la définissez comme version principale. Laissez la version d'origine de la clé activée pendant un certain temps avant de la désactiver. Cela donne le temps aux opérations de longue durée qui pourraient utiliser l'ancienne clé de se terminer.

La procédure suivante décrit les étapes à suivre pour alterner les clés d'une application Agent Search ou d'un connecteur de données. Pour obtenir des informations générales sur la rotation des clés, consultez Rotation des clés dans le guide Cloud KMS.

Important : Ne faites pas pivoter les clés sur les applications ou les connecteurs de données associés aux recommandations ou aux applications nécessitant des analyses. Ne faites pas non plus pivoter les clés à région unique utilisées pour les connecteurs tiers. Consultez Limites de Cloud KMS dans Agent Search.

  1. Réenregistrez votre clé. Pour ce faire, répétez l'étape 1 de la section Enregistrer votre clé Cloud KMS.

  2. Consultez les instructions de la section Gérer les clés du guide Cloud KMS pour effectuer les opérations suivantes :

    1. Créez une version de clé, activez-la et définissez-la comme version principale.

      Une fois la nouvelle clé définie comme clé primaire, les documents de l'application ou du connecteur de données sont à nouveau chiffrés à l'aide de la nouvelle clé. Tous les documents ajoutés ultérieurement à l'application ou au connecteur de données sont chiffrés avec la nouvelle clé.

    2. Laissez l'ancienne version de clé activée.

    3. Au bout d'une semaine environ, désactivez l'ancienne version de clé et assurez-vous que tout fonctionne comme avant.

    4. Plus tard, lorsque vous serez certain qu'aucun problème n'a été causé par la désactivation de l'ancienne version de clé, vous pourrez la détruire.

Si une clé Cloud KMS est désactivée ou révoquée

Si une clé est désactivée ou si les autorisations associées sont révoquées, l'application ou le connecteur de données cesse d'ingérer et de diffuser des données dans les 15 minutes. Vous pouvez réactiver votre clé dans les 30 jours pour reprendre les opérations avant l'expiration de la configuration CMEK et la suppression définitive des données associées. Toutefois, la réactivation d'une clé ou la restauration des autorisations prend beaucoup de temps. Il peut s'écouler jusqu'à 24 heures avant que l'application ou le connecteur de données ne puissent à nouveau diffuser des données.

Par conséquent, ne désactivez une clé que si nécessaire. Désactiver et activer une clé sur une application ou un connecteur de données est une opération qui prend du temps. Par exemple, si vous activez et désactivez une clé à plusieurs reprises, l'application ou le connecteur de données mettront beaucoup de temps à atteindre un état protégé. Si vous désactivez une clé et la réactivez immédiatement après, vous risquez de subir des jours d'indisponibilité, car la clé est d'abord désactivée dans l'application ou le connecteur de données, puis réactivée.

Résoudre les problèmes : erreur "Projets contenant la clé KMS introuvables"

Symptôme : Lorsque vous essayez de créer une application ou un connecteur de données à l'aide d'une clé KMS, une erreur semblable à la suivante s'affiche :

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

Problème : Ce message d'erreur peut être trompeur. Cela ne signifie pas forcément que la clé n'existe pas. Il peut plutôt indiquer que la clé KMS n'a pas été enregistrée pour être utilisée avec la recherche par agent à l'emplacement spécifié.

Solution : pour résoudre ce problème, enregistrez votre clé en suivant les étapes décrites dans Enregistrer votre clé Cloud KMS. Une fois l'enregistrement terminé, vous pouvez créer des applications ou des connecteurs de données protégés par cette clé.