Claves de encriptación administradas por el cliente (CMEK)

De forma predeterminada, Gemini Data Analytics encripta el contenido del cliente en reposo. Gemini Data Analytics controla la encriptación por ti sin que tengas que realizar ninguna acción adicional por tu parte. Esta opción se denomina encriptación predeterminada de Google.

Si deseas controlar tus claves de encriptación, puedes usar las claves de encriptación administradas por el cliente (CMEK) en Cloud KMS con servicios integrados en CMEK, incluido Gemini Data Analytics. El uso de claves de Cloud KMS te permite controlar su nivel de protección, ubicación, programa de rotación, permisos de uso y acceso, y límites criptográficos. El uso de Cloud KMS también te permite ver los registros de auditoría y controlar los ciclos de vida de las claves. En lugar de que Google posea y administre las claves de encriptación de claves (KEK) simétricas que protegen tus datos, tú las controlas y administras en Cloud KMS.

Después de configurar tus recursos con CMEK, la experiencia de acceso a tus recursos de Gemini Data Analytics es similar a usar la encriptación predeterminada de Google. Para obtener más información sobre tus opciones de encriptación, consulta Claves de encriptación administradas por el cliente (CMEK).

En esta página, se describe cómo usar claves de encriptación administradas por el cliente (CMEK) para proteger los datos que usa la API de Conversational Analytics con fuentes de datos de Looker. La API de Conversational Analytics es un producto dentro del servicio de Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK para recursos de la API de Conversational Analytics

Cuando configuras CMEK para un recurso de la API de Conversational Analytics, la clave de Cloud KMS especificada encripta los datos sensibles en reposo. Puedes configurar CMEK para los recursos DataAgent y Conversation de forma independiente.

Puedes configurar CMEK solo en el momento de la creación del recurso. Para usar CMEK, debes especificar el campo kms_key cuando creas un recurso DataAgent o Conversation. No puedes agregar ni cambiar una clave de Cloud KMS en un recurso existente.

Qué se protege con CMEK

CMEK para la API de Conversational Analytics protege los siguientes datos en reposo:

  • Recursos DataAgent: Todo el contenido principal del cliente dentro de los campos staging_context, published_context y last_published_context de data_analytics_agent. Esto incluye campos como system_instruction y example_queries.
  • Recursos Conversation: Todos los mensajes y el historial de estados.

Los siguientes datos no están encriptados con la clave CMEK del cliente. En cambio, estos datos están protegidos por la encriptación predeterminada de Google:

  • recursos: Campos de metadatos, incluidos name, display_name, description, labels, create_time, update_time, delete_time, purge_time y kms_keyDataAgent
  • Recursos Conversation: Campos de metadatos, incluidos name, agents, labels, create_time, last_used_time y kms_key

Limitaciones

CMEK para la API de Conversational Analytics tiene las siguientes limitaciones:

  • CMEK se debe configurar cuando se crea el recurso. No se puede agregar ni cambiar en un recurso existente.
  • La clave de Cloud KMS y el recurso de la API de Conversational Analytics deben estar en la misma ubicación. No se admite la región global.
  • Para los recursos de la API de Conversational Analytics, CMEK se admite en la región us-east4.
  • Para los recursos de la API de Conversational Analytics, CMEK solo se admite para las fuentes de datos de Looker.
  • Puedes usar solo una CMEK por proyecto y por región para todos los recursos Conversation dentro de ese proyecto y región.

Antes de comenzar

