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 Key Vault 作为密钥存储，则需要确保在项目中引用此包。

  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 存储迁移指南。

有关演示如何从 Java 使用客户端加密 v2 的示例代码，请参阅 ClientSideEncryptionV2Uploader.java。

将代码更新为使用客户端加密 v2 后，请确保解密并重新加密任何现有加密数据，如使用客户端加密 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 的客户端加密迁移。