AWS Encryption SDKExemples .NET

Les exemples suivants illustrent les schémas de codage de base que vous utilisez lors de la programmation avec leAWS Encryption SDK.NET. Plus précisément, vous instanciez leAWS Encryption SDKet la bibliothèque des fournisseurs de matériel. 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 schéma de codage que vous utilisez dans leAWS SDK for .NET.

Pour obtenir des exemples montrant comment configurer les options dans leAWS Encryption SDK, par exemple en spécifiant une suite d'algorithmes alternatifs, en limitant les clés de données chiffrées et en utilisantAWS KMSVoir les clés multi-régionsConfiguration du AWS Encryption SDK.

Pour plus d'exemples de programmation avec leAWS Encryption SDKpour .NET, consultez leexemplesdans leaws-encryption-sdk-netrépertoire de laaws-encryption-sdk-dafnysur le repository GitHub.

Chiffrement de données dans leAWS Encryption SDKpour .NET

Cet exemple présente le modèle de base pour chiffrer des données. Il crypte un petit fichier avec des clés de données protégées par uneAWS KMSclé d'enrobage.

Étape 1 : Instanciez leAWS Encryption SDKet la bibliothèque des fournisseurs de matériel.

Commencez par instancier leAWS Encryption SDKet la bibliothèque des fournisseurs de matériel. Vous allez utiliser les méthodes duAWS Encryption SDKpour chiffrer et déchiffrer des données. Vous allez utiliser les méthodes de la bibliothèque des fournisseurs de matériaux pour créer les porte-clés qui spécifient quelles clés protègent vos données.

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

Étape 2 : Créez un objet d'entrée pour le porte-clés.

Chaque méthode qui crée un porte-clés possède une classe d'objets en entrée correspondante. Par exemple, pour créer l'objet d'entrée pour leCreateAwsKmsKeyring(), créez une instance duCreateAwsKmsKeyringInputclasse.

Même si l'entrée de ce porte-clés ne spécifie pas declé de générateur, la clé KMS unique spécifiée par leKmsKeyIdparamètre est la clé du générateur. Elle génère et chiffre la clé de données qui chiffre les données.

Cet objet en entrée nécessite unAWS KMSclient pour leRégion AWSde la clé KMS. Pour créer unAWS KMSclient, instanciez leAmazonKeyManagementServiceClientdans leAWS SDK for .NET. Appelez leAmazonKeyManagementServiceClient()constructeur sans paramètres crée un client avec les valeurs par défaut.

Dans unAWS KMSporte-clés utilisé pour le chiffrement avec leAWS Encryption SDKpour .NET, vous pouvezIdentification des clés KMSen utilisant l'ID de clé, l'ARN de clé, le nom d'alias ou l'ARN d'alias. Dans unAWS KMSLe porte-clés utilisé pour le déchiffrement, vous devez utiliser un ARN de clé pour identifier chaque clé KMS. Si vous envisagez de réutiliser votre porte-clés de chiffrement pour le déchiffrement, utilisez un identificateur ARN de clé 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 porte-clés, appelez la méthode du porte-clés avec l'objet d'entrée du porte-clés. Cet exemple utilise leCreateAwsKmsKeyring(), qui ne prend qu'une seule clé KMS.

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

Étape 4 : Définissez un contexte de chiffrement.

Uncontexte de chiffrementest un élément facultatif, mais fortement recommandé des opérations cryptographiques dans leAWS Encryption SDK. Vous pouvez définir une ou plusieurs paires clé-valeur non secrète.

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};

Étape 5 : Créez l'objet d'entrée à chiffrer.

Avant d'appeler leEncrypt(), créez une instance duEncryptInputclasse.

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 brut.

Utilisation de l'Encrypt()Méthode de laAWS Encryption SDKpour chiffrer le texte brut à l'aide du porte-clés que vous avez défini.

LeEncryptOutputque leEncrypt() contient des méthodes permettant d'obtenir le message chiffré (Ciphertext), contexte de chiffrement et suite d'algorithmes.

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

Étape 7 : Obtenez le message chiffré.

LeDecrypt()dans leAWS Encryption SDKpour .NET prend leCiphertextmembre de laEncryptOutputinstance.

LeCiphertextmembre de laEncryptOutputl'objet est leMessage chiffré, 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 chiffré en toute sécurité pendant une période prolongée ou le soumettre auDecrypt()Méthode pour récupérer le texte brut.

var encryptedMessage = encryptOutput.Ciphertext;

Décryptage en mode strict dans leAWS Encryption SDKpour .NET

Les meilleures pratiques recommandent de spécifier les clés que vous utilisez pour déchiffrer les données, une option appeléemode strict. LeAWS Encryption SDKutilise uniquement les clés KMS que vous spécifiez dans votre porte-clés pour déchiffrer le texte chiffré. Les clés de votre porte-clés de déchiffrement doivent inclure au moins 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 leAWS Encryption SDK.NET.

Étape 1 : Instanciez leAWS Encryption SDKet la bibliothèque des fournisseurs de matériel.

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

Étape 2 : Créez l'objet d'entrée pour votre porte-clés.

Pour spécifier les paramètres de la méthode du porte-clés, créez un objet en entrée. Chaque méthode de porte-clés dans leAWS Encryption SDKfor .NET possède un objet d'entrée correspondant. Parce que cet exemple utilise leCreateAwsKmsKeyring()pour créer le porte-clés, il instancie laCreateAwsKmsKeyringInputclasse pour l'entrée.

Dans un porte-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 porte-clés de déchiffrement, cet exemple utilise leCreateAwsKmsKeyring()et l'objet d'entrée du porte-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 leDecrypt(), instanciez la méthodeDecryptInputclasse.

LeCiphertextdu paramètre deDecryptInput()Constructor prend leCiphertextmembre de laEncryptOutputl'objet que leEncrypt()méthode renvoyée. LeCiphertextreprésente leMessage chiffré, qui inclut les données chiffrées, les clés de données chiffrées et les métadonnées que leAWS Encryption SDKdoit déchiffrer le message.

var encryptedMessage = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = encryptedMessage,
    Keyring = keyring
};

Étape 5 : Décryptez le texte chiffré.

var decryptOutput = encryptionSdk.Decrypt(decryptInput);

Étape 6 : Vérifiez le contexte de chiffrement.

LeDecrypt()Méthode de laAWS Encryption SDKne prend pas en contexte de chiffrement. Il obtient les valeurs du contexte de chiffrement à partir des métadonnées contenues dans le message chiffré. Toutefois, avant de renvoyer ou d'utiliser le texte brut, 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 chiffrementest inclusedans le contexte de chiffrement qui était utilisé pour déchiffrer le texte chiffré. LeAWS Encryption SDKajoute 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écryptage à l'aide d'un porte-clés de découverte dans leAWS Encryption SDKpour .NET

Plutôt que de spécifier les clés KMS pour le déchiffrement, vous pouvez fournir unAWS KMS Porte-clés Discovery, qui est un porte-clés qui ne spécifie aucune clé KMS. Un porte-clés découverte permet auAWS Encryption SDKdéchiffrez les données en utilisant la clé KMS qui les a chiffrées, à condition que l'appelant dispose d'une autorisation de déchiffrement sur la clé. Pour obtenir les meilleures pratiques, ajoutez un filtre de découverte qui limite les clés KMS pouvant être utilisées à celles en particulier.Comptes AWSd'une partition spécifiée.

LeAWS Encryption SDKfor .NET fournit un porte-clés de découverte de base qui nécessite unAWS KMSclient et un porte-clés multiclé de découverte nécessitant de spécifier un ou plusieursRégions AWS. Le client et les régions limitent tous les deux les clés KMS pouvant être utilisées pour déchiffrer le message chiffré. Les objets en entrée des deux porte-clés utilisent le filtre de découverte recommandé.

L'exemple suivant illustre le modèle de déchiffrement de données avec unAWS KMSporte-clés découverte et filtre de découverte.

Étape 1 : Instanciez leAWS Encryption SDKet la bibliothèque des fournisseurs de matériel.

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

Étape 2 : Créez l'objet d'entrée pour le porte-clés.

Pour spécifier les paramètres de la méthode du porte-clés, créez un objet en entrée. Chaque méthode de porte-clés dans leAWS Encryption SDKfor .NET possède un objet d'entrée correspondant. Parce que cet exemple utilise leCreateAwsKmsDiscoveryKeyring()pour créer le porte-clés, il instancie laCreateAwsKmsDiscoveryKeyringInputclasse pour l'entrée.

List<string> accounts = new List<string> { "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 porte-clés de déchiffrement, cet exemple utilise leCreateAwsKmsDiscoveryKeyring()et l'objet d'entrée du porte-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 leDecrypt(), instanciez la méthodeDecryptInputclasse. La valeur duCiphertextest le paramètreCiphertextmembre de laEncryptOutputl'objet que leEncrypt()renvoie la méthode.

var ciphertext = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = discoveryKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

Étape 5 : Vérifiez le contexte de chiffrement.

LeAWS Encryption SDKne prend pas de contexte de chiffrement surDecrypt(). Il obtient les valeurs du contexte de chiffrement à partir des métadonnées contenues dans le message chiffré. Toutefois, avant de renvoyer ou d'utiliser le texte brut, 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 chiffrementest inclusedans le contexte de chiffrement qui a été utilisé pour déchiffrer le texte chiffré. LeAWS Encryption SDKajoute 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");
}