Esercitazione: Crittografare e decrittografare BLOB con Azure Key Vault

Questa esercitazione illustra come usare la crittografia lato client per crittografare e decrittografare i BLOB usando una chiave archiviata con Azure Key Vault.

Archiviazione BLOB di Azure supporta sia la crittografia lato servizio che quella lato client. Per la maggior parte degli scenari, Microsoft consiglia di usare le funzionalità di crittografia lato servizio per semplificare l'uso nella protezione dei dati. Per altre informazioni sulla crittografia lato servizio, vedere Crittografia di Archiviazione di Azure per i dati inattivi.

La libreria client Archiviazione BLOB di Azure per .NET supporta la crittografia dei dati lato client all'interno delle applicazioni prima del caricamento in Archiviazione di Azure e la decrittografia dei dati durante il download nel client. La libreria supporta anche l'integrazione con Azure Key Vault per la gestione delle chiavi.

Questa esercitazione illustra come:

  • Configurare le autorizzazioni per una risorsa di Azure Key Vault
  • Creare un'applicazione console per interagire con le risorse usando le librerie client .NET
  • Aggiungere una chiave a un Key Vault
  • Configurare le opzioni di crittografia lato client usando una chiave archiviata in un Key Vault
  • Creare un oggetto client del servizio BLOB con la crittografia lato client abilitata
  • Caricare un BLOB crittografato, quindi scaricare e decrittografare il BLOB

Prerequisiti

Assegnare un ruolo all'utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che accede all'insieme di credenziali delle chiavi disponga delle autorizzazioni corrette. Per creare una chiave ed eseguire azioni sulle chiavi in un Key Vault, è necessario il ruolo Key Vault Crypto Officer. È possibile assegnare ruoli RBAC di Azure a un utente usando il portale di Azure, interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente, con ambito al Key Vault, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente illustra come assegnare il ruolo Key Vault Crypto Officer all'account utente, che fornisce l'accesso necessario per completare questa esercitazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nel portale di Azure, individua il tuo Key Vault usando la barra di ricerca principale o la barra di navigazione sinistra.

  2. Nella pagina di panoramica del Key Vault selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    Una schermata che mostra come assegnare un ruolo nel portale Azure.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Key Vault Crypto Officer e selezionare il risultato corrispondente e quindi scegliere Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Impostare il progetto

  1. In una finestra della console, ad esempio PowerShell o Bash, usare il dotnet new comando per creare una nuova app console con il nome BlobEncryptionKeyVault. Questo comando crea un semplice progetto C# "Hello World" con un singolo file di origine: Program.cs.

    dotnet new console -n BlobEncryptionKeyVault
    
  2. Passare alla directory BlobEncryptionKeyVault appena creata.

    cd BlobEncryptionKeyVault
    
  3. Aprire il progetto nell'editor di codice desiderato. Per aprire il progetto in:

    • In Visual Studio, individua e fai doppio clic sul file BlobEncryptionKeyVault.csproj.
    • In Visual Studio Code, eseguire il comando seguente:
    code .
    

Per interagire con i servizi di Azure in questo esempio, installare le librerie client seguenti usando dotnet add package.

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Keys
dotnet add package Azure.Storage.Blobs

Aggiungere le direttive seguenti using e assicurarsi di aggiungere al progetto un riferimento a System.Configuration.

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.Security.KeyVault.Keys;
using Azure.Security.KeyVault.Keys.Cryptography;
using Azure.Storage;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Imposta la variabile di ambiente

Questa applicazione cerca una variabile di ambiente denominata KEY_VAULT_NAME per recuperare il nome dell'insieme di credenziali. Per impostare la variabile di ambiente, aprire una finestra della console e seguire le istruzioni per il sistema operativo. Sostituire <your-key-vault-name> con il nome dell'insieme di credenziali.

Windows:

È possibile impostare le variabili di ambiente per Windows dalla riga di comando. Tuttavia, quando si usa questo approccio, i valori sono accessibili a tutte le applicazioni in esecuzione in tale sistema operativo e possono causare conflitti se non si è attenti. Le variabili di ambiente possono essere impostate a livello di utente o di sistema:

setx KEY_VAULT_NAME "<your-key-vault-name>"

Dopo aver aggiunto la variabile di ambiente in Windows, è necessario avviare una nuova istanza della finestra di comando. Se si usa Visual Studio in Windows, potrebbe essere necessario riavviare Visual Studio dopo aver creato la variabile di ambiente per rilevare la modifica.

Linux:

export KEY_VAULT_NAME=<your-key-vault-name>

Aggiungere una chiave in Azure Key Vault

In questo esempio viene creata una chiave e aggiunta all'insieme di credenziali delle chiavi usando la libreria client di Azure Key Vault. È anche possibile creare e aggiungere una chiave a un Key Vault usando interfaccia della riga di comando di Azure, Azure portal o PowerShell.

Nell'esempio seguente viene creato un oggetto KeyClient per l'insieme di credenziali delle chiavi specificato. L'oggetto KeyClient viene quindi usato per creare una nuova chiave RSA nell'insieme di credenziali specificato.

var keyName = "testRSAKey";
var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");

// URI for the key vault resource
var keyVaultUri = $"https://{keyVaultName}.vault.azure.net";

TokenCredential tokenCredential = new DefaultAzureCredential();

// Create a KeyClient object
var keyClient = new KeyClient(new Uri(keyVaultUri), tokenCredential);

// Add a key to the key vault
var key = await keyClient.CreateKeyAsync(keyName, KeyType.Rsa);

Creare istanze di chiave e resolver delle chiavi

Verrà quindi usata la chiave appena aggiunta al Key Vault per creare le istanze del client di crittografia e del resolver delle chiavi. CryptographyClient implementa IKeyEncryptionKey ed è utilizzato per eseguire operazioni crittografiche con chiavi memorizzate in Azure Key Vault. KeyResolver implementa IKeyEncryptionResolver e recupera le chiavi di crittografia dall'identificatore della chiave e risolve la chiave.

// Cryptography client and key resolver instances using Azure Key Vault client library
CryptographyClient cryptoClient = keyClient.GetCryptographyClient(key.Value.Name, key.Value.Properties.Version);
KeyResolver keyResolver = new (tokenCredential);

Se si dispone di una chiave esistente nel Key Vault con cui si vuole eseguire la crittografia, è possibile creare le istanze della chiave e del resolver delle chiavi passando l'URI:

var keyVaultKeyUri = $"https://{keyVaultName}.vault.azure.net/keys/{keyName}";
CryptographyClient cryptoClient = new CryptographyClient(new Uri(keyVaultKeyUri), tokenCredential);

Configurare le opzioni di crittografia

È ora necessario configurare le opzioni di crittografia da usare per il caricamento e il download dei BLOB. Per usare la crittografia lato client, creare prima di tutto un ClientSideEncryptionOptions oggetto e impostarlo alla creazione del client con SpecializedBlobClientOptions.

La ClientSideEncryptionOptions class fornisce le opzioni di configurazione client per la connessione a gestione rete virtuale di Azure tramite la crittografia lato client. KeyEncryptionKey è richiesto per le operazioni di caricamento ed è utilizzato per incapsulare la chiave di crittografia dei contenuti generata. KeyResolver è necessario per le operazioni di download e recupera la chiave di crittografia della chiave corretta per decrittografare la chiave di crittografia dei contenuti scaricati. KeyWrapAlgorithm è necessario per i caricamenti e specifica l'identificatore dell'algoritmo da utilizzare per il wrapping della chiave di crittografia del contenuto.

Importante

A causa di una vulnerabilità di sicurezza nella versione 1, è consigliabile costruire l'oggetto ClientSideEncryptionOptions usando ClientSideEncryptionVersion.V2_0 per il parametro version. Per altre informazioni sulla mitigazione della vulnerabilità nelle app, vedere Attenuare la vulnerabilità di sicurezza nelle applicazioni. Per altre informazioni su questa vulnerabilità di sicurezza, vedere Archiviazione di Azure che aggiorna la crittografia lato client in SDK per risolvere la vulnerabilità di sicurezza.

// Configure the encryption options to be used for upload and download
ClientSideEncryptionOptions encryptionOptions = new (ClientSideEncryptionVersion.V2_0)
{
    KeyEncryptionKey = cryptoClient,
    KeyResolver = keyResolver,
    // String value that the client library will use when calling IKeyEncryptionKey.WrapKey()
    KeyWrapAlgorithm = "RSA-OAEP"
};

// Set the encryption options on the client options.
BlobClientOptions options = new SpecializedBlobClientOptions() { ClientSideEncryption = encryptionOptions };

Configurare l'oggetto client per l'uso della crittografia lato client