Antes de usar CMEK con la API de Conversational Analytics, completa los siguientes pasos:

  1. Habilita las APIs requeridas en la Google Cloud consola o en Google Cloud CLI.

    Console

    Habilita las siguientes APIs en la Google Cloud consola depara tu Google Cloud proyecto.

    Habilita la API de Gemini Data Analytics

    Habilita la API de Gemini for Google Cloud

    Habilita la API de Cloud Key Management Service

    Google Cloud

    gcloud

    Con Google Cloud CLI, ejecuta los siguientes comandos gcloud services enable para habilitar la API de Gemini Data Analytics, la API de Gemini for Google Cloud y la API de Cloud Key Management Service, respectivamente:

    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

    En los comandos de ejemplo anteriores de gcloud CLI, reemplaza project_id por el ID del proyecto Google Cloud .

  2. Agrega tu proyecto a la lista de entidades permitidas.

    Tu Google Cloud proyecto se debe agregar a una lista de entidades permitidas para usar CMEK con Gemini Data Analytics. Para solicitar que se agregue tu proyecto a la lista de entidades permitidas, envía el ID del proyecto a través del formulario de lista de entidades permitidas de CMEK de GDA. Agregar tu proyecto a la lista de entidades permitidas tarda aproximadamente uno o dos días hábiles en completarse.

  3. Crea un llavero de claves y una clave de Cloud KMS en la misma ubicación que tus recursos de la API de Conversational Analytics. Para obtener más información, consulta Crea una clave.

  4. Crea los agentes de servicio administrados por Google, también conocidos como cuentas de servicio por producto y por proyecto (P4SA), si aún no existen. Estos agentes de servicio son necesarios para permitir que los servicios que participan en la protección de tus recursos de la API de Conversational Analytics con CMEK accedan a tu clave de Cloud KMS.

    Ejecuta los siguientes comandos gcloud para crear los agentes de servicio: 

    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    Reemplaza PROJECT_ID por el ID del proyecto. Google Cloud

  5. Otorga la función de encriptador/desencriptador de clave de encriptación de Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) en Identity and Access Management (IAM) a ambos agentes de servicio que creaste en el paso anterior para permitir que el servicio de Gemini Data Analytics use tu clave de Cloud KMS para encriptar y desencriptar tus datos de la API de Conversational Analytics.

    Otorga el permiso al agente de servicio de 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

    Otorga el permiso al agente de servicio de Gemini for 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

    En los ejemplos de código anteriores, reemplaza los valores de muestra de la siguiente manera:

    • KEY_NAME: El nombre de tu clave de Cloud KMS.
    • KEY_LOCATION: La región de tu llavero de claves (por ejemplo, us-east4).
    • KEY_RING_NAME: El nombre del llavero de claves.
    • PROJECT_NUMBER: El Google Cloud número del proyecto en el que creas recursos de la API.
    • KMS_PROJECT_ID: El ID del proyecto en el que se creó la clave. Puede ser el mismo que el proyecto en el que creas recursos de la API.

Protege recursos con CMEK

En esta sección, se muestra cómo proteger un recurso DataAgent o Conversation nuevo con CMEK mediante la API de REST para especificar una clave de Cloud KMS en el campo kms_key durante la creación del recurso.

Puedes habilitar CMEK solo cuando creas un recurso DataAgent o Conversation.

Una clave CMEK debe estar en la misma región que el recurso que protege. Para obtener más información, consulta Limitaciones.

Protege un recurso DataAgent con CMEK

Para proteger un recurso DataAgent nuevo con CMEK, especifica una clave de Cloud KMS en el campo kms_key cuando crees el agente de datos.

Python SDK

En el siguiente ejemplo, se muestra cómo especificar una clave de Cloud KMS cuando creas un recurso DataAgent con el SDK de Python. Para obtener un ejemplo de una solicitud create completa, consulta Compila un agente de datos con el SDK de 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

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

  • BILLING_PROJECT_ID: El ID del proyecto de facturación.
  • KEY_RING_NAME: El nombre del llavero de claves de Cloud KMS.
  • KEY_NAME: El nombre de tu clave de Cloud KMS.
  • KMS_PROJECT_ID: El ID del proyecto en el que se creó la clave. Si se deja vacío, se usa billing_project.
  • LOCATION: La región del llavero de claves.

HTTP

En el siguiente ejemplo, se muestra cómo especificar una clave de Cloud KMS en el cuerpo de la solicitud cuando creas un recurso DataAgent con HTTP y Python. Para obtener un ejemplo de una solicitud create completa, consulta Compila un agente de datos con HTTP y 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,
          }
      }
  }

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

  • KMS_PROJECT_ID: El ID del proyecto en el que se creó la clave.
  • LOCATION: La región del llavero de claves.
  • KEY_RING_NAME: El nombre del llavero de claves de Cloud KMS.
  • KEY_NAME: El nombre de tu clave de Cloud KMS.

