Chaves de criptografia gerenciadas pelo cliente

Por padrão, a Pesquisa do agente criptografa o conteúdo do cliente em repouso. A Pesquisa do agente executa a criptografia, e você não precisa fazer nada. Essa opção é chamada de criptografia padrão do Google.

Se você quiser controlar suas chaves de criptografia, use chaves de criptografia gerenciadas pelo cliente (CMEKs) no Cloud KMS com serviços integrados a CMEKs, incluindo a Pesquisa de Agentes. Ao usar chaves do Cloud KMS, é possível controlar o nível de proteção, o local, a programação de rotação, as permissões de uso e acesso e os limites criptográficos. Ao usar o Cloud KMS, é possível também monitorar o uso de chaves, ver registros de auditoria e controlar ciclos de vida de chaves. Em vez de o Google ser proprietário e responsável pelo gerenciamento das chaves de criptografia de chaves (KEKs) simétricas que protegem seus dados, você controla e gerencia essas chaves no Cloud KMS.

Depois de configurar os recursos com CMEKs, a experiência de acesso aos recursos da Pesquisa por agente é semelhante à criptografia padrão do Google. Para saber mais sobre suas opções de criptografia, consulte Chaves de criptografia gerenciadas pelo cliente (CMEK).

Quando uma chave CMEK é registrada, a Pesquisa de Agentes chama o Cloud KMS periodicamente para manter uma instância logicamente isolada dos seus dados. Isso acontece mesmo que a configuração da CMEK não esteja definida como padrão e não haja apps ou conectores de dados usando-a. O uso vem da configuração e execução da instância, não do volume de dados ou do número de usuários que a acessam. Consulte os preços do Cloud Key Management Service.

Para encerrar completamente o uso do Cloud KMS, é necessário cancelar o registro da chave do Cloud KMS, desativar a chave ou revogar as permissões dela. A desativação da API Agent Search não exclui o CmekConfig nem seus dados, e você continua sendo cobrado pelo uso da CMEK.

Limitações do Cloud KMS na Agent Search

As seguintes limitações se aplicam às chaves CMEK (Cloud KMS) na Pesquisa de Agente:

  • As chaves que já foram aplicadas a um app ou conector de dados não podem ser alteradas, mas as versões delas podem ser alternadas.
  • É preciso usar apps e repositórios de dados multirregionais dos EUA ou da UE (não globais). Para mais informações sobre multirregiões e residência de dados, incluindo limites associados ao uso de locais não globais, consulte locais.

  • Se você precisar registrar mais de uma chave para um projeto, entre em contato com a equipe da sua conta do Google para solicitar um aumento de cota para configurações de CMEK, justificando por que você precisa de mais de uma chave.

    As seguintes limitações se aplicam ao EKM ou HSM com CMEK:

    • Sua cota de EKM e HSM para chamadas de criptografia e descriptografia precisa ter pelo menos 1.000 QPM de margem. Para saber como verificar suas cotas, consulte Verificar suas cotas do Cloud KMS.

    • Se você estiver usando o EKM, a chave precisará estar acessível por mais de 90% de qualquer período superior a 30 segundos. Se a chave não estiver acessível por esse período, isso poderá afetar negativamente a indexação e a atualização da pesquisa.

    • Se houver problemas de faturamento, de falta de cota ou de inacessibilidade por mais de 12 horas, o serviço desativará automaticamente o CmekConfig associado à chave do EKM ou do HSM.

  • Os apps ou conectores de dados criados antes do registro de uma chave no projeto não podem ser protegidos por ela.
  • Para apps com vários conectores de dados, se um deles usar uma configuração de CMEK, todos os outros também precisarão usar a mesma configuração.

Sobre chaves de região única para conectores de terceiros

Se você usa conectores de terceiros e quer usar suas próprias chaves para proteger os dados conectados, crie três chaves de região única complementares, além da chave multirregional. Os comandos para criar chaves são fornecidos no procedimento a seguir, Registrar sua chave do Cloud KMS.

As chaves únicas precisam ser criadas para as seguintes regiões:

Multirregional Regiões únicas
eu europe-west1 europe-west4 europe-north1
us us-east1 us-central1 us-west1

Antes de começar

Verifique se você atende aos seguintes pré-requisitos:

  • Crie uma chave simétrica multirregional do Cloud KMS. Consulte Criar um keyring e Criar uma chave na documentação do Cloud KMS.

    • Defina o período de rotação como Nunca (rotação manual).

    • Em Local, selecione Multirregional e selecione Europa ou EUA no menu suspenso.

  • O papel do IAM de criptografador/descriptografador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido ao agente de serviço do Discovery Engine. A conta do agente de serviço tem um endereço de e-mail que usa o seguinte formato: service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com. Para instruções gerais sobre como adicionar um papel a um agente de serviço, consulte Conceder ou revogar um único papel.

  • O papel do IAM de criptografador/descriptografador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido ao agente de serviço do Cloud Storage. Se essa função não for concedida, a importação de dados para apps e conectores de dados protegidos por CMEK vai falhar porque o Discovery Engine não consegue criar o bucket e o diretório temporários protegidos por CMEK necessários para a importação.

  • Não crie apps nem conectores de dados que você quer gerenciar com sua chave até concluir as instruções de registro de chave nesta página.

Registrar sua chave do Cloud KMS

Para criptografar dados usando CMEK, registre sua chave multirregional. Opcional: se os dados precisarem de chaves de região única, por exemplo, ao usar conectores de terceiros, registre as chaves de região única.

Antes de começar

Certifique-se disto:

  • A região ainda não está protegida por uma chave. O procedimento abaixo falhará se uma chave já estiver registrada para a região por meio do comando REST. Para determinar se há uma chave ativa na Pesquisa de Agente para um local, consulte Ver chaves do Cloud KMS.

Procedimento

REST

Para registrar sua própria chave para a Pesquisa do agente, siga estas etapas:

  1. Chame o método UpdateCmekConfig com a chave que você quer registrar.

    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"

    Substitua:

    • KMS_PROJECT_ID: o ID do projeto que contém a chave. O número do projeto não vai funcionar.
    • KMS_LOCATION: a multirregião da sua chave: us ou europe.
    • KEY_RING: o nome do keyring que contém a chave.
    • KEY_NAME: o nome da chave;
    • PROJECT_ID: o ID do projeto que contém o app ou o conector de dados.
    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • CMEK_CONFIG_ID: defina um ID exclusivo para o recurso CmekConfig, por exemplo, default_cmek_config.

    • SET_DEFAULT: defina como true para usar a chave como padrão para apps e conectores de dados subsequentes criados na multirregião.

  2. Verifique se a chave está pronta para uso antes de criar apps ou conectores de dados. Uma chave registrada não pode proteger recursos até que esteja pronta. Normalmente, leva alguns minutos para registrar uma chave. Consulte Verificar se a chave do Cloud KMS está pronta para uso.

    Para acompanhar a operação de registro, registre o valor name retornado pelo método e siga as instruções em Ver detalhes sobre uma operação de longa duração.

    Depois que a chave estiver pronta, os novos apps e conectores de dados nessa multirregião serão protegidos por ela. Para informações gerais sobre como criar apps, consulte Sobre apps e repositórios de dados.

  3. Crie o app. Para links com instruções de criação de vários apps, consulte Sobre apps e repositórios de dados.

Console

Procedimento

Para registrar sua própria chave para a Pesquisa de Agente, siga estas etapas:

  1. No console Google Cloud , acesse a página Aplicativos de IA.

    Aplicativos de IA

  2. Clique em Configurações e selecione a guia CMEK.

  3. Clique em Adicionar chave para o local us ou eu.

    Clique em "Adicionar chave" para um local.
    Clique em "Adicionar chave".

    1. Clique no menu suspenso Selecionar uma chave do Cloud KMS e selecione a chave.

      • Se a chave estiver em outro projeto, clique em Trocar projeto, clique no nome do projeto, digite o nome da chave criada e selecione-a.

      • Se você souber o nome do recurso da chave, clique em Inserir manualmente, cole o nome do recurso da chave e clique em Salvar.

    2. Clique em OK > Salvar.

  4. Verifique se a chave está pronta para uso antes de criar apps ou conectores de dados. Uma chave registrada não pode proteger recursos até que esteja pronta. Consulte Verificar se a chave do Cloud KMS está pronta para uso.

  5. Crie o app. Para links com instruções de criação de vários apps, consulte Sobre apps e repositórios de dados.

