Compartilhar via


Configurar chaves gerenciadas pelo cliente para criptografia de dados na IA do Azure Search

A IA do Azure Search criptografa os dados inativos automaticamente com chaves gerenciadas pelo serviço. Caso precise de mais proteção, é possível complementar a criptografia padrão com outra camada de criptografia usando uma chave criada e gerenciada por você no Azure Key Vault.

Este artigo aborda as etapas de configuração da criptografia da CMK (chave gerenciada pelo cliente) ou BYOK (Bring Your Own Key). Veja aqui algumas coisas para ter em mente:

  • A criptografia CMK é adotada em objetos individuais. Se você precisar de CMK em seu serviço de pesquisa, defina uma política de imposição.

  • A criptografia da CMK depende do Azure Key Vault. Você pode criar suas próprias chaves de criptografia e armazená-las em um cofre de chaves ou pode usar as APIs do Azure Key Vault para gerar chaves de criptografia. O Azure Key Vault deve estar na mesma assinatura e locatário da Pesquisa de IA do Azure. A Pesquisa de IA do Azure recupera sua chave gerenciada conectando-se por meio de um sistema ou identidade gerenciada pelo usuário. Esse comportamento requer que ambos os serviços compartilhem o mesmo locatário.

  • A criptografia da CMK torna-se operacional quando um objeto é criado. Não é possível criptografar objetos que já existem. A criptografia da CMK ocorre sempre que um objeto é salvo em disco, seja dados inativos para armazenamento de longo prazo ou dados temporários para armazenamento de curto prazo. Com a CMK, o disco nunca visualiza dados não criptografados.

Observação

Se um índice for criptografado por CMK, ele só será acessível se o serviço de pesquisa tiver acesso à chave. Se o acesso for revogado, o índice será inutilizável e o serviço não poderá ser escalado até que o índice seja excluído ou o acesso à chave seja restaurado.

Objetos criptografados pela CMK

Os objetos que podem ser criptografados incluem índices, listas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades. O custo para descriptografar a criptografia é alto, portanto, somente o conteúdo confidencial é criptografado.

A criptografia é executada no seguinte conteúdo:

  • Todo o conteúdo dentro de índices e listas de sinônimos, incluindo descrições.

  • Para indexadores, fontes de dados e conjuntos de habilidades, somente os campos que armazenam cadeias de conexão, descrições, chaves e entradas de usuário são criptografados. Por exemplo, os conjuntos de habilidades têm chaves de serviços de IA do Azure e algumas habilidades aceitam entradas de usuário, como entidades personalizadas. Em ambos os casos, tanto as chaves quanto as entradas do usuário nas habilidades são criptografadas.

Criptografia dupla completa

Ao introduzir a criptografia da CMK, você está criptografando o conteúdo duas vezes. Para os objetos e campos anotados na seção anterior, o conteúdo é criptografado primeiro com sua CMK e, em segundo lugar, com a chave gerenciada pela Microsoft. O conteúdo é criptografado duplamente em discos de dados para armazenamento de longo prazo e em discos temporários usados para armazenamento de curto prazo.

A habilitação da criptografia CMK aumenta o tamanho do índice e degrada o desempenho da consulta. Com base nas observações até o momento, espera-se um aumento de 30 a 60% nos tempos de consulta, embora o desempenho real varie dependendo da definição de índice e dos tipos de consultas. Como o desempenho é reduzido, recomendamos que você só habilite esse recurso em índices que realmente precisem dele.

Embora a criptografia dupla esteja disponível em todas as regiões, o suporte foi lançado em duas fases:

  • O primeiro lançamento foi em 1º de agosto de 2020 e incluiu as cinco regiões listadas abaixo. Os serviços de pesquisa criados nas seguintes regiões dão suporte à CMK para discos de dados, mas não discos temporários:

    • Oeste dos EUA 2
    • Leste dos EUA
    • Centro-Sul dos Estados Unidos
    • Gov. dos EUA – Virgínia
    • Governo dos EUA do Arizona
  • A segunda distribuição em 13 de maio de 2021 adicionou criptografia para discos temporários e criptografia da CMK estendida para todas as regiões com suporte.

    Se você estiver usando a CMK de um serviço criado durante a primeira distribuição e também quiser a criptografia da CMK em discos temporários, precisará criar um novo serviço de pesquisa em sua região de escolha e implantar novamente seu conteúdo.

Pré-requisitos

Os serviços e as ferramentas a seguir são usados neste cenário.

Você precisa ter um cliente de pesquisa que possa criar o objeto criptografado. Nesse código, deverá ser feita referência a uma chave do cofre de chaves e a informações de registro de aplicativo. Esse código pode ser um aplicativo em funcionamento ou um código de protótipo como o exemplo de código C# DotNetHowToEncryptionUsingCMK.

Dica

Você pode usar um cliente REST ou o Azure PowerShell para criar índices e mapas de sinônimos que incluem um parâmetro de chave de criptografia. Você também pode usar os SDKs do Azure. Não há suporte no portal para adicionar uma chave a índices ou mapas de sinônimos.

Dicas do Key Vault

Se você é novo no Azure Key Vault, confira o início rápido para saber mais sobre as tarefas básicas: Definir e recuperar um segredo do Azure Key Vault usando o PowerShell. Veja aqui algumas dicas para usar o Key Vault:

  • Use quantos cofres de chaves forem necessários. As chaves gerenciadas podem estar em cofres de chaves diferentes. Um serviço de pesquisa pode ter diversos objetos criptografados, cada um com uma chave de criptografia gerenciada pelo cliente diferente, armazenados em diferentes cofres de chaves.

  • Habilite o log no Key Vault para que você possa monitorar o uso de chaves.

  • Siga os procedimentos exatos durante a rotação de rotina das chaves dos cofres de chaves e dos segredos e do registro de aplicativo no Active Directory. Sempre atualize todo o conteúdo criptografado para usar novos segredos e chaves antes de excluir os antigos. O conteúdo não será descriptografado se essa etapa for ignorada.

1 – Habilitar a proteção contra limpeza

Como primeira etapa, verifique se a exclusão reversível e a proteção contra limpeza estão habilitadas no cofre de chaves. Devido à natureza da criptografia com chaves gerenciadas pelo cliente, ninguém pode recuperar seus dados quando sua chave do Azure Key Vault é excluída.

Para evitar a perda de dados causada por exclusões acidentais de chaves do Key Vault, devem ser habilitadas a exclusão reversível e a proteção de limpeza no cofre de chaves. A exclusão reversível está habilitada por padrão, portanto, você só terá problemas se tiver desabilitado propositalmente essa opção. A proteção contra a limpeza não está habilitada por padrão, mas é necessária para a criptografia de chave gerenciada pelo cliente na IA do Azure Search.

É possível definir as duas propriedades usando o portal, o PowerShell ou os comandos CLI do Azure.

  1. Entre no portal do Azure e abra a página de visão geral do cofre de chaves.

  2. Na página Visão geral em Essentials, habilite a Exclusão reversível e Proteção contra limpeza.

2 – Criar uma chave no Key Vault

Ignore a geração de chave se você já tiver uma chave no Azure Key Vault para usar, mas colete o identificador de chave. Você precisará dessas informações ao criar um objeto criptografado.

  1. Entre no portal do Azure e abra a página de visão geral do cofre de chaves.

  2. Selecione Chaves à esquerda e, em seguida, selecione + Gerar/Importar.

  3. No painel Criar uma chave, na lista de Opções, escolha o método que deseja usar para criar uma chave. É possível Gerar uma nova chave, Carregar uma chave existente ou usar Restaurar backup para selecionar um backup de uma chave.

  4. Insira um Nome para a chave e, opcionalmente, selecione outras propriedades da chave.

  5. Selecione Criar para iniciar a implantação.

  6. Selecione a chave e a versão atual e anote o identificador de chave. Ele é composto pelo URI do valor da chave, pelo nome da chave e pela versão da chave. Você precisará do identificador para definir um índice criptografado na Pesquisa de IA do Azure.

    Criar uma chave no cofre de chaves

3 – Criar uma entidade de segurança

Há muitas opções para acessar a chave de criptografia no tempo de execução. A abordagem mais simples é recuperar a chave usando a identidade gerenciada e as permissões do serviço de pesquisa. É possível usar uma identidade gerenciada pelo sistema ou pelo usuário. Isso permite omitir as etapas de registro de aplicativos e segredos de aplicativos e simplifica a definição da chave de criptografia.

Como alternativa, você pode criar e registrar um aplicativo do Microsoft Entra. O serviço de pesquisa fornecerá a ID do aplicativo nas solicitações.

Uma identidade gerenciada permite que o serviço de pesquisa se autentique no Azure Key Vault sem armazenar credenciais (ApplicationID ou ApplicationSecret) no código. O ciclo de vida desse tipo de identidade gerenciada está vinculado ao ciclo de vida do seu serviço de pesquisa, que pode ter só uma identidade gerenciada. Para obter mais informações sobre como identidades gerenciadas funcionam, consulte O que são identidades gerenciadas para recursos do Azure?.

  1. Torne seu serviço de pesquisa um serviço confiável.

    Ativar a identidade gerenciada atribuída ao sistema

As condições que impedem a adoção dessa abordagem incluem:

  • Não é possível conceder diretamente permissões de acesso do serviço de pesquisa ao cofre de chaves (por exemplo, se o serviço de pesquisa estiver em um locatário do Microsoft Entra ID diferente do Azure Key Vault).

  • Um único serviço de pesquisa é necessário para hospedar diversos índices criptografados ou mapas de sinônimos, que usam individualmente uma chave diferente de um cofre de chaves diferente. Além disso, cada um desses cofres de chaves deve usar uma identidade diferente para a autenticação. Como um serviço de pesquisa só pode ter uma identidade gerenciada, um requisito para várias identidades exclui a abordagem simplificada para seu cenário.

4 – Conceder permissões

Nesta etapa, você criará uma política de acesso no Key Vault. Essa política dá ao aplicativo que você registrou no Microsoft Entra ID permissão para usar a chave gerenciada pelo cliente.

As permissões de acesso podem ser revogadas a qualquer momento. Depois de revogado, qualquer índice de serviço de pesquisa ou mapa de sinônimos que usa esse cofre de chaves ficará inutilizável. A restauração das permissões de acesso ao cofre de chaves em um momento posterior restaurará o acesso ao índice e ao mapa de sinônimos. Para saber mais, consulte Acesso seguro a um cofre de chaves.

  1. Ainda na portal do Azure, abra a página de Visão geral do cofre de chaves.

  2. Selecione as Políticas de acesso à esquerda e selecione + Criar para iniciar o assistente Criar uma política de acesso.

    Criar uma política de acesso.

  3. Na página Permissões, selecione Obter em Permissões de chave, Permissões de segredo e Permissões de certificado. Selecione Decodificar chave e Codificar chave para **operações criptográficas na chave.

    Selecione permissões na página Permissões.

  4. Selecione Avançar.

  5. Na página Princípio, encontre e selecione a entidade de segurança usada pelo serviço de pesquisa para acessar a chave de criptografia. Ele consistirá na identidade gerenciada pelo sistema ou pelo usuário do serviço de pesquisa ou no aplicativo registrado.

  6. Selecione Próximo e Criar.

Importante

O conteúdo criptografado na IA do Azure Search está configurado para usar uma chave do Azure Key Vault específica com uma versão específica. Se você alterar a chave ou a versão, deverá atualizar o índice ou o mapa de sinônimos para usá-lo antes de excluir o anterior. Não fazer isso tornará o índice ou o mapa de sinônimos inutilizável. Não será possível descriptografar o conteúdo se a chave for perdida.

5 – Criptografar conteúdo

As chaves de criptografia são adicionadas ao criar um objeto. Para adicionar uma chave gerenciada pelo cliente a um índice, um mapa de sinônimos, um indexador, uma fonte de dados ou um conjunto de habilidades, use a API REST de Pesquisa ou um SDK do Azure para criar um objeto que tenha a criptografia habilitada. O portal não permite propriedades de criptografia na criação de objetos.

  1. Chame as APIs de Criação para especificar a propriedade encryptionKey:

  2. Insira o constructo encryptionKey na definição do objeto. Essa propriedade é de primeiro nível, no mesmo nível que nome e descrição. Os exemplos REST a seguir mostram o posicionamento da propriedade. Se você estiver usando o mesmo cofre, chave e versão, poderá colar a mesma construção "encryptionKey" em cada definição de objeto.

    O primeiro exemplo mostra uma "encryptionKey" para um serviço de pesquisa que se conecta usando uma identidade gerenciada:

    {
      "encryptionKey": {
        "keyVaultUri": "https://demokeyvault.vault.azure.net",
        "keyVaultKeyName": "myEncryptionKey",
        "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660"
      }
    }
    

    O segundo exemplo inclui "accessCredentials", que é necessário se você registrou um aplicativo no Microsoft Entra ID:

    {
      "encryptionKey": {
        "keyVaultUri": "https://demokeyvault.vault.azure.net",
        "keyVaultKeyName": "myEncryptionKey",
        "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
        "accessCredentials": {
          "applicationId": "00000000-0000-0000-0000-000000000000",
          "applicationSecret": "myApplicationSecret"
        }
      }
    }
    

Depois de criar o objeto criptografado no serviço de pesquisa, você poderá usá-lo como faria com qualquer outro objeto do mesmo tipo. A criptografia é transparente para o usuário e o desenvolvedor.

Observação

Nenhum desses detalhes do cofre de chaves é considerado secreto e todos podem ser facilmente recuperados acessando a página relevante do Azure Key Vault no portal do Azure.

6 – Configurar a política

As políticas do Azure ajudam a impor padrões organizacionais e a avaliar a conformidade em escala. A IA do Azure Search tem uma política interna opcional para imposição do CMK no serviço.

Nesta seção, você definirá a política que define um padrão CMK para seu serviço de pesquisa. Em seguida, você configurará seu serviço de pesquisa para impor essa política.

  1. Navegue até a política interna no navegador da Web. Selecione Atribuir

    Captura de tela da atribuição de uma política interna do CMK.

  2. Configure o escopo da política. Na seção Parâmetros, desmarque Mostre apenas parâmetros... e defina Efeito para Negar.

    Durante a avaliação da solicitação, uma solicitação que corresponde a uma definição de política de negação será marcada como fora de conformidade. Supondo que o padrão do seu serviço seja a criptografia CMK, "negar" significa que as solicitações que não especificam a criptografia CMK estão fora de conformidade.

    Captura de tela da alteração do efeito da política interna do CMK para negar.

  3. Conclua a criação da política.

  4. Chame os Serviços – Atualizar API para habilitar a imposição de política do CMK no nível de serviço.

PATCH https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2023-11-01

{
    "properties": {
        "encryptionWithCmk": {
            "enforcement": "Enabled",
            "encryptionComplianceStatus": "Compliant"
        }
    }
}

Exemplos de REST

Esta seção mostra o JSON de objetos para que seja possível ver onde colocar "encryptionKey" em uma definição de objeto.

Criptografia de índice

Os detalhes da criação de um novo índice por meio da API REST podem ser encontrados em Criar índice (API REST), em que a única diferença é especificar os detalhes da chave de criptografia como parte da definição do índice:

