Clés de chiffrement gérées par le client (CMEK)

Par défaut, Gemini Data Analytics chiffre les contenus client au repos. Gemini Data Analytics 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 Gemini Data Analytics. 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. Grâce à Cloud KMS, vous pouvez également afficher les journaux d'audit et 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 Gemini Data Analytics 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).

Cette page explique comment utiliser les clés de chiffrement gérées par le client (CMEK) pour protéger les données utilisées par l'API Conversational Analytics avec les sources de données Looker. L'API Conversational Analytics est un produit du service Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK pour les ressources de l'API Conversational Analytics

Lorsque vous configurez CMEK pour une ressource de l'API Conversational Analytics, la clé Cloud KMS spécifiée chiffre les données sensibles au repos. Vous pouvez configurer CMEK pour les ressources DataAgent et Conversation de manière indépendante.

Vous ne pouvez configurer CMEK qu'au moment de la création de la ressource. Pour utiliser CMEK, vous devez spécifier le champ kms_key lorsque vous créez une ressource DataAgent ou Conversation. Vous ne pouvez pas ajouter ni modifier une clé Cloud KMS sur une ressource existante.

Éléments protégés par CMEK

CMEK pour l'API Conversational Analytics protège les données au repos suivantes :

  • Ressources DataAgent : tous les contenus principaux des clients dans les champs staging_context, published_context et last_published_context de data_analytics_agent. Cela inclut des champs tels que system_instruction et example_queries.
  • Conversation resources : tous les messages et l'historique des états.

Les données suivantes ne sont pas chiffrées avec la clé CMEK du client. Ces données sont protégées par le chiffrement par défaut de Google :

  • Ressources DataAgent : champs de métadonnées, y compris name, display_name, description, labels, create_time, update_time, delete_time, purge_time et kms_key
  • Ressources Conversation : champs de métadonnées, y compris name, agents, labels, create_time, last_used_time et kms_key

Limites

L'utilisation de clés gérées par le client (CMEK) pour l'API Conversational Analytics présente les limites suivantes :

  • CMEK doit être configuré lors de la création de la ressource. Il ne peut pas être ajouté à une ressource existante ni modifié sur celle-ci.
  • La clé Cloud KMS et la ressource de l'API Conversational Analytics doivent se trouver au même emplacement. La région global n'est pas disponible.
  • Pour les ressources de l'API Conversational Analytics, le chiffrement CMEK est disponible dans la région us-east4.
  • Pour les ressources de l'API Conversational Analytics, CMEK n'est compatible qu'avec les sources de données Looker.
  • Vous ne pouvez utiliser qu'une seule CMEK par projet et par région pour toutes les ressources Conversation de ce projet et de cette région.

Avant de commencer

