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).
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
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 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.
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.
Pré-requisitos
Azure AI Search em uma camada faturável (Básico ou superior, em qualquer região).
Azure Key Vault na mesma assinatura que o Azure AI Search. Você pode criar um cofre de chaves usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. O cofre de chaves deve ter a proteção de exclusão suave e limpeza habilitada.
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).
Não há suporte para adicionar chaves de criptografia no portal do Azure.
Sem suporte a assinaturas cruzadas. O Azure Key Vault e o Azure AI Search devem estar na mesma assinatura.
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.
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.
Entre no portal do Azure e abra a página de visão geral do cofre de 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.
- Identidade gerenciada pelo sistema
- Identidade gerenciada pelo usuário (visualização)
- Registar uma aplicação
Habilite a identidade gerenciada atribuída ao sistema para seu serviço de pesquisa.
Etapa 3: Conceder permissões
O Azure Key Vault dá suporte à autorização usando controles de acesso baseados em função. Recomendamos essa abordagem em relação às políticas de acesso ao cofre de chaves. Para obter mais informações, consulte Fornecer acesso a chaves, certificados e segredos do Cofre da Chave usando funções do Azure.
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.
Entre no portal do Azure e encontre seu cofre de chaves.
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 a 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.
Chame as APIs de criação 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. 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": "<YOUR-KEY-VAULT-URI>", "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>", "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>" } }O segundo exemplo inclui accessCredentials, necessário se você registrou um aplicativo no Microsoft Entra ID:
{ "encryptionKey": { "keyVaultUri": "<YOUR-KEY-VAULT-URI>", "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>", "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>", "accessCredentials": { "applicationId": "<YOUR-APPLICATION-ID>", "applicationSecret": "<YOUR-APPLICATION-SECRET>" } } }Verifique se a chave de criptografia existe emitindo um GET no objeto.
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.
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.
PATCH https://management.azure.com/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2023-11-01
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
Girar ou atualizar chaves de criptografia
Recomendamos usar os recursos de rotação automática do Cofre de Chaves do Azure, mas você também pode girar chaves manualmente.
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.
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."
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.
Crie um espaço de trabalho de análise de log.
Adicione uma configuração de diagnóstico no cofre de chaves que usa o espaço de trabalho para retenção de dados.
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.
Instale alguns pacotes.
! pip install python-dotenv
! pip install azure-core
! pip install azure-search-documents==11.5.1
! pip install azure-identity
Crie um índice que tenha uma chave de criptografia.
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
SimpleField,
SearchFieldDataType,
SearchableField,
SearchIndex,
SearchResourceEncryptionKey
)
from azure.identity import DefaultAzureCredential
endpoint="<PUT YOUR AZURE SEARCH SERVICE ENDPOINT HERE>"
credential = DefaultAzureCredential()
index_name = "test-cmk-index"
index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
fields = [
SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
SearchableField(name="Description", type=SearchFieldDataType.String)
]
scoring_profiles = []
suggester = []
encryption_key = SearchResourceEncryptionKey(
key_name="<PUT YOUR KEY VAULT NAME HERE>",
key_version="<PUT YOUR ALPHANUMERIC KEY VERSION HERE>",
vault_uri="<PUT YOUR KEY VAULT ENDPOINT HERE>"
)
index = SearchIndex(name=index_name, fields=fields, encryption_key=encryption_key)
result = index_client.create_or_update_index(index)
print(f' {result.name} created')
Obtenha a definição de índice para verificar se a configuração da chave de criptografia existe.
index_name = "test-cmk-index-qs"
index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
result = index_client.get_index(index_name)
print(f"{result}")
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 Cliff 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 Cliff 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: