Configuration du AWS Encryption SDK - AWS Encryption SDK

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.

Configuration du AWS Encryption SDK

AWS Encryption SDKIl est conçu pour être facile à utiliser. Bien qu'il AWS Encryption SDK dispose de plusieurs options de configuration, les valeurs par défaut sont soigneusement choisies pour être pratiques et sûres pour la plupart des applications. Toutefois, vous devrez peut-être ajuster votre configuration pour améliorer les performances ou inclure une fonctionnalité personnalisée dans votre conception.

Lorsque vous configurez votre implémentation, passez en revue les AWS Encryption SDK meilleures pratiques et mettez-en en œuvre autant que possible.

Sélection d'un langage de programmation

AWS Encryption SDKIl est disponible dans plusieurs langages de programmation. Les implémentations du langage sont conçues pour être totalement interopérables et pour offrir les mêmes fonctionnalités, bien qu'elles puissent être implémentées de différentes manières. Généralement, vous utilisez la bibliothèque compatible avec votre application. Toutefois, vous pouvez sélectionner un langage de programmation pour une implémentation particulière. Par exemple, si vous préférez travailler avec des porte-clés, vous pouvez choisir le Kit SDK de chiffrement AWS pour C ou leKit SDK de chiffrement AWS pour JavaScript.

Sélection des clés d'emballage

AWS Encryption SDKGénère une clé de données symétrique unique pour chiffrer chaque message. À moins que vous n'utilisiez la mise en cache des clés de données, vous n'avez pas besoin de configurer, de gérer ou d'utiliser les clés de données. Ils AWS Encryption SDK le font pour toi.

Toutefois, vous devez sélectionner une ou plusieurs clés d'encapsulation pour chiffrer chaque clé de données. Il AWS Encryption SDK prend en charge les clés symétriques AES et les clés asymétriques RSA de différentes tailles. Il prend également en charge le chiffrement AWS KMS keys symétrique AWS Key Management Service(AWS KMS). Vous êtes responsable de la sécurité et de la durabilité de vos clés d'encapsulage. Nous vous recommandons donc d'utiliser une clé de chiffrement dans un module de sécurité matériel ou un service d'infrastructure clé, tel queAWS KMS.

Pour spécifier vos clés d'encapsulation pour le chiffrement et le déchiffrement, vous utilisez un trousseau de clés (C et JavaScript) ou un fournisseur de clés principales (Java, Python, Encryption AWS CLI). Vous pouvez spécifier une clé d'encapsulation ou plusieurs clés d'encapsulation de types identiques ou différents. Si vous utilisez plusieurs clés d'encapsulation pour encapsuler une clé de données, chaque clé d'encapsulation chiffrera une copie de la même clé de données. Les clés de données chiffrées (une par clé d'encapsulage) sont stockées avec les données cryptées dans le message crypté AWS Encryption SDK renvoyé. Pour déchiffrer les données, vous AWS Encryption SDK devez d'abord utiliser l'une de vos clés d'encapsulation pour déchiffrer une clé de données cryptée.

