本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

本主题介绍如何将您的应用程序从亚马逊简单存储服务 (Amazon S3) 加密客户端的版本 2 (V2) 迁移到版本 3 (V3)，并确保应用程序在整个迁移过程中的可用性。V3 引入了带有密钥承诺和承诺政策的 AES GCM，以增强安全性并防止数据密钥被篡改。

迁移概述

Amazon S3 加密客户端第 3 版引入了带有密钥承诺的 AES GCM，以增强安全性。这种新的加密算法可防止数据密钥被篡改，并确保加密数据的完整性。向 V3 的迁移需要仔细规划，以在整个过程中保持应用程序的可用性和数据可访问性。

此迁移分为两个阶段：

1. 更新现有客户端以读取新格式。首先，将 Ruby AWS 软件开发工具包的更新版本部署到您的应用程序。这将允许现有的 V2 加密客户端解密新的 V3 客户端写入的对象。如果您的应用程序使用多个 AWS SDK，则必须单独升级每个 SDK。

2. 将加密和解密客户端迁移到 V3。一旦所有 V2 加密客户端都可以读取新格式，您就可以将现有的加密和解密客户端迁移到相应的 V3 版本。这包括配置承诺策略和更新您的代码以使用新的客户端配置选项。

如果您尚未从 V1 迁移到 V2，则必须先完成迁移。Amazon S3 加密客户端迁移（V1 到 V2）有关从 V1 迁移到 V2 的详细说明，请参见。

了解 V3 功能

Amazon S3 加密客户端第 3 版引入了两个关键安全功能：承诺策略和带密钥承诺的 AES GCM。了解这些功能对于规划迁移策略和确保加密数据的安全性至关重要。

承诺政策

承诺策略控制加密客户端在加密和解密操作期间如何处理密钥承诺。密钥承诺可确保加密数据只能使用用于加密的确切密钥进行解密，从而防范某些类型的加密攻击。

V3 加密客户端支持三种承诺策略选项：

FORBID_ENCRYPT_ALLOW_DECRYPT

此策略无需密钥承诺即可加密对象，并允许在有或没有密钥承诺的情况下对这两个对象进行解密。

REQUIRE_ENCRYPT_ALLOW_DECRYPT

此策略使用密钥承诺对对象进行加密，并允许在有或没有密钥承诺的情况下对这两个对象进行解密。

REQUIRE_ENCRYPT_REQUIRE_DECRYPT

此策略使用密钥承诺加密对象，仅允许解密使用密钥承诺加密的对象。

带有关键承诺的 AES GCM

带有密钥承诺的 AES GCM (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) 是 V3 中引入的一种新加密算法，通过防范数据密钥篡改来增强安全性。了解该算法的工作原理及其应用时间对于规划迁移非常重要。

与以前的算法有何ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY不同

先前版本的 S3 加密客户端使用没有密钥承诺的 AES CBC 或 AES GCM 来加密指令文件中的数据密钥。ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY向加密过程添加加密承诺，将加密数据绑定到特定密钥。这可以防止攻击者篡改指令文件中的加密数据密钥，并导致客户端使用不正确的密钥解密数据。

如果没有密钥承诺，攻击者就有可能修改指令文件中的加密数据密钥，使其解密为不同的密钥，从而可能导致未经授权的访问或数据损坏。ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY通过确保加密的数据密钥只能解密为加密期间使用的原始密钥来防止这种攻击。

版本兼容性

使用加密的对象ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY只能通过 S3 加密客户端的 V3 实现以及支持读取 V3 格式的 V2 的特定过渡版本进行解密。不支持此过渡的 V2 客户端无法解密使用加密的ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY指令文件。

在迁移期间，您可以使用FORBID_ENCRYPT_ALLOW_DECRYPT承诺策略继续加密，ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY但仍允许您的 V3 客户端读取使用密钥承诺加密的对象。这提供了安全的迁移路径，您可以先升级所有读取器，然后切换到带密钥承诺的加密。

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

V3 加密客户端使用 V2 客户端默认不支持的加密算法和密钥承诺功能。迁移的第一步是将您的 V2 解密客户端更新为可以读取 V3 加密对象的 Ruby AWS SDK 版本。完成此步骤后，您的应用程序的 V2 客户端将能够解密由 V3 加密客户端加密的对象。

要读取由 V3 客户端（使用REQUIRE_ENCRYPT_ALLOW_DECRYPT或REQUIRE_ENCRYPT_REQUIRE_DECRYPT承诺策略的客户端）加密的对象，您需要使用 Gem 的 1.93.0 或更高版本。aws-sdk-s3此版本支持解密使用带有密钥承诺的 AES GCM 加密的对象。

从命令行安装

对于通过命令行安装 aws-sdk-s3 gem 的项目，使用版本选项来验证是否安装了 1.208.0 的最低版本。

gem install aws-sdk-s3 -v '>= 1.208.0'

使用 Gemfile

对于使用 Gemfile 管理依赖关系的项目，将 G aws-sdk-s3 em 的最低版本设置为 1.208.0。例如：

gem 'aws-sdk-s3', '>= 1.208.0'

将加密和解密客户端迁移到 V3

更新您的客户端以读取新的加密格式后，您可以将应用程序更新到 V3 加密和解密客户端。以下步骤向您展示如何成功将代码从 V2 迁移到 V3。

在更新代码以使用 V3 加密客户端之前，请确保您已按照上述步骤操作并使用的是 aws-sdk-s3 gem 版本 1.93.0 或更高版本。

配置 V3 客户端

V3 加密客户端引入了新的配置选项，用于控制密钥承诺行为和向后兼容性。了解这些选项对于成功迁移至关重要。

承诺政策

该commitment_policy参数控制加密客户端在加密和解密操作期间如何处理密钥承诺。这是 V3 客户端最重要的配置选项。

安全配置文件

该security_profile参数确定对读取由较早的加密客户端版本写入的对象的支持。此参数对于在迁移期间保持向后兼容性至关重要。

信封位置

该envelope_location参数决定加密元数据（包括加密的数据密钥）的存储位置。此参数影响哪些对象受带密钥承诺的 AES GCM 保护。

使用时:instruction_file，您可以选择指定instruction_file_suffix参数以自定义用于指令文件对象的后缀。默认后缀是。.instruction

何时使用每个配置选项

在迁移期间，请遵循以下推荐的配置策略：

对于envelope_location，继续使用现有的存储方法（:metadata或:instruction_file），除非您有具体的更改原因。如果您当前正在使用元数据存储，并希望获得带有数据密钥承诺的 AES GCM 的额外安全性，则可以切换到:instruction_file，但请注意，这将需要更新所有读取这些对象的客户端。

将加密和解密客户端迁移到 V3

更新您的客户端以读取新的加密格式后，您可以将应用程序更新到 V3 加密和解密客户端。以下示例向您展示如何成功地将代码从 V2 迁移到 V3。

使用 V3 加密客户端

Pre-migration (V2)

require 'aws-sdk-s3'

# Create V2 encryption client with KMS
client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy,
  commitment_policy: :forbid_encrypt_allow_decrypt
)

# Encrypt and upload object
client.put_object(bucket: 'my-bucket', key: 'my-object', body: 'secret data')

# Download and decrypt object
resp = client.get_object(bucket: 'my-bucket', key: 'my-object')
decrypted_data = resp.body.read

迁移期间（具有向后兼容性的 V3）

require 'aws-sdk-s3'

# Create V3 encryption client with KMS
client = Aws::S3::EncryptionV3::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v3_and_legacy,
  commitment_policy: :require_encrypt_allow_decrypt
)

# Encrypt and upload object
client.put_object(bucket: 'my-bucket', key: 'my-object', body: 'secret data')

# Download and decrypt object
resp = client.get_object(bucket: 'my-bucket', key: 'my-object')
decrypted_data = resp.body.read

Post-migration (V3)

require 'aws-sdk-s3'

# Create V3 encryption client with KMS
client = Aws::S3::EncryptionV3::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v3,
  # Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
  # This encrypts with key commitment and does not decrypt V2 objects
  commitment_policy: :require_encrypt_require_decrypt
)

# Encrypt and upload object
client.put_object(bucket: 'my-bucket', key: 'my-object', body: 'secret data')

# Download and decrypt object
resp = client.get_object(bucket: 'my-bucket', key: 'my-object')
decrypted_data = resp.body.read

V3 的主要区别在于添加了commitment_policy参数。将其设置为:require_encrypt_require_decrypt可确保使用密钥承诺对新对象进行加密，并且客户端仅解密使用密钥承诺加密的对象，从而增强安全性，防止数据密钥被篡改。

通put_object话本身保持不变。所有安全增强都是在客户端级别配置的。

其他示例

本节为特定迁移场景和配置选项提供了更多示例，这些示例在 V2 到 V3 迁移期间可能很有用。

指令文件与元数据存储

S3 加密客户端可以将加密元数据（包括加密的数据密钥）存储在两个不同的位置：在 S3 对象的元数据标头中或单独的指令文件中。存储方法的选择会影响哪些对象受益于具有密钥承诺保护的 AES GCM。

元数据存储（默认）

默认情况下，加密客户端将加密元数据存储在 S3 对象的元数据标头中。对于大多数用例，这是推荐的方法，因为它可以将加密元数据与对象一起保存，并且不需要管理单独的指令文件对象。

require 'aws-sdk-s3'

# Create V3 encryption client with metadata storage (default)
client = Aws::S3::EncryptionV3::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v3_and_legacy,
  commitment_policy: :require_encrypt_allow_decrypt,
  envelope_location: :metadata # Explicitly set to metadata (this is the default)
)

# Encrypt and upload object
# Encryption metadata is stored in the object's metadata headers
client.put_object(bucket: 'my-bucket', key: 'my-object',body: 'secret data')

使用元数据存储时，带密钥承诺的 AES GCM 不适用于加密的数据密钥。但是，使用commitment_policy: :require_encrypt_allow_decrypt或时，内容加密仍然受益于密钥承诺:require_encrypt_require_decrypt。

指令文件存储

或者，您可以将加密客户端配置为将加密元数据存储在名为指令文件的单独的 S3 对象中。在 V3 中使用指令文件时，加密的数据密钥受带密钥承诺的 AES GCM 保护，从而提供额外的安全性，防止数据密钥被篡改。

require 'aws-sdk-s3'

# Create V3 encryption client with instruction file storage
client = Aws::S3::EncryptionV3::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context,
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v3_and_legacy,
  commitment_policy: :require_encrypt_allow_decrypt,
  envelope_location: :instruction_file, # Store metadata in separate instruction file
  instruction_file_suffix: '.instruction' # Optional: customize the suffix (default is '.instruction')
)

# Encrypt and upload object
# Encryption metadata is stored in a separate object: 'my-object.instruction'
client.put_object(bucket: 'my-bucket', key: 'my-object', body: 'secret data')

# When retrieving the object, the client automatically reads the instruction file
resp = client.get_object(bucket: 'my-bucket', key: 'my-object')
decrypted_data = resp.body.read

使用时envelope_location: :instruction_file，加密客户端会创建两个 S3 对象：

该instruction_file_suffix参数允许您自定义用于指令文件的后缀。默认值为 .instruction。

何时使用每种存储方法