Avant de pouvoir utiliser les CMEK avec l'API Conversational Analytics, procédez comme suit :

  1. Activez les API requises dans la console Google Cloud ou Google Cloud CLI.

    Console

    Activez les API suivantes dans la console Google Cloud pour votre projet Google Cloud .

    Activer l'API Gemini Data Analytics

    Activer l'API Gemini pour Google Cloud

    Activer l'API Cloud Key Management Service

    gcloud

    Avec la Google Cloud CLI, exécutez les commandes gcloud services enable suivantes pour activer respectivement l'API Gemini Data Analytics, l'API Gemini pour Google Cloud et 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

    Dans les exemples de commandes gcloud CLI précédents, remplacez project_id par l'ID de votre projet Google Cloud .

  2. Ajoutez votre projet à la liste d'autorisation.

    Votre projet Google Cloud doit être ajouté à une liste d'autorisation pour utiliser CMEK avec Gemini Data Analytics. Pour demander l'ajout de votre projet à la liste d'autorisation, envoyez l'ID de votre projet via le formulaire d'ajout à la liste d'autorisation CMEK GDA. L'ajout de votre projet à la liste d'autorisation prend environ un à deux jours ouvrés.

  3. Créez un trousseau et une clé Cloud KMS au même emplacement que vos ressources de l'API Conversational Analytics. Pour en savoir plus, consultez Créer une clé.

  4. Créez les agents de service gérés par Google, également appelés comptes de service par produit et par projet (P4SA), s'ils n'existent pas déjà. Ces agents de service sont nécessaires pour permettre aux services impliqués dans la protection de vos ressources de l'API Conversational Analytics avec des CMEK d'accéder à votre clé Cloud KMS.

    Exécutez les commandes gcloud suivantes pour créer les agents de service : 

    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    Remplacez PROJECT_ID par l'ID de votre projet Google Cloud .

  5. Accordez le rôle Chiffreur/Déchiffreur de clés cryptographiques Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) dans Identity and Access Management (IAM) aux deux agents de service que vous avez créés à l'étape précédente. Cela permettra au service Gemini Data Analytics d'utiliser votre clé Cloud KMS pour chiffrer et déchiffrer vos données Conversational Analytics API.

    Accordez l'autorisation à l'agent de service 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

    Accordez l'autorisation à l'agent de service de l'API Gemini pour 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

    Dans les exemples de code précédents, remplacez les exemples de valeurs comme suit :

    • KEY_NAME : nom de votre clé Cloud KMS.
    • KEY_LOCATION : région de votre trousseau de clés (par exemple, us-east4).
    • KEY_RING_NAME : nom de votre trousseau de clés.
    • PROJECT_NUMBER : numéro de votre projet Google Cloud dans lequel vous créez des ressources d'API.
    • KMS_PROJECT_ID : ID du projet dans lequel la clé a été créée. Il peut s'agir du même projet que celui dans lequel vous créez des ressources d'API.

Protéger des ressources avec CMEK

Cette section explique comment protéger une nouvelle ressource DataAgent ou Conversation avec une CMEK en utilisant l'API REST pour spécifier une clé Cloud KMS dans le champ kms_key lors de la création de la ressource.

Vous ne pouvez activer la CMEK que lorsque vous créez une ressource DataAgent ou Conversation.

Une clé CMEK doit se trouver dans la même région que la ressource qu'elle protège. Pour en savoir plus, consultez la section Limites.

Protéger une ressource DataAgent avec une clé CMEK

Pour protéger une nouvelle ressource DataAgent avec CMEK, spécifiez une clé Cloud KMS dans le champ kms_key lorsque vous créez l'agent de données.

SDK Python

L'exemple suivant montre comment spécifier une clé Cloud KMS lorsque vous créez une ressource DataAgent avec le SDK Python. Pour obtenir un exemple de requête create complète, consultez Créer un agent de données à l'aide du 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

Dans l'exemple précédent, remplacez les valeurs comme suit :

  • BILLING_PROJECT_ID : ID de votre projet de facturation.
  • KEY_RING_NAME : nom de votre trousseau de clés Cloud KMS.
  • KEY_NAME : nom de votre clé Cloud KMS.
  • KMS_PROJECT_ID : ID du projet dans lequel la clé a été créée. Si ce champ est vide, la valeur billing_project est utilisée.
  • LOCATION : région de votre trousseau de clés.

HTTP

L'exemple suivant montre comment spécifier une clé Cloud KMS dans le corps de la requête lorsque vous créez une ressource DataAgent avec HTTP et Python. Pour obtenir un exemple de requête create complète, consultez Créer un agent de données à l'aide de HTTP et 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,
          }
      }
  }

Dans l'exemple précédent, remplacez les valeurs comme suit :

  • KMS_PROJECT_ID : ID du projet dans lequel la clé a été créée.
  • LOCATION : région de votre trousseau de clés.
  • KEY_RING_NAME : nom de votre trousseau de clés Cloud KMS.
  • KEY_NAME : nom de votre clé Cloud KMS.

Protéger une ressource Conversation avec une clé CMEK

Pour protéger une nouvelle ressource Conversation avec CMEK, spécifiez une clé Cloud KMS dans le champ kms_key lorsque vous créez la conversation.

