Configuration du AWS Encryption SDK - AWS Encryption SDK
Sélection d'un langage de programmationSélection des clés d'emballageUtilisation de plusieurs régions AWS KMS keysChoisir une suite d'algorithmesLimiter les clés de données chiffréesCréation d'un filtre de découverteDéfinir une politique d'engagementUtilisation de données en streamingMise en cache des clés de données

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 SDK Il 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 implémentez-en autant que possible.

Sélection d'un langage de programmation

AWS Encryption SDK Il 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 le Kit SDK de chiffrement AWS pour JavaScript.

Sélection des clés d'emballage

AWS Encryption SDK Gé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. AWS Encryption SDK Supporte les touches AES symétriques et RSA asymétriques 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 que AWS 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, AWS EncryptionCLI). 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 Service développeur.

  • Lorsque vous chiffrez avec le Kit SDK de chiffrement AWS pour Java, Kit SDK de chiffrement AWS pour JavaScript Kit SDK de chiffrement AWS pour Python, ou le AWS chiffrementCLI, vous pouvez utiliser n'importe quel identifiant de clé valide (identifiant de clé, cléARN, nom d'alias ou aliasARN) pour une KMS clé. Lorsque vous chiffrez avec le Kit SDK de chiffrement AWS pour C, vous ne pouvez utiliser qu'un identifiant ou une cléARN.

    Si vous spécifiez un nom d'alias ou un alias ARN pour une KMS clé lors du chiffrement AWS Encryption SDK , la clé ARN actuellement associée à cet alias est enregistrée, mais pas l'alias. Les modifications apportées à l'alias n'affectent pas la KMS clé 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 une clé ARN pour vous 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, la clé est AWS Encryption SDK stockée AWS KMS key dans les métadonnées ARN de la clé de données cryptée. Lors du déchiffrement en mode strict, il AWS Encryption SDK vérifie que la même clé ARN 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'utilisera AWS KMS key, même si les identifiants font référence à la même clé.

Pour spécifier une AESclé brute ou une paire de RSA clés brutes 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 le AWS 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 du AWS chiffrementCLI.

AWS KMS Les 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 Service dé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 multi-Region-aware symbole de chaque langage de programmation prend en charge les touches mono-régionales et multirégionales.

  • Pour les clés à région unique, le multi-Region-aware symbole se comporte comme le porte-clés à région unique et le fournisseur de AWS KMS 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 multi-Region-aware symbole tente de déchiffrer le texte chiffré avec la même clé multirégionale qui a chiffré les données ou avec la clé de réplique multirégionale associée dans la région que vous spécifiez.

Dans les multi-Region-aware trousseaux de clés et les fournisseurs de clés principales qui utilisent plusieurs KMS clés, vous pouvez spécifier plusieurs clés à région unique ou multirégionale. Toutefois, vous ne pouvez spécifier qu'une seule clé pour chaque ensemble de clés répliques 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 multi-Region-aware trousseaux de clés et fournisseurs de clés principales. 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 de réplication multirégionales associées dans chaque région. Avant d'exécuter ces exemples, remplacez l'exemple de clé multirégionale ARN par une valeur valide provenant de votre Compte 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 utilisant 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, voir AwsKmsMrkKeyringExample.cs dans le formulaire AWS Encryption SDK . NETréférentiel 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. Comme l'exemple spécifie une clé ARN 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.javadans le 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 multi-Region-aware symbole avec la clé de la clé multirégionale correspondante dans ARN la région. us-west-2 Si vous spécifiez la clé 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 multi-Region-aware symbole émettra un appel interrégional pour cela. AWS KMS key

Lors du déchiffrement en mode strict, le multi-Region-aware symbole nécessite une clé. ARN Il n'accepte qu'une seule clé ARN de chaque ensemble de clés multirégionales associées.

Avant d'exécuter ces exemples, remplacez l'exemple de clé multirégionale ARN par une valeur valide provenant de votre Compte 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 la clé ARN 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, voir AwsKmsMrkKeyringExample.cs dans le formulaire AWS Encryption SDK . NETréférentiel 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 paramètre pour spécifier sa clé. --wrapping-keys ARN 

# 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-west-2
 */
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 AWS KMS Discovery.)

Si vous avez chiffré avec une clé multirégionale, le multi-Region-aware symbole en mode découverte essaiera de le 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 multi-Region-aware symbole en mode découverte pour chiffrer des données, l'opération de chiffrement échoue.

L'exemple suivant montre comment déchiffrer avec le multi-Region-aware symbole en mode découverte. Comme vous ne spécifiez pas de AWS 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 AWS SDK pour votre langage de programmation.

Avant d'exécuter ces exemples, remplacez l'exemple d'ID de compte et de clé multirégionale par ARN des valeurs valides provenant de votre Compte 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 porte-clés de multi-Region-aware découverte dans le formulaire AWS Encryption SDK . NET, instanciez un CreateAwsKmsMrkDiscoveryKeyringInput objet qui prend un AWS KMS client pour un compte spécifique Région AWS, et un filtre de découverte facultatif qui limite les KMS clés à une AWS partition et à un compte particuliers. Appelez ensuite la CreateAwsKmsMrkDiscoveryKeyring() méthode avec l'objet d'entrée. Pour un exemple complet, voir AwsKmsMrkDiscoveryKeyringExample.cs dans le formulaire AWS Encryption SDK . NETréférentiel sur GitHub.

Pour créer un trousseau de clés de multi-Region-aware découverte pour plusieurs Région AWS, utilisez la CreateAwsKmsMrkDiscoveryMultiKeyring() méthode pour créer un porte-clés multiple, ou utilisez-la CreateAwsKmsMrkDiscoveryKeyring() pour créer plusieurs trousseaux de multi-Region-aware découverte, puis utilisez-la pour les combiner dans un trousseau de clés multiples. 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 à l'aide d'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
)

Choisir 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'GCMalgorithme AES - avec dérivation de clés, signatures numériques et engagement clé. 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'GCMalgorithmes recommandée AES 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 le Kit SDK de chiffrement AWS pour C, vous devez créer une suite CMM explicite. Utilisez ensuite le aws_cryptosdk_default_cmm_set_alg_id avec 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 le AWS Encryption SDK formulaire. NET, spécifiez la AlgorithmSuiteId propriété d'un EncryptInputobjet. Le AWS Encryption SDK pour. NETinclut des constantes que vous pouvez utiliser pour identifier votre suite d'algorithmes préférée.

Le AWS Encryption SDK pour. NETne 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 leCLI, qui diffuse toujours des entrées et des 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 JavaScript dans 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é basée sur les 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 du AWS 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 AWS Encryption SDK le formulaire. NET, instanciez un client pour. AWS Encryption SDK NETet définissez son MaxEncryptedDataKeys paramètre facultatif sur la valeur souhaitée. Appelez ensuite la Decrypt() méthode sur l' AWS Encryption SDK instance 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 KMS clés, 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 cryptée à l'aide de la KMS clé qui l'a chiffrée, indépendamment de qui possède ou a accès à cette KMS clé.

Si vous devez déchiffrer en mode découverte, nous vous recommandons de toujours utiliser un filtre de découverte, qui limite les KMS clés 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 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 le Kit 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 formulaire AWS Encryption SDK . 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 le Kit 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 le Kit 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éfinir 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 éviter de renvoyer ou d'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. Le AWS chiffrementCLI, 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. NETne 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 Choisir 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.