Configuration du AWS Encryption SDK

PDFRSS

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. 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 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, 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 Service développeur.

• Lors du chiffrement à l' Kit SDK de chiffrement AWS pour Java aide 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 le Kit 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 SDK enregistre 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'utilisera AWS 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 le AWS Encryption SDK. Si vous chiffrez avec une clé multirégionale dans une clé Région AWS, vous pouvez déchiffrer à l'aide d'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 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 acceptent plusieurs clés KMS, 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 d'ARN clé multirégional 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 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 à l'aide d'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 symbole multi-Region-aware 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 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 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 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 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 paramètre pour spécifier son ARN clé. --wrapping-keys

# 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 dans le AWS SDK pour votre langage de programmation.

Avant d'exécuter ces exemples, remplacez l'exemple d'ID de compte et d'ARN de la clé multirégionale par 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 jeu de clés de multi-Region-aware découverte dans .NET, instanciez un CreateAwsKmsMrkDiscoveryKeyringInput objet qui prend un AWS KMS client pour un compte en particulier Région AWS et un filtre de découverte facultatif qui limite les clés KMS à une AWS partition et à un compte particuliers. AWS Encryption SDK 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 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
)

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 le Kit 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 SDK for .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 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

Rust

Pour spécifier une suite d'algorithmes alternative dans AWS Encryption SDK for Rust, spécifiez la algorithm_suite_id propriété dans votre demande de chiffrement.

// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;

// Define the key namespace and key name
let key_namespace: &str = "HSM_01";
let key_name: &str = "AES_256_012";

// Optional: Create an encryption context
let encryption_context = HashMap::from([
    ("encryption".to_string(), "context".to_string()),
    ("is not".to_string(), "secret".to_string()),
    ("but adds".to_string(), "useful metadata".to_string()),
    ("that can help you".to_string(), "be confident that".to_string()),
    ("the data you are handling".to_string(), "is what you think it is".to_string()),
]);

// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;

// Create Raw AES keyring
let raw_aes_keyring = mpl
    .create_raw_aes_keyring()
    .key_name(key_name)
    .key_namespace(key_namespace)
    .wrapping_key(aws_smithy_types::Blob::new(AESWrappingKey))
    .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
    .send()
    .await?;
                    
// Encrypt your plaintext data
let plaintext = example_data.as_bytes();

let encryption_response = esdk_client.encrypt()
    .plaintext(plaintext)
    .keyring(raw_aes_keyring.clone())
    .encryption_context(encryption_context.clone())
    .algorithm_suite_id(AlgAes256GcmHkdfSha512CommitKey)
    .send()
    .await?;

Go

import (
    "context"

	mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
	mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
	client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
	esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
)
// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
    panic(err)
}

// Define the key namespace and key name
var keyNamespace = "HSM_01"
var keyName = "AES_256_012"

// Optional: Create an encryption context
encryptionContext := map[string]string{
    "encryption":                "context",
    "is not":                    "secret",
    "but adds":                  "useful metadata",
    "that can help you":         "be confident that",
    "the data you are handling": "is what you think it is",
}

// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
    panic(err)
}

// Create Raw AES keyring
aesKeyRingInput := mpltypes.CreateRawAesKeyringInput{
    KeyName:      keyName,
    KeyNamespace: keyNamespace,
    WrappingKey:  key,
    WrappingAlg:  mpltypes.AesWrappingAlgAlgAes256GcmIv12Tag16,
}
aesKeyring, err := matProv.CreateRawAesKeyring(context.Background(), aesKeyRingInput)
if err != nil {
    panic(err)
}

// Encrypt your plaintext data
algorithmSuiteId := mpltypes.ESDKAlgorithmSuiteIdAlgAes256GcmHkdfSha512CommitKey
res, err := encryptionClient.Encrypt(context.Background(), esdktypes.EncryptInput{
    Plaintext:         []byte(exampleText),
    EncryptionContext: encryptionContext,
    Keyring:           aesKeyring,
    AlgorithmSuiteId:  &algorithmSuiteId,
})
if err != nil {
    panic(err)
}
                    

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 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 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)

Rust

// Instantiate the AWS Encryption SDK client with limited encrypted data keys
let esdk_config = AwsEncryptionSdkConfig::builder()
                    .max_encrypted_data_keys(max_encrypted_data_keys)
                    .build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;

// Define the key namespace and key name
let key_namespace: &str = "HSM_01";
let key_name: &str = "AES_256_012";

// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;

//  Generate `max_encrypted_data_keys` raw AES keyrings to use with your keyring
let mut raw_aes_keyrings: Vec<KeyringRef> = vec![];

assert!(max_encrypted_data_keys > 0, "max_encrypted_data_keys MUST be greater than 0");

let mut i = 0;
while i < max_encrypted_data_keys {
    let aes_key_bytes = generate_aes_key_bytes();

    let raw_aes_keyring = mpl
        .create_raw_aes_keyring()
        .key_name(key_name)
        .key_namespace(key_namespace)
        .wrapping_key(aes_key_bytes)
        .wrapping_alg(AesWrappingAlg::AlgAes256GcmIv12Tag16)
        .send()
        .await?;

    raw_aes_keyrings.push(raw_aes_keyring);
    i += 1;
}

// Create a Multi Keyring with `max_encrypted_data_keys` AES Keyrings
let generator_keyring = raw_aes_keyrings.remove(0);

let multi_keyring = mpl
    .create_multi_keyring()
    .generator(generator_keyring)
    .child_keyrings(raw_aes_keyrings)
    .send()
    .await?;

Go

import (
    "context"
    
	mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
	mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
	client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
	esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
)

// Instantiate the AWS Encryption SDK client with limited encrypted data keys
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{
    MaxEncryptedDataKeys: &maxEncryptedDataKeys,
})
if err != nil {
    panic(err)
}

// Define the key namespace and key name
var keyNamespace = "HSM_01"
var keyName = "RSA_2048_06"

// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
    panic(err)
}

//  Generate `maxEncryptedDataKeys` raw AES keyrings to use with your keyring
rawAESKeyrings := make([]mpltypes.IKeyring, 0, maxEncryptedDataKeys)
var i int64 = 0
for i < maxEncryptedDataKeys {
    key, err := generate256KeyBytesAES()
	if err != nil {
		panic(err)
	}
    aesKeyRingInput := mpltypes.CreateRawAesKeyringInput{
		KeyName:      keyName,
		KeyNamespace: keyNamespace,
		WrappingKey:  key,
		WrappingAlg:  mpltypes.AesWrappingAlgAlgAes256GcmIv12Tag16,
	}
	aesKeyring, err := matProv.CreateRawAesKeyring(context.Background(), aesKeyRingInput)
    if err != nil {
		panic(err)
	}
    rawAESKeyrings = append(rawAESKeyrings, aesKeyring)
    i++
}

// Create a Multi Keyring with `max_encrypted_data_keys` AES Keyrings
createMultiKeyringInput := mpltypes.CreateMultiKeyringInput{
    Generator:     rawAESKeyrings[0],
    ChildKeyrings: rawAESKeyrings[1:],
}
multiKeyring, err := matProv.CreateMultiKeyring(context.Background(), createMultiKeyringInput)
if err != nil {
    panic(err)
}

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 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 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 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",
    )

Rust

let discovery_filter = DiscoveryFilter::builder()
    .account_ids(vec![111122223333.to_string()])
    .partition("aws".to_string())
    .build()?;

Go

import (
	mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
)

discoveryFilter := mpltypes.DiscoveryFilter{
    AccountIds: []string{111122223333},
    Partition:  "aws",
}                    
                    

Configuration du contexte de chiffrement requis (CMM)

Vous pouvez utiliser le contexte de chiffrement requis CMM pour exiger des contextes de chiffrement dans vos opérations cryptographiques. Un contexte de chiffrement est un ensemble de paires clé-valeur non secrètes. Le contexte de chiffrement est lié cryptographiquement aux données chiffrées, de sorte que le même contexte de chiffrement est requis pour déchiffrer le champ. Lorsque vous utilisez le contexte de chiffrement requis CMM, vous pouvez spécifier une ou plusieurs clés de contexte de chiffrement requises (clés obligatoires) qui doivent être incluses dans tous les appels de chiffrement et de déchiffrement.

Note

Le contexte de chiffrement requis CMM n'est pris en charge que par les versions suivantes :

• Version 3. x du Kit SDK de chiffrement AWS pour Java

• La version 4. x du AWS Encryption SDK pour .NET

• La version 4. x du Kit SDK de chiffrement AWS pour Python, lorsqu'il est utilisé avec la dépendance optionnelle MPL (Cryptographic Material Providers Library).

• La version 0.1. x ou version ultérieure du AWS Encryption SDK for Go

Si vous chiffrez des données à l'aide du contexte de chiffrement CMM requis, vous ne pouvez les déchiffrer qu'avec l'une de ces versions prises en charge.

Lors du chiffrement, il AWS Encryption SDK vérifie que toutes les clés de contexte de chiffrement requises sont incluses dans le contexte de chiffrement que vous avez spécifié. Les AWS Encryption SDK signes indiquent les contextes de chiffrement que vous avez spécifiés. Seules les paires clé-valeur qui ne sont pas des clés obligatoires sont sérialisées et stockées en texte clair dans l'en-tête du message chiffré renvoyé par l'opération de chiffrement.

Lors du déchiffrement, vous devez fournir un contexte de chiffrement contenant toutes les paires clé-valeur représentant les clés requises. AWS Encryption SDK Utilise ce contexte de chiffrement et les paires clé-valeur stockées dans l'en-tête du message chiffré pour reconstruire le contexte de chiffrement d'origine que vous avez spécifié lors de l'opération de chiffrement. S'il AWS Encryption SDK n'est pas possible de reconstruire le contexte de chiffrement d'origine, l'opération de déchiffrement échoue. Si vous fournissez une paire clé-valeur contenant la clé requise avec une valeur incorrecte, le message chiffré ne peut pas être déchiffré. Vous devez fournir la même paire clé-valeur que celle spécifiée lors du chiffrement.

Important

Réfléchissez bien aux valeurs que vous choisissez pour les clés requises dans votre contexte de chiffrement. Vous devez être en mesure de fournir à nouveau les mêmes clés et les valeurs correspondantes lors du déchiffrement. Si vous ne parvenez pas à reproduire les clés requises, le message crypté ne peut pas être déchiffré.

Les exemples suivants initialisent un AWS KMS trousseau de clés avec le contexte de chiffrement requis CMM.

C# / .NET

var encryptionContext = new Dictionary<string, string>()
{
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsKey
};
 
// Create the keyring 
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);
        
var createCMMInput = new CreateRequiredEncryptionContextCMMInput
{
    UnderlyingCMM = mpl.CreateDefaultCryptographicMaterialsManager(new CreateDefaultCryptographicMaterialsManagerInput{Keyring = kmsKeyring}),
    // If you pass in a keyring but no underlying cmm, it will result in a failure because only cmm is supported.
    RequiredEncryptionContextKeys = new List<string>(encryptionContext.Keys)
};
 
// Create the required encryption context CMM
var requiredEcCMM = mpl.CreateRequiredEncryptionContextCMM(createCMMInput);

Java

// Instantiate the AWS Encryption SDK
final AwsCrypto crypto = AwsCrypto.builder()
        .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
        .build();
    
// Create your encryption context
final Map<String, String> encryptionContext = new HashMap<>();
encryptionContext.put("encryption", "context");
encryptionContext.put("is not", "secret");
encryptionContext.put("but adds", "useful metadata");
encryptionContext.put("that can help you", "be confident that");
encryptionContext.put("the data you are handling", "is what you think it is");    

// Create a list of required encryption contexts
final List<String> requiredEncryptionContextKeys = Arrays.asList("encryption", "context");
    
// Create the keyring
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsKeyringInput keyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(keyringInput);
    
// Create the required encryption context CMM
ICryptographicMaterialsManager cmm = 
    materialProviders.CreateDefaultCryptographicMaterialsManager(
        CreateDefaultCryptographicMaterialsManagerInput.builder()
            .keyring(kmsKeyring)
            .build()
    );
ICryptographicMaterialsManager requiredCMM = 
    materialProviders.CreateRequiredEncryptionContextCMM(
        CreateRequiredEncryptionContextCMMInput.builder()
            .requiredEncryptionContextKeys(requiredEncryptionContextKeys)
            .underlyingCMM(cmm)
            .build()
        );

Python

Pour utiliser le CMM Kit SDK de chiffrement AWS pour Python avec le contexte de chiffrement requis, vous devez également utiliser la bibliothèque des fournisseurs de matériaux (MPL).

# Instantiate the AWS Encryption SDK client
client = aws_encryption_sdk.EncryptionSDKClient(
    commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
        
# Create your encryption context
encryption_context: Dict[str, str] = {
    "key1": "value1",
    "key2": "value2",
    "requiredKey1": "requiredValue1",
    "requiredKey2": "requiredValue2"
}

# Create a list of required encryption context keys
required_encryption_context_keys: List[str] = ["requiredKey1", "requiredKey2"]

# Instantiate the material providers library
mpl: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
    config=MaterialProvidersConfig()
)

# Create the AWS KMS keyring 
 keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
    kms_key_id=kms_key_id,
    kms_client=boto3.client('kms', region_name="us-west-2")
)
kms_keyring: IKeyring = mpl.create_aws_kms_keyring(keyring_input)
      
# Create the required encryption context CMM
underlying_cmm: ICryptographicMaterialsManager = \
    mpl.create_default_cryptographic_materials_manager(
        CreateDefaultCryptographicMaterialsManagerInput(
            keyring=kms_keyring
        )
    )

required_ec_cmm: ICryptographicMaterialsManager = \
    mpl.create_required_encryption_context_cmm(
        CreateRequiredEncryptionContextCMMInput(
            required_encryption_context_keys=required_encryption_context_keys,
            underlying_cmm=underlying_cmm,
        )
    )

Rust

// Instantiate the AWS Encryption SDK client
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
        
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
    
// Create your encryption context
let encryption_context = HashMap::from([
    ("key1".to_string(), "value1".to_string()),
    ("key2".to_string(), "value2".to_string()),
    ("requiredKey1".to_string(), "requiredValue1".to_string()),
    ("requiredKey2".to_string(), "requiredValue2".to_string()),
]);

// Create a list of required encryption context keys
let required_encryption_context_keys: Vec<String> = vec![
    "requiredKey1".to_string(),
    "requiredKey2".to_string(),
];

// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;

// Create the AWS KMS keyring 
let kms_keyring = mpl
    .create_aws_kms_keyring()
    .kms_key_id(kms_key_id)
    .kms_client(kms_client)
    .send()
    .await?;

kms_multi_keyring: IKeyring = mat_prov.create_aws_kms_multi_keyring(
    input=kms_multi_keyring_input
)
                    
// Create the required encryption context CMM 
let underlying_cmm = mpl
    .create_default_cryptographic_materials_manager()
    .keyring(kms_keyring)
    .send()
    .await?;

let required_ec_cmm = mpl
    .create_required_encryption_context_cmm()
    .underlying_cmm(underlying_cmm.clone())
    .required_encryption_context_keys(required_encryption_context_keys)
    .send()
    .await?;

Go

import (
    "context"

	mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
	mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
	client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
	esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/kms"
)

// Instantiate the AWS Encryption SDK client
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{})
if err != nil {
    panic(err)
}

// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
    o.Region = defaultKmsKeyRegion
})

// Create an encryption context
encryptionContext := map[string]string{
    "encryption":                "context",
    "is not":                    "secret",
    "but adds":                  "useful metadata",
    "that can help you":         "be confident that",
    "the data you are handling": "is what you think it is",
}

// Create a list of required encryption context keys
requiredEncryptionContextKeys := []string{}
requiredEncryptionContextKeys = append(requiredEncryptionContextKeys, "requiredKey1", "requiredKey2")

// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
    panic(err)
}

// Create the AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
    KmsClient: kmsClient,
    KmsKeyId:  utils.GetDefaultKMSKeyId(),
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
    panic(err)
}

// Create the required encryption context CMM
underlyingCMM, err := matProv.CreateDefaultCryptographicMaterialsManager(context.Background(), mpltypes.CreateDefaultCryptographicMaterialsManagerInput{Keyring: awsKmsKeyring})
if err != nil {
    panic(err)
}
requiredEncryptionContextInput := mpltypes.CreateRequiredEncryptionContextCMMInput{
    UnderlyingCMM: underlyingCMM,
    RequiredEncryptionContextKeys: requiredEncryptionContextKeys,
}
requiredEC, err := matProv.CreateRequiredEncryptionContextCMM(context.Background(), requiredEncryptionContextInput)
if err != nil {
    panic(err)
}
                    

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.