Isso registra sua chave, criando um CmekResource chamado default_cmek_config.

Pode levar várias horas para que os dados ingeridos apareçam nos resultados da pesquisa.

Ver chaves do Cloud KMS

Para ver uma chave registrada para a Pesquisa de Agente, siga um destes procedimentos:

  • Se você tiver o nome do recurso CmekConfig, chame o método 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"

    Substitua:

    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém os dados.
    • CMEK_CONFIG_ID: o ID do recurso CmekConfig. Se você registrou a chave usando o console, o ID é default_cmek_config.

    Veja um exemplo de chamada e resposta 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",
  "kmsKeyVersion": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/2",
  "state": "ACTIVE",
  "isDefault": true,
  "lastRotationTimestampMicros": "1788220800000000"
}

  • Se você não tiver o nome do recurso CmekConfig, chame o método ListCmekConfigs:

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

    Substitua:

    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém os dados.

    Veja um exemplo de chamada e resposta 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",
      "kmsKeyVersion": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/2",
      "state": "ACTIVE",
      "isDefault": true,
      "lastRotationTimestampMicros": "1788220800000000"
    }
  ]
}

Verificar se a chave do Cloud KMS está pronta para uso

Depois de registrar uma chave, verifique se ela está pronta para uso antes de proteger qualquer recurso:

  1. Confira as chaves do Cloud KMS registradas. Consulte Ver chaves do Cloud KMS.

  2. Analise a saída do comando. O CmekConfig estará pronto para uso se todos os valores a seguir estiverem na saída:

    • "state": "ACTIVE"
    • "isDefault": true

    Se for "isDefault": true, a chave será aplicada automaticamente para proteger novos apps e conectores de dados.

Também é possível verificar se uma configuração padrão de CMEK está definida (ou seja, "isDefault": true) usando o console Google Cloud :

  1. No console Google Cloud , acesse a página Aplicativos de IA.

  2. Clique em Configurações e selecione a guia CMEK.

  3. Verifique se o status de configuração do seu local mostra a chave registrada.

Cancelar o registro da chave do Cloud KMS

Para cancelar o registro da sua chave na Pesquisa do agente, siga estas etapas:

  1. Chame o método DeleteCmekConfig com o nome do recurso CmekConfig que você quer cancelar o registro.

    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"

    Substitua:

    • LOCATION: a multirregião do seu app ou conector de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o app ou conector de dados.
    • CMEK_CONFIG_ID: o ID do recurso CmekConfig. Se você registrou a chave usando o console, o ID é default_cmek_config.

    Veja um exemplo de chamada e resposta 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. Opcional: registre o valor name retornado pelo método e siga as instruções em Ver detalhes sobre uma operação de longa duração para saber quando a operação foi concluída.

    A exclusão de um CmekConfig é uma operação de longa duração que pode levar até alguns dias para ser concluída. Isso ocorre porque os recursos criptografados subjacentes são totalmente desprovisionados antes da remoção do CmekConfig.

Verificar se um app ou conector de dados está protegido por uma chave

Os apps e conectores de dados criados depois que a chave é registrada são protegidos por ela. Para confirmar se um app ou conector de dados específico está protegido pela sua chave, siga estas etapas:

Verificar usando o console Google Cloud

  1. Para verificar se um conector de dados está protegido por uma chave:

    1. No console Google Cloud , acesse a página Aplicativos de IA.

    2. Clique em Repositórios de dados e selecione seu conector de dados.

    3. Verifique se o campo Chave do KMS mostra sua chave registrada.

Verificar usando a CLI / API

  1. Para verificar um repositório de dados:

    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"

    Substitua:

    • LOCATION: a multirregião do seu projeto: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o app ou o conector de dados.
    • DATA_STORE_ID: o ID do repositório de dados associado ao seu app ou conector de dados.

    Veja um exemplo de chamada 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. Para verificar um app:

    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"

    Substitua:

    • LOCATION: a multirregião do seu projeto: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o app.
    • ENGINE_ID: o ID do app.

    Veja um exemplo de chamada 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. Analise a saída do comando: se o campo cmekConfig estiver na saída e o campo kmsKey mostrar a chave que você registrou, o app ou o conector de dados estará protegido pela chave.

    Veja um exemplo de resposta para um repositório de dados:

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

    Veja um exemplo de resposta para um app:

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

Outros dados protegidos pela chave do Cloud KMS

Além dos dados nos apps e conectores de dados, suas chaves podem proteger outros tipos de informações essenciais do app mantidas pela Pesquisa de Agentes, como os dados de sessão gerados durante a pesquisa com acompanhamentos. Esse tipo de informação principal será protegido por CMEK se os apps e conectores de dados forem protegidos por CMEK.

Embora não seja possível executar um comando específico para verificar se as sessões estão protegidas, é possível verificar se o app está protegido. Execute o comando Verificar se um app ou conector de dados está protegido por uma chave para que o app veja a chave no recurso cmekConfig. Assim, você vai saber que os dados da sessão estão protegidos.

Fazer a rotação de chaves do Cloud KMS

Não é possível mudar qual chave protege um app ou conector de dados, mas você pode alternar essa chave para uma nova versão. Quando você cria uma nova versão de uma chave registrada como a versão principal, a Pesquisa do agente detecta a mudança e criptografa novamente seus dados com a nova versão da chave automaticamente. Não é necessário chamar um método de pesquisa de agente para iniciar uma rotação.

Para informações gerais sobre a rotação de chaves, consulte Rotação de chaves no guia do Cloud KMS.

Importante:não gire as chaves em apps ou conectores de dados associados a recomendações ou a apps que precisam de análises. Além disso, não gire as chaves de região única usadas para conectores de terceiros. Consulte Limitações do Cloud KMS na Pesquisa de Agente.

Para alternar uma chave, siga estas etapas:

  1. Crie uma versão de chave e torne-a a versão principal. Para instruções, consulte Alternar uma chave no guia do Cloud KMS.

    Deixe a versão anterior da chave ativada. A nova criptografia começa automaticamente depois que a Pesquisa de Agente detecta a nova versão principal.

  2. Confirme se a Pesquisa do agente detectou a nova versão da chave. Para conferir sua CmekConfig, consulte Ver chaves do Cloud KMS. Verifique os seguintes campos na saída:

    • kmsKeyVersion mostra a nova versão da chave.
    • state é ACTIVE.
    • lastRotationTimestampMicros mostra quando a rotação começou.

  3. Mantenha a versão anterior da chave ativada por pelo menos 30 dias depois que o kmsKeyVersion mostrar a nova versão.

  4. Desative a versão anterior da chave e verifique se tudo está funcionando como antes. Consulte Ativar e desativar versões de chave no guia do Cloud KMS.

  5. Quando tiver certeza de que não houve problemas causados pela desativação da versão anterior da chave, destrua-a. Consulte Destruir e restaurar versões de chave no guia do Cloud KMS.

Se uma chave do Cloud KMS for desativada ou revogada

Se uma chave for desativada ou as permissões dela forem revogadas, o app ou o conector de dados vai parar de ingerir e disponibilizar dados em até 15 minutos. Você pode reativar a chave em até 30 dias para retomar as operações antes que a configuração da CMEK expire e os dados associados sejam excluídos permanentemente. No entanto, reativar uma chave ou restaurar permissões leva muito tempo. Pode levar até 24 horas para que o app ou conector de dados retome a veiculação de dados.

Portanto, não desative uma chave, a menos que seja necessário. Desativar e ativar uma chave em um app ou conector de dados é uma operação demorada. Por exemplo, alternar repetidamente uma chave entre desativada e ativada significa que o app ou o conector de dados vai levar muito tempo para alcançar um estado protegido. Desativar uma chave e reativá-la imediatamente depois pode resultar em dias de inatividade, porque a chave é primeiro desativada do app ou do conector de dados e, em seguida, reativada.

Solução de problemas: erro "Projetos de chave do KMS não encontrados"

Sintoma:ao tentar criar um app ou conector de dados usando uma chave do KMS, você recebe um erro semelhante ao seguinte:

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

Problema:essa mensagem de erro pode ser enganosa. Isso não significa necessariamente que a chave não existe. Em vez disso, pode indicar que a chave do KMS não foi registrada para uso com a Pesquisa do agente no local especificado.

Solução:para resolver esse problema, registre sua chave seguindo as etapas em Registrar sua chave do Cloud KMS. Depois que o registro for concluído, será possível criar apps ou conectores de dados protegidos por essa chave.