Amazon S3 加密客户端迁移 - Amazon SDK对于 Ruby
迁移概述更新现有客户端以读取新格式将加密和解密客户端迁移到 V2
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

Amazon S3 加密客户端迁移

此主题介绍了如何将应用程序从 Amazon Simple Storage Service (Amazon S3) 加密客户端的版本 1 (V1) 迁移到版本 2 (V2)，并确保应用程序在整个迁移过程中的可用性。

迁移概述

此迁移分为两个阶段：

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

2. 将加密和解密客户端迁移到 V2。一旦所有 V1 加密客户端都能读取新格式，就可以将现有加密和解密客户端迁移到各自的 V2 版本。

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

V2 加密客户端使用旧版本客户端不支持的加密算法。迁移的第一步是将 V1 解密客户端更新到最新版本。SDK完成此步骤后，应用程序的 V1 客户端就能够解密由 V2 加密客户端加密的对象。有关 For Ruby 的每个主要版本的 Amazon SDK详细信息，请参阅下文。

Rub Amazon SDK y 版本 3 的更新

版本 3 是 For Ruby 的最新版本。 Amazon SDK要完成此迁移，您需要使用版本 1.76.0 或更高版本的 aws-sdk-s3 Gem。

从命令行安装

对于安装 aws-sdk-s3 Gem 的项目，请使用版本选项来验证是否安装了不低于 1.76.0 的版本。

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

使用 Gemfile

对于使用 Gemfile 管理依赖项的项目，请将 aws-sdk-s3 Gem 的最低版本设置为 1.76.0。例如：

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

  1. 修改 Gemfile。

  2. 运行 bundle update aws-sdk-s3。要验证您的版本，请运行 bundle info aws-sdk-s3。

Ruby 版本 Amazon SDK 2 的更新

Amazon SDK适用于 Ruby 的第 2 版将于 2021 年 11 月 21 日进入维护模式。要完成此迁移，您需要使用版本 2.11.562 或更高版本的 aws-sdk Gem。

从命令行安装

对于安装 aws-sdk Gem 的项目，请从命令行使用版本选项来验证是否安装了不低于 2.11.562 的版本。

gem install aws-sdk -v '>= 2.11.562'

使用 Gemfile

对于使用 Gemfile 管理依赖项的项目，请将 aws-sdk Gem 的最低版本设置为 2.11.562。例如：

gem 'aws-sdk', '>= 2.11.562'

  1. 修改 Gemfile。如果存在 Gemfile.lock 文件，请将其删除或更新。

  2. 运行 bundle update aws-sdk。要验证您的版本，请运行 bundle info aws-sdk。

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

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

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

注意

使用 AES-解密时GCM，在开始使用解密后的数据之前，请将整个对象读到最后。这是为了验证自加密以来是否未对对象进行过修改。

配置 V2 加密客户端

EncryptionV2::Client 需要额外的配置。有关详细的配置信息，请参阅 EncryptionV2::Client 文档或本主题后面提供的示例。

1. 必须在构造客户端时指定密钥包装方法和内容加密算法。在创建新的 EncryptionV2::Client 时，需要为 key_wrap_schema 和 content_encryption_schema 提供值。

key_wrap_schema-如果您正在使用 Amazon KMS，则必须将其设置为:kms_context。如果您使用的是 symmetric (AES) 密钥，则必须将其设置为。:aes_gcm如果您使用的是非对称 (RSA) 密钥，则必须将其设置为。:rsa_oaep_sha1

content_encryption_schema：必须将其设置为 :aes_gcm_no_padding。

2. 必须在构造客户端时指定 security_profile。在创建新的 EncryptionV2::Client 时，需要为 security_profile 提供值。security_profile 参数决定了是否支持读取使用旧版 V1 Encryption::Client 写入的对象。有两个值：:v2 和 :v2_and_legacy。要支持迁移，请将 security_profile 设置为 :v2_and_legacy。:v2 仅适用于新应用程序开发。

3. Amazon KMS key 默认情况下强制使用 ID。在 V1 中Encryption::Client，kms_key_id用于创建客户端的未提供给。 Amazon KMS Decrypt call Amazon KMS 可以从元数据中获取这些信息并将其添加到对称密文 blob 中。在 V2 中，e`nCryptionV2:: Client`，kms_key_id 被传递给 Amazon KMS Decrypt 调用，如果它与用于加密对象的密钥不匹配，则调用将失败。如果代码以前依赖于不设置特定的 kms_key_id，则要么在创建客户端时设置 kms_key_id: :kms_allow_decrypt_with_any_cmk，要么在调用 get_object 时设置 kms_allow_decrypt_with_any_cmk: true。

示例：使用对称 (AES) 密钥

迁移前 

client = Aws::S3::Encryption::Client.new(encryption_key: aes_key)
client.put_object(bucket: bucket, key: key, body: secret_data)
resp = client.get_object(bucket: bucket, key: key)

迁移后 

client = Aws::S3::EncryptionV2::Client.new(
  encryption_key: rsa_key,
  key_wrap_schema: :rsa_oaep_sha1, # the key_wrap_schema must be rsa_oaep_sha1 for asymmetric keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
 )
client.put_object(bucket: bucket, key: key, body: secret_data)  # No changes
resp = client.get_object(bucket: bucket, key: key) # No changes

示例：与 kms_key Amazon KMS _id 一起使用

迁移前 

client = Aws::S3::Encryption::Client.new(kms_key_id: kms_key_id)
client.put_object(bucket: bucket, key: key, body: secret_data)
resp = client.get_object(bucket: bucket, key: key)

迁移后 

client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context, # the key_wrap_schema must be kms_context for KMS keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
)
client.put_object(bucket: bucket, key: key, body: secret_data)  # No changes
resp = client.get_object(bucket: bucket, key: key) # No change

示例：在没有 kms_ke Amazon KMS y_id 的情况下使用

迁移前 

client = Aws::S3::Encryption::Client.new(kms_key_id: kms_key_id)
client.put_object(bucket: bucket, key: key, body: secret_data)
resp = client.get_object(bucket: bucket, key: key)

迁移后 

client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context, # the key_wrap_schema must be kms_context for KMS keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
)
client.put_object(bucket: bucket, key: key, body: secret_data)  # No changes
resp = client.get_object(bucket: bucket, key: key, kms_allow_decrypt_with_any_cmk: true) # To allow decrypting with any cmk

迁移后替代方案

如果仅使用 S2 加密客户端读取和解密（从不写入和加密）对象，请使用此代码。

client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: :kms_allow_decrypt_with_any_cmk, # set kms_key_id to allow all get_object requests to use any cmk
  key_wrap_schema: :kms_context, # the key_wrap_schema must be kms_context for KMS keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
)
resp = client.get_object(bucket: bucket, key: key) # No change