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 de votre AWS Encryption SDK
Il AWS Encryption SDK prend en charge plusieurs [implémentations de langages de programmation](programming-languages.md) interopérables, chacune étant développée dans un référentiel open source sur. GitHub À titre de [bonne pratique](best-practices.md), nous vous recommandons d'utiliser la dernière version du AWS Encryption SDK pour chaque langue.
Vous pouvez effectuer une mise à niveau en toute sécurité à partir de la version 2.0. *x* ou version ultérieure ou AWS Encryption SDK vers la dernière version. Cependant, le 2.0. La version *x* AWS Encryption SDK introduit de nouvelles fonctionnalités de sécurité importantes, dont certaines sont des modifications majeures. Pour effectuer une mise à niveau à partir de versions antérieures à 1.7. *x* vers les versions 2.0. *x* et versions ultérieures, vous devez d'abord passer à la dernière version 1. version *x.* Les rubriques de cette section sont conçues pour vous aider à comprendre les modifications, à sélectionner la version appropriée pour votre application et à migrer en toute sécurité et avec succès vers les dernières versions du AWS Encryption SDK.
Pour plus d'informations sur les versions importantes du AWS Encryption SDK, voir[Versions du AWS Encryption SDK](about-versions.md).
**Important**
Ne procédez pas à une mise à niveau directe à partir d'une version antérieure à 1.7. *x* vers la version 2.0. *x* ou version ultérieure sans mise à niveau préalable vers la dernière version 1. version *x.* Si vous passez directement à la version 2.0. *x* ou version ultérieure et activez immédiatement toutes les nouvelles fonctionnalités, ils AWS Encryption SDK ne seront pas en mesure de déchiffrer le texte chiffré sous les anciennes versions du. AWS Encryption SDK
**Note**
La version la plus ancienne de AWS Encryption SDK pour .NET est la version 3.0. *x.* Toutes les versions de AWS Encryption SDK for .NET prennent en charge les meilleures pratiques de sécurité introduites dans la version 2.0. *x* du AWS Encryption SDK. Vous pouvez passer à la dernière version en toute sécurité sans aucune modification de code ou de données.
AWS CLI de chiffrement : lors de la lecture de ce guide de migration, utilisez la version 1.7. *x* instructions de migration pour AWS Encryption CLI 1.8. *x* et utilisez le 2.0. *x* instructions de migration pour AWS Encryption CLI 2.1. *x.* Pour en savoir plus, consultez [Versions de la CLI AWS de chiffrement](crypto-cli-versions.md).
Les nouvelles fonctionnalités de sécurité ont été initialement publiées dans les versions 1.7 de la CLI de AWS chiffrement. *x* et 2.0. *x.* Cependant, AWS Encryption CLI version 1.8. *x* remplace la version 1.7. *x* et CLI de AWS chiffrement 2.1. *x* remplace 2.0. *x.* Pour plus de détails, consultez l'[avis de sécurité](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondant dans le [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)référentiel sur GitHub.
**Nouveaux utilisateurs**
Si vous ne connaissez pas le AWS Encryption SDK, installez la dernière version du AWS Encryption SDK pour votre langage de programmation. Les valeurs par défaut activent toutes les fonctionnalités de sécurité du AWS Encryption SDK, y compris le chiffrement avec signature, la dérivation des [clés et l'engagement](concepts.md#key-commitment) des clés. AWS Encryption SDK
**Utilisateurs actuels**
Nous vous recommandons de passer de votre version actuelle à la dernière version disponible dès que possible. Tous les 1. Les versions *x* du AWS Encryption SDK sont en [end-of-support cours de phase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), tout comme les versions ultérieures dans certains langages de programmation. Pour plus de détails sur l'état de support et de maintenance du AWS Encryption SDK dans votre langage de programmation, consultez[Support et maintenance](introduction.md#support).
AWS Encryption SDK versions 2.0. *x* et versions ultérieures fournissent de nouvelles fonctionnalités de sécurité pour protéger vos données. Cependant, AWS Encryption SDK la version 2.0. *x* inclut les modifications majeures qui ne sont pas rétrocompatibles. Pour garantir une transition en toute sécurité, commencez par migrer de votre version actuelle vers la dernière version 1. *x* dans votre langage de programmation. Lorsque votre dernier 1. La version *x* est entièrement déployée et fonctionne correctement, vous pouvez migrer en toute sécurité vers les versions 2.0. *x* et versions ultérieures. Ce [processus en deux étapes](migration-guide.md) est essentiel, en particulier pour les applications distribuées.
*Pour plus d'informations sur les fonctionnalités AWS Encryption SDK de sécurité qui sous-tendent ces modifications, consultez la section [Amélioration du chiffrement côté client : engagement explicite KeyIds et clé](https://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/) dans le blog sur la AWS sécurité.*
Vous avez besoin d'aide pour utiliser le Kit SDK de chiffrement AWS pour Java avec le AWS SDK for Java 2.x ? Consultez [Conditions préalables](java.md#java-prerequisites).
**Topics**
+ [Comment migrer et déployer le AWS Encryption SDK](migration-guide.md)
+ [Mise à jour des fournisseurs de clés AWS KMS principales](migrate-mkps-v2.md)
+ [Mise à jour des AWS KMS porte-clés](migrate-keyrings-v2.md)
+ [Définition de votre politique d'engagement](migrate-commitment-policy.md)
+ [Résolution des problèmes liés à la migration vers les dernières versions](troubleshooting-migration.md)
# Comment migrer et déployer le AWS Encryption SDK
Lors de la migration depuis une AWS Encryption SDK version antérieure à 1.7. *x* vers la version 2.0. *x* ou version ultérieure, vous devez passer en toute sécurité au chiffrement avec [engagement clé](concepts.md#key-commitment). Dans le cas contraire, votre application rencontrera des textes chiffrés qu'elle ne pourra pas déchiffrer. Si vous utilisez des fournisseurs de clés AWS KMS principales, vous devez passer à de nouveaux constructeurs qui créent des fournisseurs de clés principales en mode strict ou en mode découverte.
**Note**
Cette rubrique est destinée aux utilisateurs qui migrent des versions antérieures de la version 2.0 AWS Encryption SDK vers la version 2.0. *x* ou version ultérieure. Si vous débutez avec le AWS Encryption SDK, vous pouvez commencer à utiliser la dernière version disponible immédiatement avec les paramètres par défaut.
Pour éviter une situation critique dans laquelle vous ne pouvez pas déchiffrer le texte chiffré que vous devez lire, nous vous recommandons de procéder à la migration et au déploiement en plusieurs étapes distinctes. Vérifiez que chaque étape est terminée et entièrement déployée avant de passer à l'étape suivante. Cela est particulièrement important pour les applications distribuées comportant plusieurs hôtes.
## Étape 1 : Mettez à jour votre application avec la dernière version 1. version *x*
Mise à jour vers la dernière version 1. version *x* pour votre langage de programmation. Testez soigneusement, déployez vos modifications et vérifiez que la mise à jour s'est propagée à tous les hôtes de destination avant de commencer l'étape 2.
**Important**
Vérifiez que votre dernier 1. La version *x* est la version 1.7. *x* ou une version ultérieure du AWS Encryption SDK.
Le dernier 1. Les versions *x* du AWS Encryption SDK sont rétrocompatibles avec les anciennes versions du AWS Encryption SDK et rétrocompatibles avec les versions 2.0. *x* et versions ultérieures. Ils incluent les nouvelles fonctionnalités présentes dans la version 2.0. *x*, mais incluez les valeurs par défaut sécurisées conçues pour cette migration. Ils vous permettent de mettre à niveau vos fournisseurs de clés AWS KMS principales, si nécessaire, et de les déployer entièrement avec des suites d'algorithmes capables de déchiffrer le texte chiffré avec un engagement clé.
+ Remplacez les éléments obsolètes, y compris les constructeurs des anciens fournisseurs de clés AWS KMS principales. En [Python](https://docs.python.org/3/library/warnings.html), veillez à activer les avertissements d'obsolescence. Éléments de code déconseillés dans la dernière version 1. les versions *x* sont supprimées des versions 2.0. *x* et versions ultérieures.
+ Définissez explicitement votre politique d'engagement sur`ForbidEncryptAllowDecrypt`. Bien que ce soit la seule valeur valide dans le dernier 1. *x* versions, ce paramètre est obligatoire lorsque vous utilisez le paramètre APIs introduit dans cette version. Cela empêche votre application de rejeter le texte chiffré sans engagement de clé lors de la migration vers la version 2.0. *x* et versions ultérieures. Pour en savoir plus, consultez [Définition de votre politique d'engagement](migrate-commitment-policy.md).
+ Si vous utilisez des fournisseurs de clés AWS KMS principales, vous devez mettre à jour vos anciens fournisseurs de clés principales pour qu'ils prennent en charge le *mode strict* et le *mode découverte*. Cette mise à jour est requise pour le Kit SDK de chiffrement AWS pour Java Kit SDK de chiffrement AWS pour Python, et la CLI de AWS chiffrement. Si vous utilisez des fournisseurs de clés principales en mode découverte, nous vous recommandons d'implémenter le filtre de découverte qui limite les clés d'encapsulation utilisées à ces fournisseurs en particulier Comptes AWS. Cette mise à jour est facultative, mais c'est une [bonne pratique](best-practices.md) que nous recommandons. Pour en savoir plus, consultez [Mise à jour des fournisseurs de clés AWS KMS principales](migrate-mkps-v2.md).
+ Si vous utilisez des [trousseaux de AWS KMS découverte](use-kms-keyring.md#kms-keyring-discovery), nous vous recommandons d'inclure un filtre de découverte qui limite les clés d'encapsulage utilisées pour le déchiffrement à celles-ci en particulier. Comptes AWS Cette mise à jour est facultative, mais c'est une [bonne pratique](best-practices.md) que nous recommandons. Pour en savoir plus, consultez [Mise à jour des AWS KMS porte-clés](migrate-keyrings-v2.md).
## Étape 2 : mettez à jour votre application avec la dernière version
Après avoir déployé le dernier 1. version *x* avec succès sur tous les hôtes, vous pouvez passer à la version 2.0. *x* et versions ultérieures. La version 2.0. *x* inclut les modifications majeures apportées à toutes les versions antérieures du AWS Encryption SDK. Toutefois, si vous apportez les modifications de code recommandées à l'étape 1, vous pouvez éviter les erreurs lors de la migration vers la dernière version.
Avant de passer à la dernière version, vérifiez que votre politique d'engagement est toujours définie sur`ForbidEncryptAllowDecrypt`. Ensuite, en fonction de la configuration de vos données, vous pouvez migrer à votre propre rythme vers `RequireEncryptAllowDecrypt` puis vers le paramètre par défaut,`RequireEncryptRequireDecrypt`. Nous recommandons une série d'étapes de transition comme le modèle suivant.
1. Commencez par définir votre [politique d'engagement](migrate-commitment-policy.md) sur`ForbidEncryptAllowDecrypt`. Il AWS Encryption SDK peut déchiffrer les messages avec un engagement clé, mais il ne le fait pas encore avec un engagement clé.
1. Lorsque vous êtes prêt, mettez à jour votre politique d'engagement à`RequireEncryptAllowDecrypt`. Le chiffrement de vos données AWS Encryption SDK commence par un [engagement clé](concepts.md#key-commitment). Il peut déchiffrer le texte chiffré avec et sans engagement clé.
Avant de mettre à jour votre politique d'engagement en`RequireEncryptAllowDecrypt`, vérifiez que votre dernière version 1. La version *x* est déployée sur tous les hôtes, y compris les hôtes de toutes les applications qui déchiffrent le texte chiffré que vous produisez. Versions AWS Encryption SDK antérieures à la version 1.7. *x* ne peut pas déchiffrer les messages chiffrés avec clé d'engagement.
C'est également le bon moment pour ajouter des métriques à votre application afin de déterminer si vous traitez toujours du texte chiffré sans engagement clé. Cela vous aidera à déterminer à quel moment vous pouvez mettre à jour les paramètres de votre politique d'engagement en toute sécurité`RequireEncryptRequireDecrypt`. Pour certaines applications, telles que celles qui chiffrent des messages dans une file d'attente Amazon SQS, cela peut impliquer d'attendre suffisamment longtemps pour que tout le texte chiffré sous les anciennes versions soit rechiffré ou supprimé. Pour les autres applications, telles que les objets S3 chiffrés, vous devrez peut-être télécharger, rechiffrer et charger à nouveau tous les objets.
1. Lorsque vous êtes certain qu'aucun message n'est crypté sans clé d'engagement, vous pouvez mettre à jour votre politique d'engagement en`RequireEncryptRequireDecrypt`. Cette valeur garantit que vos données sont toujours cryptées et déchiffrées avec un engagement clé. Il s'agit du paramètre par défaut, vous n'êtes donc pas obligé de le définir explicitement, mais nous vous le recommandons. Un paramètre explicite [facilitera le débogage](troubleshooting-migration.md) et les éventuelles annulations qui pourraient être nécessaires si votre application détecte du texte chiffré sans engagement de clé.
# Mise à jour des fournisseurs de clés AWS KMS principales
Pour migrer vers la dernière version 1. version *x* du AWS Encryption SDK, puis vers la version 2.0. *x* ou version ultérieure, vous devez remplacer les anciens fournisseurs de clés AWS KMS principales par des fournisseurs de clés principales créés explicitement en [*mode strict* ou en *mode découverte*](about-versions.md#changes-to-mkps). Les anciens fournisseurs de clés principales sont obsolètes dans la version 1.7. *x* et supprimé dans la version 2.0. *x.* Cette modification est requise pour les applications et les scripts qui utilisent le [Kit SDK de chiffrement AWS pour Java[Kit SDK de chiffrement AWS pour Python](python.md)](java.md), et la [CLI de AWS chiffrement](crypto-cli.md). Les exemples présentés dans cette section vous montreront comment mettre à jour votre code.
**Note**
En Python, [activez les avertissements d'obsolescence.](https://docs.python.org/3/library/warnings.html) Cela vous aidera à identifier les parties de votre code que vous devez mettre à jour.
Si vous utilisez une clé AWS KMS principale (et non un fournisseur de clé principale), vous pouvez ignorer cette étape. AWS KMS les clés principales ne sont ni déconseillées ni supprimées. Ils chiffrent et déchiffrent uniquement avec les clés d'encapsulation que vous spécifiez.
Les exemples de cette section se concentrent sur les éléments de votre code que vous devez modifier. Pour un exemple complet du code mis à jour, consultez la section Exemples du GitHub référentiel de votre [langage de programmation](programming-languages.md). De plus, ces exemples utilisent généralement une clé ARNs pour représenter AWS KMS keys. Lorsque vous créez un fournisseur de clé principale pour le chiffrement, vous pouvez utiliser n'importe quel [identifiant de AWS KMS clé](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) valide pour représenter un AWS KMS key . Lorsque vous créez un fournisseur de clé principale pour le déchiffrement, vous devez utiliser un ARN de clé.
**En savoir plus sur la migration**
Pour tous les AWS Encryption SDK utilisateurs, découvrez comment définir votre politique d'engagement dans[Définition de votre politique d'engagement](migrate-commitment-policy.md).
Pour les Kit SDK de chiffrement AWS pour JavaScript utilisateurs Kit SDK de chiffrement AWS pour C et les utilisateurs, découvrez une mise à jour facultative des trousseaux de clés. [Mise à jour des AWS KMS porte-clés](migrate-keyrings-v2.md)
**Topics**
+ [Migration vers le mode strict](#migrate-mkp-strict-mode)
+ [Migration vers le mode découverte](#migrate-mkp-discovery-mode)
## Migration vers le mode strict
Après la mise à jour vers la dernière version 1. version *x* du AWS Encryption SDK, remplacez vos anciens fournisseurs de clés principales par des fournisseurs de clés principales en mode strict. En mode strict, vous devez spécifier les clés d'encapsulation à utiliser lors du chiffrement et du déchiffrement. AWS Encryption SDK Utilise uniquement les clés d'encapsulation que vous spécifiez. Les fournisseurs de clés principales obsolètes peuvent déchiffrer les données à l'aide de n'importe quelle AWS KMS key clé de données chiffrée, y compris AWS KMS keys dans différentes Comptes AWS régions et régions.
Les fournisseurs de clés principales en mode strict sont introduits dans la AWS Encryption SDK version 1.7. *x.* Ils remplacent les anciens fournisseurs de clés principales, qui sont obsolètes dans la version 1.7. *x* et supprimé dans la version 2.0. *x.* L'utilisation de fournisseurs de clés principales en mode strict est une AWS Encryption SDK [bonne pratique](best-practices.md).
Le code suivant crée un fournisseur de clé principale en mode strict que vous pouvez utiliser pour le chiffrement et le déchiffrement.
------
#### [ Java ]
Cet exemple représente le code d'une application qui utilise la version 1.6.2 ou antérieure du Kit SDK de chiffrement AWS pour Java.
Ce code utilise la `KmsMasterKeyProvider.builder()` méthode pour instancier un fournisseur de clé AWS KMS principale qui en utilise une AWS KMS key comme clé d'encapsulation.
```
// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.withKeysForEncryption(awsKmsKey)
.build();
```
Cet exemple représente le code d'une application qui utilise la version 1.7. *x* ou une version ultérieure du Kit SDK de chiffrement AWS pour Java . Pour un exemple complet, consultez [BasicEncryptionExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)
Les `Builder.withKeysForEncryption()` méthodes `Builder.build()` et utilisées dans l'exemple précédent sont obsolètes dans la version 1.7. *x* et sont supprimés de la version 2.0. *x.*
Pour passer à un fournisseur de clé principale en mode strict, ce code remplace les appels aux méthodes obsolètes par un appel à la nouvelle `Builder.buildStrict()` méthode. Cet exemple en spécifie une AWS KMS key comme clé d'encapsulation, mais la `Builder.buildStrict()` méthode peut prendre une liste de plusieurs AWS KMS keys.
```
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your Compte AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
```
------
#### [ Python ]
Cet exemple représente le code d'une application qui utilise la version 1.4.1 du Kit SDK de chiffrement AWS pour Python. Ce code utilise`KMSMasterKeyProvider`, ce qui est obsolète dans la version 1.7. *x* et supprimé de la version 2.0. *x.* Lors du déchiffrement, il utilise toute clé de données chiffrée indépendamment de AWS KMS key celle que vous spécifiez AWS KMS keys .
Notez que cela n'`KMSMasterKey`est ni obsolète ni supprimé. Lors du chiffrement et du déchiffrement, il utilise uniquement ce que vous spécifiez. AWS KMS key
```
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
Cet exemple représente le code d'une application qui utilise la version 1.7. *x* du Kit SDK de chiffrement AWS pour Python. Pour un exemple complet, consultez le [fichier basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py).
Pour passer à un fournisseur de clé principale en mode strict, ce code remplace l'appel `KMSMasterKeyProvider()` à par un appel à`StrictAwsKmsMasterKeyProvider()`.
```
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your Compte AWS
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
------
#### [ AWS Encryption CLI ]
Cet exemple montre comment chiffrer et déchiffrer à l'aide de la AWS CLI de chiffrement version 1.1.7 ou antérieure.
Dans les versions 1.1.7 et antérieures, lors du chiffrement, vous spécifiez une ou plusieurs clés principales (ou *clés d'encapsulation*), telles qu'un. AWS KMS key Lors du déchiffrement, vous ne pouvez spécifier aucune clé d'encapsulation sauf si vous utilisez un fournisseur de clé principale personnalisé. La CLI de AWS chiffrement peut utiliser n'importe quelle clé d'encapsulation qui a chiffré une clé de données.
```
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
Cet exemple montre comment chiffrer et déchiffrer à l'aide de la AWS CLI de chiffrement version 1.7. *x* ou version ultérieure. Pour des exemples complets, voir[Exemples de CLI AWS de chiffrement](crypto-cli-examples.md).
Le `--master-keys` paramètre est obsolète dans la version 1.7. *x* et supprimé dans la version 2.0. *x.* Il a remplacé le `--wrapping-keys` paramètre by, qui est obligatoire dans les commandes de chiffrement et de déchiffrement. Ce paramètre prend en charge le mode strict et le mode découverte. Le mode strict est une AWS Encryption SDK bonne pratique qui garantit que vous utilisez la clé d'encapsulation comme vous le souhaitez.
Pour passer *en mode strict*, utilisez l'attribut **key** du `--wrapping-keys` paramètre pour spécifier une clé d'encapsulation lors du chiffrement et du déchiffrement.
```
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
## Migration vers le mode découverte
À partir de la version 1.7. *x*, il est recommandé d' AWS Encryption SDK [utiliser le](best-practices.md) *mode strict* pour les fournisseurs de clés AWS KMS principales, c'est-à-dire de spécifier les clés d'encapsulage lors du chiffrement et du déchiffrement. Vous devez toujours spécifier les clés d'encapsulage lors du chiffrement. Mais il existe des situations dans lesquelles il n'est pas pratique ARNs de spécifier la clé de AWS KMS keys pour le déchiffrement. Par exemple, si vous utilisez des alias pour vous identifier AWS KMS keys lors du chiffrement, vous perdez l'avantage des alias si vous devez répertorier les clés ARNs lors du déchiffrement. En outre, étant donné que les fournisseurs de clés principales en mode découverte se comportent comme les fournisseurs de clés principales d'origine, vous pouvez les utiliser temporairement dans le cadre de votre stratégie de migration, puis passer ultérieurement à des fournisseurs de clés principales en mode strict.
Dans de tels cas, vous pouvez utiliser des fournisseurs de clés principales en *mode découverte*. Ces fournisseurs de clés principales ne vous permettent pas de spécifier des clés d'encapsulage, vous ne pouvez donc pas les utiliser pour le chiffrement. Lors du déchiffrement, ils peuvent utiliser n'importe quelle clé d'encapsulation qui a chiffré une clé de données. Mais contrairement aux anciens fournisseurs de clés principales, qui se comportent de la même manière, vous les créez explicitement en mode découverte. Lorsque vous utilisez des fournisseurs de clés principales en mode découverte, vous pouvez limiter le nombre de clés d'encapsulage pouvant être utilisées à ceux-ci en particulier Comptes AWS. Ce filtre de découverte est facultatif, mais c'est une bonne pratique que nous recommandons. Pour plus d'informations sur AWS les partitions et les comptes, consultez [Amazon Resource Names](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax) dans le *Références générales AWS*.
Les exemples suivants créent un fournisseur de clé AWS KMS principale en mode strict pour le chiffrement et un fournisseur de clé AWS KMS principale en mode découverte pour le déchiffrement. Le fournisseur de clés principales en mode découverte utilise un filtre de découverte pour limiter les clés d'encapsulation utilisées pour le déchiffrement sur la `aws` partition et pour un exemple particulier. Comptes AWS Bien que le filtre de compte ne soit pas nécessaire dans cet exemple très simple, il s'agit d'une bonne pratique très avantageuse lorsqu'une application chiffre des données et qu'une autre application les déchiffre.
------
#### [ Java ]
Cet exemple représente le code d'une application qui utilise la version 1.7. *x* ou une version ultérieure du Kit SDK de chiffrement AWS pour Java. Pour un exemple complet, consultez [DiscoveryDecryptionExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/)
Pour instancier un fournisseur de clé principale en mode strict à des fins de chiffrement, cet exemple utilise la méthode. `Builder.buildStrict()` Pour instancier un fournisseur de clé principale en mode découverte à des fins de déchiffrement, il utilise la méthode. `Builder.buildDiscovery()` La `Builder.buildDiscovery()` méthode prend un `DiscoveryFilter` qui limite le AWS Encryption SDK à AWS KMS keys dans la AWS partition et les comptes spécifiés.
```
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your Compte AWS.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildDiscovery(accounts);
```
------
#### [ Python ]
Cet exemple représente le code d'une application qui utilise la version 1.7. *x* ou une version ultérieure du Kit SDK de chiffrement AWS pour Python . Pour un exemple complet, consultez le [fichier discovery\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py).
Pour créer un fournisseur de clé principale en mode strict pour le chiffrement, cet exemple utilise`StrictAwsKmsMasterKeyProvider`. Pour créer un fournisseur de clé principale en mode découverte à des fins de déchiffrement, il l'utilise `DiscoveryAwsKmsMasterKeyProvider` avec un `DiscoveryFilter` qui limite le AWS Encryption SDK à AWS KMS keys dans la AWS partition et les comptes spécifiés.
```
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your Compte AWS.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts
)
```
------
#### [ AWS Encryption CLI ]
Cet exemple montre comment chiffrer et déchiffrer à l'aide de la AWS CLI de chiffrement version 1.7. *x* ou version ultérieure. À partir de la version 1.7. *x*, le `--wrapping-keys` paramètre est obligatoire lors du chiffrement et du déchiffrement. Le `--wrapping-keys` paramètre prend en charge le mode strict et le mode découverte. Pour des exemples complets, voir[Exemples de CLI AWS de chiffrement](crypto-cli-examples.md).
Lors du chiffrement, cet exemple indique une clé d'encapsulation, qui est obligatoire. Lors du déchiffrement, il choisit explicitement le *mode de découverte* en utilisant l'`discovery`attribut du `--wrapping-keys` paramètre avec une valeur de. `true`
Pour limiter les clés d'encapsulation qu'ils AWS Encryption SDK peuvent utiliser en mode découverte à celles en particulier Comptes AWS, cet exemple utilise les `discovery-account` attributs `discovery-partition` et du `--wrapping-keys` paramètre. Ces attributs facultatifs ne sont valides que lorsque l'`discovery`attribut est défini sur`true`. Vous devez utiliser les `discovery-account` attributs `discovery-partition` et ensemble ; aucun des deux n'est valide seul.
```
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
# Mise à jour des AWS KMS porte-clés
Les AWS KMS trousseaux de clés contenus dans [Kit SDK de chiffrement AWS pour C](c-language.md), [AWS Encryption SDK pour .NET](dot-net.md) et dans le cadre du [Kit SDK de chiffrement AWS pour JavaScript](javascript.md)support prennent en charge les [meilleures pratiques](best-practices.md) en vous permettant de spécifier des clés d'encapsulage lors du chiffrement et du déchiffrement. Si vous créez un trousseau de [clés de AWS KMS découverte](use-kms-keyring.md#kms-keyring-discovery), vous le faites explicitement.
**Note**
La version la plus ancienne de AWS Encryption SDK pour .NET est la version 3.0. *x.* Toutes les versions de AWS Encryption SDK for .NET respectent les meilleures pratiques de sécurité introduites dans la version 2.0. *x* du AWS Encryption SDK. Vous pouvez passer à la dernière version en toute sécurité sans aucune modification de code ou de données.
Lorsque vous effectuez une mise à jour vers la dernière version 1. version *x* du AWS Encryption SDK, vous pouvez utiliser un [filtre de découverte](use-kms-keyring.md#kms-keyring-discovery) pour limiter les clés d'encapsulation utilisées par un jeu de clés de [AWS KMS découverte ou un trousseau](use-kms-keyring.md#kms-keyring-discovery) de [clés de découverte AWS KMS régional](use-kms-keyring.md#kms-keyring-regional) lors du déchiffrement vers celles-ci en particulier. Comptes AWS Le filtrage d'un trousseau de clés de découverte est une AWS Encryption SDK [bonne pratique](best-practices.md).
Les exemples présentés dans cette section vous montrent comment ajouter le filtre de découverte à un trousseau de clés de découverte AWS KMS régional.
**En savoir plus sur la migration**
Pour tous les AWS Encryption SDK utilisateurs, découvrez comment définir votre politique d'engagement dans[Définition de votre politique d'engagement](migrate-commitment-policy.md).
Pour Kit SDK de chiffrement AWS pour Java Kit SDK de chiffrement AWS pour Python, et les utilisateurs de la CLI de AWS chiffrement, découvrez une mise à jour requise pour les fournisseurs de clés principales dans[Mise à jour des fournisseurs de clés AWS KMS principales](migrate-mkps-v2.md).
Il se peut que votre application comporte un code tel que celui-ci. Cet exemple crée un jeu de clés de découverte AWS KMS régional qui ne peut utiliser des clés d'encapsulage que dans la région USA Ouest (Oregon) (us-west-2). Cet exemple représente le code des AWS Encryption SDK versions antérieures à 1.7. *x.* Cependant, il est toujours valide dans les versions 1.7. *x* et versions ultérieures.
------
#### [ C ]
```
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
```
------
#### [ JavaScript Node.js ]
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })
```
------
À partir de la version 1.7. *x*, vous pouvez ajouter un filtre de découverte à n'importe quel trousseau de clés de AWS KMS découverte. Ce filtre de découverte limite ce AWS KMS keys qu'ils AWS Encryption SDK peuvent utiliser pour le déchiffrement à ceux de la partition et des comptes spécifiés. Avant d'utiliser ce code, modifiez la partition, si nécessaire, et remplacez le compte d'exemple par IDs des comptes valides.
------
#### [ C ]
Pour un exemple complet, consultez le [fichier kms\$1discovery.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/kms_discovery.cpp).
```
std::shared_ptr discovery_filter(
KmsKeyring::DiscoveryFilter::Builder("aws")
.AddAccount("111122223333")
.AddAccount("444455556666")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
Pour un exemple complet, consultez [kms\$1filtered\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts).
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
# Définition de votre politique d'engagement
[L'engagement clé](concepts.md#key-commitment) garantit que vos données cryptées sont toujours déchiffrées dans le même texte clair. Pour fournir cette propriété de sécurité, à partir de la version 1.7. *x*, AWS Encryption SDK utilise de nouvelles [suites d'algorithmes](supported-algorithms.md) avec un engagement clé. Pour déterminer si vos données sont cryptées et déchiffrées avec un engagement clé, utilisez le paramètre de configuration de la [politique d'engagement](concepts.md#commitment-policy). [Le chiffrement et le déchiffrement des données avec un engagement clé constituent une bonne pratique.AWS Encryption SDK](best-practices.md)
La définition d'une politique d'engagement est un élément important de la deuxième étape du processus de migration, à savoir la migration depuis la dernière 1. *x* versions des AWS Encryption SDK deux versions 2.0. *x* et versions ultérieures. Après avoir défini et modifié votre politique d'engagement, assurez-vous de tester votre application de manière approfondie avant de la déployer en production. Pour obtenir des conseils sur la migration, voir[Comment migrer et déployer le AWS Encryption SDK](migration-guide.md).
Le paramètre de politique d'engagement comporte trois valeurs valides dans les versions 2.0. *x* et versions ultérieures. Dans le dernier 1. *x* versions (en commençant par la version 1.7. *x*), seul `ForbidEncryptAllowDecrypt` est valide.
+ `ForbidEncryptAllowDecrypt`— Ils AWS Encryption SDK ne peuvent pas chiffrer avec un engagement clé. Il peut déchiffrer les textes chiffrés avec ou sans clé d'engagement.
Dans le dernier 1. *x* versions, c'est la seule valeur valide. Cela garantit que vous ne chiffrez pas avec un engagement clé tant que vous n'êtes pas entièrement prêt à déchiffrer avec un engagement clé. La définition explicite de cette valeur empêche que votre politique d'engagement soit automatiquement modifiée `require-encrypt-require-decrypt` lorsque vous passez aux versions 2.0. *x* ou version ultérieure. Au lieu de cela, vous pouvez [migrer votre politique d'engagement](#migrate-commitment-policy) par étapes.
+ `RequireEncryptAllowDecrypt`— Il chiffre AWS Encryption SDK toujours avec un engagement clé. Il peut déchiffrer les textes chiffrés avec ou sans clé d'engagement. Cette valeur est ajoutée dans la version 2.0. *x.*
+ `RequireEncryptRequireDecrypt`— Il chiffre et déchiffre AWS Encryption SDK toujours avec un engagement clé. Cette valeur est ajoutée dans la version 2.0. *x.* Il s'agit de la valeur par défaut dans les versions 2.0. *x* et versions ultérieures.
Dans le dernier 1. *x* versions, la seule valeur de la politique d'engagement valide est`ForbidEncryptAllowDecrypt`. Après avoir migré vers la version 2.0. *x* ou ultérieurement, vous pouvez [modifier votre politique d'engagement par étapes au](migration-guide.md) fur et à mesure que vous êtes prêt. Ne mettez pas à jour votre politique d'engagement `RequireEncryptRequireDecrypt` tant que vous n'êtes pas certain qu'aucun message n'est crypté sans clé d'engagement.
Ces exemples vous montrent comment définir votre politique d'engagement dans la dernière version 1. dans les versions *x* et dans les versions 2.0. *x* et versions ultérieures. La technique dépend de votre langage de programmation.
**En savoir plus sur la migration**
Pour Kit SDK de chiffrement AWS pour Java, Kit SDK de chiffrement AWS pour Python, et la CLI de AWS chiffrement, découvrez les modifications requises pour les fournisseurs de clés principales dans[Mise à jour des fournisseurs de clés AWS KMS principales](migrate-mkps-v2.md).
Pour Kit SDK de chiffrement AWS pour C et Kit SDK de chiffrement AWS pour JavaScript, découvrez une mise à jour facultative des porte-clés dans[Mise à jour des AWS KMS porte-clés](migrate-keyrings-v2.md).
## Comment définir votre politique d'engagement
La technique que vous utilisez pour définir votre politique d'engagement diffère légèrement selon la mise en œuvre de chaque langue. Ces exemples vous montrent comment procéder. Avant de modifier votre politique d'engagement, passez en revue l'approche en plusieurs étapes dans[Comment migrer et déployer](migration-guide.md).
------
#### [ C ]
À partir de la version 1.7. *x* du Kit SDK de chiffrement AWS pour C, vous utilisez la `aws_cryptosdk_session_set_commitment_policy` fonction pour définir la politique d'engagement de vos sessions de chiffrement et de déchiffrement. La politique d'engagement que vous avez définie s'applique à toutes les opérations de chiffrement et de déchiffrement appelées lors de cette session.
Les `aws_cryptosdk_session_new_from_cmm` fonctions `aws_cryptosdk_session_new_from_keyring` et sont obsolètes dans la version 1.7. *x* et supprimé dans la version 2.0. *x.* Ces fonctions sont remplacées par `aws_cryptosdk_session_new_from_keyring_2` des `aws_cryptosdk_session_new_from_cmm_2` fonctions qui renvoient une session.
Lorsque vous utilisez le `aws_cryptosdk_session_new_from_keyring_2` et `aws_cryptosdk_session_new_from_cmm_2` dans la dernière version 1. *x* versions, vous devez appeler la `aws_cryptosdk_session_set_commitment_policy` fonction avec la valeur de la politique d'`COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT`engagement. Dans les versions 2.0. *x* et versions ultérieures, l'appel de cette fonction est facultatif et prend toutes les valeurs valides. Politique d'engagement par défaut pour les versions 2.0. *x* et les versions ultérieures sont`COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Pour obtenir un exemple complet, veuillez consulter [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp).
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Create an AWS KMS keyring */
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
...
/* Encrypt your data */
size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
ciphertext_output,
ciphertext_buf_sz_output,
ciphertext_len_output,
plaintext_input,
plaintext_len_input,
&plaintext_consumed_output)
...
/* Create a decrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
plaintext_output,
plaintext_buf_sz_output,
plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output)
```
------
#### [ C\$1 / .NET ]
La `require-encrypt-require-decrypt` valeur est la politique d'engagement par défaut dans toutes les versions de AWS Encryption SDK for .NET. Vous pouvez le définir explicitement en tant que meilleure pratique, mais ce n'est pas obligatoire. Toutefois, si vous utilisez le AWS Encryption SDK for .NET pour déchiffrer du texte chiffré par une autre implémentation linguistique de l'engagement AWS Encryption SDK sans clé, vous devez remplacer la valeur de la politique d'engagement par ou. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Dans le cas contraire, les tentatives de déchiffrement du texte chiffré échoueront.
Dans le AWS Encryption SDK fichier pour .NET, vous définissez la politique d'engagement pour une instance de AWS Encryption SDK. Instanciez un `AwsEncryptionSdkConfig` objet avec un `CommitmentPolicy` paramètre et utilisez l'objet de configuration pour créer l' AWS Encryption SDK instance. Appelez ensuite les `Decrypt()` méthodes `Encrypt()` et de l' AWS Encryption SDK instance configurée.
Cet exemple définit la politique d'engagement sur`require-encrypt-allow-decrypt`.
```
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var encryptionContext = new Dictionary()
{
{"purpose", "test"}encryptionSdk
};
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
------
#### [ AWS Encryption CLI ]
Pour définir une politique d'engagement dans la CLI de AWS chiffrement, utilisez le `--commitment-policy` paramètre. Ce paramètre est introduit dans la version 1.8. *x.*
Dans le dernier 1. version *x*, lorsque vous utilisez le `--wrapping-keys` paramètre dans une `--decrypt` commande `--encrypt` ou, un `--commitment-policy` paramètre avec la `forbid-encrypt-allow-decrypt` valeur est requis. Dans le cas contraire, le `--commitment-policy` paramètre n'est pas valide.
Dans les versions 2.1. *x* et versions ultérieures, le `--commitment-policy` paramètre est facultatif et prend par défaut la `require-encrypt-require-decrypt` valeur, qui ne crypte ni ne déchiffre aucun texte chiffré sans engagement de clé. Toutefois, nous vous recommandons de définir la politique d'engagement de manière explicite dans tous les appels de chiffrement et de déchiffrement afin de faciliter la maintenance et le dépannage.
Cet exemple définit la politique d'engagement. Il utilise également le `--wrapping-keys` paramètre qui remplace le `--master-keys` paramètre à partir de la version 1.8. *x.* Pour en savoir plus, consultez [Mise à jour des fournisseurs de clés AWS KMS principales](migrate-mkps-v2.md). Pour des exemples complets, voir[Exemples de CLI AWS de chiffrement](crypto-cli-examples.md).
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
#### [ Java ]
À partir de la version 1.7. *x* du Kit SDK de chiffrement AWS pour Java, vous définissez la politique d'engagement sur votre instance de`AwsCrypto`, l'objet qui représente le AWS Encryption SDK client. Ce paramètre de politique d'engagement s'applique à toutes les opérations de chiffrement et de déchiffrement effectuées sur ce client.
Le `AwsCrypto()` constructeur est obsolète dans la dernière version 1. Les versions *x* de Kit SDK de chiffrement AWS pour Java et sont supprimées dans la version 2.0. *x.* Il est remplacé par une nouvelle `Builder` classe, une nouvelle `Builder.withCommitmentPolicy()` méthode et le type `CommitmentPolicy` énuméré.
Dans le dernier 1. *x* versions, la `Builder` classe nécessite la `Builder.withCommitmentPolicy()` méthode et l'`CommitmentPolicy.ForbidEncryptAllowDecrypt`argument. À partir de la version 2.0. *x*, la `Builder.withCommitmentPolicy()` méthode est facultative ; la valeur par défaut est`CommitmentPolicy.RequireEncryptRequireDecrypt`.
Pour un exemple complet, consultez [SetCommitmentPolicyExample.java.](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SetCommitmentPolicyExample.java)
```
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
.build();
// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Encrypt your plaintext data
CryptoResult encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
À partir de la version 1.7. *x* de Kit SDK de chiffrement AWS pour JavaScript, vous pouvez définir la politique d'engagement lorsque vous appelez la nouvelle `buildClient` fonction qui instancie un AWS Encryption SDK client. La `buildClient` fonction prend une valeur énumérée qui représente votre politique d'engagement. Il renvoie des `decrypt` fonctionnalités mises à jour `encrypt` et qui appliquent votre politique d'engagement lorsque vous cryptez et déchiffrez.
Dans le dernier 1. *x* versions, la `buildClient` fonction nécessite l'`CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`argument. À partir de la version 2.0. *x*, l'argument de politique d'engagement est facultatif et la valeur par défaut est`CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Le code de Node.js et celui du navigateur sont identiques à cette fin, sauf que le navigateur a besoin d'une instruction pour définir les informations d'identification.
L'exemple suivant chiffre les données à l'aide d'un AWS KMS trousseau de clés. La nouvelle `buildClient` fonction définit la politique d'engagement sur `FORBID_ENCRYPT_ALLOW_DECRYPT` la valeur par défaut de la dernière valeur 1. *x* versions. Les mises à niveau `encrypt` et `decrypt` les fonctions qui `buildClient` en découlent appliquent la politique d'engagement que vous avez définie.
```
import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })
// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)
```
------
#### [ Python ]
À partir de la version 1.7. *x* du Kit SDK de chiffrement AWS pour Python, vous définissez la politique d'engagement sur votre instance de`EncryptionSDKClient`, un nouvel objet qui représente le AWS Encryption SDK client. La politique d'engagement que vous définissez s'applique à tous `encrypt` les `decrypt` appels qui utilisent cette instance du client.
Dans le dernier 1. *x* versions, le `EncryptionSDKClient` constructeur a besoin de la valeur `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` énumérée. À partir de la version 2.0. *x*, l'argument de politique d'engagement est facultatif et la valeur par défaut est`CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Cet exemple utilise le nouveau `EncryptionSDKClient` constructeur et définit la politique d'engagement sur 1.7. *x* valeur par défaut. Le constructeur instancie un client qui représente le. AWS Encryption SDK Lorsque vous appelez les `stream` méthodes `encrypt``decrypt`, ou sur ce client, elles appliquent la politique d'engagement que vous avez définie. Cet exemple utilise également le nouveau constructeur de la `StrictAwsKmsMasterKeyProvider` classe, qui indique le AWS KMS keys moment du chiffrement et du déchiffrement.
Pour un exemple complet, consultez le [fichier set\$1commitment.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/set_commitment.py).
```
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
master_key_provider=aws_kms_strict_master_key_provider
)
# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
source=ciphertext,
master_key_provider=aws_kms_strict_master_key_provider
)
```
------
#### [ Rust ]
La `require-encrypt-require-decrypt` valeur est la politique d'engagement par défaut dans toutes les versions de AWS Encryption SDK for Rust. Vous pouvez le définir explicitement en tant que meilleure pratique, mais ce n'est pas obligatoire. Toutefois, si vous utilisez AWS Encryption SDK for Rust pour déchiffrer du texte chiffré par une autre implémentation linguistique de l'engagement AWS Encryption SDK sans clé, vous devez modifier la valeur de la politique d'engagement en ou. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Dans le cas contraire, les tentatives de déchiffrement du texte chiffré échoueront.
Dans AWS Encryption SDK for Rust, vous définissez la politique d'engagement pour une instance de AWS Encryption SDK. Instanciez un `AwsEncryptionSdkConfig` objet avec un `comitment_policy` paramètre et utilisez l'objet de configuration pour créer l' AWS Encryption SDK instance. Appelez ensuite les `Decrypt()` méthodes `Encrypt()` et de l' AWS Encryption SDK instance configurée.
Cet exemple définit la politique d'engagement sur`forbid-encrypt-allow-decrypt`.
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
// Decrypt your ciphertext
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[string]string{
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------
# Résolution des problèmes liés à la migration vers les dernières versions
Avant de mettre à jour votre application vers la version 2.0. *x* ou version ultérieure du AWS Encryption SDK, mise à jour vers la dernière version 1. version *x* du AWS Encryption SDK et déployez-la complètement. Cela vous aidera à éviter la plupart des erreurs que vous pourriez rencontrer lors de la mise à jour vers les versions 2.0. *x* et versions ultérieures. Pour des conseils détaillés, y compris des exemples, voir[Migration de votre AWS Encryption SDK](migration.md).
**Important**
Vérifiez que votre dernier 1. La version *x* est la version 1.7. *x* ou une version ultérieure du AWS Encryption SDK.
**Note**
**AWS CLI de chiffrement** : références de ce guide à la version 1.7. *x* AWS Encryption SDK s'appliquent à la version 1.8. *x* de la CLI AWS de chiffrement. Références à la version 2.0 dans ce guide. *x* s' AWS Encryption SDK appliquent à 2.1. *x* de la CLI AWS de chiffrement.
Les nouvelles fonctionnalités de sécurité ont été initialement publiées dans les versions 1.7 de la CLI de AWS chiffrement. *x* et 2.0. *x.* Cependant, AWS Encryption CLI version 1.8. *x* remplace la version 1.7. *x* et CLI de AWS chiffrement 2.1. *x* remplace 2.0. *x.* Pour plus de détails, consultez l'[avis de sécurité](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondant dans le [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)référentiel sur GitHub.
Cette rubrique est conçue pour vous aider à identifier et à résoudre les erreurs les plus courantes que vous pouvez rencontrer.
**Topics**
+ [Objets déconseillés ou supprimés](#deprecated-removed)
+ [Conflit de configuration : politique d'engagement et suite d'algorithmes](#configuration-conflict_1)
+ [Conflit de configuration : politique d'engagement et texte chiffré](#configuration-conflict_2)
+ [Échec de la validation de l'engagement clé](#commitment-failed)
+ [Autres défaillances de chiffrement](#encrypt-failed)
+ [Autres échecs de déchiffrement](#decrypt-failed)
+ [Considérations relatives à l'annulation](#migration-rollback)
## Objets déconseillés ou supprimés
La version 2.0. *x* inclut plusieurs modifications majeures, notamment la suppression des constructeurs, méthodes, fonctions et classes existants qui étaient obsolètes dans la version 1.7. *x.* Pour éviter les erreurs de compilation, les erreurs d'importation, les erreurs de syntaxe et les erreurs de symboles introuvables (selon votre langage de programmation), passez d'abord à la dernière version 1. version *x* du AWS Encryption SDK pour votre langage de programmation. (Il doit s'agir de la version 1.7. *x* ou version ultérieure.) Lors de l'utilisation de la dernière version 1. version *x*, vous pouvez commencer à utiliser les éléments de remplacement avant que les symboles d'origine ne soient supprimés.
Si vous devez effectuer une mise à niveau vers la version 2.0. *x* ou une version ultérieure immédiatement, [consultez le journal des modifications de](about-versions.md) votre langage de programmation et remplacez les anciens symboles par les symboles recommandés par le journal des modifications.
## Conflit de configuration : politique d'engagement et suite d'algorithmes
Si vous spécifiez une suite d'algorithmes qui entre en conflit avec votre [politique d'engagement](concepts.md#commitment-policy), l'appel au chiffrement échoue avec une erreur de *conflit de configuration*.
Pour éviter ce type d'erreur, ne spécifiez pas de suite d'algorithmes. Par défaut, AWS Encryption SDK il choisit l'algorithme le plus sécurisé compatible avec votre politique d'engagement. Toutefois, si vous devez spécifier une suite d'algorithmes, par exemple une suite sans signature, veillez à choisir une suite d'algorithmes compatible avec votre politique d'engagement.
| Politique d'engagement | Suites d'algorithmes compatibles |
| --- | --- |
| ForbidEncryptAllowDecrypt | Toute suite d'algorithmes *sans* engagement clé, telle que :AES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384([03 78](algorithms-reference.md)) (avec signature) `AES_256_GCM_IV12_TAG16_HKDF_SHA256`([01 78](algorithms-reference.md)) (sans signature) |
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | Toute suite d'algorithmes *avec un* engagement clé, telle que :AES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384([05 78](algorithms-reference.md)) (avec signature) `AES_256_GCM_HKDF_SHA512_COMMIT_KEY`([04 78](algorithms-reference.md)) (sans signature) |
Si vous rencontrez cette erreur alors que vous n'avez pas spécifié de suite d'algorithmes, la suite d'algorithmes en conflit a peut-être été choisie par votre [gestionnaire de matériel cryptographique](concepts.md#crypt-materials-manager) (CMM). Le CMM par défaut ne sélectionnera pas une suite d'algorithmes conflictuelle, mais un CMM personnalisé pourrait le faire. Pour obtenir de l'aide, consultez la documentation de votre CMM personnalisé.
## Conflit de configuration : politique d'engagement et texte chiffré
La [politique d'`RequireEncryptRequireDecrypt`engagement](concepts.md#commitment-policy) ne permet pas AWS Encryption SDK de déchiffrer un message chiffré sans [clé d'engagement](concepts.md#key-commitment). Si vous demandez AWS Encryption SDK à déchiffrer un message sans engagement de clé, il renvoie une erreur de *conflit de configuration*.
Pour éviter cette erreur, avant de définir la politique d'`RequireEncryptRequireDecrypt`engagement, assurez-vous que tous les textes chiffrés chiffrés sans engagement de clé sont déchiffrés et rechiffrés avec engagement de clé, ou gérés par une autre application. Si vous rencontrez cette erreur, vous pouvez renvoyer une erreur pour le texte chiffré en conflit ou modifier temporairement votre politique d'engagement en. `RequireEncryptAllowDecrypt`
Si vous rencontrez cette erreur parce que vous avez effectué une mise à niveau vers la version 2.0. *x* ou version ultérieure à partir d'une version antérieure à 1.7. *x* sans passer d'abord à la dernière version 1. version *x* (version 1.7). *x* ou version ultérieure), pensez [à revenir](#migration-rollback) à la dernière valeur 1. version *x* et déploiement de cette version sur tous les hôtes avant la mise à niveau vers la version 2.0. *x* ou version ultérieure. Pour obtenir de l'aide, veuillez consulter [Comment migrer et déployer le AWS Encryption SDK](migration-guide.md).
## Échec de la validation de l'engagement clé
Lorsque vous déchiffrez des messages chiffrés avec clé d'engagement, vous pouvez recevoir un message d'erreur indiquant l'*échec de la validation de l'engagement par clé*. Cela indique que l'appel de déchiffrement a échoué car la clé de données d'un [message chiffré](concepts.md#DEK) n'est pas identique à la clé de données unique du message. En validant la clé de données pendant le déchiffrement, l'[engagement de la clé](concepts.md#key-commitment) vous empêche de déchiffrer un message susceptible de générer plusieurs textes en clair.
Cette erreur indique que le message chiffré que vous tentiez de déchiffrer n'a pas été renvoyé par le AWS Encryption SDK. Il peut s'agir d'un message créé manuellement ou d'une corruption de données. Si vous rencontrez cette erreur, votre application peut rejeter le message et continuer ou arrêter de traiter les nouveaux messages.
## Autres défaillances de chiffrement
Le chiffrement peut échouer pour plusieurs raisons. Vous ne pouvez pas utiliser un [trousseau de clés de AWS KMS découverte](use-kms-keyring.md#kms-keyring-discovery) ou un [fournisseur de clés principales en mode découverte](migrate-mkps-v2.md) pour chiffrer un message.
Assurez-vous de spécifier un trousseau de clés ou un fournisseur de clés principales avec des clés d'encapsulation que vous êtes [autorisé à utiliser](use-kms-keyring.md#kms-keyring-permissions) pour le chiffrement. Pour obtenir de l'aide concernant les autorisations AWS KMS keys, reportez-vous aux [sections Affichage d'une politique clé](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html) et [Détermination de l'accès à une](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html) politique AWS KMS key dans le *guide du AWS Key Management Service développeur*.
## Autres échecs de déchiffrement
Si votre tentative de déchiffrement d'un message chiffré échoue, cela signifie qu'aucune des clés de données chiffrées contenues dans le message n'a AWS Encryption SDK pu (ou n'a pas voulu) déchiffrer.
Si vous avez utilisé un trousseau de clés ou un fournisseur de clés principales qui spécifie les clés d'encapsulation, il AWS Encryption SDK utilise uniquement les clés d'encapsulation que vous spécifiez. Vérifiez que vous utilisez les clés d'encapsulage comme vous le souhaitez et que vous êtes `kms:Decrypt` autorisé à utiliser au moins l'une des clés d'encapsulation. Si vous utilisez AWS KMS keys, comme solution de rechange, vous pouvez essayer de déchiffrer le message à l'aide d'un [trousseau de clés de AWS KMS découverte](use-kms-keyring.md#kms-keyring-discovery) ou d'un fournisseur de [clés principales](migrate-mkps-v2.md) en mode découverte. Si l'opération aboutit, avant de renvoyer le texte en clair, vérifiez que la clé utilisée pour déchiffrer le message est une clé fiable.
## Considérations relatives à l'annulation
[Si votre application ne parvient pas à chiffrer ou à déchiffrer les données, vous pouvez généralement résoudre le problème en mettant à jour les symboles de code, les trousseaux de clés, les fournisseurs de clés principales ou la politique d'engagement.](concepts.md#commitment-policy) Toutefois, dans certains cas, vous pouvez décider qu'il est préférable de restaurer votre application à une version précédente du AWS Encryption SDK.
Si vous devez revenir en arrière, faites-le avec prudence. Versions des versions AWS Encryption SDK antérieures à 1.7. *x* [ne peut pas déchiffrer le texte chiffré avec clé d'engagement.](concepts.md#key-commitment)
+ En revenant à la dernière version 1. La version *x* par rapport à une version précédente du AWS Encryption SDK est généralement sûre. Vous devrez peut-être annuler les modifications apportées à votre code pour utiliser des symboles et des objets qui ne sont pas pris en charge dans les versions précédentes.
+ Une fois que vous avez commencé à chiffrer avec un engagement clé (en définissant votre politique d'engagement sur`RequireEncryptAllowDecrypt`) dans la version 2.0. *x* ou version ultérieure, vous pouvez revenir à la version 1.7. *x*, mais pas vers une version antérieure. Versions des versions AWS Encryption SDK antérieures à 1.7. *x* [ne peut pas déchiffrer le texte chiffré avec clé d'engagement.](concepts.md#key-commitment)
Si vous activez accidentellement le chiffrement avec engagement par clé avant que tous les hôtes puissent le déchiffrer avec engagement par clé, il peut être préférable de poursuivre le déploiement plutôt que de revenir en arrière. Si les messages sont transitoires ou peuvent être supprimés en toute sécurité, vous pouvez envisager une restauration avec perte de messages. Si une annulation est requise, vous pouvez envisager de créer un outil qui déchiffre et rechiffre tous les messages.