Installation et génération Débogage Porte-clés AWS KMS Contexte de chiffrement requis CMM

AWS Encryption SDKpour .NET

AWS Encryption SDKfor .NET est une bibliothèque de chiffrement côté client destinée aux développeurs qui écrivent des applications en C# et dans d'autres langages de programmation .NET. Elle est prise en charge sur Windows, macOS et Linux.

Toutes les implémentations du langage de programmation AWS Encryption SDK sont totalement interopérables. Toutefois, si vous chiffrez des données à l'aide du contexte de chiffrement requis CMM dans la version 4. x du AWS Encryption SDK pour .NET, vous ne pouvez le déchiffrer qu'avec la version 4. x du AWS Encryption SDK pour .NET ou version 3. x duKit SDK de chiffrement AWS pour Java.

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 NetV4_0_0_RetryPolicyproprié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 dans le aws-encryption-sdk-dafny 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

Note
La version 4. x of the AWS Encryption SDK for .NET prend en charge le keyring AWS KMS hiérarchique, une solution alternative de mise en cache des matériaux cryptographiques.
Pas de support pour le streaming de données
Aucune journalisation ou trace de pile AWS Encryption SDK depuis .NET
Nécessite le AWS SDK for .NET

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 duAWS 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 duAWS Encryption SDK, vous devrez peut-être ajuster votre politique d'engagement. Pour plus de détails, consultez Comment définir votre politique d'engagement.

Le AWS Encryption SDK for .NET est un produit de AWS Encryption SDK in Dafny, 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 leAWS 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, voirConfiguration du AWS Encryption SDK.
Pour plus de détails sur la programmation avec le AWS Encryption SDK pour .NET, consultez le aws-encryption-sdk-netrépertoire du aws-encryption-sdk-dafny référentiel sur GitHub.

Installation du AWS Encryption SDK pour .NET

Le AWS Encryption SDK pour .NET est disponible sous forme de AWS.Cryptography.EncryptionSDKpackage 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 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+, .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.

AWS Encryption SDKPour .NET, les touches « AWS SDK for .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 AWSAWSinformations d'identification ou d'interaction avec un AWS service. Pour obtenir de l'aide pour configurer un AWS compte si vous en avez besoin, consultezUtilisation de l'AWS Encryption SDK avec AWS KMS.

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 auAWS SDK for .NET. Les journaux et les messages d'erreur du AWS SDK for .NET peuvent vous aider à distinguer les erreurs survenant dans le fichier .NET AWS SDK for .NET de celles qui se produisent dans le AWS Encryption SDK fichier .NET. Pour obtenir de l'aide AWS SDK for .NET concernant la journalisation, consultez AWSLoggingle guide du AWS SDK for .NET développeur. (Pour consulter le sujet, développez la section Ouvrir pour afficher le contenu du .NET Framework.)

AWS KMSporte-clés dans le AWS Encryption SDK for .NET

Les AWS KMS trousseaux de clés de base AWS Encryption SDK pour .NET n'utilisent qu'une seule clé KMS. Ils ont également besoin d'un AWS KMS client, ce qui vous permet de configurer le client pour Région AWS la clé KMS.

Pour créer un AWS KMS porte-clés avec une ou plusieurs clés enveloppantes, utilisez un porte-clés à plusieurs clés. AWS Encryption SDKPour .NET, il existe un porte-clés spécial qui accepte une ou plusieurs AWS KMS clés, et un porte-clés standard qui accepte un ou plusieurs porte-clés de n'importe quel type compatible. Certains programmeurs préfèrent utiliser une méthode à plusieurs jeux de clés pour créer tous leurs trousseaux de clés, et AWS Encryption SDK for .NET prend en charge cette stratégie.

Le AWS Encryption SDK for .NET fournit des porte-clés simples et des porte-clés multiples de base pour tous les cas d'utilisation courants, y compris les clés multirégionales. AWS KMS

Par exemple, pour créer un AWS KMS porte-clés avec une seule AWS KMS clé, vous pouvez utiliser la CreateAwsKmsKeyring() méthode.

Pour créer un trousseau de clés avec une ou plusieurs AWS KMS clés, utilisez CreateAwsKmsMultiKeyring() cette méthode. Cet exemple utilise deux AWS KMS touches. Pour spécifier une clé KMS, utilisez uniquement le Generator paramètre. Le KmsKeyIds paramètre qui spécifie des clés KMS supplémentaires est facultatif.

La saisie de ce trousseau de clés ne nécessite aucun AWS KMS client. Il AWS Encryption SDK utilise plutôt le AWS KMS client par défaut pour chaque région représentée par une clé KMS dans le trousseau de clés. Par exemple, si la clé KMS identifiée par la valeur du Generator paramètre se trouve dans la région USA Ouest (Oregon) (us-west-2), un AWS KMS client par défaut est AWS Encryption SDK créé pour us-west-2 cette région. Si vous devez personnaliser le AWS KMS client, utilisez CreateAwsKmsKeyring() cette méthode.

L'exemple suivant utilise la version 4. x du AWS Encryption SDK pour .NET et la CreateAwsKmsKeyring() méthode de personnalisation du AWS KMS client.


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKeys = new List<string> { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };

// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKeys
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);

La version 4. x of the AWS Encryption SDK for .NET prend en charge les AWS KMS ensembles de clés utilisant le chiffrement symétrique (SYMMETRIC_DEFAULT) ou des clés RSA KMS asymétriques. AWS KMSles porte-clés créés avec des clés RSA KMS asymétriques ne peuvent contenir qu'une seule paire de clés.

Pour chiffrer avec un jeu de AWS KMS clés RSA asymétrique, vous n'avez pas besoin de kms : GenerateDataKey ou de KMS:Encrypt car vous devez spécifier le matériel de clé publique que vous souhaitez utiliser pour le chiffrement lorsque vous créez le trousseau de clés. Aucun AWS KMS appel n'est effectué lors du chiffrement avec ce porte-clés. Pour déchiffrer avec un trousseau de AWS KMS clés RSA asymétrique, vous devez disposer de l'autorisation KMS:Decrypt.

Pour créer un trousseau de AWS KMS clés RSA asymétrique, vous devez fournir l'ARN de la clé publique et de la clé privée à partir de votre clé RSA KMS asymétrique. La clé publique doit être codée au format PEM. L'exemple suivant crée un AWS KMS trousseau de clés avec une paire de clés RSA asymétrique.


// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = AWS KMS RSA private key ARN,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};

// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);

Contextes de chiffrement requis dans la version 4.x

Avec la version 4. x du AWS Encryption SDK pour .NET, 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 interopérable qu'avec la version 3. x duKit SDK de chiffrement AWS pour Java. Il n'est interopérable avec aucune autre implémentation de langage de programmation. Si vous chiffrez des données à l'aide du contexte de chiffrement requis CMM, vous ne pouvez les déchiffrer qu'avec la version 3. x de la version 4 de l'Kit SDK de chiffrement AWS pour Javaor. x du AWS Encryption SDK pour .NET.

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 SDKUtilise 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 est AWS Encryption SDK impossible 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 chiffré ne peut pas être déchiffré.

L'exemple suivant initialise un AWS KMS trousseau de clés avec le contexte de chiffrement requis CMM.


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

Si vous utilisez un AWS KMS trousseau de clés, le fichier AWS Encryption SDK pour .NET utilise également le contexte de chiffrement pour fournir des données authentifiées supplémentaires (AAD) dans les appels auxquels le trousseau de clés effectue des appels. AWS KMS

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Exemples