View a markdown version of this page

Migration du client de chiffrement Amazon S3 (V1 vers V2) - AWS Kit SDK pour Ruby
Aperçu de la migrationMettre à jour les clients existants pour lire les nouveaux formatsMigrer les clients de chiffrement et de déchiffrement vers la version V2

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Migration du client de chiffrement Amazon S3 (V1 vers V2)

Note

Si vous utilisez la version V2 du client de chiffrement S3 et que vous souhaitez migrer vers la version V3, consultezMigration du client de chiffrement Amazon S3 (V2 vers V3).

Cette rubrique explique comment migrer vos applications de la version 1 (V1) du client de chiffrement Amazon Simple Storage Service (Amazon S3) vers la version 2 (V2) et garantir la disponibilité des applications tout au long du processus de migration.

Aperçu de la migration

Cette migration s'effectue en deux phases :

1. Mettez à jour les clients existants pour qu'ils puissent lire les nouveaux formats. Commencez par déployer une version mise à jour du AWS SDK pour Ruby dans votre application. Cela permettra aux clients de chiffrement V1 existants de déchiffrer les objets écrits par les nouveaux clients V2. Si votre application utilise plusieurs AWS kits de développement logiciel, vous devez les mettre à niveau séparément.

2. Migrez les clients de chiffrement et de déchiffrement vers la V2. Une fois que tous vos clients de chiffrement V1 peuvent lire les nouveaux formats, vous pouvez migrer vos clients de chiffrement et de déchiffrement existants vers leurs versions V2 respectives.

Mettre à jour les clients existants pour lire les nouveaux formats

Le client de chiffrement V2 utilise des algorithmes de chiffrement que les anciennes versions du client ne prenaient pas en charge. La première étape de la migration consiste à mettre à jour vos clients de déchiffrement V1 vers la dernière version du SDK. Une fois cette étape terminée, les clients V1 de votre application seront en mesure de déchiffrer les objets chiffrés par les clients de chiffrement V2. Consultez les détails ci-dessous pour chaque version majeure du AWS SDK pour Ruby.

Mettre à jour AWS SDK pour Ruby version 3

La version 3 est la dernière version du AWS SDK pour Ruby. Pour effectuer cette migration, vous devez utiliser la version 1.76.0 ou ultérieure de la aws-sdk-s3 gemme.

Installation depuis la ligne de commande

Pour les projets qui installent la aws-sdk-s3 gem, utilisez l'option de version pour vérifier que la version minimale de 1.76.0 est installée.

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

Utilisation de Gemfiles

Pour les projets qui utilisent un Gemfile pour gérer les dépendances, définissez la version minimale du aws-sdk-s3 gem sur 1.76.0. Par exemple :

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

  1. Modifiez votre Gemfile.

  2. Exécutez bundle update aws-sdk-s3. Pour vérifier votre version, exécutezbundle info aws-sdk-s3.

Upgrade AWS SDK pour Ruby version 2

La version 2 du AWS SDK pour Ruby entrera en mode maintenance le 21 novembre 2021. Pour effectuer cette migration, vous devez utiliser la version 2.11.562 ou ultérieure de la gem aws-sdk.

Installation depuis la ligne de commande

Pour les projets qui installent la aws-sdk gem, depuis la ligne de commande, utilisez l'option de version pour vérifier que la version minimale de 2.11.562 est installée.

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

Utilisation de Gemfiles

Pour les projets qui utilisent un Gemfile pour gérer les dépendances, définissez la version minimale du aws-sdk gem sur 2.11.562. Par exemple :

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

  1. Modifiez votre Gemfile. Si vous possédez un Gemfile.lock fichier, supprimez-le ou mettez-le à jour.

  2. Exécutez bundle update aws-sdk. Pour vérifier votre version, exécutezbundle info aws-sdk.

Migrer les clients de chiffrement et de déchiffrement vers la version V2

Après avoir mis à jour vos clients pour qu'ils puissent lire les nouveaux formats de chiffrement, vous pouvez mettre à jour vos applications vers les clients de chiffrement et de déchiffrement V2. Les étapes suivantes vous montrent comment réussir la migration de votre code de la V1 vers la V2.

Avant de mettre à jour votre code pour utiliser le client de chiffrement V2, assurez-vous d'avoir suivi les étapes précédentes et que vous utilisez la version 2.11.562 ou ultérieure de aws-sdk-s3 gem.

Note

Lors du déchiffrement avec AES-GCM, lisez l'objet entier jusqu'à la fin avant de commencer à utiliser les données déchiffrées. Cela permet de vérifier que l'objet n'a pas été modifié depuis qu'il a été chiffré.

Configuration des clients de chiffrement V2

Le EncryptionV2 : :Client nécessite une configuration supplémentaire. Pour obtenir des informations de configuration détaillées, consultez la documentation EncryptionV2 : :Client ou les exemples fournis plus loin dans cette rubrique.

1. La méthode d'encapsulation des clés et l'algorithme de chiffrement du contenu doivent être spécifiés lors de la construction du client. Lorsque vous créez un nouveauEncryptionV2::Client, vous devez fournir des valeurs pour key_wrap_schema etcontent_encryption_schema.

key_wrap_schema- Si vous utilisez AWS KMS, ce paramètre doit être réglé sur:kms_context. Si vous utilisez une clé symétrique (AES), celle-ci doit être réglée sur. :aes_gcm Si vous utilisez une touche asymétrique (RSA), celle-ci doit être réglée sur. :rsa_oaep_sha1

content_encryption_schema- Ce paramètre doit être défini sur:aes_gcm_no_padding.

2. security_profile doit être spécifié lors de la construction du client. Lorsque vous créez un nouveauEncryptionV2::Client, vous devez fournir une valeur poursecurity_profile. Le paramètre security_profile détermine la prise en charge de la lecture d'objets écrits à l'aide de l'ancienne version V1. Encryption::Client Il existe deux valeurs ::v2 et:v2_and_legacy. Pour prendre en charge la migration, définissez le paramètre security_profile to:v2_and_legacy. Utilisez:v2 uniquement pour le développement de nouvelles applications.

3. AWS KMS key L'ID est appliqué par défaut. Dans la V1Encryption::Client, le kms_key_id code utilisé pour créer le client n'était pas fourni au AWS KMS Decrypt call. AWS KMS peut obtenir ces informations à partir de métadonnées et les ajouter au blob de texte chiffré symétrique. Dans la V2, E`NcryptionV2 : :Client`, le kms_key_id est transmis à l'appel AWS KMS Decrypt, et l'appel échoue s'il ne correspond pas à la clé utilisée pour crypter l'objet. Si votre code reposait auparavant sur l'absence d'un paramètre spécifiquekms_key_id, définissez-le kms_key_id: :kms_allow_decrypt_with_any_cmk sur la création du client ou kms_allow_decrypt_with_any_cmk: true sur les get_object appels.

Exemple : utilisation d'une clé symétrique (AES)

Pre-migration 

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)

Post-migration 

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

Exemple : utilisation AWS KMS avec kms_key_id

Pre-migration 

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)

Post-migration 

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

Exemple : utilisation AWS KMS sans kms_key_id

Pre-migration 

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)

Post-migration 

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

Post-Migration Alternative

Si vous lisez et déchiffrez uniquement (jamais écrivez ni chiffrez) des objets à l'aide du client de chiffrement S2, utilisez ce code.

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