Pour spécifier un fournisseur de clés ou de clés principales AWS KMS key dans un trousseau de clés, utilisez un identifiant de AWS KMS clé compatible. Pour plus de détails sur les identificateurs de clé d'une AWS KMS clé, consultez la section Identifiants de clé dans le guide du AWS Key Management Servicedéveloppeur.

  • Lors du chiffrement à l'Kit SDK de chiffrement AWS pour Javaaide de la CLI de AWS chiffrement, vous pouvez utiliser n'importe quel identifiant de clé valide (ID de clé, ARN de clé, nom d'alias ou ARN d'alias) pour une clé KMS. Kit SDK de chiffrement AWS pour JavaScript Kit SDK de chiffrement AWS pour Python Lorsque vous chiffrez avec leKit SDK de chiffrement AWS pour C, vous ne pouvez utiliser qu'un identifiant de clé ou un ARN de clé.

    Si vous spécifiez un nom d'alias ou un ARN d'alias pour une clé KMS lors du chiffrement, l'ARN de la clé actuellement associé à cet alias est enregistré ; il n'AWS Encryption SDKenregistre pas l'alias. Les modifications apportées à l'alias n'affectent pas la clé KMS utilisée pour déchiffrer vos clés de données.

  • Lors du déchiffrement en mode strict (où vous spécifiez des clés d'encapsulation particulières), vous devez utiliser un ARN de clé pour l'identifier. AWS KMS keys Cette exigence s'applique à toutes les implémentations de langage du kit AWS Encryption SDK.

    Lorsque vous chiffrez avec un AWS KMS trousseau de clés, l'ARN de la clé est AWS Encryption SDK stocké AWS KMS key dans les métadonnées de la clé de données cryptée. Lors du déchiffrement en mode strict, il AWS Encryption SDK vérifie que le même ARN de clé apparaît dans le trousseau de clés (ou dans le fournisseur de clés principales) avant de tenter d'utiliser la clé d'encapsulation pour déchiffrer la clé de données chiffrée. Si vous utilisez un identifiant de clé différent, il ne le AWS Encryption SDK reconnaîtra ni ne l'utiliseraAWS KMS key, même si les identifiants font référence à la même clé.

Pour spécifier une clé AES brute ou une paire de clés RSA brute en tant que clé d'encapsulation dans un trousseau de clés, vous devez spécifier un espace de noms et un nom. Dans un fournisseur de clé principale, Provider ID il s'agit de l'équivalent de l'espace de noms et de l'équivalent du nom. Key ID Lors du déchiffrement, vous devez utiliser exactement le même espace de noms et le même nom pour chaque clé d'encapsulation brute que ceux que vous avez utilisés lors du chiffrement. Si vous utilisez un espace de noms ou un nom différent, la clé d'encapsulage ne AWS Encryption SDK sera pas reconnue ni utilisée, même si le contenu de la clé est le même.

Utilisation de plusieurs régions AWS KMS keys

Vous pouvez utiliser AWS Key Management Service (AWS KMS) des clés multirégionales comme clés d'encapsulation dans leAWS Encryption SDK. Si vous chiffrez avec une clé multirégionale dans une cléRégion AWS, vous pouvez déchiffrer en utilisant une clé multirégionale associée dans une autre. Région AWS Support pour les clés multirégionales a été introduit dans la version 2.3. x du AWS Encryption SDK et version 3.0. x de la CLI AWS de chiffrement.

AWS KMSLes clés multirégionales sont un ensemble de AWS KMS keys clés différentes Régions AWS qui ont le même matériau clé et le même identifiant de clé. Vous pouvez utiliser ces clés associées comme s'il s'agissait de la même clé dans différentes régions. Les clés multirégionales prennent en charge les scénarios courants de reprise après sinistre et de sauvegarde qui nécessitent le chiffrement dans une région et le déchiffrement dans une autre région sans passer un appel interrégional à. AWS KMS Pour plus d'informations sur les clés multirégionales, consultez la section Utilisation des clés multirégionales dans le manuel du AWS Key Management Servicedéveloppeur.

Pour prendre en charge les clés multirégionales, des porte-clés et des fournisseurs de clés principales AWS KMS compatibles avec plusieurs régions sont AWS Encryption SDK inclus. Le nouveau symbole prenant en compte plusieurs régions dans chaque langage de programmation prend en charge les clés à région unique et à régions multiples.

  • Pour les clés à région unique, le symbole compatible avec plusieurs régions se comporte comme le porte-clés à région unique AWS KMS et le fournisseur de clés principales. Il tente de déchiffrer le texte chiffré uniquement à l'aide de la clé à région unique qui a chiffré les données.

  • Pour les clés multirégionales, le symbole compatible avec plusieurs régions tente de déchiffrer le texte chiffré avec la même clé multirégionale qui a chiffré les données ou avec la clé multirégionale associée dans la région que vous spécifiez.

Dans les trousseaux de clés compatibles avec plusieurs régions et les fournisseurs de clés principales qui acceptent plusieurs clés KMS, vous pouvez spécifier plusieurs clés à région unique et multirégionale. Toutefois, vous ne pouvez spécifier qu'une seule clé pour chaque ensemble de clés multirégionales associées. Si vous spécifiez plusieurs identificateurs de clé avec le même identifiant de clé, l'appel du constructeur échoue.

Vous pouvez également utiliser une clé multirégionale avec les porte-clés standard à région unique et les fournisseurs de AWS KMS clés principales. Toutefois, vous devez utiliser la même clé multirégionale dans la même région pour chiffrer et déchiffrer. Les trousseaux de clés à région unique et les fournisseurs de clés principales tentent de déchiffrer le texte chiffré uniquement avec les clés qui ont chiffré les données.

Les exemples suivants montrent comment chiffrer et déchiffrer des données à l'aide de clés multirégionales et des nouveaux porte-clés et fournisseurs de clés principales compatibles avec plusieurs régions. Ces exemples chiffrent les données de la us-east-1 région et déchiffrent les données de la us-west-2 région à l'aide des clés multirégionales associées dans chaque région. Avant d'exécuter ces exemples, remplacez l'exemple d'ARN clé multirégional par une valeur valide provenant de votreCompte AWS.

C

Pour chiffrer avec une clé multirégionale, utilisez la Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() méthode d'instanciation du trousseau de clés. Spécifiez une clé multirégionale.

Cet exemple simple n'inclut pas de contexte de chiffrement. Pour un exemple d'utilisation d'un contexte de chiffrement en C, consultezChiffrement et déchiffrement de chaînes.

Pour un exemple complet, consultez le fichier kms_multi_region_keys.cpp dans le Kit SDK de chiffrement AWS pour C référentiel sur GitHub.

/* Encrypt with a multi-Region KMS key in us-east-1 */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Initialize a multi-Region keyring */ const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; struct aws_cryptosdk_keyring *mrk_keyring = Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1); /* Create a session; release the keyring */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring); aws_cryptosdk_keyring_release(mrk_keyring); /* Encrypt the data * aws_cryptosdk_session_process_full is designed for non-streaming data */ aws_cryptosdk_session_process_full( session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len)); /* Clean up the session */ aws_cryptosdk_session_destroy(session);
C# / .NET

Pour chiffrer avec une clé multirégionale dans la région USA Est (Virginie du Nord) (us-east-1), instanciez un CreateAwsKmsMrkKeyringInput objet avec un identifiant de clé pour la clé multirégionale et un client pour la région spécifiée. AWS KMS Utilisez ensuite la CreateAwsKmsMrkKeyring() méthode pour créer le porte-clés.

Le CreateAwsKmsMrkKeyring() procédé crée un trousseau de clés contenant exactement une clé multirégionale. Pour chiffrer avec plusieurs clés d'encapsulation, y compris une clé multirégionale, utilisez cette méthode. CreateAwsKmsMrkMultiKeyring()

Pour un exemple complet, consultez AwsKmsMrkKeyringExample.cs dans le référentiel AWS Encryption SDK for .NET sur GitHub.

//Encrypt with a multi-Region KMS key in us-east-1 Region // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Multi-Region keys have a distinctive key ID that begins with 'mrk' // Specify a multi-Region key in us-east-1 string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Create the keyring // You can specify the Region or get the Region from the key ARN var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1), KmsKeyId = mrkUSEast1 }; var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput); // Define the encryption context var encryptionContext = new Dictionary<string, string>() { {"purpose", "test"} }; // Encrypt your plaintext data. var encryptInput = new EncryptInput { Plaintext = plaintext, Keyring = mrkEncryptKeyring, EncryptionContext = encryptionContext }; var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

Cet exemple chiffre le hello.txt fichier sous une clé multirégionale dans la région us-east-1. Étant donné que l'exemple spécifie un ARN clé avec un élément Region, il n'utilise pas l'attribut region du --wrapping-keys paramètre.

Lorsque l'ID de clé de la clé d'encapsulation ne spécifie pas de région, vous pouvez utiliser l'attribut de région --wrapping-keys pour spécifier la région, par exemple--wrapping-keys key=$keyID region=us-east-1.

# Encrypt with a multi-Region KMS key in us-east-1 Region # To run this example, replace the fictitious key ARN with a valid value. $ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab $ aws-encryption-cli --encrypt \ --input hello.txt \ --wrapping-keys key=$mrkUSEast1 \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --output .
Java

Pour chiffrer avec une clé multirégionale, instanciez une clé multirégionale AwsKmsMrkAwareMasterKeyProvider et spécifiez-la.

Pour un exemple complet, voir BasicMultiRegionKeyEncryptionExample.javale Kit SDK de chiffrement AWS pour Java référentiel sur GitHub.

//Encrypt with a multi-Region KMS key in us-east-1 Region // Instantiate the client final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // Multi-Region keys have a distinctive key ID that begins with 'mrk' // Specify a multi-Region key in us-east-1 final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Instantiate an AWS KMS master key provider in strict mode for multi-Region keys // Configure it to encrypt with the multi-Region key in us-east-1 final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider .builder() .buildStrict(mrkUSEast1); // Create an encryption context final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test"); // Encrypt your plaintext data final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData( kmsMrkProvider, encryptionContext, sourcePlaintext); byte[] ciphertext = encryptResult.getResult();
JavaScript Browser

Pour chiffrer avec une clé multirégionale, utilisez la buildAwsKmsMrkAwareStrictMultiKeyringBrowser() méthode pour créer le trousseau de clés et spécifiez une clé multirégionale.

Pour un exemple complet, consultez kms_multi_region_simple.ts dans le référentiel sur. Kit SDK de chiffrement AWS pour JavaScript GitHub

/* Encrypt with a multi-Region KMS key in us-east-1 Region */ import { buildAwsKmsMrkAwareStrictMultiKeyringBrowser, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-browser' /* Instantiate an AWS Encryption SDK client */ const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } /* Instantiate an AWS KMS client * The Kit SDK de chiffrement AWS pour JavaScript gets the Region from the key ARN */ const clientProvider = (region: string) => new KMS({ region, credentials }) /* Specify a multi-Region key in us-east-1 */ const multiRegionUsEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Instantiate the keyring */ const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({ generatorKeyId: multiRegionUsEastKey, clientProvider, }) /* Set the encryption context */ const context = { purpose: 'test', } /* Test data to encrypt */ const cleartext = new Uint8Array([1, 2, 3, 4, 5]) /* Encrypt the data */ const { result } = await encrypt(encryptKeyring, cleartext, { encryptionContext: context, })
JavaScript Node.js

Pour chiffrer avec une clé multirégionale, utilisez la buildAwsKmsMrkAwareStrictMultiKeyringNode() méthode pour créer le trousseau de clés et spécifiez une clé multirégionale.

Pour un exemple complet, consultez kms_multi_region_simple.ts dans le référentiel sur. Kit SDK de chiffrement AWS pour JavaScript GitHub

//Encrypt with a multi-Region KMS key in us-east-1 Region import { buildClient } from '@aws-crypto/client-node' /* Instantiate the AWS Encryption SDK client const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) /* Test string to encrypt */ const cleartext = 'asdf' /* Multi-Region keys have a distinctive key ID that begins with 'mrk' * Specify a multi-Region key in us-east-1 */ const multiRegionUsEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Create an AWS KMS keyring */ const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({ generatorKeyId: multiRegionUsEastKey, }) /* Specify an encryption context */ const context = { purpose: 'test', } /* Create an encryption keyring */ const { result } = await encrypt(mrkEncryptKeyring, cleartext, { encryptionContext: context, })
Python

Pour chiffrer avec une clé AWS KMS multirégionale, utilisez la MRKAwareStrictAwsKmsMasterKeyProvider() méthode et spécifiez une clé multirégionale.

Pour un exemple complet, consultez le fichier mrk_aware_kms_provider.py dans le Kit SDK de chiffrement AWS pour Python référentiel sur GitHub.

* Encrypt with a multi-Region KMS key in us-east-1 Region # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT) # Specify a multi-Region key in us-east-1 mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab" # Use the multi-Region method to create the master key provider # in strict mode strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider( key_ids=[mrk_us_east_1] ) # Set the encryption context encryption_context = { "purpose": "test" } # Encrypt your plaintext data ciphertext, encrypt_header = client.encrypt( source=source_plaintext, encryption_context=encryption_context, key_provider=strict_mrk_key_provider )

Ensuite, déplacez votre texte chiffré vers la us-west-2 région. Il n'est pas nécessaire de rechiffrer le texte chiffré.

Pour déchiffrer le texte chiffré en mode strict dans la us-west-2 région, instanciez le symbole compatible avec plusieurs régions avec le code ARN de la clé multirégionale associée dans la région. us-west-2 Si vous spécifiez l'ARN d'une clé multirégionale associée dans une région différente (y compris us-east-1 celle où elle a été chiffrée), le symbole prenant en compte plusieurs régions émettra un appel interrégional pour cela. AWS KMS key

Lors du déchiffrement en mode strict, le symbole prenant en compte plusieurs régions nécessite un ARN clé. Il n'accepte qu'un seul ARN de clé pour chaque ensemble de clés multirégionales associées.

Avant d'exécuter ces exemples, remplacez l'exemple d'ARN clé multirégional par une valeur valide provenant de votreCompte AWS.

C

Pour déchiffrer en mode strict avec une clé multirégionale, utilisez la Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() méthode d'instanciation du trousseau de clés. Spécifiez la clé multirégionale associée dans la région locale (us-west-2).

Pour un exemple complet, consultez le fichier kms_multi_region_keys.cpp dans le Kit SDK de chiffrement AWS pour C référentiel sur GitHub.

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Initialize a multi-Region keyring */ const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; struct aws_cryptosdk_keyring *mrk_keyring = Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2); /* Create a session; release the keyring */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring); aws_cryptosdk_session_set_commitment_policy(session, COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT); aws_cryptosdk_keyring_release(mrk_keyring); /* Decrypt the ciphertext * aws_cryptosdk_session_process_full is designed for non-streaming data */ aws_cryptosdk_session_process_full( session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len)); /* Clean up the session */ aws_cryptosdk_session_destroy(session);
C# / .NET

Pour déchiffrer en mode strict avec une seule clé multirégionale, utilisez les mêmes constructeurs et méthodes que ceux que vous avez utilisés pour assembler l'entrée et créer le trousseau de clés à chiffrer. Instanciez un CreateAwsKmsMrkKeyringInput objet avec l'ARN clé d'une clé multirégionale associée et un AWS KMS client pour la région USA Ouest (Oregon) (us-west-2). Utilisez ensuite la CreateAwsKmsMrkKeyring() méthode pour créer un trousseau de clés multirégions avec une clé KMS multirégionale.

Pour un exemple complet, consultez AwsKmsMrkKeyringExample.cs dans le référentiel AWS Encryption SDK for .NET sur GitHub.

// Decrypt with a related multi-Region KMS key in us-west-2 Region // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Specify the key ARN of the multi-Region key in us-west-2 string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Instantiate the keyring input // You can specify the Region or get the Region from the key ARN var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2), KmsKeyId = mrkUSWest2 }; // Create the multi-Region keyring var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput); // Decrypt the ciphertext var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = mrkDecryptKeyring }; var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

Pour déchiffrer avec la clé multirégionale associée dans la région us-west-2, utilisez l'attribut key du --wrapping-keys paramètre pour spécifier son ARN clé.

# Decrypt with a related multi-Region KMS key in us-west-2 Region # To run this example, replace the fictitious key ARN with a valid value. $ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys key=$mrkUSWest2 \ --commitment-policy require-encrypt-require-decrypt \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output .
Java

Pour déchiffrer en mode strict, instanciez une clé multirégionale AwsKmsMrkAwareMasterKeyProvider et spécifiez-la dans la région locale (us-west-2).

Pour un exemple complet, voir BasicMultiRegionKeyEncryptionExample.java dans le Kit SDK de chiffrement AWS pour Java référentiel sur GitHub.

// Decrypt with a related multi-Region KMS key in us-west-2 Region // Instantiate the client final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field. String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"; // Use the multi-Region method to create the master key provider // in strict mode AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder() .buildStrict(mrkUSWest2); // Decrypt your ciphertext CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData( kmsMrkProvider, ciphertext); byte[] decrypted = decryptResult.getResult();
JavaScript Browser

Pour déchiffrer en mode strict, utilisez la buildAwsKmsMrkAwareStrictMultiKeyringBrowser() méthode pour créer le trousseau de clés et spécifiez la clé multirégionale associée dans la région locale (us-west-2).

Pour un exemple complet, consultez kms_multi_region_simple.ts dans le référentiel sur. Kit SDK de chiffrement AWS pour JavaScript GitHub

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */ import { buildAwsKmsMrkAwareStrictMultiKeyringBrowser, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-browser' /* Instantiate an AWS Encryption SDK client */ const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } /* Instantiate an AWS KMS client * The Kit SDK de chiffrement AWS pour JavaScript gets the Region from the key ARN */ const clientProvider = (region: string) => new KMS({ region, credentials }) /* Specify a multi-Region key in us-west-2 */ const multiRegionUsWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Instantiate the keyring */ const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({ generatorKeyId: multiRegionUsWestKey, clientProvider, }) /* Decrypt the data */ const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)
JavaScript Node.js

Pour déchiffrer en mode strict, utilisez la buildAwsKmsMrkAwareStrictMultiKeyringNode() méthode pour créer le trousseau de clés et spécifiez la clé multirégionale associée dans la région locale (us-west-2).

Pour un exemple complet, consultez kms_multi_region_simple.ts dans le référentiel sur. Kit SDK de chiffrement AWS pour JavaScript GitHub

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */ import { buildClient } from '@aws-crypto/client-node' /* Instantiate the client const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) /* Multi-Region keys have a distinctive key ID that begins with 'mrk' * Specify a multi-Region key in us-east-1 */ const multiRegionUsWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab' /* Create an AWS KMS keyring */ const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({ generatorKeyId: multiRegionUsWestKey, }) /* Decrypt your ciphertext */ const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)
Python

Pour déchiffrer en mode strict, utilisez la MRKAwareStrictAwsKmsMasterKeyProvider() méthode de création du fournisseur de clé principale. Spécifiez la clé multirégionale associée dans la région locale (us-west-2).

Pour un exemple complet, consultez le fichier mrk_aware_kms_provider.py dans le Kit SDK de chiffrement AWS pour Python référentiel sur GitHub.

# Decrypt with a related multi-Region KMS key in us-west-2 Region # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT) # Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab" # Use the multi-Region method to create the master key provider # in strict mode strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider( key_ids=[mrk_us_west_2] ) # Decrypt your ciphertext plaintext, _ = client.decrypt( source=ciphertext, key_provider=strict_mrk_key_provider )

Vous pouvez également déchiffrer en mode découverte à l'aide de clés AWS KMS multirégionales. Lorsque vous déchiffrez en mode découverte, vous n'en spécifiez aucune. AWS KMS keys (Pour plus d'informations sur les porte-clés de AWS KMS découverte d'une seule région, consultezUtilisation d'un porte-clés de découverte AWS KMS.)

Si vous avez chiffré avec une clé multirégionale, le symbole compatible avec plusieurs régions en mode découverte essaiera de déchiffrer en utilisant une clé multirégionale associée dans la région locale. S'il n'en existe aucun, l'appel échoue. En mode découverte, aucun appel interrégional ne AWS Encryption SDK sera lancé pour la clé multirégionale utilisée pour le chiffrement.

Note

Si vous utilisez un symbole prenant en compte plusieurs régions en mode découverte pour chiffrer des données, l'opération de chiffrement échoue.

L'exemple suivant montre comment déchiffrer avec le symbole compatible avec plusieurs régions en mode découverte. Comme vous ne spécifiez pas deAWS KMS key, vous AWS Encryption SDK devez obtenir la région à partir d'une autre source. Dans la mesure du possible, spécifiez explicitement la région locale. Sinon, AWS Encryption SDK il obtient la région locale à partir de la région configurée dans le AWS SDK pour votre langage de programmation.

Avant d'exécuter ces exemples, remplacez l'exemple d'ID de compte et l'ARN de la clé multirégionale par des valeurs valides provenant de votreCompte AWS.

C

Pour déchiffrer en mode découverte avec une clé multirégionale, utilisez la Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() méthode de création du trousseau de clés et la Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() méthode de création du filtre de découverte. Pour spécifier la région locale, définissez a ClientConfiguration et spécifiez-la dans le AWS KMS client.

Pour un exemple complet, consultez le fichier kms_multi_region_keys.cpp dans le Kit SDK de chiffrement AWS pour C référentiel sur GitHub.

/* Decrypt in discovery mode with a multi-Region KMS key */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct a discovery filter for the account and partition. The * filter is optional, but it's a best practice that we recommend. */ const char *account_id = "111122223333"; const char *partition = "aws"; const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter = Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build(); /* Create an AWS KMS client in the desired region. */ const char *region = "us-west-2"; Aws::Client::ClientConfiguration client_config; client_config.region = region; const std::shared_ptr<Aws::KMS::KMSClient> kms_client = Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config); struct aws_cryptosdk_keyring *mrk_keyring = Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() .WithKmsClient(kms_client) .BuildDiscovery(region, discovery_filter); /* Create a session; release the keyring */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring); aws_cryptosdk_keyring_release(mrk_keyring); commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT /* Decrypt the ciphertext * aws_cryptosdk_session_process_full is designed for non-streaming data */ aws_cryptosdk_session_process_full( session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len)); /* Clean up the session */ aws_cryptosdk_session_destroy(session);
C# / .NET

Pour créer un jeu de clés de découverte prenant en compte plusieurs régions dans .NET, instanciez un CreateAwsKmsMrkDiscoveryKeyringInput objet qui prend un AWS KMS client pour une destination spécifique et un filtre de découverte facultatif qui limite les clés KMS à une partition et à un compte particuliersRégion AWS. AWS Encryption SDK AWS Appelez ensuite la CreateAwsKmsMrkDiscoveryKeyring() méthode avec l'objet d'entrée. Pour un exemple complet, consultez AwsKmsMrkDiscoveryKeyringExample.cs dans le référentiel AWS Encryption SDK for .NET sur GitHub.

Pour créer un trousseau de clés de découverte compatible avec plusieurs régions pour plusieursRégion AWS, utilisez la CreateAwsKmsMrkDiscoveryMultiKeyring() méthode pour créer un trousseau de clés multirégional, ou utilisez-la pour créer plusieurs trousseaux de découverte compatibles avec plusieurs régions, puis utilisez-la CreateAwsKmsMrkDiscoveryKeyring() pour les combiner dans un trousseau de clés multirégional. CreateMultiKeyring()

Pour un exemple, consultez AwsKmsMrkDiscoveryMultiKeyringExample.cs.

// Decrypt in discovery mode with a multi-Region KMS key // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); List<string> account = new List<string> { "111122223333" }; // Instantiate the discovery filter DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter() { AccountIds = account, Partition = "aws" } // Create the keyring var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2), DiscoveryFilter = mrkDiscoveryFilter }; var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput); // Decrypt the ciphertext var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = mrkDiscoveryKeyring }; var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

Pour déchiffrer en mode découverte, utilisez l'attribut de découverte du --wrapping-keys paramètre. Les attributs discovery-account et discovery-partition créent un filtre de découverte facultatif mais recommandé.

Pour spécifier la région, cette commande inclut l'attribut de région du --wrapping-keys paramètre.

# Decrypt in discovery mode with a multi-Region KMS key $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys discovery=true \ discovery-account=111122223333 \ discovery-partition=aws \ region=us-west-2 \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output .
Java

Pour spécifier la région locale, utilisez le builder().withDiscoveryMrkRegion paramètre. Sinon, AWS Encryption SDK il obtient la région locale à partir de la région configurée dans le AWS SDK for Java.

Pour un exemple complet, voir DiscoveryMultiRegionDecryptionExample.java dans le Kit SDK de chiffrement AWS pour Java référentiel sur GitHub.

// Decrypt in discovery mode with a multi-Region KMS key // Instantiate the client final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333); AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider .builder() .withDiscoveryMrkRegion(Region.US_WEST_2) .buildDiscovery(discoveryFilter); // Decrypt your ciphertext final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto .decryptData(mrkDiscoveryProvider, ciphertext);
JavaScript Browser

Pour déchiffrer en mode découverte avec une clé multirégionale symétrique, utilisez la méthode. AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser()

Pour un exemple complet, consultez kms_multi_region_discovery.ts dans le référentiel sur. Kit SDK de chiffrement AWS pour JavaScript GitHub

/* Decrypt in discovery mode with a multi-Region KMS key */ import { AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-browser' /* Instantiate an AWS Encryption SDK client */ const { decrypt } = buildClient() declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } /* Instantiate the KMS client with an explicit Region */ const client = new KMS({ region: 'us-west-2', credentials }) /* Create a discovery filter */ const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] } /* Create an AWS KMS discovery keyring */ const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({ client, discoveryFilter, }) /* Decrypt the data */ const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)
JavaScript Node.js

Pour déchiffrer en mode découverte avec une clé multirégionale symétrique, utilisez la méthode. AwsKmsMrkAwareSymmetricDiscoveryKeyringNode()

Pour un exemple complet, consultez kms_multi_region_discovery.ts dans le référentiel sur. Kit SDK de chiffrement AWS pour JavaScript GitHub

/* Decrypt in discovery mode with a multi-Region KMS key */ import { AwsKmsMrkAwareSymmetricDiscoveryKeyringNode, buildClient, CommitmentPolicy, KMS, } from '@aws-crypto/client-node' /* Instantiate the Encryption SDK client const { decrypt } = buildClient() /* Instantiate the KMS client with an explicit Region */ const client = new KMS({ region: 'us-west-2' }) /* Create a discovery filter */ const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] } /* Create an AWS KMS discovery keyring */ const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({ client, discoveryFilter, }) /* Decrypt your ciphertext */ const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)
Python

Pour déchiffrer en mode découverte avec une clé multirégionale, utilisez la MRKAwareDiscoveryAwsKmsMasterKeyProvider() méthode.

Pour un exemple complet, consultez le fichier mrk_aware_kms_provider.py dans le Kit SDK de chiffrement AWS pour Python référentiel sur GitHub.

# Decrypt in discovery mode with a multi-Region KMS key # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient() # Create the discovery filter and specify the region decrypt_kwargs = dict( discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"), discovery_region="us-west-2", ) # Use the multi-Region method to create the master key provider # in discovery mode mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs) # Decrypt your ciphertext plaintext, _ = client.decrypt( source=ciphertext, key_provider=mrk_discovery_key_provider )

Choix d'une suite d'algorithmes