SDK Python

L'exemple suivant montre comment spécifier une clé Cloud KMS lorsque vous créez une ressource Conversation avec le SDK Python. Pour obtenir un exemple de requête create complète, consultez Créer un agent de données à l'aide du 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

Dans l'exemple précédent, remplacez les valeurs comme suit :

  • BILLING_PROJECT_ID : ID de votre projet de facturation.
  • KEY_RING_NAME : nom de votre trousseau de clés Cloud KMS.
  • KEY_NAME : nom de votre clé Cloud KMS.
  • KMS_PROJECT_ID : ID du projet dans lequel la clé a été créée. Si ce champ est vide, la valeur billing_project est utilisée.
  • LOCATION : région de votre trousseau de clés.

HTTP

L'exemple suivant montre comment spécifier une clé Cloud KMS dans le corps de la requête lorsque vous créez une ressource Conversation avec HTTP et Python. Pour obtenir un exemple de requête create complète, consultez Créer un agent de données à l'aide de HTTP et 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}"
}

Dans l'exemple précédent, remplacez les valeurs comme suit :

  • KMS_PROJECT_ID : ID du projet dans lequel la clé a été créée.
  • LOCATION : région de votre trousseau de clés.
  • KEY_RING_NAME : nom de votre trousseau de clés Cloud KMS.
  • KEY_NAME : nom de votre clé Cloud KMS.

Dépannage

Cette section aborde les problèmes courants et les points importants à prendre en compte lorsque vous utilisez CMEK avec l'API Conversational Analytics.

Changements d'état des clés

Si une version de clé Cloud KMS qui protège une ressource de l'API Conversational Analytics devient indisponible, vous perdez l'accès aux données chiffrées par cette clé. Si vous tentez d'accéder à des données protégées alors que la clé est indisponible (par exemple, en lisant le contexte d'une ressource DataAgent ou en accédant à l'historique Conversation), la requête échoue. L'erreur renvoyée dépend de la raison pour laquelle la clé n'est pas disponible :

  • Si la version de la clé est désactivée ou détruite, l'opération échoue généralement avec une erreur FAILED_PRECONDITION.
  • Si le rôle IAM cloudkms.cryptoKeyEncrypterDecrypter est révoqué de l'agent de service gcp-sa-geminidataanalytics ou gcp-sa-cloudaicompanion, l'opération échoue généralement avec une erreur PERMISSION_DENIED ou NOT_FOUND.

Même lorsque la clé n'est pas disponible, vous pouvez toujours effectuer des opérations qui ne nécessitent pas de déchiffrer le contenu, comme supprimer la ressource DataAgent ou Conversation.

Pour rétablir l'accès aux données chiffrées, réactivez la clé et assurez-vous que les agents de service disposent des autorisations IAM requises, comme décrit dans Avant de commencer.

Quotas Cloud KMS et API Conversational Analytics

Lorsque vous utilisez une CMEK dans l'API Conversational Analytics, vos projets peuvent consommer des quotas de requêtes de chiffrement Cloud KMS. Par exemple, la lecture d'une ressource DataAgent ou l'accès à l'historique Conversation protégé par CMEK nécessitent que Cloud KMS déchiffre les données.

Les opérations de chiffrement et de déchiffrement utilisant des clés CMEK affectent les quotas de Cloud KMS de différentes manières :

  • Pour les clés logicielles CMEK générées dans Cloud KMS, aucun quota Cloud KMS n'est consommé.
  • Pour les clés CMEK matérielles (parfois appelées "clés Cloud HSM"), les opérations de chiffrement et de déchiffrement sont comptabilisées dans les quotas Cloud HSM du projet qui contient la clé.
  • Pour les clés CMEK externes (parfois appelées "clés Cloud EKM"), les opérations de chiffrement et de déchiffrement sont comptabilisées dans les quotas Cloud EKM du projet qui contient la clé.

Pour en savoir plus, consultez Quotas Cloud KMS.

Étapes suivantes