Configurar chaves gerenciadas pelo cliente para criptografia de dados no Azure AI Search
Artigo
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).
Nota
Se um índice estiver 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
A criptografia CMK é aplicada a objetos individuais. Se você precisar de CMK em seu serviço de pesquisa, defina uma política de aplicação.
A criptografia CMK é aplicada quando um objeto é criado, o que significa que você não pode criptografar objetos que já existem. A criptografia CMK ocorre sempre que um objeto é salvo no disco, tanto para dados em repouso (armazenamento de longo prazo) quanto para dados temporários armazenados em cache (armazenamento de curto prazo). Com a CMK, o disco nunca vê dados não encriptados.
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.
Conteúdo sensível em indexadores, fontes de dados, conjuntos de habilidades e vetorizadores. Esse conteúdo consiste apenas nos campos que armazenam cadeias de conexão, descrições, identidades, chaves e entradas do usuário. 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. Todas as referências a recursos externos (como fontes de dados do Azure ou modelos do Azure OpenAI) também 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 objetos 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. Para determinar a data de criação do serviço, consulte Como verificar a data de criação do serviço.
Um cliente de pesquisa que pode criar um objeto criptografado, como um cliente REST, Azure PowerShell ou um SDK do Azure (Python, .NET, Java, JavaScript).
Limitações
Não há suporte para o Azure Key Vault Managed Hardware Security Model (HSM).
Sem suporte a assinaturas cruzadas. O Azure Key Vault e o Azure AI Search devem estar na mesma assinatura.
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.
Use o mesmo locatário para que você possa recuperar 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. Para obter mais informações sobre como criar um locatário, consulte Configurar um novo locatário.
Habilite a proteção contra limpeza e exclua suavemente. 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 desativá-la 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.
Habilite o registro no cofre de chaves para que você possa monitorar o uso da chave.
Habilite a rotação automática de chaves ou siga procedimentos rigorosos durante a rotação de rotina de chaves do cofre de chaves e segredos de aplicativos e registro. 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.
Etapa 1: Criar 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.
Antes de adicionar a chave, certifique-se de que atribuiu a si mesmo a função Key Vault Crypto Officer .
A encriptação do Azure AI Search suporta chaves RSA dos tamanhos 2048, 3072 e 4096. Para obter mais informações sobre os tipos de chave suportados, consulte Sobre chaves.
Selecione Teclas de objetos> à esquerda e, em seguida, selecione Gerar/Importar.
No painel Criar uma chave, na lista de Opções, escolha Gerar para criar uma nova chave.
Insira um Nome para sua chave e aceite os padrões para outras propriedades de chave.
Opcionalmente, defina uma política de rotação de chaves para permitir a rotação automática.
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.
Etapa 2: Criar uma entidade de segurança
Você tem várias opções para configurar o acesso do Azure AI Search à chave de criptografia em tempo de execução. A abordagem mais simples é recuperar a chave usando a identidade gerenciada 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 o registro do aplicativo e segredos do aplicativo. Como alternativa, você pode criar e registrar um aplicativo Microsoft Entra e fazer com que o serviço de pesquisa forneça a ID do aplicativo em solicitações.
Recomendamos o uso de uma identidade gerenciada. 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 atribuída ao sistema. Para obter mais informações sobre como as identidades gerenciadas funcionam, consulte O que são identidades gerenciadas para recursos do Azure.
Na barra de pesquisa "Serviços de pesquisa e marketplace", procure por "Identidade gerenciada atribuída pelo usuário" e selecione Criar.
Dê à identidade um nome descritivo.
Em seguida, atribua a identidade gerenciada pelo usuário ao serviço de pesquisa. Isso pode ser feito usando a API de gerenciamento de visualização mais recente 2024-06-01-preview ou a visualização anterior.
A propriedade identity usa um tipo e uma ou mais identidades atribuídas pelo usuário totalmente qualificadas:
type é o tipo de identidade usado para o recurso. O tipo 'SystemAssigned, UserAssigned' inclui uma identidade criada pelo sistema e um conjunto de identidades atribuídas pelo usuário. O tipo 'Nenhum' remove todas as identidades do serviço.
userAssignedIdentities inclui os detalhes da identidade gerenciada pelo usuário.
Formato de identidade gerenciado pelo usuário:
/subscriptions/subscription ID/resourcegroups/resource group name/providers/Microsoft.ManagedIdentity/userAssignedIdentities/managed identity name
Exemplo de como atribuir uma identidade gerenciada pelo usuário a um serviço de pesquisa:
Atualize a "encryptionKey" seção para usar uma propriedade de identidade. Certifique-se de usar a versão da API REST de visualização ao enviar essa solicitação para o serviço de pesquisa.
Nesta etapa, atribua a função Usuário de Criptografia do Serviço de Criptografia do Cofre da Chave ao seu serviço de pesquisa. Se você estiver testando localmente, atribua essa função a si mesmo também.
Selecione Controle de acesso (IAM) e selecione Adicionar atribuição de função.
Selecione Key Vault Crypto Service Encryption User e, em seguida, selecione Next.
Selecione identidades gerenciadas, selecione membros e, em seguida, selecione a identidade gerenciada do seu serviço de pesquisa.
Selecione Rever + Atribuir.
Aguarde alguns minutos para que a atribuição de função se torne operacional.
Etapa 4: criptografar o 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 o portal do Azure, uma API REST de Pesquisa ou um SDK do Azure para criar um objeto que tenha a criptografia habilitada. Para adicionar criptografia usando o SDK do Azure, consulte o exemplo do Python neste artigo.
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. 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:
Verifique se o objeto está operacional executando uma tarefa, como consultar um índice que foi criptografado.
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.
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.
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 objeto deve ser atualizado para usá-lo antes de excluir o anterior. Se não o fizer, o objeto ficará inutilizável. Não poderá desencriptar o conteúdo se a chave for perdida.
Ao criar um novo objeto no portal do Azure, você pode especificar uma chave gerenciada pelo cliente predefinida em um cofre de chaves. Você pode habilitar a criptografia CMK para:
Índices
Origens de dados
Indexadores
Os requisitos para usar o portal do Azure são que o cofre da chave e a chave devem existir, e você concluiu as etapas anteriores para acesso autorizado à chave.
No portal do Azure, os conjuntos de habilidades são definidos no modo JSON. Use o JSON mostrado nos exemplos da API REST para fornecer uma chave gerenciada pelo cliente em um conjunto de habilidades.
Etapa 5: Testar a criptografia
Para verificar se a encriptação está a funcionar, revogue a chave de encriptação, consulte o índice (deve estar inutilizável) e, em seguida, restabeleça a chave de encriptação.
Use o portal do Azure para esta tarefa.
Na página Cofre da Chave do Azure, selecione Chaves de Objetos>.
Selecione a chave que acabou de criar e, em seguida, selecione Eliminar.
Na página Azure AI Search, selecione Índices de gerenciamento de>pesquisa.
Selecione seu índice e use o Search Explorer para executar uma consulta. Você deve receber um erro.
Retorne à página Chaves de Objetos>do Cofre da Chave do Azure.
Selecione Gerenciar chaves excluídas.
Selecione a sua chave e, em seguida, selecione Recuperar.
Retorne ao seu índice no Azure AI Search e execute novamente a consulta. Deverá ver os resultados da pesquisa. Se não vir resultados imediatos, aguarde um minuto e tente novamente.
Configurar uma política para impor a conformidade com CMK
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.
Quando você altera uma chave ou sua versão, qualquer objeto que use a chave deve primeiro ser atualizado para usar os novos valores antes de excluir os valores antigos. Caso contrário, o objeto torna-se inutilizável porque não pode ser desencriptado.
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."
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.
Selecione audit ou allLogs para a categoria, dê um nome à configuração de diagnóstico e salve-a.
Exemplo Python de uma configuração de chave de criptografia
Esta seção mostra a representação Python de um encryptionKey em uma definição de objeto. A mesma definição se aplica a índices, fontes de dados, frigideiras, indexadores e mapas de sinônimos. Para experimentar este exemplo no seu serviço de pesquisa e cofre de chaves, transfira o bloco de notas a partir de azure-search-python-samples.
Carregue o índice com alguns documentos. Todo o conteúdo do campo é considerado confidencial e é criptografado no disco usando a chave gerenciada pelo cliente.
from azure.search.documents import SearchClient
# Create a documents payload
documents = [
{
"@search.action": "upload",
"Id": "1",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities."
},
{
"@search.action": "upload",
"Id": "2",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
},
{
"@search.action": "upload",
"Id": "3",
"Description": "The hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services."
},
{
"@search.action": "upload",
"Id": "4",
"Description": "The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
}
]
search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, index_name=index_name, credential=credential)
try:
result = search_client.upload_documents(documents=documents)
print("Upload of new document succeeded: {}".format(result[0].succeeded))
except Exception as ex:
print (ex.message)
index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
Execute uma consulta para confirmar se o índice está operacional.
from azure.search.documents import SearchClient
query = "historic"
search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential, index_name=index_name)
results = search_client.search(
query_type='simple',
search_text=query,
select=["Id", "Description"],
include_total_count=True
)
for result in results:
print(f"Score: {result['@search.score']}")
print(f"Id: {result['Id']}")
print(f"Description: {result['Description']}")
A saída da consulta deve produzir resultados semelhantes ao exemplo a seguir.
Score: 0.6130029
Id: 4
Description: The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.
Score: 0.26286605
Id: 1
Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Como o conteúdo criptografado é descriptografado antes da atualização de dados ou consultas, você não verá evidências visuais de criptografia. Para verificar se a criptografia está funcionando, verifique os logs de recursos.
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:
Visão geral das opções disponíveis para gerenciar chaves de criptografia e criptografar dados durante todo o seu ciclo de vida, com especial atenção ao setor público.