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 debas realizar ninguna acción adicional. 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 utiliza la API de Conversational Analytics con fuentes de datos de Looker. La API de Conversational Analytics es un producto del servicio de Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK para recursos de la API de Conversational Analytics

Cuando configuras la 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 de DataAgent y Conversation de forma independiente.

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

Qué se protege con CMEK

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

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

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

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

Limitaciones

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

  • La 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. La región global no es compatible.
  • En el caso de los recursos de la API de Conversational Analytics, las CMEK se admiten en la región us-east4.
  • En el caso de los recursos de la API de Conversational Analytics, la CMEK solo se admite para las fuentes de datos de Looker.
  • Solo puedes usar una CMEK por proyecto y región para todos los recursos Conversation dentro de ese proyecto y región.

Antes de comenzar

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

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

    Console

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

    Habilita la API de Gemini Data Analytics

    Habilita la API de Gemini para Google Cloud

    Habilita la API de Cloud Key Management Service

    gcloud

    Con Google Cloud CLI, ejecuta los siguientes comandos de 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 gcloud CLI del ejemplo anterior, reemplaza project_id por el ID de tu proyecto de Google Cloud .

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

    Tu proyecto Google Cloud debe agregarse a una lista de entidades permitidas para usar la CMEK con Gemini Data Analytics. Para solicitar que se agregue tu proyecto a la lista de entidades permitidas, envía tu ID del proyecto a través del formulario de lista de entidades permitidas de la CMEK de GDA. Agregar tu proyecto a la lista de entidades permitidas demora entre uno y 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 los 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 involucrados 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 de 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 de Google Cloud .

  5. Otorga el rol de encriptador/desencriptador de CryptoKey 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 permiso al agente de servicio de análisis de datos de Gemini:

    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 permiso al agente de servicio de la API de Gemini para 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

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

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

Protege recursos con CMEK

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

Solo puedes habilitar la CMEK cuando creas un recurso DataAgent o Conversation.

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

Protege un recurso de 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 ver un ejemplo de una solicitud create completa, consulta Cómo compilar 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: Es el ID de tu proyecto de facturación.
  • KEY_RING_NAME: El nombre de tu llavero de claves de Cloud KMS.
  • KEY_NAME: Es el nombre de tu clave de Cloud KMS.
  • KMS_PROJECT_ID: Es el ID del proyecto en el que se creó la clave. Si se deja vacío, se usa billing_project.
  • LOCATION: Es 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. Si quieres ver un ejemplo de una solicitud create completa, consulta Crea 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: Es el ID del proyecto en el que se creó la clave.
  • LOCATION: Es la región del llavero de claves.
  • KEY_RING_NAME: El nombre de tu llavero de claves de Cloud KMS.
  • KEY_NAME: Es el nombre de tu clave de Cloud KMS.

Protege un recurso de 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 ver un ejemplo de una solicitud create completa, consulta Cómo compilar 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: Es el ID de tu proyecto de facturación.
  • KEY_RING_NAME: El nombre de tu llavero de claves de Cloud KMS.
  • KEY_NAME: Es el nombre de tu clave de Cloud KMS.
  • KMS_PROJECT_ID: Es el ID del proyecto en el que se creó la clave. Si se deja vacío, se usa billing_project.
  • LOCATION: Es 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. Si quieres ver un ejemplo de una solicitud create completa, consulta Crea 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: Es el ID del proyecto en el que se creó la clave.
  • LOCATION: Es la región del llavero de claves.
  • KEY_RING_NAME: El nombre de tu llavero de claves de Cloud KMS.
  • KEY_NAME: Es el nombre de tu clave de Cloud KMS.

Soluciona problemas

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

Cambios de estado de la llave

Si una versión de clave de Cloud KMS que protege un recurso de la API de Conversational Analytics deja de estar disponible, perderás el acceso a los datos encriptados con 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 fallará. El error que se devuelve 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 el rol 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 requieren 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 necesarios, 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 que está 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?