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).
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
A criptografia CMK é aplicada a objetos individuais. Se você precisar de CMK em seu serviço de pesquisa, defina uma política de imposiçã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 em disco, tanto para dados em repouso (armazenamento de longo prazo) quanto para dados em cache temporários (armazenamento de curto prazo). Com a CMK, o disco nunca visualiza dados não criptografados.
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 dos índices e das listas de sinônimos.
Conteúdo confidencial 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 de usuários. 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. Quaisquer referências a recursos externos (como fontes de dados do Azure ou modelos do OpenAI do Azure) também 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 objetos 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. Para determinar a data de criação do serviço, consulte Como verificar a data de criação do serviço.
Pré-requisitos
IA do Azure Search em uma camada faturável (Básica 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 exclusão reversível e a proteção contra limpeza habilitadas.
Um cliente de pesquisa que pode criar um objeto criptografado, como um cliente REST, o Azure PowerShell ou um SDK do Azure (Python, .NET, Java, JavaScript).
Limitações
Não há suporte para o Módulo de Segurança de Hardware (HSM) gerenciado do Azure Key Vault.
Não há suporte para assinatura cruzada. O Azure Key Vault e a Pesquisa de IA do Azure devem estar na mesma assinatura.
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.
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 a criação de um locatário, consulte Configurar um novo locatário.
Habilitar a proteção contra limpeza e a exclusão reversível. 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 é habilitada por padrão, portanto, você só terá problemas se a desabilitar propositalmente. 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.
Habilite o log de eventos no cofre de chaves para poder monitorar o uso de chaves.
Habilite a rotação automática de chaves ou siga procedimentos rigorosos durante a rotação de rotina das chaves do cofre de chaves e dos segredos e registros de aplicativos. 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.
Etapa 1: 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.
Antes de adicionar a chave, verifique se você atribuiu a você mesmo a função de Key Vault Crypto Officer.
A criptografia da Pesquisa de IA do Azure é compatível com chaves RSA de tamanhos 2048, 3072 e 4096. Para obter mais informações sobre os tipos de chave com suporte, confira Sobre chaves.
Entre no portal do Azure e abra a página de visão geral do cofre de chaves.
Selecione Objetos>Chaves à esquerda e, em seguida, selecione Gerar/Importar.
No painel Criar uma chave, na lista de Opções, escolha Gerar para criar uma chave.
Insira um Nome para sua chave e aceite os padrões para outras propriedades da chave.
Opcionalmente, defina uma política de rotação de chaves para habilitar a rotação automática.
Selecione Criar para iniciar a implantação.
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.
Etapa 2: criar uma entidade de segurança
Você tem várias opções para configurar o acesso da Pesquisa de IA do Azure à chave de criptografia em tempo de execução. A abordagem mais simples é recuperar a chave usando a identidade gerenciada de seu serviço de pesquisa. É possível usar uma identidade gerenciada pelo sistema ou pelo usuário. Isso permite omitir as etapas de registro de aplicativo e segredos de 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 nas solicitações.
Recomendamos o uso de uma identidade gerenciada. 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 serviço de pesquisa, que só pode ter uma identidade gerenciada atribuída ao sistema. Para obter mais informações sobre como identidades gerenciadas funcionam, consulte O que são identidades gerenciadas para recursos do Azure?.
- Identidade gerenciada pelo sistema
- Identidade gerenciada pelo usuário (versão prévia)
- Registrar um aplicativo
Habilite a identidade gerenciada atribuída pelo sistema para seu serviço de pesquisa.
Etapa 3: conceder permissões
O Azure Key Vault oferece 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 Key Vault usando funções do Azure.
Nesta etapa, atribua a função Key Vault Crypto Service Encryption User ao seu serviço de pesquisa. Se estiver testando localmente, atribua essa função a si mesmo também.
Entre no portal do Azure e localize 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 Avançar.
Selecione identidades gerenciadas, selecione membros e, em seguida, selecione a identidade gerenciada de seu serviço de pesquisa.
Selecione Examinar + 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 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 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 em Python neste artigo.
Chame as APIs de criação para especificar a propriedade encryptionKey:
Insira o constructo encryptionKey na definição do objeto. Essa propriedade é de primeiro nível, no mesmo nível que nome e descrição. Se estiver usando o mesmo cofre, chave e versão, você 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árias 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 tenha sido criptografado.
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.
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.
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, o objeto deverá ser atualizado para usá-la antes de excluir a anterior. Se isso não fizer efeito, o objeto ficará inutilizável. Não será possível descriptografar o conteúdo se a chave for perdida.
Etapa 5: testar criptografia
Para verificar se a criptografia está funcionando, revogue a chave de criptografia, consulte o índice (ele deve estar inutilizável) e, em seguida, restabeleça a chave de criptografia.
Use o portal do Azure para essa tarefa.
Na página do Azure Key Vault, selecione Objetos>Chaves.
Selecione a chave que você acabou de criar e, em seguida, selecione Excluir.
Na página Pesquisa de IA do Azure, selecione Gerenciamento de pesquisa>Índices.
Selecione seu índice e use o Explorador de Pesquisa para executar uma consulta. Você deverá receber um erro.
Retorne à página Objetos>Chaves do Azure Key Vault.
Selecione Gerenciar chaves excluídas.
Selecione sua chave e, em seguida, Recuperar.
Retorne ao seu índice na Pesquisa de IA do Azure e execute novamente a consulta. Você deverá ver os resultados da pesquisa. Se os resultados não forem imediatos, aguarde um minuto e tente novamente.
Configurar uma política para impor a conformidade com o CMK
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.
Navegue até a política interna no navegador da Web. Selecione Atribuir
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.
Conclua a criação da política.
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/<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 as chaves de criptografia
Recomendamos usar os recursos de rotação automática do Azure Key Vault, mas você também pode girar as chaves manualmente.
Quando você altera uma chave ou sua versão, qualquer objeto que use a chave deve ser atualizado primeiro para usar os novos valores antes de excluir os valores antigos. Caso contrário, o objeto se tornará inutilizável porque não poderá ser descriptografado.
Determinar a chave usada por um mapa de índice ou de sinônimo.
Criar uma nova chave no cofre de chaves, mas deixar a chave original disponível.
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.
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."
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.
Adicione uma configuração de diagnóstico no cofre de chaves que use o espaço de trabalho para retenção de dados.
Selecione auditoria ou allLogs para a categoria, dê um nome à configuração de diagnóstico e salve-a.
Exemplo em Python de uma configuração de chave de criptografia
Esta seção mostra a representação do Python de um encryptionKey em uma definição de objeto. A mesma definição se aplica a índices, fontes de dados, conjunto de habilidades, indexadores e mapas de sinônimos. Para experimentar esse exemplo em seu serviço de pesquisa e cofre de chaves, baixe o notebook em 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 do í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 sua 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 que o índice está funcionando.
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 aos do 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 dos dados ou das consultas, você não verá evidências visuais da criptografia. Para verificar se a criptografia está funcionando, verifique os logs de recursos.
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: