Mise à jour en coursAWS KMSprincipaux fournisseurs de clés

Pour migrer vers la dernière version 1.xversion duAWS Encryption SDK, puis vers la version 2.0.xou plus tard, vous devez remplacer l'ancienneAWS KMSfournisseurs de clés principales avec des fournisseurs de clés principales créés explicitement dansMode strictouMode Découverte. Les fournisseurs de clés principales existants sont obsolètes dans la version 1.7.xet supprimé dans la version 2.0.x. Cette modification est requise pour les applications et les scripts qui utilisentKit SDK de chiffrement AWS pour Java,Kit SDK de chiffrement AWS pour Python, et leAWSCLI de chiffrement. Les exemples de cette section vous montreront comment mettre à jour votre code.

Note

En Python,activer les avertissements d'obsolescence. Cela vous aidera à identifier les parties de votre code que vous devez mettre à jour.

Si vous utilisez unAWS KMSclé principale (il ne s'agit pas d'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 obtenir un exemple de code mis à jour, consultez la section Exemples du GitHubréférentiellangage de programmation. En outre, 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 quelAWS KMS identifiantpour 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 tousAWS Encryption SDKutilisateurs, découvrez comment définir votre politique d'engagement dansDéfinition de votre politique d'engagement.

PourKit SDK de chiffrement AWS pour CetKit SDK de chiffrement AWS pour JavaScriptutilisateurs, découvrez la mise à jour facultative des trousseaux de 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.xversion duAWS Encryption SDK, remplacez vos fournisseurs de clés principales existants 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. Dans laAWS Encryption SDKutilise uniquement les clés d'encapsulation que vous avez spécifiées. Les fournisseurs de clés principales obsolètes peuvent déchiffrer les données à l'aide de n'importe quelAWS KMS keyqui a crypté une clé de données, y comprisAWS KMS keysdansComptes AWSet Régions.

Les fournisseurs de clés principales en mode strict sont introduits dansAWS Encryption SDKVersion 1.7.x. Ils remplacent les fournisseurs de clés principales existants, qui sont obsolètes dans la version 1.7.xet supprimé dans 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 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 deKit SDK de chiffrement AWS pour Java.

Ce code utilise leKmsMasterKeyProvider.builder()méthode pour instancier unAWS KMSfournisseur de clés principales qui en utilise uneAWS KMS keycomme clé d'emballage.

// 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.xou une version ultérieure duKit SDK de chiffrement AWS pour Java. Pour obtenir un exemple complet, consultezBasicEncryptionExample.java.

Dans laBuilder.build()etBuilder.withKeysForEncryption()les méthodes utilisées dans l'exemple précédent sont obsolètes dans la version 1.7.xet sont supprimés de la version 2.0.x.

Pour passer à un fournisseur de clés principales en mode strict, ce code remplace les appels à des méthodes obsolètes par un appel à la nouvelleBuilder.buildStrict()Méthode. Cet exemple spécifie unAWS KMS keycomme clé d'emballage, mais leBuilder.buildStrict()la 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 deKit SDK de chiffrement AWS pour Python. Ce code utiliseKMSMasterKeyProvider, qui est obsolète dans la version 1.7.xet supprimé de la version 2.0.x. Lors du déchiffrement, il utilise n'importe quelAWS KMS keyqui a crypté une clé de données sans tenir compte deAWS KMS keysvous spécifiez.

Notez queKMSMasterKeyn'est ni obsolète ni supprimé. Lors du chiffrement et du déchiffrement, il utilise uniquement leAWS KMS keyvous 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.xde laKit SDK de chiffrement AWS pour Python. Pour obtenir un exemple complet, consultezbasic_encryption.py.

Pour passer à un fournisseur de clés principales en mode strict, ce code remplace l'appel àKMSMasterKeyProvider()avec 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

L'exemple suivant décrit comment chiffrer et déchiffrer à l'aide duAWSVersion Encryption CLI 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 (ouclés d'emballage), tel qu'unAWS 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é. Dans laAWSLa CLI de chiffrement peut utiliser n'importe quelle clé d'encapsulation cryptant 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 .  

L'exemple suivant décrit comment chiffrer et déchiffrer à l'aide duAWSVersion CLI de chiffrement 1.7.xou plus tard. Pour des exemples complets, voirExemples deAWSCLI de chiffrement.

Dans la--master-keysle paramètre est obsolète dans la version 1.7.xet supprimé dans la version 2.0.x. Il est remplacé par--wrapping-keysparamètre, 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. Mode strict estAWS Encryption SDKbonne pratique qui garantit que vous utilisez la clé d'emballage que vous souhaitez.

Pour mettre à niveauMode strict, utilisezcléAttribut--wrapping-keysparamètre permettant de 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, c'est unAWS Encryption SDK bonne pratiqueà utiliserMode strictpourAWS KMSfournisseurs de clés principales, c'est-à-dire pour spécifier les clés d'encapsulation 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és deAWS KMS keyscar le décryptage n'est pas pratique. Par exemple, si vous utilisez des alias pour identifierAWS KMS keyslors 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 ultérieurement à des fournisseurs de clés principales en mode strict.

Dans de tels cas, vous pouvez utiliser des fournisseurs de clés principales dansMode 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 fournisseurs de clés principales traditionnels, 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 à ceux-ci en particulierComptes AWS. Ce filtre de découverte est facultatif, mais il s'agit d'une bonne pratique que nous recommandons. Pour plus d'informations surAWSpartitions et comptes, voirNoms des ressources Amazondans leAWSRéférence générale.

Les exemples suivants créentAWS KMSfournisseur de clé principale en mode strict pour le chiffrement etAWS KMSfournisseur de clé 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 auxawspartition 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 crypte des données et qu'une autre les déchiffre.

Java

Cet exemple représente le code d'une application qui utilise la version 1.7.xou une version ultérieure duKit SDK de chiffrement AWS pour Java. Pour obtenir un exemple complet, consultezDiscoveryDecryptionExample.java.

Pour instancier un fournisseur de clé principale en mode strict pour le chiffrement, cet exemple utiliseBuilder.buildStrict()Méthode. Pour instancier un fournisseur de clé principale en mode découverte à des fins de déchiffrement, il utiliseBuilder.buildDiscovery()Méthode. Dans laBuilder.buildDiscovery()MéthodeDiscoveryFilterqui limiteAWS Encryption SDKpourAWS KMS keysdansAWSpartition et comptes.

// 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.xou une version ultérieure duKit SDK de chiffrement AWS pour Python. Pour obtenir un exemple complet, consultezdiscovery_kms_provider.py.

Pour créer un fournisseur de clé principale en mode strict pour le chiffrement, cet exemple utiliseStrictAwsKmsMasterKeyProvider. Pour créer un fournisseur de clé principale en mode découverte pour le déchiffrement, il utiliseDiscoveryAwsKmsMasterKeyProvideravec unDiscoveryFilterqui limiteAWS Encryption SDKpourAWS KMS keysdansAWSpartition et comptes.

# 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

L'exemple suivant décrit comment chiffrer et déchiffrer à l'aide duAWSVersion CLI de chiffrement 1.7.xou plus tard. À partir de la version 1.7.x, le--wrapping-keysUn paramètre est requis lors du chiffrement et du déchiffrement. Dans la--wrapping-keysle paramètre prend en charge le mode strict et le mode découverte. Pour des exemples complets, voirExemples deAWSCLI de chiffrement.

Lors du chiffrement, cet exemple spécifie une clé d'encapsulation, qui est obligatoire. Lors du déchiffrement, il choisit explicitementMode Découverteen utilisantdiscoveryAttribut--wrapping-keysparamètre avec une valeur detrue.

Pour limiter les clés d'encapsulation queAWS Encryption SDKpeut être utilisé en mode découverte pour ceux en particulierComptes AWS, cet exemple utilise lediscovery-partitionetdiscovery-accountAttributs--wrapping-keysparamètre. Ces attributs facultatifs ne sont valides que lorsquediscoveryAttribut est défini surtrue. Vous devez utiliserdiscovery-partitionetdiscovery-accountattributs combinés ; aucun 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 .