Crittografia lato client per i BLOB

Per usare la crittografia lato client dal codice .NET, fare riferimento alla libreria client di Archiviazione BLOB. Assicurarsi di usare la versione 12.13.0 o successiva. Se si necessita di eseguire la migrazione dalla versione 11x alla versione 12.13.0, vedere la guida alla migrazione.

Per l'integrazione di Azure Key Vault per la crittografia lato client sono necessari due pacchetti aggiuntivi:

• Il pacchetto Azure.Core fornisce le interfacce IKeyEncryptionKey e IKeyEncryptionKeyResolver. La libreria client di archiviazione BLOB per .NET definisce già questo assembly come dipendenza.

• Il pacchetto Azure.Security.KeyVault.Keys (versione 4.x e successive) fornisce il client REST di Key Vault e i client crittografici usati con la crittografia lato client. Assicurarsi che questo pacchetto venga fatto riferimento nel progetto se si usa Azure Key Vault come archivio chiavi.

  Azure Key Vault è progettato per le chiavi master ad alto valore, e i limiti di limitazione per ogni insieme di credenziali delle chiavi riflettono questa progettazione. A partire dalla versione 4.1.0 di Azure.Security.KeyVault.Keys, l'interfaccia IKeyEncryptionKeyResolver non supporta la memorizzazione nella cache delle chiavi. Se la memorizzazione nella cache dovesse risultare necessaria a causa della limitazione, è possibile usare l'approccio illustrato in questo campione per inserire un livello di memorizzazione nella cache in un'istanza Azure.Security.KeyVault.Keys.Cryptography.KeyResolver.

Gli sviluppatori possono fornire una chiave, un resolver di chiavi o entrambi. Le chiavi vengono identificate usando un identificatore di chiave che fornisce la logica per il wrapping e l'annullamento del wrapping della chiave CEK. Un resolver delle chiavi viene usato per risolvere una chiave durante il processo di decrittografia. Il resolver delle chiavi definisce un metodo di risoluzione che restituisce una chiave in base a un identificatore di chiave. Il resolver offre agli utenti la possibilità di scegliere tra più chiavi gestite in più posizioni.

In caso di crittografia, la chiave viene sempre usata e l'assenza di una chiave genera un errore.

Per la decrittografia, se la chiave viene specificata e il relativo identificatore corrisponde all'identificatore di chiave richiesto, la chiave viene usata per la decrittografia. In caso contrario, la libreria client tenta di chiamare il resolver. Se non è specificato alcun resolver, la libreria client genera un errore. Se un resolver è specificato, il resolver delle chiavi viene chiamato per ottenere la chiave. Se il resolver è specificato ma non ha un mapping per l'identificatore di chiave, la libreria client genera un errore.

Per usare la crittografia lato client, creare un oggetto ClientSideEncryptionOptions e impostarlo alla creazione del client con SpecializedBlobClientOptions. Non è possibile impostare le opzioni di crittografia per ogni API. Tutto il resto viene gestito internamente dalla libreria client.

// Your key and key resolver instances, either through Azure Key Vault SDK or an external implementation.
IKeyEncryptionKey key;
IKeyEncryptionKeyResolver keyResolver;

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

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

// Create blob client with client-side encryption enabled.
// Client-side encryption options are passed from service clients to container clients, 
// and from container clients to blob clients.
// 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.
BlobClient blob = new BlobServiceClient
(new Uri($"https://{accountName}.blob.core.windows.net"), new DefaultAzureCredential(), options).GetBlobContainerClient("my-container").GetBlobClient("myBlob");

// Upload the encrypted contents to the blob.
blob.Upload(stream);

// Download and decrypt the encrypted contents from the blob.
MemoryStream outputStream = new MemoryStream();
blob.DownloadTo(outputStream);

È possibile applicare opzioni di crittografia a BlobServiceClient, BlobContainerClient o costruttori BlobClient che accettano oggetti BlobClientOptions.

Se un oggetto BlobClient esiste già nel codice ma non dispone di opzioni di crittografia lato client, è possibile usare un metodo di estensione per crearne una copia con l'oggetto ClientSideEncryptionOptions specificato. Questo metodo di estensione evita il sovraccarico causato dalla costruzione di un nuovo oggetto BlobClient.

using Azure.Storage.Blobs.Specialized;

// An existing BlobClient instance and encryption options.
BlobClient plaintextBlob;
ClientSideEncryptionOptions encryptionOptions;

// Get a copy of the blob that uses client-side encryption.
BlobClient clientSideEncryptionBlob = plaintextBlob.WithClientSideEncryptionOptions(encryptionOptions);

Dopo aver aggiornato il codice per usare la crittografia lato client v2, assicurarsi di decrittografare e crittografare nuovamente i dati crittografati esistenti, come descritto in Crittografare nuovamente i dati crittografati in precedenza con la crittografia lato client v2.

Per usare la crittografia lato client dal codice Java, fare riferimento alla libreria client di Archiviazione BLOB. Assicurarsi di usare la versione 12.18.0 o successiva. Se si necessita di eseguire la migrazione da una versione precedente della libreria client Java, vedere la Guida alla migrazione dell'Archiviazione BLOB per Java.

Per usare la crittografia lato client v2.1, includere una dipendenza dalla azure-storage-blob-cryptography versione 12.27.0 o successiva. La crittografia lato client v2 ha una dimensione di blocco fissa di 4 MiB, mentre la versione 2.1 include la possibilità di configurare la lunghezza dell'area per la crittografia autenticata. La lunghezza dell'area è configurabile da 16 byte fino a 1 GiB.

Per usare la crittografia lato client v2.1, creare un'istanza BlobClientSideEncryptionOptions e impostare facoltativamente la lunghezza dell'area usando il setAuthenticatedRegionDataLengthInBytes metodo . Passare quindi le opzioni di crittografia al costruttore EncryptedBlobClientBuilder .

Aggiungere le direttive import seguenti al codice:

import com.azure.core.cryptography.*;
import com.azure.storage.blob.specialized.cryptography.*;

L'esempio di codice seguente illustra come usare la crittografia lato client v2.1 per crittografare un BLOB per il caricamento:

// Your key instance, either through Azure Key Vault SDK or an external implementation
AsyncKeyEncryptionKey keyEncryptionKey;
AsyncKeyEncryptionKeyResolver keyResolver;
String keyWrapAlgorithm = "algorithm name";

// Sets the region length to 4 KiB
BlobClientSideEncryptionOptions encryptionOptions = new BlobClientSideEncryptionOptions()
    .setAuthenticatedRegionDataLengthInBytes(1024 * 4);
 
EncryptedBlobClient ebc = new EncryptedBlobClientBuilder(EncryptionVersion.V2_1)
    .blobClient(client)
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint("https://<storage-account-name>.blob.core.windows.net/")
    .clientSideEncryptionOptions(encryptionOptions)
    .buildEncryptedBlobClient();

ebc.upload(BinaryData.fromString("sample data"));

Per altre informazioni sulla libreria usata per la crittografia lato client, vedere Archiviazione di Azure libreria client di crittografia BLOB per Java.

Se si esegue la migrazione dalla crittografia lato client v1, assicurarsi di decrittografare e crittografare nuovamente i dati crittografati esistenti, come descritto in Crittografare nuovamente i dati crittografati in precedenza con la crittografia lato client v2.

Per usare la crittografia lato client dal codice Python, fare riferimento alla libreria client di Archiviazione BLOB. Assicurarsi di usare la versione 12.13.0 o successiva. Se si necessita di eseguire la migrazione da una versione precedente della libreria client Python, vedere la Guida alla migrazione dell'Archiviazione BLOB per Python.

L'esempio seguente illustra come usare la migrazione lato client v2 da Python:

blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    blob_client.require_encryption = True
    blob_client.key_encryption_key = kek
    blob_client.encryption_version = ‘2.0’  # Use Version 2.0!

    with open("decryptedcontentfile.txt", "rb") as stream:
        blob_client.upload_blob(stream, overwrite=OVERWRITE_EXISTING)

Dopo aver aggiornato il codice per usare la crittografia lato client v2, assicurarsi di decrittografare e crittografare nuovamente i dati crittografati esistenti, come descritto in Crittografare nuovamente i dati crittografati in precedenza con la crittografia lato client v2.

Per un progetto campione che illustra come eseguire la migrazione di dati dalla crittografia lato client v1 a v2 e come crittografare dati con la crittografia lato client v2 in .NET, vedere il progetto campione di migrazione della crittografia.

Per un progetto campione che illustra come eseguire la migrazione di dati dalla crittografia lato client v1 a v2 e come crittografare dati con la crittografia lato client v2 in Java, vedere ClientSideEncryptionV2Uploader.

Per un progetto campione che illustra come eseguire la migrazione di dati dalla crittografia lato client v1 a v2 e come crittografare dati con la crittografia lato client v2 in Python, vedere Migrazione della crittografa lato client da v1 a v2.