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

Par défaut, Gemini Data Analytics chiffre le contenu client au repos. Gemini Data Analytics gère le chiffrement pour vous sans aucune action supplémentaire 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 une 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 la CMEK indépendamment pour les ressources DataAgent et Conversation.

Vous ne pouvez configurer la CMEK qu'au moment de la création de la ressource. Pour utiliser la 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

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

  • Ressources DataAgent : tous les contenus client principaux 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.
  • Ressources Conversation : tous les messages et l'historique des états.

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

  • DataAgent ressources : 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

La CMEK pour l'API Conversational Analytics présente les limites suivantes :

  • La CMEK doit être configurée lors de la création de la ressource. Elle ne peut pas être ajoutée ni modifiée sur une ressource existante.
  • 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 compatible.
  • Pour les ressources de l'API Conversational Analytics, la CMEK est compatible dans la région us-east4.
  • Pour les ressources de l'API Conversational Analytics, la 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 la CMEK avec l'API Conversational Analytics, procédez comme suit :

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

    Console

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

    Activer l'API Gemini Data Analytics

    Activer Gemini pour l' Google Cloud API

    Activer l'API Cloud Key Management Service

    gcloud

    Avec Google Cloud CLI, exécutez les commandes gcloud services enable suivantes pour activer respectivement l'API Gemini Data Analytics, Gemini pour Google Cloud l'API 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 commandes gcloud CLI de l'exemple précédent, remplacez project_id par l'ID de votre Google Cloud projet.

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

    Votre Google Cloud projet doit être ajouté à une liste d'autorisation pour utiliser la CMEK avec Gemini Data Analytics. Pour demander l'ajout de votre projet à la liste d'autorisation, envoyez votre ID de projet via le formulaire de 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 de clés et une clé Cloud KMS au même emplacement que vos ressources de l'API Conversational Analytics. Pour en savoir plus, consultez la page 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 la 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 Google Cloud projet.

  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 pour permettre au service Gemini Data Analytics d'utiliser votre clé Cloud KMS pour chiffrer et déchiffrer les données de votre API Conversational Analytics.

    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 Gemini pour l' Google Cloud API :

    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 dans lequel vous créez des ressources d'API. Google Cloud
    • 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 une CMEK

Cette section explique comment protéger une nouvelle ressource DataAgent ou Conversation avec une CMEK à l'aide de 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 CMEK

Pour protéger une nouvelle ressource DataAgent avec une 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 la section 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 laissé vide, billing_project est utilisé.
  • 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 la section 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 CMEK

Pour protéger une nouvelle ressource Conversation avec une 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 la section 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 laissé vide, billing_project est utilisé.
  • 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 la section 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 la CMEK avec l'API Conversational Analytics.

Modifications de l'é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é est indisponible :

  • Si la version de 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é est indisponible, vous pouvez toujours effectuer des opérations qui ne nécessitent pas de déchiffrer le contenu, comme la suppression de 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 la section 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 une CMEK nécessite 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.

Étape suivante