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.
Mise à jourAWS KMS des fournisseurs de clés principales
Pour migrer vers la dernière version 1. version x duAWS Encryption SDK, puis à la version 2.0. x ou version ultérieure, vous devez remplacer les fournisseursAWS KMS de clés principales existants par des fournisseurs de clés principales créés explicitement en mode strict ou en mode découverte. Les fournisseurs de clés principales vers 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 JavaKit SDK de chiffrement AWS pour Python, et l'interface de ligne de commande deAWS chiffrement. Les exemples de cette section vous montreront comment mettre à jour votre code.
Si vous utilisez une cléAWS KMS principale (et non un fournisseur de clé principale), vous pouvez ignorer cette étape. AWS KMSles clés principales ne sont ni obsolètes ni supprimées. Ils chiffrent et déchiffrent uniquement à l'aide des 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 correspondant à votre langage de programmation. De plus, ces exemples utilisent généralement des ARN clés pour représenterAWS KMS keys. Lorsque vous créez un fournisseur de clé principale pour le chiffrement, vous pouvez utiliser n'importe quel identifiant deAWS KMS clé valide pour représenter unAWS 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 lesAWS Encryption SDK utilisateurs, découvrez comment définir votre politique d'engagement dansDéfinition de votre politique d'engagement.
PourKit SDK de chiffrement AWS pour C lesKit SDK de chiffrement AWS pour JavaScript utilisateurs finaux, découvrez une mise à jour facultative des porte-clés dansMise à jour en coursAWS KMSporte-clés.
Migration vers le mode strict
Après la mise à jour vers la dernière version 1. version x duAWS 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 SDKutilise 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 deAWS KMS key n'importe quelle clé de données cryptée, y comprisAWS KMS keys dans différentesComptes AWS régions.
Les fournisseurs de clés principales en mode strict sont introduits dans laAWS Encryption SDK version 1.7. x. Ils remplacent les anciens fournisseurs de clés principales, qui sont obsolètes depuis 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 uneAWS Encryption SDK bonne pratique.
Le code suivant crée un fournisseur de clé principale en mode strict que vous pouvez utiliser pour chiffrer et déchiffrer.
- Java
-
Cet exemple représente le code d'une application qui utilise la version 1.6.2 ou une version antérieure duKit SDK de chiffrement AWS pour Java.
Ce code utilise laKmsMasterKeyProvider.builder() méthode pour instancier un fournisseur de cléAWS KMS principale qui en utilise unAWS 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 version ultérieure duKit SDK de chiffrement AWS pour Java. Pour un exemple complet, consultez BasicEncryptionExample.java.
LesBuilder.withKeysForEncryption() méthodesBuilder.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 à des méthodes obsolètes par un appel à la nouvelleBuilder.buildStrict() méthode. Cet exemple en spécifie uneAWS KMS key comme clé d'encapsulation, mais laBuilder.buildStrict() méthode peut prendre une liste de plusieursAWS 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 duKit SDK de chiffrement AWS pour Python. Ce code utiliseKMSMasterKeyProvider, 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 cryptée sans tenir compte deAWS KMS key celleAWS KMS keys que vous avez spécifiée.
Notez qu'KMSMasterKeyil n'est ni obsolète ni supprimé. Lors du chiffrement et du déchiffrement, il utilise uniquement ce queAWS KMS key vous spécifiez.
# 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 duKit SDK de chiffrement AWS pour Python. Pour un exemple complet, consultez 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 version 1.1.7 ou antérieure de la CLI deAWS chiffrement.
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'uneAWS KMS key. Lors du déchiffrement, vous ne pouvez spécifier aucune clé d'encapsulation à moins d'utiliser un fournisseur de clé principale personnalisé. La CLI deAWS 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 version 1.7 de l'interface de ligne de commande deAWS chiffrement. x ou version ultérieure. Pour des exemples complets, reportez-vous à la sectionExemples deAWSCLI de chiffrement.
Le--master-keys paramètre est obsolète dans la version 1.7. x et supprimé dans la version 2.0. x. Il est remplacé par le--wrapping-keys paramètre by, qui est requis 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 uneAWS Encryption SDK bonne pratique qui garantit que vous utilisez la clé d'encapsulation que vous 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 SDKutiliser le mode strict pour les fournisseurs deAWS KMS clés principales, c'est-à-dire de spécifier des clés d'encapsulage lors du chiffrement et du déchiffrement. Vous devez toujours spécifier des clés d'encapsulation lors du chiffrement. Mais il existe des situations dans lesquelles la spécification des ARN clésAWS KMS keys pour le déchiffrement n'est pas pratique. Par exemple, si vous utilisez des alias pour vous identifierAWS KMS keys lors du chiffrement, vous perdez l'avantage des alias si vous devez répertorier les ARN clés lors du déchiffrement. De plus, é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 à des fournisseurs de clés principales en mode strict ultérieurement.
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'encapsulation. 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 les clés d'encapsulation pouvant être utilisées à ces fournisseurs en particulierComptes AWS. Ce filtre de découverte est facultatif, mais c'est une bonne pratique que nous recommandons. Pour plus d'informations surAWS les partitions et les comptes, consultez Amazon Resource Names 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é principale en mode découverte utilise un filtre de découverte pour limiter les clés d'encapsulation utilisées pour le déchiffrement à laaws partition et à un exemple particulierComptes 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 qui s'avère très utile 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 version ultérieure duKit SDK de chiffrement AWS pour Java. Pour un exemple complet, consultez DiscoveryDecryptionExample.java.
Pour instancier un fournisseur de clé principale en mode strict à des fins de chiffrement, cet exemple utilise laBuilder.buildStrict() méthode. Pour instancier un fournisseur de clé principale en mode découverte à des fins de déchiffrement, il utilise laBuilder.buildDiscovery() méthode. LaBuilder.buildDiscovery() méthode prend unDiscoveryFilter qui limite les deuxAWS Encryption SDKAWS KMS keys à laAWS partition et aux 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 version ultérieure duKit SDK de chiffrement AWS pour Python. Pour un exemple complet, consultez discovery_kms_provider.py.
Pour créer un fournisseur de clé principale en mode strict à des fins de chiffrement, cet exemple utiliseStrictAwsKmsMasterKeyProvider. Pour créer un fournisseur de clé principale en mode découverte à des fins de déchiffrement, il utiliseDiscoveryAwsKmsMasterKeyProvider with aDiscoveryFilter qui limite leAWS Encryption SDK àAWS KMS keys à laAWS partition et aux 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 version 1.7 de l'interface de ligne de commande deAWS chiffrement. x ou version ultérieure. À partir de la version 1.7. x, le--wrapping-keys paramètre est requis 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, reportez-vous à la sectionExemples deAWSCLI de chiffrement.
Lors du chiffrement, cet exemple spécifie une clé d'encapsulation, qui est requise. Lors du déchiffrement, il choisit explicitement le mode de découverte en utilisant l'discoveryattribut du--wrapping-keys paramètre avec une valeur detrue.
Pour limiter les clés d'encapsulationAWS Encryption SDK pouvant être utilisées en mode découverte à celles-ci en particulierComptes AWS, cet exemple utilise lesdiscovery-account attributsdiscovery-partition et du--wrapping-keys paramètre. Ces attributs facultatifs ne sont valides que lorsque l'discoveryattribut est défini surtrue. Vous devez utiliser lesdiscovery-account attributsdiscovery-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 .
