Amazon S3 加密客户端迁移 - 适用于 Ruby 的 AWS 开发工具包
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

Amazon S3 加密客户端迁移

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

迁移概述

此迁移过程分为两个阶段:

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

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

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

V2 加密客户端使用客户端的旧版本不支持的加密算法。迁移的第一步是将 V1 解密客户端更新为最新的 SDK 版本。完成此步骤后,您的应用程序的 V1 客户端将能够解密由 V2 加密客户端加密的对象。请参阅以下有关每个适用于 Ruby 的 AWS 开发工具包主要版本的详细信息。

更新适用于 Ruby 的 AWS 开发工具包版本 3

版本 3 是适用于 Ruby 的 AWS 开发工具包的最新版本。要完成此迁移,您需要使用版本 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 的 AWS 开发工具包版本 2

适用于 Ruby 的 AWS 开发工具包的版本 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 加密客户端

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

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

key_wrap_schema - 如果您使用的是 AWS KMS,则必须将其设置为 :kms_context。 如果您使用的是对称 (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. 默认情况下,将强制执行 AWS KMS CMK ID。 在 V1 中,Encryption::Client,用于创建客户端的 kms_key_id 未提供给 AWS KMS Decrypt call。 AWS KMS 可以从元数据获取此信息,并将其添加到对称密文 blob 中。在 V2 中,E`ncryptionV2::Client`,kms_key_id 将传递给 AWS KMS Decrypt 调用,如果调用与用于加密对象的密钥不匹配,则调用将失败。如果您的代码以前依赖的是不设置特定的 kms_key_id,请在创建客户端时设置 kms_key_id: :kms_allow_decrypt_with_any_cmk 或在 kms_allow_decrypt_with_any_cmk: true 调用中设置 get_object

示例:使用对称 (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

示例:将 AWS KMS 与 kms_key_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_key_id 的 AWS KMS

迁移前

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