Blob 的客户端加密

若要从 .NET 代码使用客户端加密，请参阅 Blob 存储客户端库。 请确保使用的是版本 12.13.0 或更高版本。 如果需要从版本 11.x 迁移到版本 12.13.0，请参阅迁移指南。

对于客户端加密，Azure Key Vault 集成需要另外两个包：

• Azure.Core 包提供 IKeyEncryptionKey 和 IKeyEncryptionKeyResolver 接口。 用于 .NET 的 Blob 存储客户端库已将此程序集定义为一个依赖项。

• Azure.Security.KeyVault.Keys 包（版本 4.x 及更高版本）提供 Key Vault REST 客户端和与客户端加密一起使用的加密客户端。 如果使用 Azure 密钥保管库作为密钥存储，请务必在项目中引用此包。

  Azure Key Vault 专为高价值主密钥设计，每个密钥保管库的限制也反映了这种设计。 从 Azure.Security.KeyVault.Keys 版本 4.1.0 开始，IKeyEncryptionKeyResolver 接口不支持密钥缓存。 如果在限制条件下需要缓存，可以使用本示例中演示的方法将缓存层注入到 Azure.Security.KeyVault.Keys.Cryptography.KeyResolver 实例中。

开发人员可以提供密钥、密钥解析程序或同时提供密钥和密钥解析程序。 密钥是使用密钥标识符标识的，提供包装和解包 CEK 的逻辑。 密钥解析程序用于在解密过程中解析密钥。 密钥解析程序定义了解析方法，该方法根据给定的密钥标识符返回密钥。 解析程序使用户能够在多个位置中托管的多个密钥之间进行选择。

加密时将始终使用该密钥，缺少密钥会导致错误。

在解密时，如果指定了密钥，并且其标识符与所需的密钥标识符匹配，则使用该密钥进行解密。 否则，客户端库会尝试调用解析程序。 如果没有指定的解析程序，则客户端库将引发错误。 如果指定了解析程序，则会调用密钥解析程序来获取密钥。 如果指定了解析程序，但该解析程序不具有密钥标识符的映射，则客户端库将引发错误。

若要使用客户端加密，请创建一个 ClientSideEncryptionOptions 对象并在创建客户端时为其设置 SpecializedBlobClientOptions。 你无法按 API 设置加密选项。 其他所有事项均由客户端库在内部处理。

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

可以将加密选项应用于接受 BlobClientOptions 对象的 BlobServiceClient、BlobContainerClient 或 BlobClient 构造函数。

如果代码中已存在 BlobClient 对象，但没有客户端加密选项，则可以使用一个扩展方法通过给定的 ClientSideEncryptionOptions 创建该对象的副本。 此扩展方法避免了从头开始构造新的 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);

将代码更新为使用客户端加密 v2 后，请务必解密并重新加密任何现有加密数据，如使用客户端加密 v2 重新加密以前加密的数据中所述。

若要从 Java 代码使用客户端加密，请参阅 Blob 存储客户端库。 请确保使用的是版本 12.18.0 或更高版本。 如果需要从早期版本的 Java 客户端库进行迁移，请参阅适用于 Java 的 Blob 存储迁移指南。

如果要使用客户端加密 v2.1，请包含 azure-storage-blob-cryptography 版本 12.27.0 或更高版本的依赖项。 客户端加密 v2 的区块大小固定为 4 MiB，而 v2.1 包括了为经过身份验证的加密配置区域长度的功能。 区域长度可从 16 字节到最多 1 GiB 进行配置。

要使用客户端加密 v2.1，请创建 BlobClientSideEncryptionOptions 实例，并选择性地使用 setAuthenticatedRegionDataLengthInBytes 方法设置区域长度。 然后，将加密选项传递给 EncryptedBlobClientBuilder 构造函数。

将以下 import 指令添加到代码中：

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

以下代码示例演示了如何使用客户端加密 v2.1 来加密要上传的 Blob：

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

要详细了解用于客户端加密的库，请参阅适用于 Java 的 Azure 存储 Blob 加密客户端库。

如果要从客户端加密 v1 进行迁移，请务必解密并重新加密任何现有的加密数据，如使用客户端加密 v2 重新加密以前加密的数据中所述。

若要从 Python 代码使用客户端加密，请参阅 Blob 存储客户端库。 请确保使用的是版本 12.13.0 或更高版本。 如果需要从早期版本的 Python 客户端库进行迁移，请参阅适用于 Python 的 Blob 存储迁移指南。

以下示例演示如何从 Python 使用客户端迁移 v2：

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)

将代码更新为使用客户端加密 v2 后，请务必解密并重新加密任何现有加密数据，如使用客户端加密 v2 重新加密以前加密的数据中所述。

有关演示如何将数据从客户端加密 v1 迁移到 v2 的示例项目，以及如何使用 .NET 中的客户端加密 v2 加密数据，请参阅加密迁移示例项目。

有关演示如何将数据从客户端加密 v1 迁移到 v2 的示例项目，以及如何使用 Java 中的客户端加密 v2 加密数据，请参阅 ClientSideEncryptionV2Uploader。

有关演示如何将数据从客户端加密 v1 迁移到 v2 的示例项目，以及如何使用 Python 中的客户端加密 v2 加密数据，请参阅从 V1 到 V2 的客户端加密迁移。