{
 "name": "hotels",
 "fields": [
  {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
  {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
  {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
  {"name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene"},
  {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
  {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
  {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
  {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
  {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
  {"name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true}
 ],
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

Agora é possível enviar a solicitação de criação de índice e começar a usar o índice normalmente.

Criptografia do mapa de sinônimos

Crie um mapa de sinônimos criptografados usando a API REST criar mapa de sinônimos da IA do Azure Search. Use a propriedade "encryptionKey" para especificar a chave de criptografia que será usada.

{
  "name" : "synonymmap1",
  "format" : "solr",
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA",
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

Agora é possível enviar a solicitação de criação de mapa de sinônimo e começar a usá-lo normalmente.

Criptografia de fonte de dados

Crie uma fonte de dados criptografada usando Criar Fonte de Dados (API REST). Use a propriedade "encryptionKey" para especificar a chave de criptografia que será usada.

{
  "name" : "datasource1",
  "type" : "azureblob",
  "credentials" :
  { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=datasource;AccountKey=accountkey;EndpointSuffix=core.windows.net"
  },
  "container" : { "name" : "containername" },
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

Agora é possível enviar a solicitação de criação de fonte de dados e começar a usá-la normalmente.

Criptografia do conjunto de habilidades

Crie um conjunto de habilidades criptografado usando a API REST Criar Conjunto de Habilidades. Use a propriedade "encryptionKey" para especificar a chave de criptografia que será usada.

{
    "name": "skillset1",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
      "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "myEncryptionKey",
        "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
        "keyVaultUri": "https://demokeyvault.vault.azure.net",
        "accessCredentials": {
            "applicationId": "00000000-0000-0000-0000-000000000000",
            "applicationSecret": "myApplicationSecret"}
    }
}

Agora é possível enviar a solicitação de criação de conjunto de habilidades e começar a usá-lo normalmente.

Criptografia do indexador

Crie um indexador criptografado usando a API REST Criar Indexador. Use a propriedade "encryptionKey" para especificar a chave de criptografia que será usada.

{
  "name": "indexer1",
  "dataSourceName": "datasource1",
  "skillsetName": "skillset1",
  "parameters": {
      "configuration": {
          "imageAction": "generateNormalizedImages"
      }
  },
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

Agora é possível enviar a solicitação de criação do indexador e começar a usá-lo normalmente.

Importante

Embora "encryptionKey" não possa ser adicionado a índices de pesquisa ou mapas de sinônimos existentes, ele pode ser atualizado fornecendo valores diferentes para qualquer um dos três detalhes do cofre de chaves (por exemplo, atualizar a versão da chave). Ao mudar para uma nova chave do Key Vault ou uma nova versão de chave, qualquer índice de pesquisa ou mapa de sinônimos que usa a chave deve primeiro ser atualizado para usar a nova chave\versão antes de excluir a chave\versão anterior. A falha ao fazer isso tornará o mapa de índice ou sinônimo inutilizável, e não será possível descriptografar o conteúdo depois que o acesso à chave for perdido. Apesar disso, a restauração posterior das permissões de acesso ao cofre de chaves restaurará o acesso ao conteúdo.

Trabalhar com conteúdo criptografado

Com a criptografia de chave gerenciada pelo cliente, será possível notar a latência para indexação e consultas devido ao trabalho extra de criptografar/descriptografar. A IA do Azure Search não registra a atividade de criptografia, mas você pode monitorar o acesso à chave pelo registro em log do cofre de chaves. É recomendável habilitar o registro em log como parte da configuração do cofre de chaves.

Espera-se que a rotação de chaves ocorra ao longo do tempo. Sempre que for feita a rotação das chaves, é importante seguir esta sequência:

  1. Determinar a chave usada por um mapa de índice ou de sinônimo.
  2. Criar uma nova chave no cofre de chaves, mas deixar a chave original disponível.
  3. Atualizar as propriedades encryptionKey em um mapa de índice ou sinônimo para usar os novos valores. Somente os objetos que foram criados originalmente com essa propriedade poderão ser atualizados para usar um valor diferente.
  4. Desabilitar ou excluir a chave anterior no cofre de chaves. Monitorar o acesso à chave para verificar se a nova chave está sendo usada.

Por motivos de desempenho, o serviço de pesquisa armazena em cache a chave por até várias horas. Se a chave for desabilitada ou excluída sem o fornecimento de uma nova, as consultas continuarão a funcionar de forma temporária até que o cache expire. No entanto, quando o serviço de pesquisa não puder mais descriptografar o conteúdo, você receberá esta mensagem: "Acesso proibido. A chave de consulta usada pode ter sido revogada – tente novamente."

Próximas etapas

Se você não estiver familiarizado com a arquitetura de segurança do Azure, confira a documentação de segurança do Azure e, em particular, este artigo: