Clientseitige Verschlüsselung für Blobs

Um clientseitige Verschlüsselung aus Ihrem .NET-Code zu verwenden, verweisen Sie auf die Blob Storage-Clientbibliothek. Stellen Sie sicher, dass Sie Version 12.13.0 oder höher verwenden. Wenn Sie von Version 11.x zu Version 12.13.0 migrieren müssen, finden Sie weitere Informationen im Migrationsleitfaden.

Zwei zusätzliche Pakete sind für die Integration von Azure Key Vault für clientseitige Verschlüsselung erforderlich:

• Das Azure.Core-Paket bietet die IKeyEncryptionKey- und IKeyEncryptionKeyResolver-Schnittstelle. Die Blob Storage-Clientbibliothek für .NET definiert diese Assembly als Abhängigkeit.

• Das Azure.Security.KeyVault.Keys-Paket (Version 4.x und höher) stellt den Key Vault-REST-Client und die kryptografischen Clients bereit, die mit clientseitiger Verschlüsselung verwendet werden. Stellen Sie sicher, dass in Ihrem Projekt auf dieses Paket verwiesen wird, wenn Sie Azure Key Vault als Schlüsselspeicher verwenden.

  Azure Key Vault ist für hochwertige Hauptschlüssel ausgelegt, und die Drosselungsgrenzwerte pro Schlüsseltresor spiegeln dieses Konzept wider. Ab Version 4.1.0 von Azure.Security.KeyVault.Keys unterstützt die IKeyEncryptionKeyResolver-Schnittstelle keine Zwischenspeicherung von Schlüsseln. Sollte das Zwischenspeichern aufgrund der Drosselung notwendig sein, können Sie mit dem Ansatz in diesem Beispiel eine Zwischenspeicherungsebene in eine Azure.Security.KeyVault.Keys.Cryptography.KeyResolver-Instanz einfügen.

Entwickler können einen Schlüssel, einen Schlüsselresolver oder einen Schlüssel und einen Schlüsselresolver bereitstellen. Schlüssel sind mit einer Schlüsselkennung gekennzeichnet, die die Logik für das Umschließen und Aufheben des Umschließens des CEK bereitstellt. Mit einem Schlüsselresolver wird ein Schlüssel während des Entschlüsselungsvorgangs aufgelöst. Der Schlüsselresolver definiert eine Auflösungsmethode, die bei einer angegebenen Schlüsselkennung einen Schlüssel zurückgibt. Der Resolver ermöglicht den Benutzern die Auswahl zwischen mehreren Schlüsseln, die an mehreren Speicherorten verwaltet werden.

Bei der Verschlüsselung wird immer der Schlüssel verwendet, und das Fehlen eines Schlüssels führt zu einem Fehler.

Wenn der Schlüssel bei der Entschlüsselung angegeben wird und seine Kennung mit der geforderten Schlüsselkennung übereinstimmt, wird dieser Schlüssel zur Entschlüsselung verwendet. Andernfalls versucht die Clientbibliothek, den Resolver aufzurufen. Wenn kein Resolver angegeben ist, löst die Clientbibliothek einen Fehler aus. Wenn ein Resolver angegeben wird, wird der Schlüsselresolver aufgerufen, um den Schlüssel abzurufen. Wenn der Resolver angegeben wird, jedoch nicht über eine Zuordnung für die Schlüsselkennung verfügt, löst die Clientbibliothek einen Fehler aus.

Um die clientseitige Verschlüsselung zu verwenden, erstellen Sie ein ClientSideEncryptionOptions-Objekt und legen es bei der Clienterstellung mit SpecializedBlobClientOptions fest. Verschlüsselungsoptionen können nicht pro API festgelegt werden. Alles Weitere wird intern von der Clientbibliothek behandelt.

// 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);

Sie können Verschlüsselungsoptionen auf BlobServiceClient-, BlobContainerClient- oder BlobClient-Konstruktoren anwenden, die BlobClientOptions-Objekte akzeptieren.

Wenn ein BlobClient-Objekt bereits in Ihrem Code vorhanden ist, aber keine clientseitigen Verschlüsselungsoptionen aufweist, können Sie eine Erweiterungsmethode verwenden, um eine Kopie dieses Objekts mit den angegebenen ClientSideEncryptionOptions zu erstellen. Diese Erweiterungsmethode vermeidet den Mehraufwand, ein neues BlobClient-Objekt von Grund auf neu zu erstellen.

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);

Nachdem Sie den Code zur Verwendung der clientseitigen Verschlüsselung v2 aktualisiert haben, stellen Sie sicher, dass Sie vorhandene verschlüsselte Daten entschlüsseln und erneut verschlüsseln, wie in Erneutes Verschlüsseln zuvor verschlüsselter Daten mit clientseitiger Verschlüsselung v2 beschrieben.

Um clientseitige Verschlüsselung aus Ihrem Java-Code zu verwenden, verweisen Sie auf die Blob Storage-Clientbibliothek. Stellen Sie sicher, dass Sie Version 12.18.0 oder höher verwenden. Wenn Sie aus einer früheren Version der Java-Clientbibliothek migrieren müssen, finden Sie Informationen im Blob Storage-Migrationshandbuch für Java.

Um die clientseitige Verschlüsselung v2.1 zu verwenden, schließen Sie eine Abhängigkeit von azure-storage-blob-cryptography Version 12.27.0 oder höher ein. Clientseitige Verschlüsselung v2 verfügt über eine feste Blockgröße von 4 MiB, während v2.1 die Möglichkeit enthält, die Regionslänge für die authentifizierte Verschlüsselung zu konfigurieren. Die Länge der Region ist von 16 Byte bis zu 1 GiB konfigurierbar.

Um die clientseitige Verschlüsselung v2.1 zu verwenden, erstellen Sie eine BlobClientSideEncryptionOptions-Instanz, und legen Sie optional die Regionslänge mithilfe der Methode setAuthenticatedRegionDataLengthInBytes fest. Übergeben Sie dann die Verschlüsselungsoptionen an den EncryptedBlobClientBuilder-Konstruktor.

Fügen Sie Ihrem Code die folgenden import-Anweisungen hinzu:

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

Das folgende Codebeispiel zeigt, wie Sie mit clientseitiger Verschlüsselung v2.1 einen BLOB für den Upload verschlüsseln:

// 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"));

Weitere Informationen zur Bibliothek, die für die clientseitige Verschlüsselung verwendet wird, finden Sie unter Azure Storage Blobs Cryptography-Clientbibliothek für Java.

Wenn Sie von der clientseitigen Verschlüsselung v1 migrieren, stellen Sie sicher, dass Sie vorhandene verschlüsselte Daten entschlüsseln und erneut verschlüsseln, wie in Erneutes Verschlüsseln zuvor verschlüsselte Daten mit clientseitiger Verschlüsselung v2 beschrieben.

Um clientseitige Verschlüsselung aus Ihrem Python-Code zu verwenden, verweisen Sie auf die Blob Storage-Clientbibliothek. Stellen Sie sicher, dass Sie Version 12.13.0 oder höher verwenden. Wenn Sie aus einer früheren Version der Python-Clientbibliothek migrieren müssen, finden Sie Informationen im Blob Storage-Migrationsleitfaden für Python.

Im folgenden Beispiel wird gezeigt, wie Sie clientseitige Migration v2 aus Python verwenden:

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)

Nachdem Sie den Code zur Verwendung der clientseitigen Verschlüsselung v2 aktualisiert haben, stellen Sie sicher, dass Sie vorhandene verschlüsselte Daten entschlüsseln und erneut verschlüsseln, wie in Erneutes Verschlüsseln zuvor verschlüsselter Daten mit clientseitiger Verschlüsselung v2 beschrieben.

Ein Beispielprojekt, das zeigt, wie Daten von clientseitiger Verschlüsselung v1 zu v2 migriert werden, und wie Daten mit clientseitiger Verschlüsselung v2 in .NET verschlüsselt werden, finden Sie im Verschlüsselungsmigration-Beispielprojekt.

Ein Beispielprojekt, das zeigt, wie Daten von clientseitiger Verschlüsselung v1 zu v2 migriert werden, und wie Daten mit clientseitiger Verschlüsselung v2 in Java verschlüsselt werden, finden Sie unter ClientSideEncryptionV2Uploader.

Ein Beispielprojekt, das zeigt, wie Daten von clientseitiger Verschlüsselung v1 zu v2 migriert werden, und wie Daten mit clientseitiger Verschlüsselung v2 in Python verschlüsselt werden, finden Sie unter Client Side Encryption Migration from V1 to V2 (Clientseitige Verschlüsselungsmigration von V1 zu V2).