Configurare le chiavi gestite dal cliente per la crittografia dei dati in Ricerca di intelligenza artificiale di Azure
Ricerca di intelligenza artificiale di Azure crittografa automaticamente i dati inattivi con chiavi gestite dal servizio. Se è necessaria una maggiore protezione, è possibile integrare la crittografia predefinita con un altro livello di crittografia usando le chiavi create e gestite in Azure Key Vault.
Questo articolo illustra la procedura di configurazione della crittografia della chiave gestita dal cliente (CMK) o "bring-your-own-key" (BYOK).
Nota
Se un indice è crittografato tramite CMK, è accessibile solo se il servizio di ricerca ha accesso alla chiave. Se l'accesso viene revocato, l'indice non è utilizzabile e il servizio non può essere ridimensionato fino a quando l'indice non viene eliminato o non viene ripristinato l'accesso alla chiave.
Oggetti crittografati della chiave gestita dal cliente
La crittografia della chiave gestita dal cliente viene eseguita su singoli oggetti. Se è necessaria la chiave gestita dal cliente nel servizio di ricerca, impostare un criterio di imposizione.
La crittografia della chiave gestita dal cliente diventa operativa quando viene creato un oggetto. Non è possibile crittografare gli oggetti già esistenti. La crittografia della chiave gestita dal cliente si verifica ogni volta che un oggetto viene salvato su disco, ovvero i dati inattivi per l'archiviazione a lungo termine o i dati temporanei per l'archiviazione a breve termine. Con la chiave gestita dal cliente, il disco non vede mai dati non crittografati.
Gli oggetti che possono essere crittografati includono indici, elenchi di sinonimi, indicizzatori, origini dati e set di competenze. La crittografia è dispendiosa a livello di calcolo per decrittografare in modo che solo il contenuto sensibile sia crittografato.
La crittografia viene eseguita sul contenuto seguente:
Tutto il contenuto all'interno di indici e elenchi di sinonimi.
Contenuto sensibile in indicizzatori, origini dati, set di competenze e vettorizzatori. Questo contenuto è costituito solo da campi che archivia stringa di connessione, descrizioni, identità, chiavi e input utente. Ad esempio, i set di competenze hanno chiavi dei servizi di intelligenza artificiale di Azure e alcune competenze accettano input utente, ad esempio entità personalizzate. In entrambi i casi, le chiavi e gli input dell'utente nelle competenze vengono crittografati. Vengono crittografati anche tutti i riferimenti a risorse esterne, ad esempio origini dati di Azure o modelli OpenAI di Azure.
Crittografia doppia completa
Quando si introduce la crittografia CMK, si crittografa il contenuto due volte. Per gli oggetti e i campi indicati nella sezione precedente, il contenuto viene prima crittografato con la chiave gestita da Microsoft e in secondo luogo con la chiave gestita da Microsoft. Il contenuto viene crittografato doppiamente nei dischi dati per l'archiviazione a lungo termine e nei dischi temporanei usati per l'archiviazione a breve termine.
L'abilitazione della crittografia della chiave gestita dal cliente aumenta le dimensioni dell'indice e degrada le prestazioni delle query. In base alle osservazioni fino ad oggi, è possibile prevedere un aumento del 30-60% nei tempi di query, anche se le prestazioni effettive variano a seconda della definizione dell'indice e dei tipi di query. Poiché le prestazioni sono diminuite, è consigliabile abilitare questa funzionalità solo sugli oggetti che lo richiedono realmente.
Anche se la doppia crittografia è ora disponibile in tutte le aree, il supporto è stato implementato in due fasi:
La prima implementazione è stata il 1° agosto 2020 e includeva le cinque aree elencate di seguito. I servizi di ricerca creati nelle aree seguenti supportano CMK per i dischi dati, ma non i dischi temporanei:
- West US 2
- Stati Uniti orientali
- Stati Uniti centro-meridionali
- US Gov Virginia
- US Gov Arizona
La seconda implementazione il 13 maggio 2021 ha aggiunto la crittografia per i dischi temporanei e la crittografia CMK estesa a tutte le aree supportate.
Se si usa CMK da un servizio creato durante la prima implementazione e si vuole anche la crittografia CMK su dischi temporanei, è necessario creare un nuovo servizio di ricerca nell'area preferita e ridistribuire il contenuto. Per determinare la data di creazione del servizio, vedere Come controllare la data di creazione del servizio.
Prerequisiti
Ricerca di intelligenza artificiale di Azure in un livello fatturabile (Basic o superiore, in qualsiasi area).
Azure Key Vault nella stessa sottoscrizione di Azure AI Search. È possibile creare un insieme di credenziali delle chiavi usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. L'eliminazione temporanea e la protezione dall'eliminazione devono essere abilitate per l'insieme di credenziali delle chiavi.
Client di ricerca in grado di creare un oggetto crittografato, ad esempio un client REST, Azure PowerShell o Azure SDK (Python, .NET, Java, JavaScript).
Limiti
Nessun supporto per il modello di sicurezza hardware gestito di Azure Key Vault.
Nessun supporto per l'aggiunta di chiavi di crittografia nel portale di Azure.
Nessun supporto tra sottoscrizioni. Azure Key Vault e Ricerca di intelligenza artificiale di Azure devono trovarsi nella stessa sottoscrizione.
Suggerimenti per Key Vault
Se non si ha familiarità con Azure Key Vault, vedere questa guida introduttiva per informazioni sulle attività di base: Impostare e recuperare un segreto da Azure Key Vault usando PowerShell.
Ecco alcuni suggerimenti per l'uso di Key Vault:
Usare tutti gli insiemi di credenziali delle chiavi necessari. Le chiavi gestite possono trovarsi in insiemi di credenziali delle chiavi diversi. Un servizio di ricerca può avere più oggetti crittografati, ognuno crittografato con una chiave di crittografia gestita dal cliente diversa, archiviata in insiemi di credenziali delle chiavi diversi.
Usare lo stesso tenant in modo da poter recuperare la chiave gestita connettendosi tramite un'identità gestita dal sistema o dall'utente. Questo comportamento richiede che entrambi i servizi condividano lo stesso tenant. Per altre informazioni sulla creazione di un tenant, vedere Configurare un nuovo tenant.
Abilitare la protezione dall'eliminazione e l'eliminazione temporanea. A causa della natura della crittografia con chiavi gestite dal cliente, nessuno può recuperare i dati se la chiave di Azure Key Vault viene eliminata. Per evitare la perdita di dati causata da eliminazioni accidentali delle chiavi di Key Vault, è necessario abilitare la protezione dall'eliminazione temporanea nell'insieme di credenziali delle chiavi. L'eliminazione temporanea è abilitata per impostazione predefinita, quindi si verificano problemi solo se lo si disabilita intenzionalmente. La protezione dall'eliminazione non è abilitata per impostazione predefinita, ma è necessaria per la crittografia della chiave gestita dal cliente in Ricerca di intelligenza artificiale di Azure.
Abilitare la registrazione nell'insieme di credenziali delle chiavi in modo da poter monitorare l'utilizzo delle chiavi.
Abilitare l'autorotazione delle chiavi o seguire procedure rigorose durante la rotazione di routine delle chiavi dell'insieme di credenziali delle chiavi e dei segreti e della registrazione dell'applicazione. Aggiornare sempre tutto il contenuto crittografato per usare nuovi segreti e chiavi prima di eliminarli. Se non si verifica questo passaggio, il contenuto non può essere decrittografato.
Passaggio 1: Creare una chiave in Key Vault
Ignorare la generazione di chiavi se si ha già una chiave in Azure Key Vault che si vuole usare, ma raccogliere l'identificatore della chiave. Queste informazioni sono necessarie durante la creazione di un oggetto crittografato.
Prima di aggiungere la chiave, assicurarsi di aver assegnato a se stessi il ruolo di Responsabile della crittografia di Key Vault.
La crittografia di Ricerca intelligenza artificiale di Azure supporta chiavi RSA di dimensioni 2048, 3072 e 4096. Per altre informazioni sui tipi di chiave supportati, vedere Informazioni sulle chiavi.
Accedere al portale di Azure e aprire la pagina di panoramica dell'insieme di credenziali delle chiavi.
Selezionare Chiavi oggetti> a sinistra e quindi genera/importa.
Nell'elenco Opzioni del riquadro Crea una chiave scegliere Genera per creare una nuova chiave.
Immettere un nome per la chiave e accettare le impostazioni predefinite per altre proprietà della chiave.
Facoltativamente, impostare un criterio di rotazione delle chiavi per abilitare la rotazione automatica.
Selezionare Crea per avviare la distribuzione.
Selezionare la chiave, selezionare la versione corrente e quindi prendere nota dell'identificatore di chiave. È composto dall'URI del valore della chiave, dal nome della chiave e dalla versione della chiave. È necessario l'identificatore per definire un indice crittografato in Ricerca di intelligenza artificiale di Azure.
Passaggio 2: Creare un'entità di sicurezza
Sono disponibili diverse opzioni per configurare l'accesso di Ricerca intelligenza artificiale di Azure alla chiave di crittografia in fase di esecuzione. L'approccio più semplice consiste nel recuperare la chiave usando l'identità gestita del servizio di ricerca. È possibile usare un'identità gestita dal sistema o dall'utente. In questo modo è possibile omettere i passaggi per la registrazione dell'applicazione e i segreti dell'applicazione. In alternativa, è possibile creare e registrare un'applicazione Microsoft Entra e fare in modo che il servizio di ricerca fornisca l'ID applicazione nelle richieste.
È consigliabile usare un'identità gestita. Un'identità gestita consente al servizio di ricerca di eseguire l'autenticazione in Azure Key Vault senza archiviare le credenziali (ApplicationID o ApplicationSecret) nel codice. Il ciclo di vita di questo tipo di identità gestita è associato al ciclo di vita del servizio di ricerca, che può avere un'unica identità gestita assegnata dal sistema. Per altre informazioni sul funzionamento delle identità gestite, vedere Informazioni sulle identità gestite per le risorse di Azure.
Abilitare l'identità gestita assegnata dal sistema per il servizio di ricerca.
Passaggio 3: Concedere le autorizzazioni
Azure Key Vault supporta l'autorizzazione usando i controlli degli accessi in base al ruolo. È consigliabile usare questo approccio sui criteri di accesso dell'insieme di credenziali delle chiavi. Per altre informazioni, vedere Fornire l'accesso a chiavi, certificati e segreti di Key Vault usando i ruoli di Azure.
In questo passaggio assegnare al servizio di ricerca il ruolo utente crittografia crittografia del servizio di crittografia dell'insieme di credenziali delle chiavi. Se si esegue il test in locale, assegnare questo ruolo anche a se stessi.
Accedere al portale di Azure e trovare l'insieme di credenziali delle chiavi.
Selezionare Controllo di accesso (IAM) e selezionare Aggiungi assegnazione di ruolo.
Selezionare Key Vault Crypto Service Encryption User (Utente crittografia servizio crittografia key vault) e quindi selezionare Avanti.
Selezionare identità gestite, selezionare membri e quindi selezionare l'identità gestita del servizio di ricerca.
Selezionare Rivedi + Assegna.
Attendere alcuni minuti prima che l'assegnazione di ruolo diventi operativa.
Passaggio 4: Crittografare il contenuto
Le chiavi di crittografia vengono aggiunte quando si crea un oggetto. Per aggiungere una chiave gestita dal cliente in un indice, una mappa sinonimo, un indicizzatore, un'origine dati o un set di competenze, usare l'API REST di ricerca o un SDK di Azure per creare un oggetto con crittografia abilitata. Per aggiungere la crittografia con Azure SDK, vedere l'esempio python in questo articolo.
Chiamare le API di creazione per specificare la proprietà encryptionKey :
Inserire il costrutto encryptionKey nella definizione dell'oggetto. Questa proprietà è una proprietà di primo livello, allo stesso livello del nome e della descrizione. Se si usa lo stesso insieme di credenziali, la stessa chiave e la stessa versione, è possibile incollare lo stesso costrutto encryptionKey in ogni definizione di oggetto.
Il primo esempio mostra una encryptionKey per un servizio di ricerca che si connette usando un'identità gestita:
{ "encryptionKey": { "keyVaultUri": "<YOUR-KEY-VAULT-URI>", "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>", "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>" } }Il secondo esempio include accessCredentials, necessario se è stata registrata un'applicazione nell'ID Microsoft Entra:
{ "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>" } } }Verificare che la chiave di crittografia esista eseguendo un get sull'oggetto .
Verificare che l'oggetto sia operativo eseguendo un'attività, ad esempio eseguire una query su un indice crittografato.
Dopo aver creato l'oggetto crittografato nel servizio di ricerca, è possibile usarlo come qualsiasi altro oggetto del relativo tipo. La crittografia è trasparente per l'utente e lo sviluppatore.
Nessuno di questi dettagli dell'insieme di credenziali delle chiavi è considerato segreto e può essere facilmente recuperato passando alla pagina pertinente di Azure Key Vault nel portale di Azure.
Importante
Il contenuto crittografato in Ricerca intelligenza artificiale di Azure è configurato per l'uso di una chiave specifica di Azure Key Vault con una versione specifica. Se si modifica la chiave o la versione, l'oggetto deve essere aggiornato per usarlo prima di eliminare quello precedente. In caso contrario, l'oggetto non è utilizzabile. Non sarà possibile decrittografare il contenuto se la chiave viene persa.
Passaggio 5: Testare la crittografia
Per verificare che la crittografia funzioni, revocare la chiave di crittografia, eseguire una query sull'indice (deve essere inutilizzabile) e quindi ripristinare la chiave di crittografia.
Usare il portale di Azure per questa attività.
Nella pagina Insieme di credenziali delle chiavi di Azure selezionare Chiavi degli oggetti>.
Selezionare la chiave appena creata e quindi selezionare Elimina.
Nella pagina Ricerca di intelligenza artificiale di Azure selezionare Indici di gestione della ricerca>.
Selezionare l'indice e usare Esplora ricerche per eseguire una query. Verrà visualizzato un errore.
Tornare alla pagina Chiavi degli oggetti>di Azure Key Vault.
Selezionare Gestisci chiavi eliminate.
Selezionare la chiave e quindi selezionare Ripristina.
Tornare all'indice in Ricerca di intelligenza artificiale di Azure ed eseguire di nuovo la query. Verranno visualizzati i risultati della ricerca. Se non vengono visualizzati risultati immediati, attendere un minuto e riprovare.
Configurare un criterio per applicare la conformità della chiave gestita dal cliente
I criteri di Azure consentono di imporre standard aziendali e di valutare la conformità su larga scala. Ricerca di intelligenza artificiale di Azure include un criterio predefinito facoltativo per l'imposizione della chiave gestita a livello di servizio.
In questa sezione vengono impostati i criteri che definiscono uno standard CMK per il servizio di ricerca. Configurare quindi il servizio di ricerca per applicare questo criterio.
Passare al criterio predefinito nel Web browser. Selezionare Assegna
Configurare l'ambito dei criteri. Nella sezione Parametri deselezionare Mostra solo i parametri... e impostare Effetto su Nega.
Durante la valutazione della richiesta, una richiesta che corrisponde a una definizione di criteri di negazione viene contrassegnata come non conforme. Supponendo che lo standard per il servizio sia la crittografia cmk, "deny" significa che le richieste che non specificano la crittografia CMK non sono conformi.
Completare la creazione dei criteri.
Chiamare l'API Servizi - Aggiornamento per abilitare l'imposizione dei criteri CMK a livello di servizio.
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"
}
}
}
Ruotare o aggiornare le chiavi di crittografia
È consigliabile usare le funzionalità di autorotazione di Azure Key Vault, ma è anche possibile ruotare manualmente le chiavi.
Quando si modifica una chiave o la relativa versione, qualsiasi oggetto che usa la chiave deve essere aggiornato per usare i nuovi valori prima di eliminare i valori precedenti. In caso contrario, l'oggetto diventa inutilizzabile perché non può essere decrittografato.
Determinare la chiave usata da un indice o da una mappa sinonimo.
Creare una nuova chiave nell'insieme di credenziali delle chiavi, ma lasciare disponibile la chiave originale.
Aggiornare le proprietà encryptionKey in una mappa di indice o sinonimo per usare i nuovi valori. Solo gli oggetti creati originariamente con questa proprietà possono essere aggiornati per utilizzare un valore diverso.
Disabilitare o eliminare la chiave precedente nell'insieme di credenziali delle chiavi. Monitorare l'accesso alla chiave per verificare che venga usata la nuova chiave.
Per motivi di prestazioni, il servizio di ricerca memorizza nella cache la chiave per un massimo di diverse ore. Se si disabilita o si elimina la chiave senza specificarne una nuova, le query continuano a funzionare in modo temporaneo fino alla scadenza della cache. Tuttavia, una volta che il servizio di ricerca non è più in grado di decrittografare il contenuto, viene visualizzato questo messaggio: "Accesso negato. La chiave di query usata potrebbe essere stata revocata. Riprovare".
Usare il contenuto crittografato
Con la crittografia della chiave gestita dal cliente, è possibile notare la latenza sia per l'indicizzazione che per le query a causa del lavoro aggiuntivo di crittografia/decrittografia. Ricerca di intelligenza artificiale di Azure non registra l'attività di crittografia, ma è possibile monitorare l'accesso alle chiavi tramite la registrazione dell'insieme di credenziali delle chiavi.
È consigliabile abilitare la registrazione come parte della configurazione dell'insieme di credenziali delle chiavi.
Aggiungere un'impostazione di diagnostica nell'insieme di credenziali delle chiavi che usa l'area di lavoro per la conservazione dei dati.
Selezionare audit o allLogs per la categoria, assegnare un nome all'impostazione di diagnostica e quindi salvarlo.
Esempio python di una configurazione della chiave di crittografia
Questa sezione illustra la rappresentazione Python di un encryptionKey oggetto in una definizione di oggetto. La stessa definizione si applica agli indici, alle origini dati, ai set di competenze, agli indicizzatori e alle mappe sinonimiche. Per provare questo esempio nel servizio di ricerca e nell'insieme di credenziali delle chiavi, scaricare il notebook da azure-search-python-samples.
Installare alcuni pacchetti.
! pip install python-dotenv
! pip install azure-core
! pip install azure-search-documents==11.5.1
! pip install azure-identity
Creare un indice con una chiave di crittografia.
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')
Ottenere la definizione dell'indice per verificare l'esistenza della configurazione della chiave di crittografia.
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}")
Caricare l'indice con alcuni documenti. Tutto il contenuto del campo viene considerato sensibile e crittografato su disco usando la chiave gestita dal 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)
Eseguire una query per verificare che l'indice sia operativo.
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']}")
L'output della query dovrebbe produrre risultati simili all'esempio seguente.
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.
Poiché il contenuto crittografato viene decrittografato prima dell'aggiornamento dei dati o delle query, non verranno visualizzate prove visive della crittografia. Per verificare che la crittografia funzioni, controllare i log delle risorse.
Passaggi successivi
Se non si ha familiarità con l'architettura di sicurezza di Azure, vedere la documentazione sulla sicurezza di Azure e in particolare questo articolo: