AWS Encryption SDKfür .NET-Beispiele

Die folgenden Beispiele zeigen die grundlegenden Codierungsmuster, die Sie beim Programmieren mit dem AWS Encryption SDK für .NET verwenden. Insbesondere instanziieren Sie die Bibliothek AWS Encryption SDK und die Material Provider-Bibliothek. Bevor Sie dann jede Methode aufrufen, instanziieren Sie ein Objekt, das die Eingabe für die Methode definiert. Dies ist dem Codierungsmuster sehr ähnlich, das Sie in der verwenden. AWS SDK for .NET

Beispiele für die Konfiguration von Optionen in derAWS Encryption SDK, z. B. die Angabe einer alternativen Algorithmussuite, die Beschränkung verschlüsselter Datenschlüssel und die Verwendung von Schlüsseln für AWS KMS mehrere Regionen, finden Sie unterKonfigurieren der AWS Encryption SDK.

Weitere Beispiele AWS Encryption SDK für die Programmierung mit für.NET finden Sie in den Beispielen im aws-encryption-sdk-net Verzeichnis des aws-encryption-sdk-dafny Repositorys unter GitHub.

Verschlüsseln von Daten im AWS Encryption SDK für.NET

Dieses Beispiel zeigt das grundlegende Muster für die Verschlüsselung von Daten. Es verschlüsselt eine kleine Datei mit Datenschlüsseln, die durch einen AWS KMS Umschließungsschlüssel geschützt sind.

Schritt 1: Instanziieren Sie die Bibliothek AWS Encryption SDK und die Materiallieferantenbibliothek.

Beginnen Sie mit der Instanziierung der Bibliothek AWS Encryption SDK und der Materiallieferantenbibliothek. Sie verwenden die Methoden in, AWS Encryption SDK um Daten zu verschlüsseln und zu entschlüsseln. Sie verwenden die Methoden in der Materialanbieter-Bibliothek, um die Schlüsselbunde zu erstellen, die angeben, welche Schlüssel Ihre Daten schützen.

Die Art AWS Encryption SDK und Weise, wie Sie die Material Provider-Bibliothek instanziieren, unterscheidet sich zwischen den Versionen 3. x und 4. x von AWS Encryption SDK für .NET. Alle folgenden Schritte sind für beide Versionen 3 identisch. x und 4. x von AWS Encryption SDK für .NET.

Version 3.x

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

Version 4.x

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

Schritt 2: Erstellen Sie ein Eingabeobjekt für den Schlüsselbund.

Jede Methode, die einen Schlüsselbund erstellt, hat eine entsprechende Eingabeobjektklasse. Um beispielsweise das Eingabeobjekt für die CreateAwsKmsKeyring() Methode zu erstellen, erstellen Sie eine Instanz der CreateAwsKmsKeyringInput Klasse.

Obwohl die Eingabe für diesen Schlüsselbund keinen Generatorschlüssel spezifiziert, ist der einzelne KMS-Schlüssel, der durch den KmsKeyId Parameter angegeben wird, der Generatorschlüssel. Er generiert und verschlüsselt den Datenschlüssel, der die Daten verschlüsselt.

Dieses Eingabeobjekt benötigt einen AWS KMS Client für den AWS-Region KMS-Schlüssel. Um einen AWS KMS Client zu erstellen, instanziieren Sie die AmazonKeyManagementServiceClient Klasse in der. AWS SDK for .NET Wenn Sie den AmazonKeyManagementServiceClient() Konstruktor ohne Parameter aufrufen, wird ein Client mit den Standardwerten erstellt.

In einem AWS KMS Schlüsselbund, der AWS Encryption SDK für die Verschlüsselung mit für.NET verwendet wird, können Sie die KMS-Schlüssel anhand der Schlüssel-ID, des Schlüssel-ARN, des Aliasnamens oder des Alias-ARN identifizieren. In einem AWS KMS Schlüsselbund, der zum Entschlüsseln verwendet wird, müssen Sie einen Schlüssel-ARN verwenden, um jeden KMS-Schlüssel zu identifizieren. Wenn Sie Ihren Verschlüsselungsschlüsselbund für die Entschlüsselung wiederverwenden möchten, verwenden Sie eine ARN-Schlüssel-ID für alle KMS-Schlüssel.

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

