理解 V4 概念更新现有客户端以读取 V4 格式迁移到 V4 客户端其他配置示例

Amazon S3 加密客户端迁移（V2 到 V4）

注意

如果您使用的是 V1 并想迁移到 V4，则必须先迁移到 V2。请参阅Amazon S3 加密客户端迁移（V1 到 V2）。

本主题介绍如何将您的应用程序从亚马逊简单存储服务 (Amazon S3) 加密客户端的版本 2 (V2) 迁移到版本 4 (V4)，并确保应用程序在整个迁移过程中的可用性。V4 使用 AES-GCM 密钥承诺进行内容加密，并引入了承诺策略，以增强抵御密钥替换攻击的安全性。

V4 客户端在Amazon.Extensions.S3.Encryption NuGet 软件包中可用。

重要

重大更改：配置了REQUIRE_ENCRYPT_REQUIRE_DECRYPT策略的 V4 客户端无法解密使用 V1 或 V2 客户端加密的对象。只有最新的 V2 客户端才能使用密钥承诺解密 V4-encrypted 对象。在迁移到该REQUIRE_ENCRYPT_REQUIRE_DECRYPT策略之前，必须使用启用密钥承诺的 V4 客户端重新加密所有现有数据。

理解 V4 概念

V4 使用 AES-GCM 密钥承诺进行内容加密，并引入了增强加密数据保护的关键安全概念：

承诺政策

承诺策略控制加密客户端在加密和解密操作期间如何处理密钥承诺。V4 支持三种承诺策略：

FORBID_ENCRYPT_ALLOW_DECRYPT

加密：无承诺

解密：允许未提交的对象

安全性：不强制执行承诺，可能允许篡改

兼容性：所有 V2 和 V4 实现都可以读取使用此策略加密的对象

REQUIRE_ENCRYPT_ALLOW_DECRYPT

加密：附密钥承诺

解密：允许提交和不提交对象

安全：保护新对象免受密钥替换攻击，旧对象仍可读

兼容性：只有 V4 支持此政策

REQUIRE_ENCRYPT_REQUIRE_DECRYPT（V4 的默认值）

加密：附密钥承诺

解密：仅提交对象

安全：全面执行承诺以最大限度地提高安全性

兼容性：只有 V4 支持此政策

带有关键承诺的 AES GCM

V4 使用 AES-GCM 密钥承诺进行内容加密，从而增强安全性：

篡改保护：它通过加密方式将密钥绑定到加密数据来防止密钥替换攻击。
版本兼容性：使用密钥承诺加密的对象只能由 V4 客户端和更新版本解密。

警告

在生产环境中启用密钥承诺加密之前，请确保所有需要解密对象的应用程序都已升级到 V4 或更高版本，因为 V2 客户端已被弃用。

更新现有客户端以读取 V4 格式

V4 加密客户端使用旧版本的客户端不支持的加密算法。迁移的第一步是更新您的 V2 客户端，以便它们可以读取新的 V4 格式。

更新 NuGet 软件包依赖关系

更新您的应用程序以使用包含 V4 支持的最新版本的Amazon.Extensions.S3.Encryption NuGet 软件包。对每个应用程序执行以下步骤：

更新到最新的Amazon.Extensions.S3.Encryption软件包。如果您的项目直接依赖于AWSSDK.S3或AWSSDK.KeyManagementService包，则必须更新这些依赖项或将其删除，以便将它们的更新版本与该新包一起使用。

确保您的using语句引用正确的命名空间：


using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

重新构建并重新部署您的应用程序。

您现有的 V2 客户端将继续使用更新后的软件包，并将能够解密由 V4 客户端加密的对象（取决于所使用的承诺政策）。

构建和部署应用程序

更新 NuGet 软件包依赖关系后：

构建您的应用程序以确保正确解决所有依赖关系。
在开发环境中测试您的应用程序，以验证现有功能是否可以继续运行。
将更新后的应用程序部署到您的生产环境。

此更新使您现有的 V2 客户端能够解密将由 V4 客户端加密的对象，从而确保迁移过程中的兼容性。

迁移到 V4 客户端

更新现有客户端以读取新的加密格式后，您可以继续安全地更新应用程序以使用 V4 加密和解密客户端。V4 客户端通过密钥承诺提供增强的安全性，同时保持与现有加密对象的兼容性。

4 步迁移流程

从 V2 到 V4 的迁移遵循结构化的 4 步流程，以确保兼容性和安全性。每个步骤都代表一种特定的配置，在继续下一步之前，应将其部署到所有应用程序中。

第 0 步：V2 客户端（起点）-您现有的 V2 实现
第 1 步：兼容 V2 的 V4 -迁移到 V4 客户端，同时保持加密行为 V2-compatible
第 2 步：使用密钥承诺写入的 V4 -使用密钥承诺开始加密，同时允许解密传统对象
第 3 步：全面强制执行的 V4 -加密和解密都需要密钥承诺

第 0 步：V2 客户端（起点）

这代表您现有的 V2 客户端配置。此步骤演示了迁移前的起始状态。


using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 0: V2 Client - Starting configuration
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2(kmsKeyId, KmsType.KmsContext, encryptionContext);

#pragma warning disable 0618
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
#pragma warning enable 0618

var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

第 1 步：兼容 V2 的 V4

迁移到 V4 客户端，同时保持与 V2 相同的行为。此步骤使用FORBID_ENCRYPT_ALLOW_DECRYPT策略进行无承诺的加密，并允许解密所有对象。


using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 1: V4 Client with V2 compatibility
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcm);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

行为：无需承诺即可加密，可以解密提交和未提交的对象。与 V2 行为相同。

第 2 步：包含关键承诺写作的 V4

使用密钥承诺开始加密，同时保持解密的向后兼容性。此步骤使用REQUIRE_ENCRYPT_ALLOW_DECRYPT策略。

警告

在部署步骤 2 之前，请确保所有读取器已更新到步骤 1 或更高版本以处理密钥承诺加密。


using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 2: V4 Client with key commitment writes
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

行为：承诺加密，可以解密提交和未提交的对象。保护新对象免受密钥替换攻击。

第 3 步：全面执行的 V4

加密和解密都需要密钥承诺。此步骤使用REQUIRE_ENCRYPT_REQUIRE_DECRYPT策略来最大限度地提高安全性。

警告

在部署步骤 3 之前，请确保系统中的所有对象均已使用密钥承诺重新加密（步骤 2）。此步骤将无法解密未经承诺的加密对象。


using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 3: V4 Client with full key commitment enforcement
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

行为：承诺加密，仅解密承诺加密的对象。抵御密钥替换攻击的最大安全性。

其他配置示例

本节提供了在迁移期间使用不同选项配置 V4 客户端的其他示例。

启用旧版支持

要使 V4 客户端能够读取由 V1 和 V2 客户端加密的对象，请为客户端配置允许传统解密的承诺策略：


using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

// Configure V4 client to read V1/V2 objects
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};

// This configuration allows:
// - Encryption: With commitment (secure)
// - Decryption: Both V2 (non-committing) and V4 (committing) objects

在迁移期间，如果您需要解密由旧客户端加密的对象，同时确保以增强安全性对新对象进行加密，请使用此配置。

配置存储方法

V4 支持两种加密元数据的存储方法。选择最适合您的用例的方法：

对象元数据（默认）


var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
// Encryption metadata is stored in S3 object metadata

指令文件


var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.InstructionFile
};
// Encryption metadata is stored in a separate S3 object (instruction file)

InstructionFile当您需要保留对象元数据以用于其他目的或处理具有元数据大小限制的对象时使用。

配置承诺政策

根据您的安全要求和迁移阶段选择适当的承诺政策：

迁移阶段（V2 兼容性）


// For migration: encrypt without commitment, allow all decryption
var migrationConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT);

过渡阶段（推荐）


// For transition: encrypt with commitment, allow legacy decryption
var transitionConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);

全面安全阶段


// For maximum security: require commitment for both encryption and decryption
var secureConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);

从初始迁移FORBID_ENCRYPT_ALLOW_DECRYPT期间开始，进入过渡阶段，最后REQUIRE_ENCRYPT_REQUIRE_DECRYPT在所有客户端都已升级且所有对象都经过承诺重新加密后使用。REQUIRE_ENCRYPT_ALLOW_DECRYPT

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

S3 加密客户端迁移（V1 到 V2）

特殊注意事项