Esercitazione: Crittografare e decrittografare BLOB con l'insieme di credenziali delle chiavi di Azure

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 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:

Prerequisiti

• Sottoscrizione di Azure: creare gratuitamente un account
• Account di archiviazione di Azure: creare un account di archiviazione
• Insieme di credenziali delle chiavi: crearne uno usando portale di Azure, l'interfaccia della riga di comando di Azure o PowerShell
• Visual Studio 2022 installato

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 insieme di credenziali delle chiavi, è necessario il ruolo Key Vault Crypto Officer.You'll need the Key Vault Crypto Officer role to create a key and perform actions on keys in a key vault. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'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 all'insieme di credenziali delle chiavi, 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.

az keyvault show --resource-group '<your-resource-group-name>' --name '<your-unique-keyvault-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Key Vault Crypto Officer" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourKeyVaultName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Key Vault Crypto Officer" `
    -Scope <yourKeyVaultId>

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:

   • Visual Studio, individuare e fare doppio clic sul BlobEncryptionKeyVault.csproj file.
   • 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

Install-Package Azure.Identity
Install-Package Azure.Security.KeyVault.Keys
Install-Package Azure.Storage.Blobs

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

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 variabile di ambiente

Questa applicazione cerca una variabile di ambiente denominata KEY_VAULT_NAME per recuperare il nome dell'insieme di credenziali delle chiavi. 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 delle chiavi.

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 insieme di credenziali delle chiavi usando l'interfaccia della riga di comando di Azure, portale di Azure o PowerShell.

Nell'esempio seguente viene creato un oggetto KeyClient per l'insieme di credenziali 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 all'insieme di credenziali per creare le istanze del client di crittografia e del resolver delle chiavi. CryptographyClient implementa IKeyEncryptionKey e viene usato per eseguire operazioni di crittografia con chiavi archiviate in Azure Key Vault. KeyResolver implementa IKeyEncryptionResolver e recupera le chiavi di crittografia della chiave dall'identificatore di 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 nell'insieme di credenziali con cui si vuole crittografare, è 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 classe ClientSideEncryptionOptions fornisce le opzioni di configurazione client per la connessione all'archiviazione BLOB tramite la crittografia lato client. KeyEncryptionKey è necessario per le operazioni di caricamento e viene usato per eseguire il wrapping della chiave di crittografia del contenuto generata. KeyResolver è necessario per le operazioni di download e recupera la chiave di crittografia della chiave corretta per annullare il wrapping della chiave di crittografia del contenuto scaricato. KeyWrapAlgorithm è necessario per i caricamenti e specifica l'identificatore dell'algoritmo da usare per il wrapping della chiave di crittografia del contenuto.

// 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 un BLOB ed eseguire il caricamento

Quando l'oggetto BlobClient chiama 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 chiave di crittografia della rete.
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 archiviazione di Azure:

// 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 un BLOB ed eseguire il download

La libreria client Archiviazione di Azure presuppone che l'utente gestisca la chiave di crittografia della chiave in locale o in un insieme di credenziali delle chiavi. L'utente non deve conoscere la chiave specifica usata 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 decrittografata (decrittografata) usando la chiave kek. La libreria client non ha accesso alla chiave kek durante questo processo, ma richiama solo l'algoritmo di annullamento del wrapping 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