Schritt 3: Erstellen Sie den Schlüsselbund.

Um den Schlüsselbund zu erstellen, rufen Sie die Schlüsselbundmethode mit dem Schlüsselbund-Eingabeobjekt auf. In diesem Beispiel wird die CreateAwsKmsKeyring() Methode verwendet, die nur einen KMS-Schlüssel benötigt.

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

Schritt 4: Definieren Sie einen Verschlüsselungskontext.

Ein Verschlüsselungskontext ist ein optionales, aber dringend empfohlenes Element kryptografischer Operationen in derAWS Encryption SDK. Sie können ein oder mehrere nicht geheime Schlüssel-Wert-Paare definieren.

Anmerkung

Mit Version 4. x of the AWS Encryption SDK für .NET, Sie können in allen Verschlüsselungsanforderungen mit dem erforderlichen Verschlüsselungskontext CMM einen Verschlüsselungskontext angeben.

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

Schritt 5: Erstellen Sie das Eingabeobjekt für die Verschlüsselung.

Bevor Sie die Encrypt() Methode aufrufen, erstellen Sie eine Instanz der EncryptInput Klasse.

string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
            
// Define the encrypt input
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    EncryptionContext = encryptionContext
};

Schritt 6: Verschlüsseln Sie den Klartext.

Verwenden Sie die Encrypt() Methode vonAWS Encryption SDK, um den Klartext mit dem von Ihnen definierten Schlüsselbund zu verschlüsseln.

Die EncryptOutput Encrypt() Methode gibt Methoden zum Abrufen der verschlüsselten Nachricht (Ciphertext), den Verschlüsselungskontext und die Algorithmus-Suite an.

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

Schritt 7: Holen Sie sich die verschlüsselte Nachricht.

Die Decrypt() Methode in AWS Encryption SDK for .NET verwendet das Ciphertext Mitglied der EncryptOutput Instanz.

Das Ciphertext Mitglied des EncryptOutput Objekts ist die verschlüsselte Nachricht, ein portables Objekt, das die verschlüsselten Daten, verschlüsselten Datenschlüssel und Metadaten einschließlich des Verschlüsselungskontextes enthält. Sie können die verschlüsselte Nachricht sicher für einen längeren Zeitraum speichern oder sie an die Decrypt() Methode zur Wiederherstellung des Klartextes weiterleiten.

var encryptedMessage = encryptOutput.Ciphertext;

Entschlüsselung im strikten Modus in für.NET AWS Encryption SDK

Bewährte Methoden empfehlen, dass Sie die Schlüssel angeben, die Sie zum Entschlüsseln von Daten verwenden. Diese Option wird als strikter Modus bezeichnet. Der AWS Encryption SDK verwendet nur die KMS-Schlüssel, die Sie in Ihrem Schlüsselbund angeben, um den Chiffretext zu entschlüsseln. Die Schlüssel in Ihrem Entschlüsselungsschlüsselbund müssen mindestens einen der Schlüssel enthalten, mit denen die Daten verschlüsselt wurden.

Dieses Beispiel zeigt das grundlegende Muster der Entschlüsselung im strikten Modus mit dem AWS Encryption SDK für.NET.

Schritt 1: Instanziieren Sie die Bibliothek AWS Encryption SDK und die Material Provider-Bibliothek.

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

Schritt 2: Erstellen Sie das Eingabeobjekt für Ihren Schlüsselbund.

Um die Parameter für die Schlüsselbundmethode anzugeben, erstellen Sie ein Eingabeobjekt. Jede Schlüsselbundmethode in der AWS Encryption SDK für.NET hat ein entsprechendes Eingabeobjekt. Da in diesem Beispiel die CreateAwsKmsKeyring() Methode verwendet wird, um den Schlüsselbund zu erstellen, wird die CreateAwsKmsKeyringInput Klasse für die Eingabe instanziiert.

In einem Schlüsselbund für die Entschlüsselung müssen Sie einen Schlüssel-ARN verwenden, um KMS-Schlüssel zu identifizieren.

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

Schritt 3: Erstellen Sie den Schlüsselbund.

Um den Schlüsselbund für die Entschlüsselung zu erstellen, werden in diesem Beispiel die CreateAwsKmsKeyring() Methode und das Schlüsselbund-Eingabeobjekt verwendet.

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

Schritt 4: Erstellen Sie das Eingabeobjekt für die Entschlüsselung.

Um das Eingabeobjekt für die Decrypt() Methode zu erstellen, instanziieren Sie die Klasse. DecryptInput

Der Ciphertext Parameter des DecryptInput() Konstruktors verwendet das Ciphertext Mitglied des EncryptOutput Objekts, das die Encrypt() Methode zurückgegeben hat. Die Ciphertext Eigenschaft stellt die verschlüsselte Nachricht dar, die die verschlüsselten Daten, verschlüsselten Datenschlüssel und Metadaten enthält, die zum Entschlüsseln der Nachricht AWS Encryption SDK benötigt werden.

Mit Version 4. x von AWS Encryption SDK für .NET können Sie den optionalen EncryptionContext Parameter verwenden, um Ihren Verschlüsselungskontext in der Decrypt() Methode anzugeben.

Verwenden Sie den EncryptionContext Parameter, um zu überprüfen, ob der beim Verschlüsseln verwendete Verschlüsselungskontext in dem Verschlüsselungskontext enthalten ist, der zum Entschlüsseln des Chiffretextes verwendet wird. Dadurch werden Paare zum Verschlüsselungskontext AWS Encryption SDK hinzugefügt, einschließlich der digitalen Signatur, wenn Sie eine Algorithmussuite mit Signierung verwenden, z. B. die Standard-Algorithmussuite.

var encryptedMessage = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = encryptedMessage,
    Keyring = keyring,
    EncryptionContext = encryptionContext // OPTIONAL
};

Schritt 5: Entschlüsseln Sie den Chiffretext.

var decryptOutput = encryptionSdk.Decrypt(decryptInput);

Schritt 6: Überprüfen Sie den Verschlüsselungskontext — Version 3. x

Die Decrypt() Methode der Version 3. x von AWS Encryption SDK for .NET benötigt keinen Verschlüsselungskontext. Es ruft die Verschlüsselungskontextwerte aus den Metadaten in der verschlüsselten Nachricht ab. Bevor Sie den Klartext zurückgeben oder verwenden, sollten Sie jedoch überprüfen, ob der Verschlüsselungskontext, der zum Entschlüsseln des Chiffretextes verwendet wurde, den Verschlüsselungskontext enthält, den Sie bei der Verschlüsselung angegeben haben.

Stellen Sie sicher, dass der beim Verschlüsseln verwendete Verschlüsselungskontext in dem Verschlüsselungskontext enthalten ist, der zum Entschlüsseln des Chiffretextes verwendet wurde. Das AWS Encryption SDK fügt dem Verschlüsselungskontext Paare hinzu, einschließlich der digitalen Signatur, wenn Sie eine Algorithmussuite mit Signierung verwenden, z. B. die Standard-Algorithmussuite.

// 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");
}

Entschlüsseln mit einem Discovery-Schlüsselbund im für.NET AWS Encryption SDK

Anstatt die KMS-Schlüssel für die Entschlüsselung anzugeben, können Sie einen AWS KMS Discovery-Schlüsselbund angeben. Dabei handelt es sich um einen Schlüsselbund, der keine KMS-Schlüssel angibt. Mit einem Discovery-Schlüsselbund können die Daten mit dem KMS-Schlüssel, der sie verschlüsselt hat, AWS Encryption SDK entschlüsselt werden, sofern der Anrufer über die Entschlüsselungsberechtigung für den Schlüssel verfügt. Für bewährte Methoden sollten Sie einen Erkennungsfilter hinzufügen, der die KMS-Schlüssel, die verwendet werden können, auf diejenigen beschränkt, die insbesondere AWS-Konten für eine bestimmte Partition verwendet werden können.

Der AWS Encryption SDK für.NET bietet einen einfachen Discovery-Schlüsselbund, für den ein AWS KMS Client erforderlich ist, und einen Discovery-Mehrfachschlüsselbund, für den Sie einen oder mehrere Schlüssel angeben müssen. AWS-Regionen Sowohl der Client als auch die Regionen beschränken die Anzahl der KMS-Schlüssel, die zum Entschlüsseln der verschlüsselten Nachricht verwendet werden können. Die Eingabeobjekte für beide Schlüsselbunde verwenden den empfohlenen Erkennungsfilter.

Das folgende Beispiel zeigt das Muster für die Entschlüsselung von Daten mit einem AWS KMS Discovery-Schlüsselbund und einem Discovery-Filter.

Schritt 1: Instanziieren Sie die Bibliothek AWS Encryption SDK und die Materiallieferantenbibliothek.

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

Schritt 2: Erstellen Sie das Eingabeobjekt für den Schlüsselbund.

Um die Parameter für die Schlüsselbundmethode anzugeben, erstellen Sie ein Eingabeobjekt. Jede Schlüsselbundmethode in der AWS Encryption SDK für.NET hat ein entsprechendes Eingabeobjekt. Da in diesem Beispiel die CreateAwsKmsDiscoveryKeyring() Methode verwendet wird, um den Schlüsselbund zu erstellen, wird die CreateAwsKmsDiscoveryKeyringInput Klasse für die Eingabe instanziiert.

List<string> accounts = new List<string> { "111122223333" };

var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = accounts,
        Partition = "aws"
    }
};

Schritt 3: Erstellen Sie den Schlüsselbund.

Um den Schlüsselbund für die Entschlüsselung zu erstellen, werden in diesem Beispiel die CreateAwsKmsDiscoveryKeyring() Methode und das Schlüsselbund-Eingabeobjekt verwendet.

var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);

Schritt 4: Erstellen Sie das Eingabeobjekt für die Entschlüsselung.

Um das Eingabeobjekt für die Decrypt() Methode zu erstellen, instanziieren Sie die Klasse. DecryptInput Der Wert des Ciphertext Parameters ist das Ciphertext Mitglied des EncryptOutput Objekts, das die Encrypt() Methode zurückgibt.

Mit Version 4. x von AWS Encryption SDK für .NET können Sie den optionalen EncryptionContext Parameter verwenden, um Ihren Verschlüsselungskontext in der Decrypt() Methode anzugeben.

Verwenden Sie den EncryptionContext Parameter, um zu überprüfen, ob der beim Verschlüsseln verwendete Verschlüsselungskontext in dem Verschlüsselungskontext enthalten ist, der zum Entschlüsseln des Chiffretextes verwendet wird. Dadurch werden Paare zum Verschlüsselungskontext AWS Encryption SDK hinzugefügt, einschließlich der digitalen Signatur, wenn Sie eine Algorithmussuite mit Signierung verwenden, z. B. die Standard-Algorithmussuite.

var ciphertext = encryptOutput.Ciphertext;

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

Schritt 5: Überprüfen Sie den Verschlüsselungskontext — Version 3. x

Die Decrypt() Methode der Version 3. x von AWS Encryption SDK for .NET nimmt keinen Verschlüsselungskontext anDecrypt(). Es ruft die Verschlüsselungskontextwerte aus den Metadaten in der verschlüsselten Nachricht ab. Bevor Sie den Klartext zurückgeben oder verwenden, sollten Sie jedoch überprüfen, ob der Verschlüsselungskontext, der zum Entschlüsseln des Chiffretextes verwendet wurde, den Verschlüsselungskontext enthält, den Sie bei der Verschlüsselung angegeben haben.

Stellen Sie sicher, dass der beim Verschlüsseln verwendete Verschlüsselungskontext in dem Verschlüsselungskontext enthalten ist, der zum Entschlüsseln des Chiffretextes verwendet wurde. Das AWS Encryption SDK fügt dem Verschlüsselungskontext Paare hinzu, einschließlich der digitalen Signatur, wenn Sie eine Algorithmussuite mit Signierung verwenden, z. B. die Standard-Algorithmussuite.

// 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");
}