In questo esempio vengono applicate le opzioni di configurazione della crittografia lato client a un BlobServiceClient oggetto . Se applicata a livello di client del servizio, queste opzioni di crittografia vengono passate dal client del servizio ai client contenitore e dai client contenitore ai client BLOB. Quando l'oggetto BlobClient esegue un'operazione di caricamento o download, le librerie client Archiviazione BLOB di Azure usano la crittografia envelope per crittografare e decrittografare i BLOB sul lato client. La crittografia envelope crittografa una chiave con una o più chiavi aggiuntive.

// Create a blob client with client-side encryption enabled.
// Attempting to construct a BlockBlobClient, PageBlobClient, or AppendBlobClient from a BlobContainerClient
// with client-side encryption options present will throw, as this functionality is only supported with BlobClient.
Uri blobUri = new (string.Format($"https://{accountName}.blob.core.windows.net"));
BlobClient blob = new BlobServiceClient(blobUri, tokenCredential, options).GetBlobContainerClient("test-container").GetBlobClient("testBlob");

Crittografare il blob e caricarlo

Quando l'oggetto BlobClient invoca un metodo di caricamento, vengono eseguiti diversi passaggi per eseguire la crittografia lato client:

  1. La libreria client Archiviazione di Azure genera un vettore di inizializzazione casuale (IV) di 16 byte e una chiave di crittografia del contenuto casuale (CEK) di 32 byte ed esegue la crittografia envelope dei dati BLOB usando queste informazioni.
  2. I dati BLOB vengono crittografati usando la CEK.
  3. La chiave cek viene quindi sottoposta a wrapping (crittografata) usando la chiave di crittografia della chiave (KEK) specificata in ClientSideEncryptionOptions. In questo esempio la chiave kek è una coppia di chiavi asimmetrica archiviata nella risorsa di Azure Key Vault specificata. Il client BLOB stesso non ha mai accesso alla chiave kek, richiama semplicemente l'algoritmo di wrapping delle chiavi fornito da Key Vault.
  4. I dati BLOB crittografati vengono quindi caricati nell'account di archiviazione.

Aggiungere il codice seguente per crittografare un BLOB e caricarlo nell'account di Azure Storage:

// Upload the encrypted contents to the blob
Stream blobContent = BinaryData.FromString("Ready for encryption, Captain.").ToStream();
await blob.UploadAsync(blobContent);

Dopo aver caricato il BLOB, è possibile visualizzare il BLOB nell'account di archiviazione per visualizzare il contenuto crittografato insieme ai metadati di crittografia.

Decrittografare il BLOB e scaricarlo

La libreria client di Archiviazione di Azure presuppone che l'utente gestisca la KEK in locale o in Key Vault. L'utente non deve necessariamente conoscere la chiave specifica utilizzata per la crittografia. Il sistema di risoluzione delle chiavi specificato in ClientSideEncryptionOptions verrà usato per risolvere gli identificatori di chiave quando i dati BLOB vengono scaricati e decrittografati.

Quando l'oggetto BlobClient chiama un metodo di download, vengono eseguiti diversi passaggi per decrittografare i dati BLOB crittografati:

  1. La libreria client scarica i dati BLOB crittografati, inclusi i metadati di crittografia, dall'account di archiviazione.
  2. La chiave CEK di cui è stato eseguito il wrapping viene quindi sottoposta a unwrapping (decrittografata) usando la chiave KEK. La libreria client non ha accesso alla chiave KEK durante questo processo, ma richiama solo l'algoritmo di unwrap della chiave specificato in ClientSideEncryptionOptions. La chiave privata della coppia di chiavi RSA rimane nell'insieme di credenziali delle chiavi, quindi la chiave crittografata dai metadati blob che contiene la chiave CEK viene inviata all'insieme di credenziali delle chiavi per la decrittografia.
  3. La libreria client usa la chiave cek per decrittografare i dati blob crittografati.

Aggiungere il codice seguente per scaricare e decrittografare il BLOB caricato in precedenza.

// Download and decrypt the encrypted contents from the blob
Response<BlobDownloadInfo>  response = await blob.DownloadAsync();
BlobDownloadInfo downloadInfo = response.Value;
Console.WriteLine((await BinaryData.FromStreamAsync(downloadInfo.Content)).ToString());

Passaggi successivi

In questa esercitazione si è appreso come usare le librerie client .NET per eseguire la crittografia lato client per le operazioni di caricamento e download di BLOB.

Per una panoramica generale della crittografia lato client per i BLOB, incluse le istruzioni per la migrazione dei dati crittografati alla versione 2, vedere Crittografia lato client per i BLOB.

Per altre informazioni su Azure Key Vault, vedere la pagina di panoramica di Azure Key Vault