AWS Encryption SDKfür .NET - AWS Encryption SDK
Installieren und ErstellenDebuggingAWS KMS-SchlüsselbündeErforderlicher Verschlüsselungskontext (CMM)

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

AWS Encryption SDKfür .NET

Die AWS Encryption SDK for .NET ist eine clientseitige Verschlüsselungsbibliothek für Entwickler, die Anwendungen in C# und anderen .NET-Programmiersprachen schreiben. Sie wird unter Windows, macOS und Linux unterstützt.

Alle Programmiersprachenimplementierungen von sind vollständig interoperabel. AWS Encryption SDK Wenn Sie jedoch Daten mit dem erforderlichen Verschlüsselungskontext CMM in Version 4 verschlüsseln. x von AWS Encryption SDK für .NET, Sie können es nur mit Version 4 entschlüsseln. x der AWS Encryption SDK für .NET oder Version 3. x derAWS-Verschlüsselungs-SDK for Java.

Anmerkung

Version 4.0.0 von AWS Encryption SDK für .NET weicht von der AWS Encryption SDK Nachrichtenspezifikation ab. Aus diesem Grund können Nachrichten, die mit Version 4.0.0 verschlüsselt wurden, nur mit Version 4.0.0 oder höher von for.NET entschlüsselt werden. AWS Encryption SDK Sie können mit keiner anderen Programmiersprachenimplementierung entschlüsselt werden.

Version 4.0.1 von AWS Encryption SDK for .NET schreibt Nachrichten gemäß der AWS Encryption SDK Nachrichtenspezifikation und ist mit anderen Programmiersprachenimplementierungen interoperabel. Standardmäßig kann Version 4.0.1 Nachrichten lesen, die mit Version 4.0.0 verschlüsselt wurden. Wenn Sie jedoch mit Version 4.0.0 verschlüsselte Nachrichten nicht entschlüsseln möchten, können Sie die NetV4_0_0_RetryPolicyEigenschaft so angeben, dass der Client diese Nachrichten nicht lesen kann. Weitere Informationen finden Sie in den Versionshinweisen zu Version 4.0.1 im Repository unter. aws-encryption-sdk-dafny GitHub

Das AWS Encryption SDK für.NET unterscheidet sich von einigen anderen Programmiersprachenimplementierungen AWS Encryption SDK in folgenden Punkten:

Das AWS Encryption SDK für .NET enthält alle Sicherheitsfunktionen, die in Version 2.0 eingeführt wurden. x und höher von anderen Sprachimplementierungen von. AWS Encryption SDK Wenn Sie jedoch for.NET verwenden, AWS Encryption SDK um Daten zu entschlüsseln, die mit einer Version vor 2.0 verschlüsselt wurden. x-Version einer anderen Sprachimplementierung vonAWS Encryption SDK, möglicherweise müssen Sie Ihre Verpflichtungsrichtlinie anpassen. Details hierzu finden Sie unter So legen Sie Ihre Engagement-Richtlinie fest.

Die AWS Encryption SDK für.NET-Version ist ein Produkt von AWS Encryption SDK In Dafny, einer formalen Überprüfungssprache, in der Sie Spezifikationen, den Code zu ihrer Implementierung und die Beweise, um sie zu testen, schreiben. Das Ergebnis ist eine Bibliothek, die die Funktionen von AWS Encryption SDK in einem Framework implementiert, das die funktionale Korrektheit gewährleistet.

Weitere Informationen

  • 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 unter. Konfigurieren der AWS Encryption SDK

  • Einzelheiten zur Programmierung mit dem AWS Encryption SDK für.NET finden Sie im aws-encryption-sdk-netVerzeichnis des aws-encryption-sdk-dafny Repositorys unter GitHub.

Themen

Installation von AWS Encryption SDK für.NET

Das AWS Encryption SDK für .NET ist als AWS.Cryptography.EncryptionSDKPaket in verfügbar NuGet. Einzelheiten zur Installation und Erstellung von AWS Encryption SDK für.NET finden Sie in der Datei README.md im Repository. aws-encryption-sdk-net

Version 3.x

Ausführung 3. x of the AWS Encryption SDK für .NET unterstützt .NET Framework 4.5.2 — 4.8 nur unter Windows. Es unterstützt .NET Core 3.0+ und .NET 5.0 und höher auf allen unterstützten Betriebssystemen.

Version 4.x

Ausführung 4. x of the AWS Encryption SDK für .NET unterstützt .NET 6.0 und .NET Framework net48 und höher.

AWS Encryption SDKFür .NET sind die Schlüssel AWS SDK for .NET auch dann erforderlich, wenn Sie nicht AWS Key Management Service (AWS KMS) verwenden. Es ist mit dem NuGet Paket installiert. Sofern Sie jedoch keine AWS KMS Schlüssel verwenden, benötigt AWS Encryption SDK für.NET keine AWS Anmeldeinformationen und keine Interaktion mit einem AWS Dienst. AWS-Konto Hilfe beim Einrichten eines AWS Kontos finden Sie bei Bedarf unterVerwenden der AWS Encryption SDK mit AWS KMS.

Debuggen des AWS Encryption SDK für .NET

Das AWS Encryption SDK für .NET generiert keine Protokolle. Ausnahmen im AWS Encryption SDK für.NET erzeugen eine Ausnahmemeldung, aber keine Stack-Traces.

Um Ihnen beim Debuggen zu helfen, stellen Sie sicher, dass Sie die AWS SDK for .NET Anmeldung bei aktivieren. Mithilfe der Protokolle und Fehlermeldungen von AWS SDK for .NET können Sie Fehler, die in der auftreten, AWS SDK for .NET von denen in AWS Encryption SDK für.NET unterscheiden. Hilfe zur AWS SDK for .NET Protokollierung finden Sie AWSLoggingim AWS SDK for .NETEntwicklerhandbuch. (Um das Thema zu lesen, erweitern Sie den Abschnitt Öffnen, um .NET Framework-Inhalte anzuzeigen.)

AWS KMSSchlüsselanhänger im AWS Encryption SDK für.NET

Die grundlegenden AWS KMS Schlüsselbunde im AWS Encryption SDK für.NET benötigen nur einen KMS-Schlüssel. Sie benötigen außerdem einen AWS KMS Client, sodass Sie den Client für den AWS-Region KMS-Schlüssel konfigurieren können.

Um einen AWS KMS Schlüsselbund mit einem oder mehreren Schlüsseln zu erstellen, verwenden Sie einen Mehrfachschlüsselbund. Der AWS Encryption SDK für.NET hat einen speziellen Mehrfachschlüsselbund, der einen oder mehrere AWS KMS Schlüssel akzeptiert, und einen Standard-Mehrfachschlüsselbund, der einen oder mehrere Schlüsselbunde eines beliebigen unterstützten Typs akzeptiert. Manche Programmierer ziehen es vor, eine Methode mit mehreren Schlüsselbunden zu verwenden, um all ihre Schlüsselbunde zu erstellen, und for.NET unterstützt diese Strategie. AWS Encryption SDK

Die AWS Encryption SDK für.NET bietet grundlegende Einzelschlüsselringe und Mehrfachschlüsselringe für alle typischen Anwendungsfälle, einschließlich Schlüssel für mehrere Regionen. AWS KMS

Um beispielsweise einen AWS KMS Schlüsselbund mit einem Schlüssel zu erstellen, können Sie die Methode verwenden. AWS KMS CreateAwsKmsKeyring()

Version 3.x

Im folgenden Beispiel wird Version 3 verwendet. x von AWS Encryption SDK für .NET, um einen AWS KMS Standardclient für die Region zu erstellen, der den angegebenen Schlüssel enthält.

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

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

// Create the keyring
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Version 4.x

Das folgende Beispiel verwendet Version 4. x von AWS Encryption SDK für .NET, um einen AWS KMS Client für die Region zu erstellen, der den angegebenen Schlüssel enthält.

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

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsArn
};

// Create the keyring
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);

Verwenden Sie die CreateAwsKmsMultiKeyring() Methode, um einen Schlüsselbund mit einem oder mehreren AWS KMS Schlüsseln zu erstellen. In diesem Beispiel werden zwei AWS KMS Schlüssel verwendet. Verwenden Sie nur den Generator Parameter, um einen KMS-Schlüssel anzugeben. Der KmsKeyIds Parameter, der zusätzliche KMS-Schlüssel angibt, ist optional.

Die Eingabe für diesen Schlüsselbund benötigt keinen AWS KMS Client. Stattdessen AWS Encryption SDK verwendet der den AWS KMS Standardclient für jede Region, die durch einen KMS-Schlüssel im Schlüsselbund repräsentiert wird. Befindet sich der KMS-Schlüssel, der durch den Wert des Generator Parameters identifiziert wird, beispielsweise in der Region USA West (Oregon) (us-west-2), AWS Encryption SDK wird ein AWS KMS Standardclient für die us-west-2 Region erstellt. Wenn Sie den AWS KMS Client anpassen müssen, verwenden Sie die CreateAwsKmsKeyring() Methode.

Im folgenden Beispiel wird Version 4 verwendet. x von AWS Encryption SDK für .NET und die CreateAwsKmsKeyring() Methode zum Anpassen des AWS KMS Clients.

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

Version 4. x of the AWS Encryption SDK für .NET unterstützt AWS KMS Schlüsselringe, die symmetrische Verschlüsselung (SYMMETRIC_DEFAULT) oder asymmetrische RSA-KMS-Schlüssel verwenden. AWS KMSSchlüsselringe, die mit asymmetrischen RSA-KMS-Schlüsseln erstellt wurden, können nur ein key pair enthalten.

Um mit einem asymmetrischen AWS KMS RSA-Schlüsselbund zu verschlüsseln, benötigen Sie kms: GenerateDataKey oder kms:Encrypt nicht, da Sie bei der Erstellung des Schlüsselbunds das Material der öffentlichen Schlüssel angeben müssen, das Sie für die Verschlüsselung verwenden möchten. Bei der Verschlüsselung mit diesem Schlüsselbund werden keine Anrufe getätigt. AWS KMS Um mit einem asymmetrischen AWS KMS RSA-Schlüsselbund zu entschlüsseln, benötigen Sie die kms:Decrypt-Berechtigung.

Um einen asymmetrischen AWS KMS RSA-Schlüsselbund zu erstellen, müssen Sie den öffentlichen Schlüssel und den privaten Schlüssel ARN aus Ihrem asymmetrischen RSA-KMS-Schlüssel angeben. Der öffentliche Schlüssel muss PEM-codiert sein. Im folgenden Beispiel wird ein AWS KMS Schlüsselbund mit einem asymmetrischen RSA-Schlüsselpaar erstellt.

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

Erforderliche Verschlüsselungskontexte in Version 4.x

Mit Version 4. x of the AWS Encryption SDK für .NET können Sie den erforderlichen Verschlüsselungskontext CMM verwenden, um Verschlüsselungskontexte für Ihre kryptografischen Operationen vorzuschreiben. Ein Verschlüsselungskontext ist ein Satz nicht geheimer Schlüssel-Wert-Paare. Der Verschlüsselungskontext ist kryptografisch an die verschlüsselten Daten gebunden, sodass derselbe Verschlüsselungskontext erforderlich ist, um das Feld zu entschlüsseln. Wenn Sie den erforderlichen Verschlüsselungskontext CMM verwenden, können Sie einen oder mehrere erforderliche Verschlüsselungskontextschlüssel (erforderliche Schlüssel) angeben, die in allen Verschlüsselungs- und Entschlüsselungsaufrufen enthalten sein müssen.

Anmerkung

Der erforderliche Verschlüsselungskontext CMM ist nur mit Version 3 interoperabel. x von. AWS-Verschlüsselungs-SDK for Java Es ist mit keiner anderen Programmiersprachenimplementierung interoperabel. Wenn Sie Daten mit dem erforderlichen Verschlüsselungskontext CMM verschlüsseln, können Sie sie nur mit Version 3 entschlüsseln. x der AWS-Verschlüsselungs-SDK for Java oder Version 4. x von AWS Encryption SDK für .NET.

Beim Verschlüsseln AWS Encryption SDK wird überprüft, ob alle erforderlichen Verschlüsselungskontextschlüssel in dem von Ihnen angegebenen Verschlüsselungskontext enthalten sind. Das AWS Encryption SDK signiert die von Ihnen angegebenen Verschlüsselungskontexte. Nur die Schlüssel-Wert-Paare, bei denen es sich nicht um erforderliche Schlüssel handelt, werden serialisiert und im Klartext-Format im Header der verschlüsselten Nachricht gespeichert, die der Verschlüsselungsvorgang zurückgibt.

Beim Entschlüsseln müssen Sie einen Verschlüsselungskontext angeben, der alle Schlüssel-Wert-Paare enthält, die die erforderlichen Schlüssel darstellen. Der AWS Encryption SDK verwendet diesen Verschlüsselungskontext und die im Header der verschlüsselten Nachricht gespeicherten Schlüssel-Wert-Paare, um den ursprünglichen Verschlüsselungskontext zu rekonstruieren, den Sie beim Verschlüsselungsvorgang angegeben haben. Wenn der ursprüngliche Verschlüsselungskontext AWS Encryption SDK nicht rekonstruiert werden kann, schlägt der Entschlüsselungsvorgang fehl. Wenn Sie ein Schlüssel-Wert-Paar angeben, das den erforderlichen Schlüssel mit einem falschen Wert enthält, kann die verschlüsselte Nachricht nicht entschlüsselt werden. Sie müssen dasselbe Schlüssel-Wert-Paar angeben, das bei Encrypt angegeben wurde.

Wichtig

Überlegen Sie sich sorgfältig, welche Werte Sie für die erforderlichen Schlüssel in Ihrem Verschlüsselungskontext wählen. Sie müssen in der Lage sein, dieselben Schlüssel und die entsprechenden Werte beim Entschlüsseln erneut anzugeben. Wenn Sie die erforderlichen Schlüssel nicht reproduzieren können, kann die verschlüsselte Nachricht nicht entschlüsselt werden.

Im folgenden Beispiel wird ein AWS KMS Schlüsselbund mit dem erforderlichen Verschlüsselungskontext CMM initialisiert.

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

Wenn Sie einen AWS KMS Schlüsselbund verwenden, verwendet AWS Encryption SDK for .NET auch den Verschlüsselungskontext, um zusätzliche authentifizierte Daten (AAD) in den Aufrufen des Schlüsselbundes bereitzustellen. AWS KMS