Bloblar için istemci tarafı şifrelemesi

.NET kodunuzdan istemci tarafı şifrelemesini kullanmak için Blob Depolama istemci kitaplığına başvurun. 12.13.0 veya sonraki bir sürümü kullandığınızdan emin olun. 11.x sürümünden 12.13.0 sürümüne geçiş yapmanız gerekiyorsa Geçiş kılavuzuna bakın.

İstemci tarafı şifreleme için Azure Key Vault tümleştirmesi için iki ek paket gerekir:

• Azure.Core paketi ve IKeyEncryptionKeyResolver arabirimlerini sağlarIKeyEncryptionKey. .NET için Blob Depolama istemci kitaplığı bu derlemeyi zaten bir bağımlılık olarak tanımlar.

• Azure.Security.KeyVault.Keys paketi (sürüm 4.x ve üzeri), Key Vault REST istemcisini ve istemci tarafı şifreleme ile kullanılan şifreleme istemcilerini sağlar. Anahtar deponuz olarak Azure Key Vault kullanıyorsanız projenizde bu pakete başvurıldığından emin olun.

  Azure Key Vault, yüksek değerli ana anahtarlar için tasarlanmıştır ve anahtar kasası başına azaltma sınırları bu tasarımı yansıtır. Azure.Security.KeyVault.Keys'in 4.1.0 sürümünden IKeyEncryptionKeyResolver itibaren arabirim anahtar önbelleğe almayı desteklemez. Azaltma nedeniyle önbelleğe alma gerekliyse, bir örneğe önbelleğe alma katmanı Azure.Security.KeyVault.Keys.Cryptography.KeyResolver eklemek için bu örnekte belirtilen yaklaşımı kullanabilirsiniz.

Geliştiriciler anahtar, anahtar çözümleyici veya hem anahtar hem de anahtar çözümleyici sağlayabilir. Anahtarlar, CEK'yi sarmalama ve açma mantığını sağlayan bir anahtar tanımlayıcısı kullanılarak tanımlanır. Şifre çözme işlemi sırasında bir anahtarı çözümlemek için anahtar çözümleyicisi kullanılır. Anahtar çözümleyicisi, anahtar tanımlayıcısı verilen bir anahtarı döndüren bir çözüm yöntemi tanımlar. Çözümleyici, kullanıcılara birden çok konumda yönetilen birden çok anahtar arasından seçim yapma olanağı sağlar.

Şifrelemede anahtar her zaman kullanılır ve anahtarın olmaması hatayla sonuçlanır.

Şifre çözmede, anahtar belirtilirse ve tanımlayıcısı gerekli anahtar tanımlayıcısıyla eşleşirse, şifre çözme için bu anahtar kullanılır. Aksi takdirde, istemci kitaplığı çözümleyiciyi çağırmaya çalışır. Herhangi bir çözümleyici belirtilmemişse istemci kitaplığı bir hata oluşturur. Bir çözümleyici belirtilirse anahtarı almak için anahtar çözümleyicisi çağrılır. Çözümleyici belirtilirse ancak anahtar tanımlayıcısı için eşlemesi yoksa istemci kitaplığı bir hata oluşturur.

İstemci tarafı şifrelemeyi kullanmak için bir ClientSideEncryptionOptions nesnesi oluşturun ve Bunu SpecializedBlobClientOptions ile istemci oluşturma sırasında ayarlayın. Şifreleme seçeneklerini API temelinde ayarlayamazsınız. Diğer her şey istemci kitaplığı tarafından dahili olarak işlenir.

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

BlobClientOptions nesnelerini kabul eden bir BlobServiceClient, BlobContainerClient veya BlobClient oluşturucularına şifreleme seçenekleri uygulayabilirsiniz.

Kodunuzda bir BlobClient nesnesi zaten varsa ancak istemci tarafı şifreleme seçenekleri yoksa, verilen ClientSideEncryptionOptions ile bu nesnenin bir kopyasını oluşturmak için bir uzantı yöntemi kullanabilirsiniz. Bu uzantı yöntemi, sıfırdan yeni bir BlobClient nesnesi oluşturma yükünü önler.

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

kodunuzu istemci tarafı şifreleme v2 kullanacak şekilde güncelleştirdikten sonra, önceden şifrelenmiş verileri istemci tarafı şifreleme v2 ile yeniden şifreleme bölümünde açıklandığı gibi mevcut şifrelenmiş verilerin şifresini çözdüğünüzden ve yeniden şifrelediğinizden emin olun.

Java kodunuzdan istemci tarafı şifreleme kullanmak için Blob Depolama istemci kitaplığına başvurun. 12.18.0 veya sonraki bir sürümü kullandığınızdan emin olun. Java istemci kitaplığının önceki bir sürümünden geçiş yapmanız gerekiyorsa Java için Blob Depolama geçiş kılavuzuna bakın.

İstemci tarafı şifreleme v2.1 kullanmak için 12.27.0 veya sonraki bir sürüme azure-storage-blob-cryptography bağımlılık ekleyin. İstemci tarafı şifreleme v2'nin sabit öbek boyutu 4 MiB iken v2.1, kimliği doğrulanmış şifreleme için bölge uzunluğunu yapılandırma özelliğini içerir. Bölge uzunluğu 16 bayttan 1 GiB'ye kadar yapılandırılabilir.

İstemci tarafı şifreleme v2.1 kullanmak için bir BlobClientSideEncryptionOptions örneği oluşturun ve isteğe bağlı olarak yöntemini kullanarak setAuthenticatedRegionDataLengthInBytes bölge uzunluğunu ayarlayın. Ardından şifreleme seçeneklerini EncryptedBlobClientBuilder oluşturucusunun üzerine geçirin.

Aşağıdaki import yönergelerini kodunuza ekleyin:

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

Aşağıdaki kod örneği, karşıya yüklemek üzere bir blobu şifrelemek için istemci tarafı şifreleme v2.1'in nasıl kullanılacağını gösterir:

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

İstemci tarafı şifreleme için kullanılan kitaplık hakkında daha fazla bilgi edinmek için bkz . Java için Azure Depolama Blobları Şifreleme istemci kitaplığı.

İstemci tarafı şifreleme v1'den geçiş yapıyorsanız, önceden şifrelenmiş verileri istemci tarafı şifreleme v2 ile yeniden şifreleme bölümünde açıklandığı gibi mevcut şifrelenmiş verilerin şifresini çözdüğünüzden ve yeniden şifrelediğinizden emin olun.

Python kodunuzdan istemci tarafı şifreleme kullanmak için Blob Depolama istemci kitaplığına başvurun. 12.13.0 veya sonraki bir sürümü kullandığınızdan emin olun. Python istemci kitaplığının önceki bir sürümünden geçiş yapmanız gerekiyorsa Python için Blob Depolama geçiş kılavuzuna bakın.

Aşağıdaki örnekte Python'dan istemci tarafı geçişi v2'nin nasıl kullanılacağı gösterilmektedir:

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)

kodunuzu istemci tarafı şifreleme v2 kullanacak şekilde güncelleştirdikten sonra, önceden şifrelenmiş verileri istemci tarafı şifreleme v2 ile yeniden şifreleme bölümünde açıklandığı gibi mevcut şifrelenmiş verilerin şifresini çözdüğünüzden ve yeniden şifrelediğinizden emin olun.

verileri istemci tarafı şifreleme v1'den v2'ye geçirmeyi ve .NET'te istemci tarafı şifreleme v2 ile verileri şifrelemeyi gösteren örnek bir proje için bkz . Şifreleme geçişi örnek projesi.

İstemci tarafı şifreleme v1'den v2'ye veri geçirmeyi ve Java'da istemci tarafı şifreleme v2 ile verileri şifrelemeyi gösteren örnek bir proje için bkz . ClientSideEncryptionV2Uploader.

verileri istemci tarafı şifreleme v1'den v2'ye geçirmeyi ve Python'da istemci tarafı şifreleme v2 ile verileri şifrelemeyi gösteren örnek bir proje için bkz . V1'den V2'ye İstemci Tarafı Şifreleme Geçişi.