AWS Encryption SDKper.NET - AWS Encryption SDK

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

AWS Encryption SDKper.NET

The AWS Encryption SDK for .NET è una libreria di crittografia lato client per sviluppatori che scrivono applicazioni in C# e altri linguaggi di programmazione.NET. ed è supportata su Windows, macOS e Linux.

Tutte le implementazioni del linguaggio di programmazione di sono completamente interoperabiliAWS Encryption SDK. Tuttavia, se si crittografano i dati utilizzando il contesto di crittografia richiesto, CMM nella versione 4. x di AWS Encryption SDK per .NET, è possibile decrittografarlo solo con la versione 4. x del AWS Encryption SDK per .NET o versione 3. x delSDK di crittografia AWS per Java.

Nota

La versione 4.0.0 di per.NET si discosta dalla specifica del AWS Encryption SDK messaggio. AWS Encryption SDK Di conseguenza, i messaggi crittografati dalla versione 4.0.0 possono essere decrittografati solo dalla versione 4.0.0 o successiva di per.NET. AWS Encryption SDK Non possono essere decrittografati da nessun'altra implementazione del linguaggio di programmazione.

La versione 4.0.1 di AWS Encryption SDK for .NET scrive messaggi in base alla specifica del AWS Encryption SDK messaggio ed è interoperabile con altre implementazioni del linguaggio di programmazione. Per impostazione predefinita, la versione 4.0.1 è in grado di leggere i messaggi crittografati dalla versione 4.0.0. Tuttavia, se non si desidera decrittografare i messaggi crittografati dalla versione 4.0.0, è possibile specificare la NetV4_0_0_RetryPolicyproprietà per impedire al client di leggere questi messaggi. Per ulteriori informazioni, consulta le note di rilascio della versione 4.0.1 nel repository su. aws-encryption-sdk-dafny GitHub

The AWS Encryption SDK for .NET si differenzia da alcune delle altre implementazioni del linguaggio di programmazione per i AWS Encryption SDK seguenti motivi:

The AWS Encryption SDK for .NET include tutte le funzionalità di sicurezza introdotte nelle versioni 2.0. x e versioni successive di altre implementazioni linguistiche diAWS Encryption SDK. Tuttavia, se si utilizza AWS Encryption SDK for .NET per decrittografare dati crittografati con una versione precedente alla 2.0. versione x, un'altra implementazione linguistica diAWS Encryption SDK, potrebbe essere necessario modificare la politica di impegno. Per informazioni dettagliate, vedi Come impostare la tua politica di impegno.

The AWS Encryption SDK for .NET è un prodotto di AWS Encryption SDK in Dafny, un linguaggio di verifica formale in cui si scrivono le specifiche, il codice per implementarle e le bozze per testarle. Il risultato è una libreria che implementa le funzionalità di AWS Encryption SDK in un framework che garantisce la correttezza funzionale.

Ulteriori informazioni

  • Per esempi che mostrano come configurare le opzioni inAWS Encryption SDK, ad esempio la specificazione di una suite di algoritmi alternativa, la limitazione delle chiavi di dati crittografate e l'utilizzo di chiavi multiregionali, vedi. AWS KMS Configurazione della AWS Encryption SDK

  • Per informazioni dettagliate sulla programmazione con AWS Encryption SDK for .NET, consulta la aws-encryption-sdk-netdirectory del repository on. aws-encryption-sdk-dafny GitHub

Installazione del file AWS Encryption SDK per.NET

Il AWS Encryption SDK for.NET è disponibile come AWS.Cryptography.EncryptionSDKpacchetto in NuGet. Per informazioni dettagliate sull'installazione e la AWS Encryption SDK creazione di per.NET, consulta il file README.md nel repository. aws-encryption-sdk-net

Versione 3.x

Versione 3. x of the AWS Encryption SDK for .NET supporta .NET Framework 4.5.2 — 4.8 solo su Windows. Supporta .NET Core 3.0+ e .NET 5.0 e versioni successive su tutti i sistemi operativi supportati.

Versione 4.x

Versione 4. x of the AWS Encryption SDK for .NET supporta .NET 6.0 e .NET Framework net48 e versioni successive.

Il AWS Encryption SDK per.NET richiede le AWS SDK for .NET chiavi anche se non si utilizzano AWS Key Management Service (AWS KMS). Viene installato con il NuGet pacchetto. Tuttavia, a meno che non si utilizzino AWS KMS chiavi, AWS Encryption SDK per.NET non richiede AWS credenziali o interazioni con alcun AWS servizio. Account AWS Per informazioni sulla configurazione di un AWS account, se necessario, consultaUtilizzo dell'AWS Encryption SDK con AWS KMS.

Esecuzione del debug di per.NET AWS Encryption SDK

Il file AWS Encryption SDK for .NET non genera alcun registro. Le eccezioni in per.NET generano un messaggio di eccezione, ma nessuna traccia dello stack. AWS Encryption SDK

Per aiutarti a eseguire il debug, assicurati di abilitare l'accesso a. AWS SDK for .NET I log e i messaggi di errore di AWS SDK for .NET possono aiutarti a distinguere gli errori derivanti AWS SDK for .NET da quelli presenti in .NET. AWS Encryption SDK Per informazioni sulla AWS SDK for .NET registrazione, consulta la Guida per AWSLogginggli AWS SDK for .NETsviluppatori. (Per vedere l'argomento, espandi la sezione Apri per visualizzare il contenuto di.NET Framework).

AWS KMSportachiavi in AWS Encryption SDK per.NET

I AWS KMS portachiavi di base presenti per.NET richiedono solo una chiave KMS. AWS Encryption SDK Richiedono anche un AWS KMS client, che ti dà l'opportunità di configurare il client per la chiave Regione AWS KMS.

Per creare un AWS KMS portachiavi con una o più chiavi avvolgenti, usa un portachiavi multiplo. AWS Encryption SDKFor.NET ha uno speciale portachiavi multiplo che accetta una o più AWS KMS chiavi e un portachiavi multiplo standard che accetta uno o più portachiavi di qualsiasi tipo supportato. Alcuni programmatori preferiscono utilizzare un metodo con portachiavi multipli per creare tutti i propri portachiavi, e for .NET supporta questa strategia. AWS Encryption SDK

The AWS Encryption SDK for .NET fornisce portachiavi di base a chiave singola e portachiavi multipli per tutti i casi d'uso tipici, incluse le chiavi multiregionali. AWS KMS

Ad esempio, per creare un AWS KMS portachiavi con una sola AWS KMS chiave, puoi utilizzare il metodo. CreateAwsKmsKeyring()

Version 3.x

L'esempio seguente utilizza la versione 3. x di a per.NET AWS Encryption SDK per creare un AWS KMS client predefinito per la regione che contiene la chiave specificata.

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

L'esempio seguente utilizza la versione 4. x di a per.NET AWS Encryption SDK per creare un AWS KMS client per la regione che contiene la chiave specificata.

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

Per creare un portachiavi con una o più AWS KMS chiavi, usa il CreateAwsKmsMultiKeyring() metodo. Questo esempio utilizza due AWS KMS chiavi. Per specificare una chiave KMS, utilizzate solo il Generator parametro. Il KmsKeyIds parametro che specifica le chiavi KMS aggiuntive è facoltativo.

L'input per questo portachiavi non richiede un client. AWS KMS AWS Encryption SDKUtilizza invece il AWS KMS client predefinito per ogni regione rappresentato da una chiave KMS nel portachiavi. Ad esempio, se la chiave KMS identificata dal valore del Generator parametro si trova nella regione degli Stati Uniti occidentali (Oregon) (us-west-2), AWS Encryption SDK crea un AWS KMS client predefinito per la regione. us-west-2 Se è necessario personalizzare il AWS KMS client, utilizzare il CreateAwsKmsKeyring() metodo.

L'esempio seguente utilizza la versione 4. x del AWS Encryption SDK per .NET e il CreateAwsKmsKeyring() metodo per personalizzare il 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);

Versione 4. x of the AWS Encryption SDK for .NET supporta i AWS KMS portachiavi che utilizzano la crittografia simmetrica (SYMMETRIC_DEFAULT) o le chiavi RSA KMS asimmetriche. AWS KMSi portachiavi creati con chiavi RSA KMS asimmetriche possono contenere solo una coppia di chiavi.

Per crittografare con un AWS KMS portachiavi RSA asimmetrico, non è necessario kms: GenerateDataKey o KMS:Encrypt perché è necessario specificare il materiale della chiave pubblica che si desidera utilizzare per la crittografia quando si crea il portachiavi. Non viene effettuata alcuna chiamata durante la crittografia con questo portachiavi. AWS KMS Per decrittografare con un portachiavi AWS KMS RSA asimmetrico, è necessaria l'autorizzazione KMS:Decrypt.

Per creare un AWS KMS portachiavi RSA asimmetrico, devi fornire la chiave pubblica e la chiave privata ARN della tua chiave RSA KMS asimmetrica. La chiave pubblica deve essere codificata in PEM. L'esempio seguente crea un AWS KMS portachiavi con una coppia di chiavi RSA asimmetrica.

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

Contesti di crittografia richiesti nella versione 4.x

Con la versione 4. x of the AWS Encryption SDK per .NET, è possibile utilizzare il contesto di crittografia richiesto CMM per richiedere contesti di crittografia nelle operazioni crittografiche. Un contesto di crittografia è un insieme di coppie chiave-valore non segrete. Il contesto di crittografia è associato crittograficamente ai dati crittografati in modo che sia necessario lo stesso contesto di crittografia per decrittografare il campo. Quando si utilizza il contesto di crittografia richiesto CMM, è possibile specificare una o più chiavi di contesto di crittografia richieste (chiavi obbligatorie) che devono essere incluse in tutte le chiamate di crittografia e decrittografia.

Nota

Il contesto di crittografia richiesto CMM è interoperabile solo con la versione 3. x di. SDK di crittografia AWS per Java Non è interoperabile con nessun'altra implementazione del linguaggio di programmazione. Se si crittografano i dati utilizzando il contesto di crittografia richiesto CMM, è possibile decrittografarli solo con la versione 3. x della versione o 4. SDK di crittografia AWS per Java x del AWS Encryption SDK per.NET.

In encrypt, AWS Encryption SDK verifica che tutte le chiavi del contesto di crittografia richieste siano incluse nel contesto di crittografia specificato. Segna AWS Encryption SDK i contesti di crittografia specificati. Solo le coppie chiave-valore che non sono chiavi richieste vengono serializzate e archiviate in testo semplice nell'intestazione del messaggio crittografato restituito dall'operazione di crittografia.

In decrypt, è necessario fornire un contesto di crittografia che contenga tutte le coppie chiave-valore che rappresentano le chiavi richieste. AWS Encryption SDKUtilizza questo contesto di crittografia e le coppie chiave-valore memorizzate nell'intestazione del messaggio crittografato per ricostruire il contesto di crittografia originale specificato nell'operazione di crittografia. Se AWS Encryption SDK non è possibile ricostruire il contesto di crittografia originale, l'operazione di decrittografia ha esito negativo. Se si fornisce una coppia chiave-valore che contiene la chiave richiesta con un valore errato, il messaggio crittografato non può essere decrittografato. È necessario fornire la stessa coppia chiave-valore specificata in encrypt.

Importante

Valuta attentamente i valori che scegli per le chiavi richieste nel tuo contesto di crittografia. Devi essere in grado di fornire nuovamente le stesse chiavi e i valori corrispondenti al momento di decrypt. Se non riesci a riprodurre le chiavi richieste, il messaggio crittografato non può essere decrittografato.

L'esempio seguente inizializza un AWS KMS portachiavi con il contesto di crittografia richiesto 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);

Se si utilizza un AWS KMS portachiavi, anche il contesto di crittografia AWS Encryption SDK for .NET utilizza il contesto di crittografia per fornire dati autenticati aggiuntivi (AAD) nelle chiamate a cui effettua il portachiavi. AWS KMS