本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS Encryption SDK 適用於 .NET 的
for AWS Encryption SDK .NET 是適用於以 C\$1 和其他 .NET 程式設計語言撰寫應用程式的開發人員的用戶端加密程式庫。Windows、macOS 和 Linux 都提供支援。
**注意**
AWS Encryption SDK 適用於 .NET 的 4.0. AWS Encryption SDK 0 版偏離訊息規格。因此，4.0.0 版加密的訊息只能由 .NET AWS Encryption SDK 的 4.0.0 版或更新版本解密。任何其他程式設計語言實作無法解密它們。
AWS Encryption SDK 適用於 .NET 的 4.0.1 版會根據訊息規格寫入 AWS Encryption SDK 訊息，並可與其他程式設計語言實作互通。根據預設，4.0.1 版可以讀取 4.0.0 版加密的訊息。不過，如果您不想解密 4.0.0 版加密的訊息，您可以指定 [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) 屬性，以防止用戶端讀取這些訊息。如需詳細資訊，請參閱 GitHub 上 aws-encryption-sdk 儲存庫中的 [v4.0.1 版本備註](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1)。
AWS Encryption SDK for .NET 與 的一些其他程式設計語言實作有以下 AWS Encryption SDK 不同：
+ 不支援[資料金鑰快取](data-key-caching.md)
**注意**
AWS Encryption SDK 適用於 .NET 的 4.*x* 版支援[AWS KMS 階層式 keyring](use-hierarchical-keyring.md)，這是替代的密碼編譯資料快取解決方案。
+ 不支援串流資料
+ .NET AWS Encryption SDK 版 中[沒有記錄或堆疊追蹤](#dot-net-debugging)
+ [需要 適用於 .NET 的 AWS SDK](#dot-net-install)
for AWS Encryption SDK .NET 包含 2.0.*x* 版和更新版本中引入的所有安全功能，以及 的其他語言實作 AWS Encryption SDK。不過，如果您使用 AWS Encryption SDK for .NET 來解密由 2.0.*x* 之前版本另一個語言實作所加密的資料 AWS Encryption SDK，您可能需要調整您的[承諾政策](concepts.md#commitment-policy)。如需詳細資訊，請參閱[如何設定您的承諾政策](migrate-commitment-policy.md#migrate-commitment-step1)。
AWS Encryption SDK 適用於 .NET 的 是 [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK 中的產品，這是一種正式的驗證語言，您可以在其中撰寫規格、實作它們的程式碼，以及測試它們的證明。結果是一個程式庫，可在架構中實作 的功能 AWS Encryption SDK ，以確保功能正確性。
**進一步了解**
+ 如需示範如何在 中設定選項的範例 AWS Encryption SDK，例如指定替代演算法套件、限制加密的資料金鑰，以及使用 AWS KMS 多區域金鑰，請參閱 [設定 AWS Encryption SDK](configure.md)。
+ 如需使用 AWS Encryption SDK 適用於 .NET 的 進行程式設計的詳細資訊，請參閱 GitHub 上 aws-encryption-sdk 儲存庫的[https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)目錄。
**Topics**
+ [安裝和建置](#dot-net-install)
+ [除錯](#dot-net-debugging)
+ [範例](dot-net-examples.md)
## 安裝 AWS Encryption SDK 適用於 .NET 的
AWS Encryption SDK 適用於 .NET 的 可作為 NuGet 中的[https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)套件使用。如需安裝和建置 AWS Encryption SDK for .NET 的詳細資訊，請參閱 `aws-encryption-sdk-net`儲存庫中的 [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) 檔案。
**3.x 版**
AWS Encryption SDK 適用於 .NET 的 3.*x* 版僅支援 Windows 上的 .NET Framework 4.5.2 – 4.8。它在所有支援的作業系統上支援 .NET Core 3.0\$1 和 .NET 5.0 及更新版本。
**4.x 版**
AWS Encryption SDK 適用於 .NET 的 4.*x* 版支援 .NET 6.0 和 .NET Framework net48 及更新版本。4.*x* 版需要適用於 .NET v3 的 AWS SDK。
**5.x 版**
AWS Encryption SDK 適用於 .NET 的 5.*x* 版支援 .NET 6.0 和 .NET Framework net48 及更新版本。5.*x* 版需要材質提供者程式庫 (MPL) 的 2.*x* 版，以及適用於 .NET v4 的 AWS SDK。
適用於 .NET 的 SDK 即使您未使用 AWS Key Management Service (AWS KMS) 金鑰， AWS Encryption SDK 適用於 .NET 的 都需要 。它與 NuGet 套件一起安裝。不過，除非您使用 AWS KMS 金鑰，否則 AWS Encryption SDK 針對 .NET AWS 帳戶，不需要 、 AWS 憑證或與任何 AWS 服務的互動。如需設定 AWS 帳戶的說明，請參閱 [AWS Encryption SDK 搭配 使用 AWS KMS](getting-started.md)。
## 偵錯適用於 .NET AWS Encryption SDK 的
AWS Encryption SDK for .NET 不會產生任何日誌。for AWS Encryption SDK .NET 中的例外狀況會產生例外狀況訊息，但不會產生堆疊追蹤。
為了協助您偵錯，請務必在 中啟用記錄 適用於 .NET 的 SDK。的日誌和錯誤訊息 適用於 .NET 的 SDK 可協助您區分 中產生的錯誤 適用於 .NET 的 SDK 與 AWS Encryption SDK 適用於 .NET 的 中的錯誤。如需 適用於 .NET 的 SDK 記錄的說明，請參閱《 *適用於 .NET 的 AWS SDK 開發人員指南*》中的 [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)。（若要查看主題，請展開**開啟以檢視 .NET Framework 內容**區段。)
# AWS Encryption SDK 適用於 .NET 的範例
下列範例顯示使用 AWS Encryption SDK for .NET 進行程式設計時所使用的基本編碼模式。具體而言，您會執行個體化 AWS Encryption SDK 和材料提供者程式庫。然後，在呼叫每個方法之前，您可以執行個體化物件，定義方法的輸入。這與您在 中使用的編碼模式非常相似 適用於 .NET 的 SDK。
如需示範如何在 中設定選項的範例 AWS Encryption SDK，例如指定替代演算法套件、限制加密的資料金鑰，以及使用 AWS KMS 多區域金鑰，請參閱 [設定 AWS Encryption SDK](configure.md)。
如需使用 AWS Encryption SDK 適用於 .NET 的 進行程式設計的更多範例，請參閱 GitHub 上儲存`aws-encryption-sdk`庫`aws-encryption-sdk-net`目錄中[的範例](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples)。
## 在 AWS Encryption SDK 適用於 .NET 的 中加密資料
此範例顯示加密資料的基本模式。它使用由一個 AWS KMS 包裝金鑰保護的資料金鑰來加密小型檔案。
步驟 1：執行個體化 AWS Encryption SDK 和材料提供者程式庫。
從執行個體化 AWS Encryption SDK 和材料提供者程式庫開始。您將使用 中的方法來 AWS Encryption SDK 加密和解密資料。您將使用材料提供者程式庫中的方法來建立 keyring，以指定哪些金鑰保護您的資料。
您執行個體化 AWS Encryption SDK 和材料提供者程式庫的方式，在 AWS Encryption SDK 適用於 .NET 的 版本 3.*x* 和 4.*x* 之間有所不同。適用於 .NET 的 3.*x* 和 4 AWS Encryption SDK .*x* 版的所有下列步驟都相同。
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
步驟 2：建立 keyring 的輸入物件。
每個建立 keyring 的方法都有對應的輸入物件類別。例如，若要建立 `CreateAwsKmsKeyring()`方法的輸入物件，請建立 `CreateAwsKmsKeyringInput`類別的執行個體。
即使此 keyring 的輸入未指定[產生器金鑰](use-kms-keyring.md#kms-keyring-encrypt)， `KmsKeyId` 參數指定的單一 KMS 金鑰仍為產生器金鑰。它會產生並加密加密資料的資料金鑰。
此輸入物件需要 KMS 金鑰 AWS 區域 的 AWS KMS 用戶端。若要建立 AWS KMS 用戶端，請在 中執行個體化 `AmazonKeyManagementServiceClient`類別 適用於 .NET 的 SDK。呼叫沒有參數的`AmazonKeyManagementServiceClient()`建構函數會建立具有預設值的用戶端。
在用於使用 AWS Encryption SDK for .NET 加密的 AWS KMS keyring 中，您可以使用金鑰 ID、金鑰 ARN、別名名稱或別名 ARN 來[識別 KMS](use-kms-keyring.md#kms-keyring-id) 金鑰。在用於解密的 AWS KMS keyring 中，您必須使用金鑰 ARN 來識別每個 KMS 金鑰。如果您打算重複使用加密 keyring 進行解密，請為所有 KMS 金鑰使用金鑰 ARN 識別符。
```
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
};
```
步驟 3：建立 keyring。
若要建立 keyring，請使用 keyring 輸入物件呼叫 keyring 方法。此範例使用 `CreateAwsKmsKeyring()`方法，只需要一個 KMS 金鑰。
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
步驟 4：定義加密內容。
[加密內容](concepts.md#encryption-context)是選用的，但強烈建議在 中進行密碼編譯操作 AWS Encryption SDK。您可以定義一或多個非秘密金鑰值對。
使用適用於 .NET 的 4 AWS Encryption SDK .*x* 版，您可以在具有[所需加密內容 CMM 的所有加密請求中要求加密內容](configure.md#config-required-encryption-context-cmm)。
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
步驟 5：建立用於加密的輸入物件。
呼叫 `Encrypt()`方法之前，請先建立 `EncryptInput`類別的執行個體。
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
步驟 6：加密純文字。
使用 的 `Encrypt()`方法 AWS Encryption SDK ，使用您定義的 keyring 加密純文字。
`Encrypt() `方法傳回`EncryptOutput`的 具有取得加密訊息 (`Ciphertext`)、加密內容和演算法套件的方法。
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
步驟 7：取得加密的訊息。
AWS Encryption SDK 適用於 .NET 的 中的 `Decrypt()`方法採用`EncryptOutput`執行個體`Ciphertext`的成員。
`EncryptOutput` 物件`Ciphertext`的成員是[加密的訊息](concepts.md#message)，這是一個可攜式物件，其中包含加密的資料、加密的資料金鑰和中繼資料，包括加密內容。您可以安全地將加密的訊息存放一段時間，或將其提交至 `Decrypt()`方法以復原純文字。
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## 在 AWS Encryption SDK 適用於 .NET 的 中以嚴格模式解密
最佳實務建議您指定用來解密資料的金鑰，這是稱為*嚴格模式*的選項。 AWS Encryption SDK 僅使用您在 keyring 中指定的 KMS 金鑰來解密加密文字。解密 keyring 中的金鑰必須包含至少一個加密資料的金鑰。
此範例顯示使用 AWS Encryption SDK for .NET 在嚴格模式下解密的基本模式。
步驟 1：執行個體化 AWS Encryption SDK 和 材料提供者程式庫。
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
步驟 2：建立 keyring 的輸入物件。
若要指定 keyring 方法的參數，請建立輸入物件。 AWS Encryption SDK 適用於 .NET 的 中的每個 keyring 方法都有對應的輸入物件。由於此範例使用 `CreateAwsKmsKeyring()`方法來建立 keyring，因此會執行個體化輸入的 `CreateAwsKmsKeyringInput`類別。
在解密 keyring 中，您必須使用金鑰 ARN 來識別 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
};
```
步驟 3：建立 keyring。
若要建立解密 keyring，此範例會使用 `CreateAwsKmsKeyring()`方法和 keyring 輸入物件。
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
步驟 4：建立用於解密的輸入物件。
若要建立 `Decrypt()`方法的輸入物件，請執行個體化 `DecryptInput`類別。
`DecryptInput()` 建構函數的 `Ciphertext` 參數會採用`Encrypt()`方法傳回的`EncryptOutput`物件`Ciphertext`成員。`Ciphertext` 屬性代表[加密的訊息](concepts.md#message)，其中包含 解密訊息所需的加密資料、加密的資料金鑰和中繼資料 AWS Encryption SDK 。
使用適用於 .NET 的 4 AWS Encryption SDK .*x* 版，您可以使用選用`EncryptionContext`參數在 `Decrypt()`方法中指定加密內容。
使用 `EncryptionContext` 參數來驗證用於加密的加密內容*是否包含在*用於解密加密文字的加密內容中。如果您使用演算法套件搭配簽署，例如預設演算法套件， 會將配對 AWS Encryption SDK 新增至加密內容，包括數位簽章。
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
步驟 5：解密加密文字。
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
步驟 6：驗證加密內容 – 3.*x* 版
AWS Encryption SDK 適用於 .NET 的 3.*x* 版`Decrypt()`方法不會採用加密內容。它會從加密訊息中的中繼資料取得加密內容值。不過，在傳回或使用純文字之前，最佳實務是驗證用來解密加密文字的加密內容是否包含您在加密時提供的加密內容。
確認用於加密的加密內容*包含在*用來解密加密文字的加密內容中。如果您使用演算法套件搭配簽署，例如預設演算法套件， 會將配對 AWS Encryption SDK 新增至加密內容，包括數位簽章。
```
// 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");
}
```
## 在 AWS Encryption SDK for .NET 中使用 探索 keyring 進行解密
您可以提供 AWS KMS *探索 keyring*，這是不指定任何 KMS 金鑰的 keyring，而不是指定用於解密的 KMS 金鑰。探索 keyring 可讓 使用加密資料的任何 KMS 金鑰 AWS Encryption SDK 來解密資料，前提是發起人對金鑰具有解密許可。針對最佳實務，請新增探索篩選條件，以限制可用於指定分割區 AWS 帳戶 的 KMS 金鑰。
AWS Encryption SDK 適用於 .NET 的 提供基本探索 keyring，其需要 AWS KMS 用戶端，以及需要您指定一或多個 的探索多 keyring AWS 區域。用戶端和區域都會限制可用於解密加密訊息的 KMS 金鑰。兩個 keyring 的輸入物件都採用建議的探索篩選條件。
下列範例顯示使用 AWS KMS 探索 keyring 和 探索篩選條件解密資料的模式。
步驟 1：執行個體化 AWS Encryption SDK 和材料提供者程式庫。
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
步驟 2：建立 keyring 的輸入物件。
若要指定 keyring 方法的參數，請建立輸入物件。 AWS Encryption SDK 適用於 .NET 的 中的每個 keyring 方法都有對應的輸入物件。由於此範例使用 `CreateAwsKmsDiscoveryKeyring()`方法來建立 keyring，因此會執行個體化輸入的 `CreateAwsKmsDiscoveryKeyringInput`類別。
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
步驟 3：建立 keyring。
若要建立解密 keyring，此範例會使用 `CreateAwsKmsDiscoveryKeyring()`方法和 keyring 輸入物件。
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
步驟 4：建立用於解密的輸入物件。
若要建立 `Decrypt()`方法的輸入物件，請執行個體化 `DecryptInput`類別。`Ciphertext` 參數的值是 `Encrypt()` 方法傳回之`EncryptOutput`物件`Ciphertext`的成員。
使用 AWS Encryption SDK 適用於 .NET 的 4.*x* 版，您可以使用選用`EncryptionContext`參數在 `Decrypt()`方法中指定加密內容。
使用 `EncryptionContext` 參數來驗證用於加密的加密內容*是否包含在*用於解密加密文字的加密內容中。如果您使用演算法套件搭配簽署，例如預設演算法套件， 會將配對 AWS Encryption SDK 新增至加密內容，包括數位簽章。
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
步驟 5：驗證加密內容 – 3.*x* 版
AWS Encryption SDK 適用於 .NET 的 3.*x* 版`Decrypt()`方法不會在 上採用加密內容`Decrypt()`。它會從加密訊息中的中繼資料取得加密內容值。不過，在傳回或使用純文字之前，最佳實務是驗證用來解密加密文字的加密內容是否包含您在加密時提供的加密內容。
確認用於加密的加密內容*包含在*用來解密加密文字的加密內容中。如果您使用演算法套件搭配簽署，例如預設演算法套件， 會將配對 AWS Encryption SDK 新增至加密內容，包括數位簽章。
```
// 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");
}
```