Protege un recurso Conversation con CMEK

Para proteger un recurso Conversation nuevo con CMEK, especifica una clave de Cloud KMS en el campo kms_key cuando crees la conversación.

Python SDK

En el siguiente ejemplo, se muestra cómo especificar una clave de Cloud KMS cuando creas un recurso Conversation con el SDK de Python. Para obtener un ejemplo de una solicitud create completa, consulta Compila un agente de datos con el SDK de 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

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

  • BILLING_PROJECT_ID: El ID del proyecto de facturación.
  • KEY_RING_NAME: El nombre del llavero de claves de Cloud KMS.
  • KEY_NAME: El nombre de tu clave de Cloud KMS.
  • KMS_PROJECT_ID: El ID del proyecto en el que se creó la clave. Si se deja vacío, se usa billing_project.
  • LOCATION: La región del llavero de claves.

HTTP

En el siguiente ejemplo, se muestra cómo especificar una clave de Cloud KMS en el cuerpo de la solicitud cuando creas un recurso Conversation con HTTP y Python. Para obtener un ejemplo de una solicitud create completa, consulta Compila un agente de datos con HTTP y 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}"
}

En el ejemplo anterior, reemplaza los valores de la siguiente manera:

  • KMS_PROJECT_ID: El ID del proyecto en el que se creó la clave.
  • LOCATION: La región del llavero de claves.
  • KEY_RING_NAME: El nombre del llavero de claves de Cloud KMS.
  • KEY_NAME: El nombre de tu clave de Cloud KMS.

Soluciona problemas

En esta sección, se tratan los problemas comunes y las consideraciones importantes cuando usas CMEK con la API de Conversational Analytics.

Cambios de estado de la clave

Si una versión de clave de Cloud KMS que protege un recurso de la API de Conversational Analytics deja de estar disponible, pierdes el acceso a los datos encriptados por esa clave. Si intentas acceder a datos protegidos mientras la clave no está disponible, por ejemplo, leyendo el contexto de un recurso DataAgent o accediendo al historial de Conversation, la solicitud falla. El error que se muestra depende del motivo por el que la clave no está disponible:

  • Si la versión de la clave está inhabilitada o destruida, la operación suele fallar con un error FAILED_PRECONDITION.
  • Si se revoca la función de IAM cloudkms.cryptoKeyEncrypterDecrypter del agente de servicio gcp-sa-geminidataanalytics o gcp-sa-cloudaicompanion, la operación suele fallar con un error PERMISSION_DENIED o NOT_FOUND.

Incluso cuando la clave no está disponible, puedes realizar operaciones que no requieran desencriptar el contenido, como borrar el recurso DataAgent o Conversation.

Para restablecer el acceso a los datos encriptados, vuelve a habilitar la clave y asegúrate de que los agentes de servicio tengan los permisos de IAM requeridos, como se describe en Antes de comenzar.

Cuotas de Cloud KMS y la API de Conversational Analytics

Cuando usas CMEK en la API de Conversational Analytics, tus proyectos pueden consumir cuotas de solicitudes criptográficas de Cloud KMS. Por ejemplo, leer un recurso DataAgent o acceder al historial de Conversation protegido por CMEK requiere que Cloud KMS desencripte los datos.

Las operaciones de encriptación y desencriptación con claves CMEK afectan las cuotas de Cloud KMS de las siguientes maneras:

  • En el caso de las claves CMEK de software generadas en Cloud KMS, no se consume cuota de Cloud KMS.
  • En el caso de las claves CMEK de hardware, a veces llamadas claves de Cloud HSM, las operaciones de encriptación y desencriptación se descuentan de las cuotas de Cloud HSM en el proyecto que contiene la clave.
  • Para las claves CMEK externas, a veces llamadas claves de Cloud EKM, las operaciones de encriptación y desencriptación se descuentan de las cuotas de Cloud EKM del proyecto que contiene la clave.

Para obtener más información, consulta Cuotas de Cloud KMS.

¿Qué sigue?