Configurar chaves gerenciadas pelo cliente para criptografia de dados no Azure AI Search
O Azure AI Search criptografa automaticamente os dados em repouso com chaves gerenciadas pelo serviço. Se for necessária mais proteção, pode complementar a encriptação predefinida com outra camada de encriptação utilizando chaves que cria e gere no Cofre de Chaves do Azure.
Este artigo orienta você pelas etapas de configuração da criptografia de chave gerenciada pelo cliente (CMK) ou "traga sua própria chave" (BYOK). Aqui estão alguns pontos a ter em mente:
A criptografia CMK é executada em objetos individuais. Se você precisar de CMK em seu serviço de pesquisa, defina uma política de aplicação.
A criptografia CMK depende do Cofre da Chave do Azure. Você pode criar suas próprias chaves de criptografia e armazená-las em um cofre de chaves ou pode usar as APIs do Cofre de Chaves do Azure para gerar chaves de criptografia. O Azure Key Vault deve estar na mesma assinatura e locatário que o Azure AI Search. O Azure AI Search 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 CMK torna-se operacional quando um objeto é criado. Não é possível criptografar objetos que já existem. A criptografia CMK ocorre sempre que um objeto é salvo no disco, seja dados em repouso para armazenamento de longo prazo ou dados temporários para armazenamento de curto prazo. Com a CMK, o disco nunca vê dados não encriptados.
Nota
Se um índice for criptografado por CMK, ele só poderá ser acessado se o serviço de pesquisa tiver acesso à chave. Se o acesso for revogado, o índice não poderá ser utilizado e o serviço não poderá ser dimensionado até que o índice seja excluído ou o acesso à chave seja restaurado.
Objetos criptografados CMK
Os objetos que podem ser criptografados incluem índices, listas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades. A encriptação é computacionalmente cara para desencriptar, pelo que apenas o conteúdo sensível é encriptado.
A encriptação é realizada sobre o 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 do usuário, como entidades personalizadas. Em ambos os casos, as chaves e as entradas do usuário nas habilidades são criptografadas.
Encriptação dupla total
Ao introduzir a criptografia CMK, você está criptografando o conteúdo duas vezes. Para os objetos e campos observados na seção anterior, o conteúdo é primeiro criptografado com sua CMK e, em segundo lugar, com a chave gerenciada pela Microsoft. O conteúdo é duplamente criptografado em discos de dados para armazenamento de longo prazo e em discos temporários usados para armazenamento de curto prazo.
A ativação da criptografia CMK aumenta o tamanho do índice e degrada o desempenho da consulta. Com base nas observações feitas até o momento, você pode esperar um aumento de 30% a 60% nos tempos de consulta, embora o desempenho real varie dependendo da definição do índice e dos tipos de consultas. Como o desempenho é reduzido, recomendamos que você habilite esse recurso apenas em índices que realmente o exigem.
Embora a criptografia dupla esteja agora disponível em todas as regiões, o suporte foi implementado 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 suportavam CMK para discos de dados, mas não discos temporários:
- E.U.A. Oeste 2
- E.U.A. Leste
- E.U.A. Centro-Sul
- US Gov - Virginia
- US Gov - Arizona
A segunda implementação em 13 de maio de 2021 adicionou criptografia para discos temporários e estendeu a criptografia CMK para todas as regiões suportadas.
Se você estiver usando CMK de um serviço criado durante a primeira distribuição e também quiser criptografia CMK em discos temporários, precisará criar um novo serviço de pesquisa na região de sua escolha e reimplantar seu conteúdo.
Pré-requisitos
As seguintes ferramentas e serviços são usados nesse cenário.
Azure AI Search em uma camada faturável (Básico ou superior, em qualquer região).
Azure Key Vault, você pode criar um cofre de chaves usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Crie o recurso na mesma assinatura que o Azure AI Search. O cofre de chaves deve ter a proteção de exclusão suave e limpeza habilitada.
ID do Microsoft Entra. Se você não tiver um, configure um novo locatário.
Você deve ter um cliente de pesquisa que possa criar o objeto criptografado. Neste código, você faz referência a uma chave do cofre de chaves e informações de registro do aplicativo. Esse código pode ser um aplicativo de trabalho ou um código protótipo, como o exemplo de código C# DotNetHowToEncryptionUsingCMK.
Gorjeta
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 SDKs do Azure. Não há suporte para suporte de portal para adicionar uma chave a índices ou mapas de sinônimos.
Dicas do Key Vault
Se você é novo no Azure Key Vault, revise este guia de início rápido para saber mais sobre tarefas básicas: Definir e recuperar um segredo do Azure Key Vault usando o PowerShell. Aqui estão algumas dicas para usar o Key Vault:
Use quantos cofres de chaves precisar. As chaves gerenciadas podem estar em diferentes cofres de chaves. Um serviço de pesquisa pode ter vários objetos criptografados, cada um criptografado com uma chave de criptografia gerenciada pelo cliente diferente, armazenados em diferentes cofres de chaves.
Habilite o registro no Cofre da Chave para que você possa monitorar o uso da chave.
Lembre-se de seguir procedimentos rigorosos durante a rotação de rotina das chaves do cofre de chaves e segredos e registros de aplicativos do Ative Directory. Sempre atualize todo o conteúdo criptografado para usar novos segredos e chaves antes de excluir os antigos. Se perder este passo, o seu conteúdo não pode ser desencriptado.
1 - Ative a proteção contra purga
Como primeiro passo, certifique-se de que a proteção de eliminação suave e limpeza está ativada no cofre de chaves. Devido à natureza da criptografia com chaves gerenciadas pelo cliente, ninguém poderá recuperar seus dados se sua chave do Cofre da Chave do Azure for excluída.
Para evitar a perda de dados causada por exclusões acidentais de chaves do Cofre de Chaves, a proteção de exclusão suave e limpeza deve ser ativada no cofre de chaves. A exclusão suave está habilitada por padrão, portanto, você só encontrará problemas se a tiver desativado propositalmente. A proteção contra limpeza não está habilitada por padrão, mas é necessária para a criptografia de chave gerenciada pelo cliente no Azure AI Search.
Você pode definir ambas as propriedades usando os comandos portal, PowerShell ou CLI do Azure.
Entre no portal do Azure e abra a página de visão geral do cofre de chaves.
Na página Visão geral, em Essentials, habilite a proteção Soft-delete e Purge.
2 - Crie uma chave no Cofre da Chave
Ignore a geração de chaves se já tiver uma chave no Cofre de Chaves do Azure que pretende utilizar, mas recolha o identificador de chave. Você precisa dessas informações ao criar um objeto criptografado.
Entre no portal do Azure e abra a página de visão geral do cofre de chaves.
Selecione Teclas à esquerda e, em seguida, selecione + Gerar/Importar.
No painel Criar uma chave, na lista de Opções, escolha o método que deseja usar para criar uma chave. Você pode Gerar uma nova chave, Carregar uma chave existente ou usar Restaurar Backup para selecionar um backup de uma chave.
Insira um Nome para sua chave e, opcionalmente, selecione outras propriedades de chave.
Selecione Criar para iniciar a implantação.
Selecione a chave, selecione a versão atual e, em seguida, anote o identificador de chave. É composto pelo valor da chave Uri, o nome da chave e a versão da chave. Você precisa do identificador para definir um índice criptografado no Azure AI Search.
3 - Criar uma entidade de segurança
Você tem várias opções para acessar a chave de criptografia em tempo de execução. A abordagem mais simples é recuperar a chave usando a identidade gerenciada e as permissões do seu serviço de pesquisa. Você pode usar um sistema ou uma identidade gerenciada pelo usuário. Isso permite que você omita as etapas para registro de aplicativo e segredos de aplicativo e simplifica a definição de chave de criptografia.
Como alternativa, você pode criar e registrar um aplicativo Microsoft Entra. O serviço de pesquisa fornece o ID do aplicativo nas solicitações.
Uma identidade gerenciada permite que seu serviço de pesquisa se autentique no Cofre da Chave do Azure 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 só pode ter uma identidade gerenciada. Para obter mais informações sobre como as identidades gerenciadas funcionam, consulte O que são identidades gerenciadas para recursos do Azure.
- Identidade gerenciada pelo sistema
- Identidade gerenciada pelo usuário (visualização)
- Registar uma aplicação
Faça do seu serviço de pesquisa um serviço confiável.
As condições que o impedem de adotar essa abordagem incluem:
Você não pode conceder diretamente ao seu serviço de pesquisa permissões de acesso ao cofre de chaves (por exemplo, se o serviço de pesquisa estiver em um locatário de ID do Microsoft Entra diferente do Cofre de Chaves do Azure).
Um único serviço de pesquisa é necessário para hospedar vários índices criptografados ou mapas de sinônimos, cada um usando uma chave diferente de um cofre de chaves diferente, onde cada cofre de chaves deve usar uma identidade diferente para 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ê cria uma política de acesso no Cofre da Chave. Esta política dá ao aplicativo que você registrou com o Microsoft Entra ID permissão para usar sua chave gerenciada pelo cliente.
As permissões de acesso podem ser revogadas a qualquer momento. Uma vez revogado, qualquer índice de serviço de pesquisa ou mapa de sinônimo que use esse cofre de chaves se torna inutilizável. Restaurar as permissões de acesso ao cofre de chaves posteriormente restaura o acesso ao mapa de índice e sinônimo. Para obter mais informações, consulte Acesso seguro a um cofre de chaves.
Ainda no portal do Azure, abra a página Visão geral do cofre de chaves.
Selecione as políticas de acesso à esquerda e selecione + Criar para iniciar o assistente Criar uma política de acesso .
Na página Permissões, selecione Obter permissões de chave, permissões secretas e permissões de certificado. Selecione Unwrap Key e Wrap Key para operações criptográficas ** na chave.
Selecione Seguinte.
Na página Princípio, localize e selecione a entidade de segurança usada pelo serviço de pesquisa para acessar a chave de criptografia. Esta será a identidade gerida pelo sistema ou pelo utilizador do serviço de pesquisa ou da aplicação registada.
Selecione Avançar e Criar.
Importante
O conteúdo criptografado no Azure AI Search é configurado para usar uma chave específica do Azure Key Vault com uma versão específica. Se você alterar a chave ou versão, o mapa de índice ou sinônimo deve ser atualizado para usá-lo antes de excluir o anterior. Se não o fizer, o mapa de índice ou sinónimo ficará inutilizável. Não poderá desencriptar o conteúdo se a chave for perdida.
5 - Criptografar conteúdo
As chaves de criptografia são adicionadas quando você cria um objeto. Para adicionar uma chave gerenciada pelo cliente em um índice, mapa de sinônimo, indexador, fonte de dados ou 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.
Chame as APIs Create para especificar a propriedade encryptionKey :
Insira a construção encryptionKey na definição de objeto. Esta propriedade é uma propriedade de primeiro nível, no mesmo nível de 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", 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ê pode usá-lo como faria com qualquer outro objeto de seu tipo. A criptografia é transparente para o usuário e desenvolvedor.
Nota
Nenhum desses detalhes do cofre de chaves é considerado secreto e pode ser facilmente recuperado navegando até a página relevante do Cofre da Chave do Azure no portal do Azure.
6 - Configurar política
As políticas do Azure ajudam a impor padrões organizacionais e a avaliar a conformidade em escala. O Azure AI Search tem uma política interna opcional para imposição de CMK em todo o serviço.
Nesta seção, você define a política que define um padrão CMK para seu serviço de pesquisa. Em seguida, você configura seu serviço de pesquisa para aplicar essa política.
Navegue até a política interna em seu navegador da Web. Selecione Atribuir
Configure o escopo da política. Na seção Parâmetros, desmarque Mostrar apenas parâmetros e defina Efeito como Negar.
Durante a avaliação da solicitação, uma solicitação que corresponda a uma definição de política de negação é marcada como não compatível. Supondo que o padrão para o seu serviço seja a criptografia CMK, "negar" significa que as solicitações que não especificam a criptografia CMK não são compatíveis.
Conclua a criação da política.
Chame a API Services - Update para habilitar a aplicação da política CMK no nível de serviço.
PATCH https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2022-11-01
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Enabled",
"encryptionComplianceStatus": "Compliant"
}
}
}
Exemplos REST
Esta seção mostra o JSON para vários objetos para que você possa ver onde localizar "encryptionKey" em uma definição de objeto.
Encriptação de índice
Os detalhes da criação de um novo índice por meio da API REST podem ser encontrados em Create Index (REST API), onde 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 você pode enviar a solicitação de criação de índice e, em seguida, começar a usar o índice normalmente.
Encriptação de mapas de sinónimos
Crie um mapa de sinônimo criptografado usando a API REST Criar Mapa de Sinônimo do Azure AI Search. Use a propriedade "encryptionKey" para especificar qual chave de criptografia usar.
{
"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 você pode enviar a solicitação de criação de mapa de sinônimo e, em seguida, começar a usá-la normalmente.
Criptografia da fonte de dados
Crie uma fonte de dados criptografada usando a API Create Data Source (REST API). Use a propriedade "encryptionKey" para especificar qual chave de criptografia usar.
{
"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 você pode enviar a solicitação de criação da fonte de dados e, em seguida, começar a usá-la normalmente.
Encriptação Skillset
Crie um conjunto de habilidades criptografado usando a API REST Create Skillset. Use a propriedade "encryptionKey" para especificar qual chave de criptografia usar.
{
"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 você pode enviar a solicitação de criação do conjunto de habilidades e, em seguida, começar a usá-la normalmente.
Criptografia de indexador
Crie um indexador criptografado usando a API REST Create Indexer. Use a propriedade "encryptionKey" para especificar qual chave de criptografia usar.
{
"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 você pode enviar a solicitação de criação do indexador e, em seguida, começar a usá-la normalmente.
Importante
Embora "encryptionKey" não possa ser adicionado a índices de pesquisa existentes ou mapas de sinônimos, 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 Cofre da Chave ou uma nova versão da chave, qualquer índice de pesquisa ou mapa de sinônimo que use a chave deve primeiro ser atualizado para usar a nova chave\versão antes de excluir a chave\versão anterior. Se não o fizer, o mapa de índice ou sinónimo ficará inutilizável, uma vez que não será possível desencriptar o conteúdo quando o acesso à chave for perdido. Embora a restauração posterior das permissões de acesso ao cofre de chaves restaure o acesso ao conteúdo.
Trabalhar com conteúdo encriptado
Com a criptografia de chave gerenciada pelo cliente, você pode notar latência para indexação e consultas devido ao trabalho extra de criptografia/descriptografia. O Azure AI Search não registra a atividade de criptografia, mas você pode monitorar o acesso à chave por meio do registro em log do cofre de chaves. Recomendamos que você habilite 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 rodar teclas, é importante seguir esta sequência:
- Determine a chave usada por um mapa de índice ou sinônimo.
- Crie uma nova chave no cofre de chaves, mas deixe a chave original disponível.
- Atualize as propriedades encryptionKey em um mapa de índice ou sinônimo para usar os novos valores. Somente os objetos que foram originalmente criados com essa propriedade podem ser atualizados para usar um valor diferente.
- Desative ou exclua a chave anterior no cofre de chaves. Monitore o acesso à chave para verificar se a nova chave está sendo usada.
Por motivos de desempenho, o serviço de pesquisa armazena a chave em cache por até várias horas. Se você desabilitar ou excluir a chave sem fornecer uma nova, as consultas continuarão a funcionar temporariamente até que o cache expire. No entanto, uma vez que o serviço de pesquisa não pode mais descriptografar o conteúdo, você recebe esta mensagem: "Acesso proibido. A chave de consulta usada pode ter sido revogada - tente novamente."
Próximos passos
Se não estiver familiarizado com a arquitetura de segurança do Azure, consulte a documentação de Segurança do Azure e, em particular, este artigo: