Configuration du AWS Encryption SDK - AWS Encryption SDK
Sélection d'un langage de programmationSélection des clés d'emballageUtilisation de multi-régionAWS KMS keysChoisir une suite d'algorithmesLimiter les clés de données cryptéesCréation d'un filtre de découverteDéfinition d'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 SDKIl est conçu pour être facile à utiliser. Bien qu'ilAWS Encryption SDK dispose de plusieurs options de configuration, les valeurs par défaut sont soigneusement choisies pour être pratiques et sécurisées pour la plupart des applications. Toutefois, il se peut que vous deviez 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 lesAWS Encryption SDK meilleures pratiques et mettez-en en œuvre autant que possible.

Sélection d'un langage de programmation

AWS Encryption SDKIl est disponible dans plusieurs langages de programmation. Les implémentations du langage sont conçues pour être totalement interopérables et pour offrir les mêmes fonctionnalités, bien qu'elles puissent être mises en œuvre de différentes manières. En général, 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 leKit SDK de chiffrement AWS pour C ou leKit SDK de chiffrement AWS pour JavaScript.

Sélection des clés d'emballage

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

Vous devez toutefois sélectionner une ou plusieurs clés d'encapsulation pour chiffrer chaque clé de données. IlAWS 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 symétrique AWS Key Management Service(AWS KMS)AWS KMS keys. Vous êtes responsable de la sécurité et de la durabilité de vos clés d'encapsulation. Nous vous recommandons donc d'utiliser une clé de chiffrement dans un module de sécurité matériel ou un service d'infrastructure clé, tel queAWS KMS.

Pour spécifier vos clés d'encapsulation pour le chiffrement et le déchiffrement, vous utilisez un jeu de clés (C et JavaScript) ou un fournisseur de clés principales (Java, Python,AWS Encryption CLI). Vous pouvez spécifier une ou plusieurs clés d'encapsulation du même type ou de types différents. Si vous utilisez plusieurs clés d'encapsulation pour encapsuler une clé de données, chaque clé d'encapsulation cryptera une copie de la même clé de données. Les clés de données cryptées (une par clé d'encapsulation) sont stockées avec les données cryptées dans le message crypté qu'ellesAWS Encryption SDK renvoient. Pour déchiffrer les données, vousAWS 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éAWS KMS key dans un jeu de clés ou un fournisseur de clé principale, utilisez un identifiant deAWS KMS clé compatible. Pour plus de détails sur les identificateurs de clé d'uneAWS KMS clé, consultez la section Identificateurs de clé du guide duAWS Key Management Service développeur.

  • Lors du chiffrement à l'aide de l'interface de ligne de commandeKit SDK de chiffrement AWS pour JavaKit SDK de chiffrement AWS pour JavaScriptKit SDK de chiffrement AWS pour Python, ou de la CLI deAWS 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. Pour le chiffrement avec leKit SDK de chiffrement AWS pour C, vous pouvez uniquement utiliser un ID 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, leAWS Encryption SDK enregistre l'ARN de clé actuellement associé à cet alias ; il n'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'identifierAWS KMS keys. Cette exigence s'applique à toutes les implémentations de langage du kit AWS Encryption SDK.

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

Pour spécifier une clé AES brute ou une key pair RSA brute en tant que clé d'encapsulation dans un jeu de clés, vous devez spécifier un espace de noms et un nom. Dans un fournisseur de clé principale, leProvider ID est l'équivalent de l'espace de noms et 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, ils ne reconnaîtront ni n'AWS Encryption SDKutiliseront la clé d'encapsulation, même si le matériau de la clé est identique.

Utilisation de multi-régionAWS KMS keys

Vous pouvez utiliser des clés multirégionsAWS Key Management Service (AWS KMS) comme clés d'encapsulation dans leAWS Encryption SDK. Si vous chiffrez avec une clé multirégion dans une cléRégion AWS, vous pouvez le déchiffrer à l'aide d'une clé multirégion associée dans une autreRégion AWS. La prise en charge des clés multirégions est introduite dans la version 2.3. x de la version 3.0AWS Encryption SDK et. x de la CLI deAWS chiffrement.

AWS KMSLes clés multi-région sont un ensemble d'AWS KMS keyséléments différentsRégions AWS qui possèdent le même matériau de clé et le même ID de clé. Vous pouvez utiliser ces clés connexes comme s'il s'agissait de la même clé dans différentes régions. Les clés multirégions 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 d'appel interrégionalAWS KMS. Pour plus d'informations sur les clés multi-région, veuillez consulter la rubrique Utilisation de clés multi-régions dans le Guide duAWS Key Management Service développeur.

Pour prendre en charge les clés multirégions, ilAWS Encryption SDK inclut des ensembles deAWS KMS clés compatibles avec plusieurs régions et des fournisseurs de clés principales. Le nouveau symbole multi-région dans chaque langage de programmation prend en charge les clés à région unique et multi-région.

  • Pour les clés à région unique, le symbole prenant en compte plusieurs régions se comporte de la même manière que le jeu deAWS KMS clés à région unique et le fournisseur de clés principales. Il tente de déchiffrer le texte chiffré uniquement à l'aide de la clé à région unique qui a chiffré les données.

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

Dans les ensembles de clés compatibles avec plusieurs régions et les fournisseurs de clés principales qui utilisent plusieurs clés KMS, vous pouvez spécifier plusieurs clés à région unique et à régions multiples. Vous ne pouvez toutefois spécifier qu'une clé pour chaque ensemble de clés multi-région 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égion avec lesAWS KMS trousses de clés standard à région unique et les fournisseurs de clés principales. Toutefois, vous devez utiliser la même clé multirégion dans la même région pour chiffrer et déchiffrer. Les trousses de clés à région unique et les fournisseurs de clés principales tentent de déchiffrer le texte chiffré uniquement à l'aide des 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égions et des nouveaux ensembles de clés et fournisseurs de clés principales compatibles avec plusieurs régions. Ces exemples chiffrent les données de laus-east-1 région et déchiffrent les données de laus-west-2 région à l'aide de clés multirégionales associées dans chaque région. Avant d'exécuter ces exemples, remplacez l'ARN de clé multi-régions par une valeur valide de votreCompte AWS.

C

Pour chiffrer à l'aide d'une clé multirégion, utilisez laAws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() méthode permettant d'instancier le jeu de clés. Spécifiez une clé multi-région.

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 kms_multi_region_keys.cpp dans leKit 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é multi-région dans la région USA Est (Virginie du Nord) (us-east-1), instanciez unCreateAwsKmsMrkKeyringInput objet avec un identificateur de clé pour la clé multi-région et unAWS KMS client pour la région spécifiée. Utilisez ensuite laCreateAwsKmsMrkKeyring() méthode pour créer le porte-clés.

LaCreateAwsKmsMrkKeyring() méthode crée un jeu de clés contenant exactement une clé multirégion. Pour chiffrer à l'aide de plusieurs clés d'encapsulation, y compris une clé multirégion, utilisezCreateAwsKmsMrkMultiKeyring() cette méthode.

Pour un exemple complet, consultez AwsKmsMrkKeyringExample.cs dansAWS Encryption SDK le référentiel .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 lehello.txt fichier sous une clé multi-région dans la région us-east-1. Étant donné que l'exemple spécifie un ARN clé avec un élément Region, cet exemple n'utilise pas l'attribut region du--wrapping-keys paramètre.

Lorsque l'ID de la clé d'encapsulation ne spécifie pas de région, vous pouvez utiliser l'attribut de région du--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égion, instanciez une clé multirégionAwsKmsMrkAwareMasterKeyProvider et spécifiez-la.

Pour un exemple complet, consultez BasicMultiRegionKeyEncryptionExample.java dans leKit 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 à l'aide d'une clé multirégion, utilisez labuildAwsKmsMrkAwareStrictMultiKeyringBrowser() méthode permettant de créer le jeu de clés et de spécifier une clé multirégion.

Pour un exemple complet, consultez kms_multi_region_simple.ts dans leKit SDK de chiffrement AWS pour JavaScript référentiel sur 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 à l'aide d'une clé multirégion, utilisez labuildAwsKmsMrkAwareStrictMultiKeyringNode() méthode permettant de créer le jeu de clés et de spécifier une clé multirégion.

Pour un exemple complet, consultez kms_multi_region_simple.ts dans leKit SDK de chiffrement AWS pour JavaScript référentiel sur 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 à l'aide d'une cléAWS KMS multirégion, utilisez laMRKAwareStrictAwsKmsMasterKeyProvider() méthode et spécifiez une clé multirégion.

Pour un exemple complet, consultez mrk_aware_kms_provider.py dans leKit 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 laus-west-2 Région. Vous n'avez pas besoin de rechiffrer le texte chiffré.

Pour déchiffrer le texte chiffré en mode strict dans laus-west-2 région, instanciez le symbole prenant en compte plusieurs régions avec l'ARN clé de la clé multirégion associée dans laus-west-2 région. Si vous spécifiez l'ARN d'une clé multirégion associée dans une autre région (y comprisus-east-1, dans laquelle elle a été chiffrée), le symbole prenant en compte plusieurs régions émettra un appel interrégional à cet effetAWS KMS key.

Lors du déchiffrement en mode strict, le symbole prenant en compte plusieurs régions nécessite une clé ARN. Elle accepte une seule clé ARN chaque ensemble de clés multi-région associées.

Avant d'exécuter ces exemples, remplacez l'ARN de clé multi-régions par une valeur valide de votreCompte AWS.

C

Pour déchiffrer en mode strict avec une clé multirégion, utilisez laAws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() méthode pour instancier le jeu de clés. Spécifiez la clé multi-région associée dans la région locale (us-west-2).

Pour un exemple complet, consultez kms_multi_region_keys.cpp dans leKit 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égion, utilisez les mêmes constructeurs et méthodes que ceux que vous avez utilisés pour assembler les données d'entrée et créer le jeu de clés à des fins de chiffrement. Instanciez unCreateAwsKmsMrkKeyringInput objet avec l'ARN clé d'une clé multi-région associée et unAWS KMS client pour la région USA Ouest (Oregon) (us-west-2). Utilisez ensuite laCreateAwsKmsMrkKeyring() méthode pour créer un jeu de clés multirégion avec une clé KMS multirégion.

Pour un exemple complet, consultez AwsKmsMrkKeyringExample.cs dansAWS Encryption SDK le référentiel .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 à l'aide de la clé multirégion associée dans la région us-west-2, utilisez l'attribut key du--wrapping-keys paramètre pour spécifier son ARN clé. 

# Decrypt with a related multi-Region KMS key in us-west-2 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$mrkUSWest2 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

Pour déchiffrer en mode strict, instanciez uneAwsKmsMrkAwareMasterKeyProvider clé multi-région associée dans la région locale (us-west-2).

Pour un exemple complet, consultez BasicMultiRegionKeyEncryptionExample.java dans leKit 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 labuildAwsKmsMrkAwareStrictMultiKeyringBrowser() méthode pour créer le jeu de clés et spécifiez la clé multi-région associée dans la région locale (us-west-2).

Pour un exemple complet, consultez kms_multi_region_simple.ts dans leKit SDK de chiffrement AWS pour JavaScript référentiel sur 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 labuildAwsKmsMrkAwareStrictMultiKeyringNode() méthode pour créer le jeu de clés et spécifiez la clé multi-région associée dans la région locale (us-west-2).

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

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the client
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsWestKey,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)
Python

Pour déchiffrer en mode strict, utilisez laMRKAwareStrictAwsKmsMasterKeyProvider() méthode permettant de créer le fournisseur de clé principale. Spécifiez la clé multi-région associée dans la région locale (us-west-2).

Pour un exemple complet, consultez mrk_aware_kms_provider.py dans leKit 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ésAWS KMS multirégions. Vous n'spécifiez aucune valeur pour le déchiffrement en mode découverteAWS KMS keys. (Pour plus d'informations sur les porte-clés deAWS KMS découverte à région unique, voirUtilisation d'un porte-clés de découverte AWS KMS.)

Si vous avez chiffré à l'aide d'une clé multirégion, le symbole prenant en compte plusieurs régions en mode découverte essaiera de déchiffrer à l'aide d'une clé multirégion associée dans la région locale. S'il n'en existe pas, l'appel échoue. En mode découverte, aucun appel interrégional neAWS Encryption SDK sera lancé pour la clé multirégion utilisée pour le chiffrement.

Note

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

L'exemple suivant montre comment déchiffrer à l'aide du symbole multirégional en mode découverte. Comme vous n'en spécifiez pasAWS KMS key, ilsAWS Encryption SDK doivent 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 obtient la région locale à partir de la région configurée dans leAWS SDK pour votre langage de programmation.

Avant d'exécuter ces exemples, remplacez l'exemple d'ID de compte et d'ARN de clé multi-région par des valeurs valides de votreCompte AWS.

C

Pour déchiffrer en mode découverte à l'aide d'une clé multirégion, utilisez laAws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() méthode de création du jeu de clés et laAws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() méthode de création du filtre de découverte. Pour spécifier la région locale, définissez unClientConfiguration et spécifiez-le dans leAWS KMS client.

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

/* Decrypt in discovery mode with a multi-Region KMS key */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct a discovery filter for the account and partition. The
 *  filter is optional, but it's a best practice that we recommend.
 */
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

/* Create an AWS KMS client in the desired region. */
const char *region = "us-west-2";

Aws::Client::ClientConfiguration client_config;
client_config.region = region;
const std::shared_ptr<Aws::KMS::KMSClient> kms_client =
    Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config);

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()
        .WithKmsClient(kms_client)
        .BuildDiscovery(region, discovery_filter);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

Pour créer un jeu de clés de découverte compatible avec plusieurs régions dans leAWS Encryption SDK pour .NET, instanciez unCreateAwsKmsMrkDiscoveryKeyringInput objet qui prend unAWS KMS client pour un client spécifiqueRégion AWS et un filtre de découverte facultatif qui limite les clés KMS à uneAWS partition et à un compte particuliers. Appelez ensuite laCreateAwsKmsMrkDiscoveryKeyring() méthode avec l'objet d'entrée. Pour un exemple complet, consultez AwsKmsMrkDiscoveryKeyringExample.cs dansAWS Encryption SDK le référentiel .NET sur GitHub.

Pour créer un jeu de clés de découverte prenant en compte plusieurs régionsRégion AWS, utilisez laCreateAwsKmsMrkDiscoveryMultiKeyring() méthode permettant de créer un jeu de clés multirégional, ou utilisez-laCreateAwsKmsMrkDiscoveryKeyring() pour créer plusieurs porte-clés de découverte prenant en compte plusieurs régions, puis utilisez laCreateMultiKeyring() méthode pour les combiner dans un jeu de clés multirégional.

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 discovery 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 lebuilder().withDiscoveryMrkRegion paramètre. Sinon,AWS Encryption SDK obtient la région locale à partir de la région configurée dans le AWS SDK for Java.

Pour un exemple complet, consultez DiscoveryMultiRegionDecryptionExample.java dans leKit 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égion symétrique, utilisez laAwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser() méthode.

Pour un exemple complet, consultez kms_multi_region_discovery.ts dans leKit SDK de chiffrement AWS pour JavaScript référentiel sur 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égion symétrique, utilisez laAwsKmsMrkAwareSymmetricDiscoveryKeyringNode() méthode.

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

/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringNode,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-node'

/* Instantiate the Encryption SDK client
const { decrypt } = buildClient()

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2' })

/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }

/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({
    client,
    discoveryFilter,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)
Python

Pour déchiffrer en mode découverte avec une clé multirégion, utilisez laMRKAwareDiscoveryAwsKmsMasterKeyProvider() méthode.

Pour un exemple complet, consultez mrk_aware_kms_provider.py dans leKit 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

IlAWS Encryption SDK prend en charge plusieurs algorithmes de chiffrement symétriques et asymétriques pour crypter 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 crypter vos données, il utiliseAWS Encryption SDK par défaut une suite d'algorithmes recommandée qui utilise l'algorithme AES-GCM avec dérivation des 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 signatures numériques. Pour plus d'informations sur les suites d'algorithmes prisesAWS Encryption SDK en charge par le logiciel, reportez-vous à la sectionSuites 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 une dérivation et un engagement clés, mais sans signatures numériques. Lorsque vous chiffrez à l'aide d'une suite d'algorithmes qui n'inclut pas de signatures numériques, utilisez le mode de déchiffrement non signé uniquement lors du déchiffrement. Ce mode, qui échoue s'il rencontre un texte chiffré signé, est particulièrement utile lors du déchiffrement en continu.

C

Pour spécifier une suite d'algorithmes alternative dans leKit SDK de chiffrement AWS pour C, vous devez créer une CMM de manière explicite. Utilisez-le ensuiteaws_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 cryptées sans signature numérique, utilisezAWS_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 suite d'algorithmes alternative dans leAWS Encryption SDK pour .NET, spécifiez laAlgorithmSuiteId propriété d'un EncryptInputobjet. LeAWS Encryption SDK pour .NET inclut des constantes que vous pouvez utiliser pour identifier votre suite d'algorithmes préférée.

LeAWS Encryption SDK pour .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 les données en streaming.

// 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 duhello.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--decrypt-unsigned paramètre. Ce paramètre est recommandé pour vous assurer que vous déchiffrez un texte chiffré non signé, en particulier avec l'interface de ligne de commande, 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 suite d'algorithmes alternative, utilisez laAwsCrypto.builder().withEncryptionAlgorithm() méthode. Cet exemple spécifie 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 lacreateUnsignedMessageDecryptingStream() méthode pour vous assurer que tout le texte chiffré que vous déchiffrez 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 suite d'algorithmes alternative, utilisez lesuiteId paramètre avec une valeur d'AlgorithmSuiteIdentifierénumération.

// 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 ladecrypt méthode standard. Kit SDK de chiffrement AWS pour JavaScriptdans le navigateur, il n'y a pas dedecrypt-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 suite d'algorithmes alternative, utilisez lesuiteId paramètre avec une valeur d'AlgorithmSuiteIdentifierénumération.

// 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 decryptUnsignedMessage Stream. Cette méthode échoue si elle rencontre 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 lealgorithm paramètre avec une valeurAlgorithm 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 modedecrypt-unsigned streaming, en particulier lors du déchiffrement en cours de diffusion. 

# 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 cryptées

Vous pouvez limiter le nombre de clés de données cryptées dans un message crypté. 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 à votre infrastructure clé. La limitation des clés de données cryptées est particulièrement utile lorsque vous déchiffrez des messages provenant d'une source non fiable.

Bien que la plupart des messages chiffrés aient 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 cryptées. Un acteur malveillant peut créer un message chiffré à l'aide de milliers de clés de données cryptées, dont aucune ne peut être déchiffrée. Par conséquent, ilsAWS Encryption SDK essaieraient de déchiffrer chaque clé de données chiffrée jusqu'à ce qu'ils aient épuisé les clés de données cryptées du message.

Pour limiter les clés de données cryptées, utilisez leMaxEncryptedDataKeys paramètre. Ce paramètre est disponible pour tous les langages de programmation pris en charge à partir des versions 1.9. x et 2.2. x duAWS Encryption SDK. Il est facultatif et valide lors du chiffrement et du déchiffrement. Les exemples suivants déchiffrent des données qui ont été chiffrées sous trois clés d'encapsulation différentes. LaMaxEncryptedDataKeys valeur est fixée à 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 cryptées dans leAWS Encryption SDK pour .NET, instanciez un clientAWS Encryption SDK pour .NET et définissez sonMaxEncryptedDataKeys paramètre facultatif sur la valeur souhaitée. Appelez ensuite laDecrypt() méthode sur l'AWS Encryption SDKinstance configurée.

// Decrypt with limited data keys

// Instantiate the material providers
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
    MaxEncryptedDataKeys = 3
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);

// Create the keyring
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = decryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI
# Decrypt with limited encrypted data keys

$ aws-encryption-cli --decrypt \
    --input hello.txt.encrypted \
    --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \
    --buffer \
    --max-encrypted-data-keys 3 \
    --encryption-context purpose=test \
    --metadata-output ~/metadata \
    --output .
Java
// Construct a client with limited encrypted data keys
final AwsCrypto crypto = AwsCrypto.builder()
  .withMaxEncryptedDataKeys(3)
  .build();

// Create an AWS KMS master key provider
final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
      .buildStrict(keyArn1, keyArn2, keyArn3);
   
// Decrypt
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)
JavaScript Browser
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}
const clientProvider = getClient(KMS, {
  credentials: { accessKeyId, secretAccessKey, sessionToken }
})

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  clientProvider,
  keyIds: [keyArn1, keyArn2, keyArn3],
})

// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
JavaScript Node.js
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  keyIds: [keyArn1, keyArn2, keyArn3],
})
  
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
Python
# Instantiate a client with limited encrypted data keys
client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3)

# Create an AWS KMS master key provider
master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(
    key_ids=[key_arn1, key_arn2, key_arn3])

# Decrypt
plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

Création d'un filtre de découverte

Lorsque vous déchiffrez des données chiffrées à l'aide de clés KMS, il est recommandé de les déchiffrer en mode strict, c'est-à-dire de limiter les clés d'encapsulation utilisées uniquement à celles que vous spécifiez. Toutefois, si nécessaire, vous pouvez également déchiffrer en mode découverte, où vous ne spécifiez aucune clé d'encapsulation. Dans ce mode,AWS KMS peut déchiffrer la clé de données chiffrée à l'aide de la clé KMS qui l'a chiffrée, quel que soit le propriétaire de cette clé KMS ou y ait accès.

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 partitionCompte 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 pour votre filtre de découverte.

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

Les exemples de cette section illustrent la création d'un filtre de découverte. Avant d'utiliser le code, remplacez les valeurs d'exemple par des valeurs valides pour la partitionCompte AWS and.

C

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

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

Pour un exemple complet, consultez DiscoveryFilterExample.cs dans leAWS 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, consultez DiscoveryDecryptionExample.java dans leKit SDK de chiffrement AWS pour Java.

// Create a discovery filter for an AWS account and partition

DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
JavaScript (Node and Browser)

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

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

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

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

Définition d'une politique d'engagement

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

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érieuresAWS Encryption SDK à la version 2.0. x et versions ultérieures. Cette progression est expliquée en détail dans la rubrique sur la migration.

La valeur de la politique d'engagement par défaut dans les dernières versions deAWS Encryption SDK (à partir de la version 2.0). x)RequireEncryptRequireDecrypt, convient parfaitement à la plupart des situations. Toutefois, si vous devez déchiffrer un texte chiffré sans saisie de clé, vous devrez peut-être modifier votre politique d'engagement enRequireEncryptAllowDecrypt. 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, n'oubliez pas que le texte en clair estAWS Encryption SDK renvoyé 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 l'ensemble du processus de déchiffrement soit terminé.

Ce problème se pose 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émentationsAWS Encryption SDK linguistiques, commeKit 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 deAWS 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 les implémentations d'autres langages, vous pouvez utiliser les fonctionnalités de mise en mémoire tampon existantes. (LeAWS Encryption SDK pour .NET ne prend pas en charge le streaming.)

Si vous utilisez une suite d'algorithmes sans signature numérique, veillez à utiliserdecrypt-unsigned cette fonctionnalité dans chaque implémentation linguistique. Cette fonctionnalité déchiffre le texte chiffré mais échoue si elle rencontre un 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, maisAWS 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 effectuez des tests pour vous assurer que les avantages l'emportent sur les inconvénients liés à la réutilisation des clés de données.