Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
O Azure AI Search criptografa automaticamente os dados em repouso com chaves gerenciadas pela Microsoft. Se precisar de outra camada de encriptação ou da capacidade de revogar chaves e encerrar o acesso ao conteúdo, pode utilizar chaves que cria e gere no Cofre de Chaves do Azure. Este artigo explica como configurar a criptografia de chave gerenciada pelo cliente (CMK).
Você pode armazenar chaves usando o Azure Key Vault ou o Azure Key Vault Managed HSM (Hardware Security Module). Um HSM gerenciado do Azure Key Vault é um HSM validado pelo FIPS 140-2 Nível 3. O suporte a HSM é novo no Azure AI Search. Para migrar para o HSM, rode as suas chaves e escolha o Managed HSM para armazenamento.
Importante
A encriptação CMK é irreversível. Você pode girar chaves e alterar a configuração da CMK, mas a criptografia de índice dura o tempo de vida do índice. Criptografia pós-CMK, um índice só é acessível se o serviço de pesquisa tiver acesso à chave. Se você revogar o acesso à chave excluindo ou alterando a atribuição de função, o índice ficará inutilizável e o serviço não poderá ser dimensionado até que o índice seja excluído ou o acesso à chave seja restaurado. Se você excluir ou girar chaves, a chave mais recente será armazenada em cache por até 60 minutos.
Objetos criptografados CMK
A criptografia CMK se aplica a objetos individuais quando eles são criados. Isso 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. Conteúdo confidencial refere-se a 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 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.
Se você precisar de CMK em seu serviço de pesquisa, defina uma política de aplicação.
Pré-requisitos
Azure AI Search em uma camada faturável (Básico ou superior, em qualquer região).
Azure Key Vault e um cofre de chaves com eliminação suave e proteção contra eliminação habilitada. Ou, Azure Key Vault Managed HSM. Esse recurso pode estar em qualquer assinatura, mas deve estar no mesmo locatário do Azure AI Search.
Capacidade de configurar permissões para acesso a chaves e atribuir funções. Para criar chaves, tem de ser Key Vault Crypto Officer no Azure Key Vault ou Managed HSM Crypto Officer no Azure Key Vault Managed HSM.
Para atribuir funções, você deve ser Proprietário da assinatura, Administrador de Acesso de Usuário, Administrador de Controle de Acesso baseado em função ou ser atribuído a uma função personalizada com permissões Microsoft.Authorization/roleAssignments/write .
Etapa 1: Criar uma chave de criptografia
Use o Azure Key Vault ou o Azure Key Vault Managed HSM para criar uma chave. 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.
Recomendamos que reveja estas dicas antes de começar.
As operações necessárias são Wrap, Unwrap, Encrypt e Decrypt.
Você pode criar um cofre de chaves usando o portal do Azure, a CLI do Azure ou o Azure PowerShell.
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.
Depois que a chave for criada, obtenha seu identificador de chave. Selecione a chave, selecione a versão atual e copie o identificador de chave. É composto pelo valor da chave Uri, pelo nome da chave e pela versão da chave. Você precisa do identificador para definir um índice criptografado no Azure AI Search. Lembre-se de que as operações necessárias são Wrap, Unwrap, Encrypt e Decrypt.
Etapa 2: Criar um principal de segurança
Crie uma entidade de segurança que seu serviço de pesquisa usa para acessar a chave de criptografia. Você pode usar uma identidade gerenciada e atribuição de função, ou você pode registrar um aplicativo e fazer com que o serviço de pesquisa forneça o ID do aplicativo em solicitações.
Recomendamos o uso de uma identidade e funções gerenciadas. Você pode usar uma identidade gerenciada pelo sistema ou uma identidade gerenciada pelo usuário. Uma identidade gerenciada permite que seu serviço de pesquisa se autentique por meio do Microsoft Entra ID, 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. É uma operação de dois cliques, ativar e salvar.
Etapa 3: Conceder permissões
Se você configurou seu serviço de pesquisa para usar uma identidade gerenciada, atribua funções que lhe deem acesso à chave de criptografia.
O controlo de acesso baseado em função é recomendado em vez do modelo de permissão de Política de Acesso. Para obter mais informações ou etapas de migração, comece com o controle de acesso baseado em função do Azure (Azure RBAC) versus políticas de acesso (legado).
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 uma função:
- No Cofre da Chave do Azure, selecione Usuário de Criptografia do Serviço de Criptografia do Cofre da Chave.
- Em Managed HSM, selecione Managed HSM Crypto Service Encryption User.
Selecione identidades gerenciadas, selecione membros e, em seguida, selecione a identidade gerenciada do seu serviço de pesquisa. Se você estiver testando localmente, atribua essa função a si mesmo também.
Selecione Rever + Atribuir.
Aguarde alguns minutos para que a atribuição de função se torne operacional.
Etapa 4: criptografar o conteúdo
A criptografia ocorre quando você cria ou atualiza um objeto. Você pode usar o portal do Azure para objetos selecionados. Para qualquer objeto, use a API REST de Pesquisa ou um SDK do Azure. Analise o exemplo do Python neste artigo para ver como o conteúdo é criptografado programaticamente.
Ao criar um novo objeto no portal do Azure, você pode especificar uma chave gerenciada pelo cliente predefinida em um cofre de chaves. O portal do Azure permite 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.
Entre no portal do Azure e abra sua página de serviço de pesquisa.
Em Gerenciamento de pesquisa, selecione Índices, Indexadores ou Fontes de Dados.
Adicione um novo objeto. Na definição de objeto, selecione criptografia gerenciada pela Microsoft.
Selecione Chaves gerenciadas pelo cliente e escolha sua assinatura, cofre, chave e versão.
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. Certifique-se de que tem uma atribuição de função que conceda acesso de leitura à chave.
Na página Cofre da Chave do Azure, selecione Objetos>Chaves.
Selecione a chave que criou e, em seguida, selecione Eliminar.
Na página Azure AI Search, selecione Gerenciamento de pesquisa>Índices.
Selecione seu índice e use o Search Explorer para executar uma consulta. Você deve receber um erro.
Volte para a página Objetos>Chaves do Cofre de Chaves 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 duas políticas internas opcionais relacionadas à CMK. Estas políticas aplicam-se a serviços de pesquisa novos e existentes.
| Efeito | Efeito se ativado |
|---|---|
| AuditIfNotExists | Verifica a conformidade da política: os objetos têm uma chave gerenciada pelo cliente definida e o conteúdo é criptografado. Este efeito aplica-se aos serviços existentes com conteúdo. Ele é avaliado cada vez que um objeto é criado ou atualizado, ou de acordo com o cronograma de avaliação. Saiba mais... |
| Negar | Verifica a aplicação da política: o serviço de pesquisa tem SearchEncryptionWithCmk definido como Enabled. Este efeito aplica-se apenas a novos serviços, que devem ser criados com a encriptação ativada. Os serviços existentes permanecem operacionais, mas você não pode atualizá-los a menos que corrija o serviço. Nenhuma das ferramentas usadas para provisionar serviços expõe essa propriedade, portanto, esteja ciente de que a definição da política limita a configuração programática. |
Atribuir uma política
No portal do Azure, navegue até uma política interna e selecione Atribuir.
Eis um exemplo da política AuditIfExists no portal do Azure:
Defina o escopo da política selecionando a assinatura e o grupo de recursos. Exclua quaisquer serviços de pesquisa aos quais a política não deva ser aplicada.
Aceite ou modifique os padrões. Selecione Rever + criar, seguido de Criar.
Habilitar a aplicação da política de CMK
Uma política atribuída a um grupo de recursos na sua subscrição entra em vigor imediatamente. As políticas de auditoria sinalizam recursos não compatíveis, mas as políticas de negação impedem a criação e a atualização de serviços de pesquisa não compatíveis. Esta seção explica como criar um serviço de pesquisa compatível ou atualizar um serviço para torná-lo compatível. Para colocar os objetos em conformidade, comece na etapa um deste artigo.
Criar um serviço de pesquisa compatível
Para novos serviços de pesquisa, crie-os com SearchEncryptionWithCmk definido como Enabled.
Nem o portal do Azure nem as ferramentas de linha de comando (a CLI do Azure e o Azure PowerShell) fornecem essa propriedade nativamente, mas você pode usar a API REST de Gerenciamento para provisionar um serviço de pesquisa com uma definição de política CMK.
Este exemplo é de Manage your Azure AI Search service with REST APIs, modificado para incluir a propriedade SearchEncryptionWithCmk .
### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "North Central US",
"sku": {
"name": "basic"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "default",
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
Atualizar um serviço de pesquisa existente
Para serviços de pesquisa existentes que agora não estão em conformidade, corrija-os usando Services - Update API ou o comando Azure CLI az resource update . A aplicação de patches nos serviços restaura a capacidade de atualizar as propriedades do serviço de pesquisa.
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
Use as instruções a seguir para girar chaves ou migrar do Cofre de Chaves do Azure para o Modelo de Segurança de Hardware (HSM).
Para rotação de chaves, recomendamos usar as capacidades de rotação automática do Cofre de Chaves do Azure. Se utilizar a autorotação, omita a versão da chave nas definições de objeto. A chave mais recente é usada, em vez de uma versão específica.
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.
Lembre-se de que as chaves são armazenadas em cache por 60 minutos. Lembre-se disso ao testar e girar chaves.
Crie uma nova chave no cofre de chaves, mas deixe a chave original disponível. Nesta etapa, você pode alternar do cofre de chaves para o HSM.
Atualize as propriedades encryptionKey num índice ou mapa de sinónimos 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: "Access forbidden. The query key used might have been revoked - please retry."
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.
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 do Azure para que você possa recuperar sua chave gerenciada por meio de atribuições de função e conectando-se por meio de um sistema ou identidade gerenciada pelo usuá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 a exclusão suave em um 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 desativá-la propositalmente. A proteção contra limpeza não está habilitada por padrão, mas é necessária para a criptografia CMK 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 rotineira de chaves dos cofres de chaves, segredos de aplicações e registo. 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.
Trabalhar com conteúdo encriptado
Com a criptografia CMK, você pode notar latência para indexação e consultas devido ao trabalho extra de criptografia/descriptografia. O Azure AI Search não regista a atividade de criptografia, mas pode monitorizar o acesso às chaves através dos registos do cofre de chaves.
Recomendamos que se ative o logging 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 utiliza o espaço de trabalho para a 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, panelas, 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 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: