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

亚马逊 S3 加密客户端迁移（从 V2 到 V3）

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

迁移概述

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

此迁移分为两个阶段：

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

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

如果您尚未从 V1 迁移到 V2，则必须先完成迁移。亚马逊 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 加密对象的 AWS SDK for Ruby 版本。完成此步骤后，您的应用程序的 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 加密客户端

迁移前 (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

迁移后 (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。

何时使用每种存储方法