Il AWS Encryption SDK prend en charge plusieurs algorithmes de chiffrement symétriques et asymétriques pour chiffrer vos clés de données sous les clés d'encapsulation que vous spécifiez. Toutefois, lorsqu'il utilise ces clés de données pour chiffrer vos données, il utilise AWS Encryption SDK par défaut une suite d'algorithmes recommandée qui utilise l'algorithme AES-GCM avec dérivation de clés, signatures numériques et engagement des clés. Bien que la suite d'algorithmes par défaut soit susceptible de convenir à la plupart des applications, vous pouvez choisir une autre suite d'algorithmes. Par exemple, certains modèles de confiance seraient satisfaits par une suite d'algorithmes sans signature numérique. Pour plus d'informations sur les suites d'algorithmes prises AWS Encryption SDK en charge, consultezSuites d'algorithmes prises en charge dans le kit AWS Encryption SDK.

Les exemples suivants vous montrent comment sélectionner une autre suite d'algorithmes lors du chiffrement. Ces exemples sélectionnent une suite d'algorithmes AES-GCM recommandée avec dérivation de clés et engagement de clés, mais sans signatures numériques. Lorsque vous chiffrez avec une suite d'algorithmes qui n'inclut pas de signatures numériques, utilisez le mode de déchiffrement uniquement non signé lors du déchiffrement. Ce mode, qui échoue en cas de détection d'un texte chiffré signé, est particulièrement utile lors du déchiffrement en continu.

C

Pour spécifier une autre suite d'algorithmes dans leKit SDK de chiffrement AWS pour C, vous devez créer un CMM de manière explicite. Utilisez ensuite le aws_cryptosdk_default_cmm_set_alg_id avec le CMM et la suite d'algorithmes sélectionnée.

/* Specify an algorithm suite without signing */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct an AWS KMS keyring */ struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn); /* To set an alternate algorithm suite, create an cryptographic materials manager (CMM) explicitly */ struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring); aws_cryptosdk_keyring_release(kms_keyring); /* Specify the algorithm suite for the CMM */ aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY); /* Construct the session with the CMM, then release the CMM reference */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm); aws_cryptosdk_cmm_release(cmm); /* Encrypt the data Use aws_cryptosdk_session_process_full with non-streaming data */ if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full( session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len)) { aws_cryptosdk_session_destroy(session); return AWS_OP_ERR; }

Lorsque vous déchiffrez des données chiffrées sans signature numérique, utilisez. AWS_CRYPTOSDK_DECRYPT_UNSIGNED Cela entraîne l'échec du déchiffrement s'il rencontre un texte chiffré signé.

/* Decrypt unsigned streaming data */ /* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct an AWS KMS keyring */ struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn); /* Create a session for decrypting with the AWS KMS keyring Then release the keyring reference */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring); aws_cryptosdk_keyring_release(kms_keyring); if (!session) { return AWS_OP_ERR; } /* Limit encrypted data keys */ aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1); /* Decrypt Use aws_cryptosdk_session_process_full with non-streaming data */ if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full( session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len)) { aws_cryptosdk_session_destroy(session); return AWS_OP_ERR; }
C# / .NET

Pour spécifier une autre suite d'algorithmes dans AWS Encryption SDK .NET, spécifiez la AlgorithmSuiteId propriété d'un EncryptInputobjet. Le AWS Encryption SDK for .NET inclut des constantes que vous pouvez utiliser pour identifier votre suite d'algorithmes préférée.

AWS Encryption SDKfor .NET ne dispose pas de méthode permettant de détecter le texte chiffré signé lors du déchiffrement en continu, car cette bibliothèque ne prend pas en charge le streaming de données.

// Specify an algorithm suite without signing // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Create the keyring var keyringInput = new CreateAwsKmsKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), KmsKeyId = keyArn }; var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput); // Encrypt your plaintext data var encryptInput = new EncryptInput { Plaintext = plaintext, Keyring = keyring, AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY }; var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

Lors du chiffrement du hello.txt fichier, cet exemple utilise le --algorithm paramètre pour spécifier une suite d'algorithmes sans signatures numériques.

# Specify an algorithm suite without signing # 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 $ aws-encryption-cli --encrypt \ --input hello.txt \ --wrapping-keys key=$keyArn \ --algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt \ --output hello.txt.encrypted \ --decode

Lors du déchiffrement, cet exemple utilise le paramètre. --decrypt-unsigned Ce paramètre est recommandé pour garantir que vous déchiffrez du texte chiffré non signé, en particulier avec la CLI, qui diffuse toujours les entrées et les sorties.

# Decrypt unsigned streaming data # 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 $ aws-encryption-cli --decrypt-unsigned \ --input hello.txt.encrypted \ --wrapping-keys key=$keyArn \ --max-encrypted-data-keys 1 \ --commitment-policy require-encrypt-require-decrypt \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output .
Java

Pour spécifier une autre suite d'algorithmes, utilisez la AwsCrypto.builder().withEncryptionAlgorithm() méthode. Cet exemple indique une suite d'algorithmes alternative sans signatures numériques.

// Specify an algorithm suite without signing // Instantiate the client AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) .build(); String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Create a master key provider in strict mode KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder() .buildStrict(awsKmsKey); // Create an encryption context to identify this ciphertext Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming"); // Encrypt your plaintext data CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData( masterKeyProvider, sourcePlaintext, encryptionContext); byte[] ciphertext = encryptResult.getResult();

Lorsque vous diffusez des données à des fins de déchiffrement, utilisez cette createUnsignedMessageDecryptingStream() méthode pour vous assurer que tout le texte chiffré que vous décryptez n'est pas signé.

// Decrypt unsigned streaming data // Instantiate the client AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .withMaxEncryptedDataKeys(1) .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); // Decrypt the encrypted message FileInputStream in = new FileInputStream(srcFile + ".encrypted"); CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in); // Return the plaintext data // Write the plaintext data to disk FileOutputStream out = new FileOutputStream(srcFile + ".decrypted"); IOUtils.copy(decryptingStream, out); decryptingStream.close();
JavaScript Browser

Pour spécifier une autre suite d'algorithmes, utilisez le suiteId paramètre avec une valeur AlgorithmSuiteIdentifier enum.

// Specify an algorithm suite without signing // Instantiate the client const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Specify a KMS key const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Create a keyring with the KMS key const keyring = new KmsKeyringBrowser({ generatorKeyId }) // Encrypt your plaintext data const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Lors du déchiffrement, utilisez la méthode standard. decrypt Kit SDK de chiffrement AWS pour JavaScriptdans le navigateur n'a pas de decrypt-unsigned mode car le navigateur ne prend pas en charge le streaming.

// Decrypt unsigned streaming data // Instantiate the client const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Create a keyring with the same KMS key used to encrypt const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; const keyring = new KmsKeyringBrowser({ generatorKeyId }) // Decrypt the encrypted message const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)
JavaScript Node.js

Pour spécifier une autre suite d'algorithmes, utilisez le suiteId paramètre avec une valeur AlgorithmSuiteIdentifier enum.

// Specify an algorithm suite without signing // Instantiate the client const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Specify a KMS key const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; // Create a keyring with the KMS key const keyring = new KmsKeyringNode({ generatorKeyId }) // Encrypt your plaintext data const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

Lorsque vous déchiffrez des données chiffrées sans signature numérique, utilisez Stream. decryptUnsignedMessage Cette méthode échoue si elle détecte un texte chiffré signé.

// Decrypt unsigned streaming data // Instantiate the client const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) // Create a keyring with the same KMS key used to encrypt const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; const keyring = new KmsKeyringNode({ generatorKeyId }) // Decrypt the encrypted message const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))
Python

Pour spécifier un autre algorithme de chiffrement, utilisez le algorithm paramètre avec une valeur Algorithm enum.

# Specify an algorithm suite without signing # Instantiate a client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, max_encrypted_data_keys=1) # 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 the plaintext using an alternate algorithm suite ciphertext, encrypted_message_header = client.encrypt( algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider )

Lorsque vous déchiffrez des messages chiffrés sans signature numérique, utilisez le mode decrypt-unsigned streaming, en particulier lors du déchiffrement en streaming.

# Decrypt unsigned streaming data # Instantiate the client client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, max_encrypted_data_keys=1) # 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] ) # Decrypt with decrypt-unsigned with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext: with client.stream(mode="decrypt-unsigned", source=ciphertext, key_provider=master_key_provider) as decryptor: for chunk in decryptor: plaintext.write(chunk) # Verify that the encryption context assert all( pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items() ) return ciphertext_filename, cycled_plaintext_filename

Limiter les clés de données chiffrées

Vous pouvez limiter le nombre de clés de données chiffrées dans un message chiffré. Cette fonctionnalité des meilleures pratiques peut vous aider à détecter un jeu de clés mal configuré lors du chiffrement ou un texte chiffré malveillant lors du déchiffrement. Cela évite également les appels inutiles, coûteux et potentiellement exhaustifs vers votre infrastructure clé. La limitation des clés de données chiffrées est particulièrement utile lorsque vous décryptez des messages provenant d'une source non fiable.

Bien que la plupart des messages chiffrés comportent une clé de données chiffrée pour chaque clé d'encapsulation utilisée dans le chiffrement, un message chiffré peut contenir jusqu'à 65 535 clés de données chiffrées. Un acteur malveillant peut créer un message chiffré avec des milliers de clés de données chiffrées, dont aucune ne peut être déchiffrée. Par conséquent, ils AWS Encryption SDK essaieraient de déchiffrer chaque clé de données chiffrée jusqu'à épuisement des clés de données chiffrées contenues dans le message.

Pour limiter les clés de données chiffrées, utilisez le MaxEncryptedDataKeys paramètre. Ce paramètre est disponible pour tous les langages de programmation pris en charge à partir de la version 1.9. x et 2.2. x duAWS Encryption SDK. Il est facultatif et valide lors du chiffrement et du déchiffrement. Les exemples suivants déchiffrent des données chiffrées sous trois clés d'encapsulation différentes. La MaxEncryptedDataKeys valeur est définie sur 3.

C
/* Load error strings for debugging */ aws_cryptosdk_load_error_strings(); /* Construct an AWS KMS keyring */ struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 }); /* Create a session */ struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring); aws_cryptosdk_keyring_release(kms_keyring); /* Limit encrypted data keys */ aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3); /* Decrypt */ size_t ciphertext_consumed_output; aws_cryptosdk_session_process(session, plaintext_output, plaintext_buf_sz_output, &plaintext_len_output, ciphertext_input, ciphertext_len_input, &ciphertext_consumed_output); assert(aws_cryptosdk_session_is_done(session)); assert(ciphertext_consumed == ciphertext_len);
C# / .NET

Pour limiter les clés de données chiffrées dans le AWS Encryption SDK pour .NET, instanciez un client AWS Encryption SDK pour .NET et définissez son MaxEncryptedDataKeys paramètre facultatif sur la valeur souhaitée. Appelez ensuite la Decrypt() méthode sur l'AWS Encryption SDKinstance configurée.

// Decrypt with limited data keys // Instantiate the material providers var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); // Configure the commitment policy on the AWS Encryption SDK instance var config = new AwsEncryptionSdkConfig { MaxEncryptedDataKeys = 3 }; var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config); // Create the keyring string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; var createKeyringInput = new CreateAwsKmsKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), KmsKeyId = keyArn }; var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput); // Decrypt the ciphertext var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = decryptKeyring }; var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI
# Decrypt with limited encrypted data keys $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \ --buffer \ --max-encrypted-data-keys 3 \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output .
Java
// Construct a client with limited encrypted data keys final AwsCrypto crypto = AwsCrypto.builder() .withMaxEncryptedDataKeys(3) .build(); // Create an AWS KMS master key provider final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder() .buildStrict(keyArn1, keyArn2, keyArn3); // Decrypt final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)
JavaScript Browser
// Construct a client with limited encrypted data keys const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 }) declare const credentials: { accessKeyId: string secretAccessKey: string sessionToken: string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } }) // Create an AWS KMS keyring const keyring = new KmsKeyringBrowser({ clientProvider, keyIds: [keyArn1, keyArn2, keyArn3], }) // Decrypt const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
JavaScript Node.js
// Construct a client with limited encrypted data keys const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 }) // Create an AWS KMS keyring const keyring = new KmsKeyringBrowser({ keyIds: [keyArn1, keyArn2, keyArn3], }) // Decrypt const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
Python
# Instantiate a client with limited encrypted data keys client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3) # Create an AWS KMS master key provider master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider( key_ids=[key_arn1, key_arn2, key_arn3]) # Decrypt plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

Création d'un filtre de découverte

Lorsque vous déchiffrez des données chiffrées à l'aide de clés KMS, il est recommandé de les déchiffrer en mode strict, c'est-à-dire de limiter les clés d'encapsulation utilisées à celles que vous spécifiez. Toutefois, si nécessaire, vous pouvez également déchiffrer en mode découverte, dans lequel vous ne spécifiez aucune clé d'encapsulation. Dans ce mode, AWS KMS vous pouvez déchiffrer la clé de données chiffrée à l'aide de la clé KMS qui l'a chiffrée, indépendamment de qui possède ou a accès à cette clé KMS.

Si vous devez déchiffrer en mode découverte, nous vous recommandons de toujours utiliser un filtre de découverte, qui limite les clés KMS pouvant être utilisées à celles d'une partition Compte AWS et spécifiée. Le filtre de découverte est facultatif, mais il s'agit d'une bonne pratique.

Utilisez le tableau suivant pour déterminer la valeur de partition de votre filtre de découverte.

Région Partition
Régions AWS aws
Régions de Chine aws-cn
AWS GovCloud (US) Regions aws-us-gov

Les exemples présentés dans cette section montrent comment créer un filtre de découverte. Avant d'utiliser le code, remplacez les valeurs d'exemple par des valeurs valides pour la partition Compte AWS and.

C

Pour des exemples complets, consultez le fichier kms_discovery.cpp dans leKit SDK de chiffrement AWS pour C.

/* Create a discovery filter for an AWS account and partition */ const char *account_id = "111122223333"; const char *partition = "aws"; const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter = Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();
C# / .NET

Pour un exemple complet, voir DiscoveryFilterExample.cs dans le fichier AWS Encryption SDK pour .NET.

// Create a discovery filter for an AWS account and partition List<string> account = new List<string> { "111122223333" }; DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter() { AccountIds = account, Partition = "aws" }
AWS Encryption CLI
# Decrypt in discovery mode with a discovery filter $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --wrapping-keys discovery=true \ discovery-account=111122223333 \ discovery-partition=aws \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output .
Java

Pour un exemple complet, voir DiscoveryDecryptionExample.java dans leKit SDK de chiffrement AWS pour Java.

// Create a discovery filter for an AWS account and partition DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
JavaScript (Node and Browser)

Pour des exemples complets, consultez kms_filtered_discovery.ts (Node.js) et kms_multi_region_discovery.ts (navigateur) dans le. Kit SDK de chiffrement AWS pour JavaScript

/* Create a discovery filter for an AWS account and partition */ const discoveryFilter = { accountIDs: ['111122223333'], partition: 'aws', }
Python

Pour un exemple complet, consultez le fichier discovery_kms_provider.py dans leKit SDK de chiffrement AWS pour Python.

# Create the discovery filter and specify the region decrypt_kwargs = dict( discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"), discovery_region="us-west-2", )

Définition d'une politique d'engagement

Une politique d'engagement est un paramètre de configuration qui détermine si votre application chiffre et déchiffre avec un engagement clé. Le chiffrement et le déchiffrement avec un engagement clé constituent une bonne pratique. AWS Encryption SDK

La définition et l'ajustement de votre politique d'engagement constituent une étape essentielle de la migration depuis les versions 1.7. x et versions antérieures AWS Encryption SDK à la version 2.0. x et versions ultérieures. Cette progression est expliquée en détail dans la rubrique relative à la migration.

La valeur de la politique d'engagement par défaut dans les dernières versions du AWS Encryption SDK (à partir de la version 2.0). x)RequireEncryptRequireDecrypt, est idéal pour la plupart des situations. Toutefois, si vous devez déchiffrer un texte chiffré sans engagement de clé, vous devrez peut-être modifier votre politique d'engagement en. RequireEncryptAllowDecrypt Pour des exemples de définition d'une politique d'engagement dans chaque langage de programmation, voirDéfinition de votre politique d'engagement.

Utilisation de données en streaming

Lorsque vous diffusez des données à des fins de déchiffrement, sachez que le texte brut AWS Encryption SDK renvoyé est déchiffré une fois les contrôles d'intégrité terminés, mais avant que la signature numérique ne soit vérifiée. Pour vous assurer de ne pas renvoyer ou utiliser du texte en clair tant que la signature n'est pas vérifiée, nous vous recommandons de mettre en mémoire tampon le texte en clair diffusé jusqu'à ce que le processus de déchiffrement soit complet.

Ce problème se produit uniquement lorsque vous diffusez du texte chiffré à des fins de déchiffrement, et uniquement lorsque vous utilisez une suite d'algorithmes, telle que la suite d'algorithmes par défaut, qui inclut des signatures numériques.

Pour faciliter la mise en mémoire tampon, certaines implémentations de AWS Encryption SDK langage, comme Kit SDK de chiffrement AWS pour JavaScript dans Node.js, incluent une fonctionnalité de mise en mémoire tampon dans le cadre de la méthode de déchiffrement. La CLI de AWS chiffrement, qui diffuse toujours les entrées et les sorties, a introduit un --buffer paramètre dans les versions 1.9. x et 2.2. x. Dans d'autres implémentations linguistiques, vous pouvez utiliser les fonctionnalités de mise en mémoire tampon existantes. (Le AWS Encryption SDK pour .NET ne prend pas en charge le streaming.)

Si vous utilisez une suite d'algorithmes sans signature numérique, veillez à utiliser decrypt-unsigned cette fonctionnalité dans chaque implémentation de langage. Cette fonctionnalité déchiffre le texte chiffré mais échoue en cas de détection de texte chiffré signé. Pour plus de détails, consultez Choix d'une suite d'algorithmes.

Mise en cache des clés de données

En général, la réutilisation des clés de données est déconseillée, mais AWS Encryption SDK propose une option de mise en cache des clés de données qui permet une réutilisation limitée des clés de données. La mise en cache des clés de données peut améliorer les performances de certaines applications et réduire les appels vers votre infrastructure clé. Avant d'utiliser la mise en cache des clés de données en production, ajustez les seuils de sécurité et testez pour vous assurer que les avantages l'emportent sur les inconvénients de la réutilisation des clés de données.