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.
# AWS Encryption SDK pour .NET
AWS Encryption SDK for .NET est une bibliothèque de chiffrement côté client destinée aux développeurs qui écrivent des applications en C\$1 et dans d'autres langages de programmation .NET. Elle est prise en charge sur Windows, macOS et Linux.
**Note**
La version 4.0.0 de AWS Encryption SDK for .NET s'écarte de la spécification du AWS Encryption SDK message. Par conséquent, les messages chiffrés par la version 4.0.0 ne peuvent être déchiffrés que par la version 4.0.0 ou ultérieure pour .NET. AWS Encryption SDK Ils ne peuvent être déchiffrés par aucune autre implémentation de langage de programmation.
La version 4.0.1 de AWS Encryption SDK for .NET écrit des messages conformément à la spécification des AWS Encryption SDK messages et est interopérable avec d'autres implémentations de langages de programmation. Par défaut, la version 4.0.1 peut lire les messages chiffrés par la version 4.0.0. Toutefois, si vous ne souhaitez pas déchiffrer les messages chiffrés par la version 4.0.0, vous pouvez spécifier la [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs)propriété pour empêcher le client de lire ces messages. Pour plus d'informations, consultez les [notes de mise à jour de la version 4.0.1](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) dans le aws-encryption-sdk référentiel sur. GitHub
Le AWS Encryption SDK pour .NET se distingue de certaines des autres implémentations du langage de programmation de la AWS Encryption SDK manière suivante :
+ Aucune prise en charge de la mise en [cache des clés de données](data-key-caching.md)
**Note**
La version 4. *x* of the AWS Encryption SDK for .NET prend en charge le [keyring AWS KMS hiérarchique](use-hierarchical-keyring.md), une solution alternative de mise en cache des matériaux cryptographiques.
+ Pas de support pour le streaming de données
+ [Pas de journalisation ni de traces de pile](#dot-net-debugging) AWS Encryption SDK pour .NET
+ [Nécessite le AWS SDK pour .NET](#dot-net-install)
Le AWS Encryption SDK pour .NET inclut toutes les fonctionnalités de sécurité introduites dans les versions 2.0. *x* et versions ultérieures d'autres implémentations linguistiques du AWS Encryption SDK. Toutefois, si vous utilisez le AWS Encryption SDK pour .NET pour déchiffrer des données chiffrées par une version antérieure à la version 2.0. version *x*, autre implémentation linguistique du AWS Encryption SDK, vous devrez peut-être ajuster votre [politique d'engagement](concepts.md#commitment-policy). Pour en savoir plus, consultez [Comment définir votre politique d'engagement](migrate-commitment-policy.md#migrate-commitment-step1).
Le AWS Encryption SDK for .NET est un produit de AWS Encryption SDK in [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), un langage de vérification formel dans lequel vous écrivez des spécifications, le code pour les implémenter et les preuves pour les tester. Le résultat est une bibliothèque qui implémente les fonctionnalités du AWS Encryption SDK dans un framework garantissant l'exactitude fonctionnelle.
**En savoir plus**
+ Pour des exemples montrant comment configurer des options dans le AWS Encryption SDK, telles que la spécification d'une suite d'algorithmes alternative, la limitation des clés de données chiffrées et l'utilisation de clés AWS KMS multirégionales, voir[Configuration du AWS Encryption SDK](configure.md).
+ Pour plus de détails sur la programmation avec le AWS Encryption SDK pour .NET, consultez le [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)répertoire du aws-encryption-sdk référentiel sur GitHub.
**Topics**
+ [Installation et génération](#dot-net-install)
+ [Débogage](#dot-net-debugging)
+ [Exemples](dot-net-examples.md)
## Installation du AWS Encryption SDK pour .NET
Le AWS Encryption SDK pour .NET est disponible sous forme de [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)package dans NuGet. Pour plus de détails sur l'installation et la génération du fichier AWS Encryption SDK pour .NET, consultez le fichier [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) dans le référentiel. `aws-encryption-sdk-net`
**Version 3.x**
Version 3. *x* of the AWS Encryption SDK for .NET prend en charge .NET Framework 4.5.2 à 4.8 uniquement sous Windows. Il prend en charge .NET Core 3.0\$1, .NET 5.0 et versions ultérieures sur tous les systèmes d'exploitation pris en charge.
**Version 4.x**
La version 4. *x* of the AWS Encryption SDK for .NET prend en charge .NET 6.0 et .NET Framework net48 et versions ultérieures. La version 4. *x* nécessite le AWS SDK pour .NET v3.
**Version 5.x**
La version 5. *x* of the AWS Encryption SDK for .NET prend en charge .NET 6.0 et .NET Framework net48 et versions ultérieures. La version 5. *x* nécessite la version 2. *x* de la Material Providers Library (MPL) et du AWS SDK pour .NET v4.
AWS Encryption SDK Pour .NET, les touches « SDK pour .NET même si vous n'utilisez pas AWS Key Management Service (AWS KMS) » sont requises. Il est installé avec le NuGet package. Toutefois, sauf si vous utilisez AWS KMS des clés, AWS Encryption SDK car .NET ne nécessite pas d' Compte AWS AWS informations d'identification ou d'interaction avec un AWS service. Pour obtenir de l'aide pour configurer un AWS compte si vous en avez besoin, consultez[En utilisant le AWS Encryption SDK avec AWS KMS](getting-started.md).
## Débogage du AWS Encryption SDK pour .NET
Le AWS Encryption SDK for .NET ne génère aucun journal. Les exceptions dans le AWS Encryption SDK fichier for .NET génèrent un message d'exception, mais aucune trace de pile.
Pour vous aider à déboguer, veillez à activer la connexion au SDK pour .NET. Les journaux et les messages d'erreur du SDK pour .NET peuvent vous aider à distinguer les erreurs survenant dans le fichier .NET SDK pour .NET de celles qui se produisent dans le AWS Encryption SDK fichier .NET. Pour obtenir de l'aide SDK pour .NET concernant la journalisation, consultez [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)le *guide du AWS SDK pour .NET développeur*. (Pour consulter le sujet, développez la section **Ouvrir pour afficher le contenu du .NET Framework**.)
# AWS Encryption SDK pour des exemples .NET
Les exemples suivants montrent les modèles de codage de base que vous utilisez lors de la programmation avec le AWS Encryption SDK pour .NET. Plus précisément, vous instanciez la bibliothèque AWS Encryption SDK et les fournisseurs de matériaux. Ensuite, avant d'appeler chaque méthode, vous instanciez un objet qui définit l'entrée de la méthode. Cela ressemble beaucoup au modèle de codage que vous utilisez dans le SDK pour .NET.
Pour des exemples montrant comment configurer des options dans le AWS Encryption SDK, telles que la spécification d'une suite d'algorithmes alternative, la limitation des clés de données chiffrées et l'utilisation de clés AWS KMS multirégionales, voir[Configuration du AWS Encryption SDK](configure.md).
Pour plus d'exemples de programmation avec le AWS Encryption SDK pour .NET, consultez les [exemples](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples) dans le `aws-encryption-sdk-net` répertoire du `aws-encryption-sdk` référentiel sur GitHub.
## Chiffrer des données dans le AWS Encryption SDK pour .NET
Cet exemple montre le schéma de base pour le chiffrement des données. Il chiffre un petit fichier avec des clés de données protégées par une clé AWS KMS d'encapsulation.
Étape 1 : Instancier la bibliothèque AWS Encryption SDK et la bibliothèque des fournisseurs de matériaux.
Commencez par instancier la bibliothèque AWS Encryption SDK et les fournisseurs de matériaux. Vous allez utiliser les méthodes décrites dans le AWS Encryption SDK pour chiffrer et déchiffrer les données. Vous allez utiliser les méthodes de la bibliothèque des fournisseurs de matériel pour créer les porte-clés qui spécifient les clés qui protègent vos données.
La façon dont vous instanciez la bibliothèque AWS Encryption SDK et la bibliothèque des fournisseurs de matériaux diffère selon les versions 3. *x* et 4. *x* du AWS Encryption SDK pour .NET. Toutes les étapes suivantes sont identiques pour les deux versions 3. *x* et 4. *x* du AWS Encryption SDK pour .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Étape 2 : Créez un objet de saisie pour le trousseau de clés.
Chaque méthode qui crée un trousseau de clés possède une classe d'objet d'entrée correspondante. Par exemple, pour créer l'objet d'entrée pour la `CreateAwsKmsKeyring()` méthode, créez une instance de la `CreateAwsKmsKeyringInput` classe.
Même si l'entrée de ce trousseau de clés ne spécifie pas de [clé de générateur](use-kms-keyring.md#kms-keyring-encrypt), la clé KMS unique spécifiée par le `KmsKeyId` paramètre est la clé de générateur. Il génère et chiffre la clé de données qui chiffre les données.
Cet objet d'entrée nécessite un AWS KMS client pour Région AWS la clé KMS. Pour créer un AWS KMS client, instanciez la `AmazonKeyManagementServiceClient` classe dans le. SDK pour .NET L'appel du `AmazonKeyManagementServiceClient()` constructeur sans paramètres crée un client avec les valeurs par défaut.
Dans un AWS KMS trousseau de clés utilisé pour le chiffrement avec .NET, vous pouvez [identifier AWS Encryption SDK les clés KMS à l'aide de l'](use-kms-keyring.md#kms-keyring-id)ID de clé, de l'ARN de la clé, du nom de l'alias ou de l'ARN de l'alias. Dans un AWS KMS trousseau de clés utilisé pour le déchiffrement, vous devez utiliser un ARN de clé pour identifier chaque clé KMS. Si vous prévoyez de réutiliser votre jeu de clés de chiffrement pour le déchiffrer, utilisez un identifiant ARN pour toutes les clés KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Étape 3 : Créez le porte-clés.
Pour créer le trousseau de clés, appelez la méthode du trousseau avec l'objet de saisie du trousseau de clés. Cet exemple utilise la `CreateAwsKmsKeyring()` méthode, qui n'utilise qu'une seule clé KMS.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Étape 4 : définir un contexte de chiffrement
Un [contexte de chiffrement](concepts.md#encryption-context) est un élément facultatif, mais fortement recommandé, des opérations cryptographiques dans le AWS Encryption SDK. Vous pouvez définir une ou plusieurs paires clé-valeur non secrètes.
Avec la version 4. *x* de AWS Encryption SDK pour .NET, vous pouvez exiger un contexte de chiffrement dans toutes les demandes de chiffrement avec le [contexte de chiffrement requis CMM](configure.md#config-required-encryption-context-cmm).
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
Étape 5 : Créez l'objet d'entrée pour le chiffrement.
Avant d'appeler la `Encrypt()` méthode, créez une instance de la `EncryptInput` classe.
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
Étape 6 : Chiffrez le texte en clair.
Utilisez la `Encrypt()` méthode du AWS Encryption SDK pour chiffrer le texte en clair à l'aide du trousseau de clés que vous avez défini.
La `EncryptOutput` `Encrypt() ` méthode renvoie des méthodes pour obtenir le message crypté (`Ciphertext`), le contexte de chiffrement et la suite d'algorithmes.
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
Étape 7 : Obtenez le message crypté.
La `Decrypt()` méthode décrite dans AWS Encryption SDK for .NET prend le `Ciphertext` membre de l'`EncryptOutput`instance.
Le `Ciphertext` membre de l'`EncryptOutput`objet est le [message chiffré](concepts.md#message), un objet portable qui inclut les données chiffrées, les clés de données chiffrées et les métadonnées, y compris le contexte de chiffrement. Vous pouvez stocker le message crypté en toute sécurité pendant une période prolongée ou le soumettre à la `Decrypt()` méthode pour récupérer le texte en clair.
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## Déchiffrement en mode strict dans le fichier pour .NET AWS Encryption SDK
Les meilleures pratiques recommandent de spécifier les clés que vous utilisez pour déchiffrer les données, une option connue sous le nom de *mode strict*. AWS Encryption SDK Utilise uniquement les clés KMS que vous spécifiez dans votre trousseau de clés pour déchiffrer le texte chiffré. Les clés de votre jeu de clés de déchiffrement doivent inclure au moins l'une des clés qui ont chiffré les données.
Cet exemple montre le schéma de base du déchiffrement en mode strict avec le AWS Encryption SDK pour .NET.
Étape 1 : Instancier la bibliothèque AWS Encryption SDK et les fournisseurs de matériaux.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Étape 2 : Créez l'objet de saisie pour votre trousseau de clés.
Pour définir les paramètres de la méthode keyring, créez un objet d'entrée. Chaque méthode de porte-clés de AWS Encryption SDK for .NET possède un objet d'entrée correspondant. Comme cet exemple utilise la `CreateAwsKmsKeyring()` méthode pour créer le trousseau de clés, il instancie la `CreateAwsKmsKeyringInput` classe pour l'entrée.
Dans un trousseau de clés de déchiffrement, vous devez utiliser un ARN de clé pour identifier les clés KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Étape 3 : Créez le porte-clés.
Pour créer le trousseau de clés de déchiffrement, cet exemple utilise la `CreateAwsKmsKeyring()` méthode et l'objet d'entrée du trousseau de clés.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Étape 4 : Créez l'objet d'entrée à déchiffrer.
Pour créer l'objet d'entrée pour la `Decrypt()` méthode, instanciez la `DecryptInput` classe.
Le `Ciphertext` paramètre du `DecryptInput()` constructeur prend le `Ciphertext` membre de l'`EncryptOutput`objet renvoyé par la `Encrypt()` méthode. La `Ciphertext` propriété représente le [message chiffré](concepts.md#message), qui inclut les données chiffrées, les clés de données chiffrées et les métadonnées AWS Encryption SDK nécessaires pour déchiffrer le message.
Avec la version 4. *x* de AWS Encryption SDK pour .NET, vous pouvez utiliser le `EncryptionContext` paramètre facultatif pour spécifier votre contexte de chiffrement dans la `Decrypt()` méthode.
Utilisez le `EncryptionContext` paramètre pour vérifier que le contexte de chiffrement utilisé lors du chiffrement *est inclus* dans le contexte de chiffrement utilisé pour déchiffrer le texte chiffré. AWS Encryption SDK ajoute des paires au contexte de chiffrement, y compris la signature numérique si vous utilisez une suite d'algorithmes avec signature, telle que la suite d'algorithmes par défaut.
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
Étape 5 : Décrypter le texte chiffré
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Étape 6 : Vérifiez le contexte de chiffrement — Version 3. *x*
La `Decrypt()` méthode de la version 3. *x* du AWS Encryption SDK pour .NET ne prend pas de contexte de chiffrement. Il obtient les valeurs du contexte de chiffrement à partir des métadonnées du message chiffré. Toutefois, avant de renvoyer ou d'utiliser le texte en clair, il est recommandé de vérifier que le contexte de chiffrement utilisé pour déchiffrer le texte chiffré inclut le contexte de chiffrement que vous avez fourni lors du chiffrement.
Vérifiez que le contexte de chiffrement utilisé pour chiffrer *est inclus* dans le contexte de chiffrement utilisé pour déchiffrer le texte chiffré. AWS Encryption SDK ajoute des paires au contexte de chiffrement, y compris la signature numérique si vous utilisez une suite d'algorithmes avec signature, telle que la suite d'algorithmes par défaut.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
## Déchiffrement à l'aide d'un trousseau de découverte dans le for .NET AWS Encryption SDK
Plutôt que de spécifier les clés KMS pour le déchiffrement, vous pouvez fournir un jeu de *clés de AWS KMS découverte*, qui est un jeu de clés qui ne spécifie aucune clé KMS. Un trousseau de découverte permet de AWS Encryption SDK déchiffrer les données en utilisant la clé KMS qui les a chiffrées, à condition que l'appelant ait l'autorisation de déchiffrer la clé. Pour des raisons de bonnes pratiques, ajoutez un filtre de découverte qui limite les clés KMS pouvant être utilisées à celles Comptes AWS d'une partition spécifique.
Le jeu de clés AWS Encryption SDK pour .NET fournit un jeu de clés de découverte de base qui nécessite un AWS KMS client et un jeu de clés de découverte multiple qui nécessite que vous en spécifiiez un ou plusieurs. Régions AWS Le client et les régions limitent tous deux les clés KMS qui peuvent être utilisées pour déchiffrer le message chiffré. Les objets d'entrée pour les deux trousses de clés utilisent le filtre de découverte recommandé.
L'exemple suivant montre le modèle de déchiffrement des données à l'aide d'un trousseau de découverte et d'un AWS KMS filtre de découverte.
Étape 1 : Instancier la bibliothèque AWS Encryption SDK et la bibliothèque des fournisseurs de matériaux.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Étape 2 : Créez l'objet de saisie pour le trousseau de clés.
Pour définir les paramètres de la méthode keyring, créez un objet d'entrée. Chaque méthode de porte-clés de AWS Encryption SDK for .NET possède un objet d'entrée correspondant. Comme cet exemple utilise la `CreateAwsKmsDiscoveryKeyring()` méthode pour créer le trousseau de clés, il instancie la `CreateAwsKmsDiscoveryKeyringInput` classe pour l'entrée.
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
Étape 3 : Créez le porte-clés.
Pour créer le trousseau de clés de déchiffrement, cet exemple utilise la `CreateAwsKmsDiscoveryKeyring()` méthode et l'objet d'entrée du trousseau de clés.
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
Étape 4 : Créez l'objet d'entrée à déchiffrer.
Pour créer l'objet d'entrée pour la `Decrypt()` méthode, instanciez la `DecryptInput` classe. La valeur du `Ciphertext` paramètre est le `Ciphertext` membre de l'`EncryptOutput`objet renvoyé par la `Encrypt()` méthode.
Avec la version 4. *x* de AWS Encryption SDK pour .NET, vous pouvez utiliser le `EncryptionContext` paramètre facultatif pour spécifier votre contexte de chiffrement dans la `Decrypt()` méthode.
Utilisez le `EncryptionContext` paramètre pour vérifier que le contexte de chiffrement utilisé lors du chiffrement *est inclus* dans le contexte de chiffrement utilisé pour déchiffrer le texte chiffré. AWS Encryption SDK ajoute des paires au contexte de chiffrement, y compris la signature numérique si vous utilisez une suite d'algorithmes avec signature, telle que la suite d'algorithmes par défaut.
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Étape 5 : Vérifiez le contexte de chiffrement — Version 3. *x*
La `Decrypt()` méthode de la version 3. *x* of the AWS Encryption SDK for .NET ne prend pas en charge de contexte de chiffrement activé`Decrypt()`. Il obtient les valeurs du contexte de chiffrement à partir des métadonnées du message chiffré. Toutefois, avant de renvoyer ou d'utiliser le texte en clair, il est recommandé de vérifier que le contexte de chiffrement utilisé pour déchiffrer le texte chiffré inclut le contexte de chiffrement que vous avez fourni lors du chiffrement.
Vérifiez que le contexte de chiffrement utilisé lors du chiffrement *est inclus* dans le contexte de chiffrement utilisé pour déchiffrer le texte chiffré. AWS Encryption SDK ajoute des paires au contexte de chiffrement, y compris la signature numérique si vous utilisez une suite d'algorithmes avec signature, telle que la suite d'algorithmes par défaut.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```