Client-side encryption for blobs

To use client-side encryption from your .NET code, reference the Blob Storage client library. Make sure that you're using version 12.13.0 or later. If you need to migrate from version 11.x to version 12.13.0, see the Migration guide.

Two additional packages are required for Azure Key Vault integration for client-side encryption:

• The Azure.Core package provides the IKeyEncryptionKey and IKeyEncryptionKeyResolver interfaces. The Blob Storage client library for .NET already defines this assembly as a dependency.

• The Azure.Security.KeyVault.Keys package (version 4.x and later) provides the Key Vault REST client and the cryptographic clients that are used with client-side encryption. Make sure that this package is referenced in your project if you're using Azure Key Vault as your key store.

  Azure Key Vault is designed for high-value master keys, and throttling limits per key vault reflect this design. As of version 4.1.0 of Azure.Security.KeyVault.Keys, the IKeyEncryptionKeyResolver interface doesn't support key caching. Should caching be necessary due to throttling, you can use the approach demonstrated in this sample to inject a caching layer into an Azure.Security.KeyVault.Keys.Cryptography.KeyResolver instance.

Developers can provide a key, a key resolver, or both a key and a key resolver. Keys are identified using a key identifier that provides the logic for wrapping and unwrapping the CEK. A key resolver is used to resolve a key during the decryption process. The key resolver defines a resolve method that returns a key given a key identifier. The resolver provides users the ability to choose between multiple keys that are managed in multiple locations.

On encryption, the key is always used and the absence of a key results in an error.

On decryption, if the key is specified and its identifier matches the required key identifier, that key is used for decryption. Otherwise, the client library attempts to call the resolver. If there's no resolver specified, then the client library throws an error. If a resolver is specified, then the key resolver is invoked to get the key. If the resolver is specified but doesn't have a mapping for the key identifier, then the client library throws an error.

To use client-side encryption, create a ClientSideEncryptionOptions object and set it on client creation with SpecializedBlobClientOptions. You can't set encryption options on a per-API basis. Everything else is handled by the client library internally.

// 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.chinacloudapi.cn"), 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);

You can apply encryption options to a BlobServiceClient, BlobContainerClient, or BlobClient constructors that accept BlobClientOptions objects.

If a BlobClient object already exists in your code but lacks client-side encryption options, then you can use an extension method to create a copy of that object with the given ClientSideEncryptionOptions. This extension method avoids the overhead of constructing a new BlobClient object from scratch.

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

After you update your code to use client-side encryption v2, make sure that you decrypt and re-encrypt any existing encrypted data, as described in Re-encrypt previously encrypted data with client-side encryption v2.

To use client-side encryption from your Java code, reference the Blob Storage client library. Make sure that you're using version 12.18.0 or later. If you need to migrate from an earlier version of the Java client library, see the Blob Storage migration guide for Java.

To use client-side encryption v2.1, include a dependency on azure-storage-blob-cryptography version 12.27.0 or later. Client-side encryption v2 has a fixed chunk size of 4 MiB, while v2.1 includes the ability to configure the region length for authenticated encryption. The region length is configurable from 16 bytes up to 1 GiB.

To use client-side encryption v2.1, create a BlobClientSideEncryptionOptions instance and optionally set the region length using the setAuthenticatedRegionDataLengthInBytes method. Then pass the encryption options to the EncryptedBlobClientBuilder constructor.

Add the following import directives to your code:

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

The following code example shows how to use client-side encryption v2.1 to encrypt a blob for upload:

// 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.chinacloudapi.cn/")
    .clientSideEncryptionOptions(encryptionOptions)
    .buildEncryptedBlobClient();

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

To learn more about the library used for client-side encryption, see Azure Storage Blobs Cryptography client library for Java.

If you're migrating from client-side encryption v1, make sure that you decrypt and re-encrypt any existing encrypted data, as described in Re-encrypt previously encrypted data with client-side encryption v2.

To use client-side encryption from your Python code, reference the Blob Storage client library. Make sure that you're using version 12.13.0 or later. If you need to migrate from an earlier version of the Python client library, see the Blob Storage migration guide for Python.

The following example shows how to use client-side migration v2 from 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)

After you update your code to use client-side encryption v2, make sure that you decrypt and re-encrypt any existing encrypted data, as described in Re-encrypt previously encrypted data with client-side encryption v2.

For a sample project that shows how to migrate data from client-side encryption v1 to v2 and how to encrypt data with client-side encryption v2 in .NET, see the Encryption migration sample project.

For a sample project that shows how to migrate data from client-side encryption v1 to v2 and how to encrypt data with client-side encryption v2 in Java, see ClientSideEncryptionV2Uploader.

For a sample project that shows how to migrate data from client-side encryption v1 to v2 and how to encrypt data with client-side encryption v2 in Python, see Client Side Encryption Migration from V1 to V2.